7 Enhanced Java Support

This chapter contains the following sections:

7.1 Overview

Oracle Forms provides Java classes that define the appearance and behavior of standard user interface components such as buttons, text areas, radio groups, list items, and so on. A Forms pluggable Java component (PJC) can be thought of as an extension of the default Forms client component. When you create a PJC, you write your own Java code to extend the functionality of any of the provided default classes.

7.1.1 Dispatching Events from Forms Developer

In addition to extending the standard Forms user interface components, you can also create a PJC that includes Java Swing user interface components in your form. A pluggable Java component extends a class provided by Forms, that is, oracle.forms.ui.VBean, and lives in the Bean Area as seen on the Forms canvas. The Bean Area does not have its own user interface, but rather is a container. On the layout editor or on a canvas, you see only an empty rectangle until you associate an implementation class with it and add some user interface components.

In earlier releases of Oracle Forms, Forms user interface components implemented the IView interface. However, it did not have any special method to add or remove CustomListener from the pluggable Java component or the view. In Oracle Forms 11g, you can add or remove CustomListener in the IView interface.

7.1.2 Dispatching Events to Forms Services

Oracle Forms 11g makes it easier to dispatch CustomEvent along with parameters and payloads. Since JavaBean classes do this by exposing the public method dispatchCustomEvent, you need to add the same method for your PJC. You call the dispatchCustomEvent method from the PJC to dispatch the CustomEvent.

Since CustomEvent is usually associated with parameters, Forms provides a way to add them. In a JavaBean, you can use the getHandler().setProperty() method to set the parameters. Users must be able to do the same for PJC. For more information, see Section 7.2.2, "About the Custom Item Event Trigger at Runtime".

7.2 About Custom Item Event Triggers

In Oracle Forms 11g, you can add the WHEN-CUSTOM-ITEM-EVENT trigger to items at design time and code the pluggable Java components so that the trigger can be fired at runtime. This trigger fires whenever a JavaBean custom component in the form causes the occurrence of an event. You can use a WHEN-CUSTOM-ITEM-EVENT trigger to respond to a selection or change of value of a custom component. The system variable SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS stores a parameter name that contains the supplementary arguments for an event that is fired by a custom control. Control event names are case sensitive.

7.2.1 Adding the When-Custom-Item-Event Trigger at Design Time

The most common way of adding a trigger to an item is by clicking the Create button in the Object Navigator toolbar in Oracle Forms Developer, while the focus is on the Trigger node, or by pressing the corresponding shortcut key. Forms Developer presents to you a list of available triggers at that level or for that item.

Another way of adding some of the commonly used triggers is by right-clicking the trigger node of the item in the Object Navigator. Then, select one of the triggers listed in the smart Triggers menu.

For more information on working with triggers, see the Oracle Forms Developer online help.

7.2.2 About the Custom Item Event Trigger at Runtime

In Oracle Forms 11g, pluggable Java components can raise the WHEN-CUSTOM-ITEM-EVENT trigger. This enhanced trigger provides greater control over the content of the communication between the client and server.

The Forms client dispatches CustomEvent through the pluggable Java component, which fires the WHEN-CUSTOM-ITEM-EVENT trigger on the Forms Services. The WHEN-CUSTOM-ITEM-EVENT trigger provides a simple way to retrieve the event name and parameter values that are passed from the client pluggable Java component through CustomEvent. The event name is stored in SYSTEM.CUSTOM_ITEM_EVENT; parameters (name and value) are stored in SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS.

The Forms Built-in get_parameter_attr is used to retrieve the values and different parameters from SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS. The supported datatype for the values or payloads that are returned from get_parameter_attr is a VARCHAR2 string.

7.2.3 Example: A Java class for a Push Button

In this example, a Java class is created for a push button that enables selecting a client file using the File Open option and returns the path to the server.

  1. Create a Java class for a push button with simple PJC code such as:

      // MyButtonPJC.java
     import java.awt.event.ActionEvent;
     import java.awt.event.ActionListener;
     import javax.swing.JFileChooser;
     import oracle.forms.ui.CustomEvent;
     import oracle.forms.ui.VButton;
     import oracle.forms.properties.ID;
     public class MyButtonPJC extends VButton implements ActionListener
     {
       private static final ID CLIENT_SELECTED_FILE = ID.registerProperty("CLIENT_SELECTED_FILE");
       public MyButtonPJC()
       {
         addActionListener(this);
       }
       public void actionPerformed(ActionEvent event)
       {
         JFileChooser fc = new JFileChooser();
         if(fc.showOpenDialog(getHandler().getApplet()) == JFileChooser.APPROVE_OPTION)
         {
           CustomEvent ce = new CustomEvent(getHandler(), "MyButtonPJC_Event");
           ce.setProperty(CLIENT_SELECTED_FILE, fc.getSelectedFile().getAbsolutePath());
           this.dispatchCustomEvent(ce);
         }
       }
       public void destroy()
       {
         removeActionListener(this);
         super.destroy();
        }
    }
    
  2. Ensure CLASSPATH variable is defined in the environment and $ORACLE_HOME/forms/java/frmall.jar is added to it.

  3. Compile the Java class. For ease of creating the jar later, place the output class files in a separate directory by using the -d <output-directory> option of the javac (java compiler).

  4. Navigate to the output directory and create a jar file, for example, MyButtonPJC.jar, containing the generated class files by using the command

    jar cvf <jar-file-path> *

  5. MyButtonPJC.jar needs to be signed before deploying in Forms applet. You can use sign_webutil.sh (sign_webutil.bat in Windows) that is available in the directory $ORACLE_INSTANCE\bin to sign the jar file. For more information, see Forms Builder Online Help.

  6. Copy MyButtonPJC.jar to $ORACLE_HOME/forms/java directory.

  7. Add the path of MyButtonPJC.jar to the FORMS_BUILDER_CLASSPATH. This makes the class files in that jar available in Forms Builder.

  8. Add the push button on the layout in the Forms application.

  9. In Property Palette of the push button, set MyButtonPJC as the implementation class.

  10. Add WHEN-CUSTOM-ITEM-EVENT trigger to the push button.

  11. Add the following PL/SQL code to the WHEN-CUSTOM-ITEM-EVENT trigger of the push button. This code handles the CustomEvent dispatched by the PJC and then extracts the parameters in the event.

     declare
        filePath VARCHAR2(1024);
        dataType      PLS_INTEGER;
      begin
        Message('Custom Event Name='||:SYSTEM.CUSTOM_ITEM_EVENT);
        get_parameter_attr(:SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS,'CLIENT_SELECTED_FILE',dataType, filePath);
        Message('The selected client file path is '|| filePath);
      end;
    
  12. Add MyButtonPJC.jar to the list of comma-separated jars (only jar file name, not the full path) in the archive parameter in Forms configuration file (formsweb.cfg). This ensures that the jar file is loaded in Forms applet on the client side.