Calling Custom Events from a PJC in Oracle Forms 11g

Purpose

In this tutorial we will have a closer look at Oracle Forms and Pluggable Java Components that can dispatch custom events from Forms client side components to the Oracle Forms engine running on the application server.

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.

A pluggable Java component extends a class provided by Forms, that is, oracle.forms.ui.VBean. PJCs still support the "native" events that are associated with the base component - for example, When-Button-Pressed for a button, but with PJCs in Oracle Forms 11g, you can add your own client side listener to listen for client side events and trigger a When-Custom-Item-Event in Forms.

Prerequisites

This sample assumes Oracle Forms 11g and an Oracle database with the SCOTT shema installed and unlocked.

Time to Complete

Approximately 30 minutes

Topics

This tutorial covers the following topics:

	Overview
	Scenario
	Creating the Java class
	Creating the JAR File
	Adding code to the Form
	Summary

Viewing Screenshots

Place the cursor over this icon to load and view all the screenshots for this tutorial. (Caution: This action loads all screenshots simultaneously, so, depending on your Internet connection, may result in a slow response time.)

Note: Alternatively, you can place the cursor over an individual icon in the following steps to load and view only the screenshot associated with that step. You can hide an individual screenshot by clicking it.

Overview

In this demonstration you create a Java class which extends the VtextField. You add a mouse event listener. When a double click with the mouse is detected, the listener sends a custom event to the forms engine with the 'Show_LOV' command.

Back to Topic List

Scenario

A text item that supports a list of values (LOV). The current behaviour is that the user has to input a combined keystroke or click a separate button to launch the LOV. In the scenario for this tutorial, the text itemwith the LOV will extend the existing functionality of the text item to listen for a double mouse click. If this is detected an event is raised back in Forms to launch the LOV. Thus, a double click a item can now launch the LOV. A solution is available in this zip file.

Back to Topic List

Creating the Java class

The first step of this tutorial is to create the Java class that will extend the basic Forms text item to add a mouse double-click listener.

Back to Topic List

Using your favorite Java IDE or notepad, create the following class (VTextFieldLOV.java)


      package extension;
      import oracle.forms.ui.VTextField;

        import oracle.forms.ui.CustomEvent;

        import oracle.forms.properties.ID;

        import oracle.forms.handler.IHandler;
      import java.awt.event.ActionListener;

        import java.awt.event.ActionEvent;

        import java.awt.event.MouseAdapter;

        import java.awt.event.MouseEvent;
      public class VTextFieldLOV extends VTextField implements ActionListener 
        {
       public VTextFieldLOV() {

        super();

        }
       public void init(IHandler h) {

        super.init(h);
       this.addMouseListener(new MouseAdapter() {

        public void mouseClicked(MouseEvent me) {

        if (me.getClickCount() == 2) {

        actionPerformed(new ActionEvent(this, 1, "SHOW_LOV"));

        }

        }
       });

        }
       public void actionPerformed(ActionEvent e) {

        if (e.getActionCommand() == "SHOW_LOV") {

        CustomEvent ce = new CustomEvent(getHandler(), "SHOW_LOV");

        this.dispatchCustomEvent(ce);

        }

        }

        }

Before compiling the class you need to set the location of the JDK and frmall.jar. (Oracle Forms comes with a 1.6 JDK as part of the middleware - this example assumes you would use that JDK and a 1.6 plug in for the client)

On Windows
SET ORACLE_INSTANCE=<Drive letter>\oracle\Middleware\asinst_1
SET ORACLE_HOME=<Drive letter>\oracle\Middleware\as_1
SET PATH=%ORACLE_HOME%\jdk\bin;%PATH%
SET CLASSPATH=%ORACLE_HOME%\forms\java\frmall.jar;%CLASSPATH%

On Unix
export ORACLE_INSTANCE=/xx/Oracle/Middleware/asinst_1
export ORACLE_HOME=/xx/Oracle/Middleware/as_1
export PATH=$ORACLE_HOME/jdk/bin:$PATH
export CLASSPATH=$ORACLE_HOME/forms/java/frmall.jar:$CLASSPATH

Compile the Java class. This will create two files named VTextFieldLOV.class and VTextFieldLOV$1.class

javac VTextFieldLOV.java.

Back to Topic

Creating the JAR file

The next step is to package up the Java class you have created into an archive file that will be downloaded to the client

Now create the extension.jar file

Create a sub-directory extension

Copy the VTextFieldLOV.class and VTextFieldLOV$1.class to the sub-directory extension

jar -cvf extension.jar extension

Copy the extension.jar to ORACLE_HOME/forms/java directory

Windows
copy extension.jar %ORACLE_HOME%\forms\java

Unix
cp extension.jar $ORACLE_HOME/forms/java

Adding code to the Form

The final step is to create a Form and define that the text item should use your new class. You will also set up the event that will be called by the "new" text item component.

Back to Topic List

1.	Set the FORMS_BUILDER_CLASSPATH environment variable. This will ensure the new class can be found by the Forms builder Windows FORMS_BUILDER_CLASSPATH=%ORACLE_HOME%\forms\java;%FORMS_BUILDER_CLASSPATH% Unix FORMS_BUILDER_CLASSPATH=$ORACLE_HOME/forms/java:$FORMS_BUILDER_CLASSPATH
2.	Open the form named LOV_EXAMPLE found in this zip file.
3.	Ensure that the Implementation Class in the deptno field is set to extension.VTextFieldLOV
4.	Confirm you have a When-Custom-Item-Event trigger on the deptno field Compile the Form (CTRL + T)
5.	Create a separate configuration section in the formsweb.cfg file Windows ….\Middleware\User_Projects\domains\ClassicDomain\servers\WLS_FORMS\stage\formsapp\11.1.1\formsapp\config Unix …./Middleware/User_Projects/domains/ClassicDomain/servers/WLS_FORMS/stage/formsapp/11.1.1/formsapp/config `[lov_example] archive=frmall.jar,extension.jar userid=<username>/<password>@<database> form=lov_example.fmx`
5.	Test the Form http://localhost:port/forms/frmservlet?config=lov_example Double clicking on the deptno field will display the LOV for that field

Back to Topic

Summary

This example shows how Forms UI components can be extended to provide additional behavior by listening for client side events and passing those events back to Forms

Back to Topic List

Place the cursor over this icon to hide all screenshots.