Oracle Web Forms

Oracle's Forms9i uses a three-tier architecture: the client tier; the application tier, and the database tier.

The client tier consists of Oracle's Forms Client. When the user runs a Forms session over the web, the Forms Java client is dynamically downloaded from the Application Server. The Forms Java client is an extensible java applet that runs in the browser's Java Virtual Machine (JVM). Currently the JVM is restricted to Oracle's own version of Sun's Java Plug-in called JInitiator.

The Forms application tier is made of several components, which are part of Oracle's 9i Application Server Release. The Forms Runtime Engine is a process that runs applications. Each client is "attached" to their own Forms Runtime, which is terminated when the session ends. The Forms Listener is a servlet responsible for directing requests to a Forms Runtime Engine and relaying responses back to the client.

It is important to understand that all of the Forms logic is executed by the Forms Runtime Engine running on this middle tier. That is, the Forms Runtime Engine opens the appropriate FMX file, connects to the database and executes the Form. No logic executes on the client. Only what Oracle classes as UI information is sent to the client. Each major action on the client, such as navigating between Form fields, choosing an item from a list, etc, incurs a round trip to the Application server in order to be processed by the Forms Runtime Engine.

The database tier will typically run on a dedicated server or cluster environment. The Forms Runtime Engine will usually make one or more connections to a database instance.

Fire Integration

In most aspects the behavior and configuration of a Fire application within a Forms environment is similar to the standard web-deployed Fire plugin (see here). The major differences lie in applet configuration and client-code interface.

The Xmarc FireBean

Because the Forms Client is a Java Applet, the functionality of the Forms Client can be extended by using Java. A Fire JavaBean has therefore been developed to act as a proxy between the Fire process and Oracle Forms9i. The FireBean's responsibilities include:

checking if the Fire Engine package is installed on the client machine. If it is not, the FireBean installs the package into an installation directory.
determining the Java Plug-in vendor.
creating and embedding a window within the Oracle Forms9i application running in the browser.
starting a Fire session if one is not already started. The FireBean then passes application specific information, APPSESSION , APPVIEW and APPSTART to the running session. The FireBean also sends specific display information including the window handle to Fire which allows Fire session to embed its windows into the Forms application
executing Fire commands using either FireBean.evaluateAsString() and FireBean.execute() for synchronous execution or FireBean.executeAsync() for asynchronous execution.
relaying events raised in Fire to the Forms application.

Certain FireBean behavior can be controlled by defining various parameter tags. These can be added into Oracle's Forms Services HTML template files. For example, <ORACLE9iAS_HOME>/forms90/server/baseie.html and <ORACLE9iAS_HOME>/forms90/server/formsweb.cfg .

Table 1 details the applet parameters that can be used to customize the FireBean download of the Fire Engine package.

Parameter	Description
FIREVERSION	Fire runtime version required to run the current application. The FireBean checks it against the installed Fire Engine version on the client. If it is greater than the installed version, the newer version is downloaded and installed by the FireBean.
FIREBASE (optional)	Base URL where the FireBean (jam.jar) and Fire Engine (fire_<arch_os>.zip) are located. Typically this is a webfire directory somewhere in a web server hierarchy. If this omitted (which is typical), the FireBean will derive a URL from the value of the applet ARCHIVE parameter, since the required files are in the same directory on the web-server as jam.jar.

Table 2 contains the applet parameters used to pass details of the Fire application.

Parameter	Description
APPSESSION	A name given to the Fire session in which the application will run. This should be a unique name for the deployment of the application. If required, multiple FireBeans can share the same Fire session, allowing an Oracle Forms application to have multiple Forms-resident Fire windows. In this case multiple FireBeans would share the same APPSESSION parameter but would have different APPVIEW parameters.
APPVIEW	A name used to identify the Forms container window (bean area) to Fire.This value is passed to the Fire application when something needs to be done on the window. It is a parameter to the appview.cmd macro within the application.
APPSTART	The URL of the Fire application control file (.fsc or .xml). This in turn provides details of the application library (.fsa) which Fire should execute to run the application. The location can be on a different web server to the one hosting FIREBASE.

Note: Parameters APPWIDTH and APPHEIGHT are ignored. The size of the embedded Fire window is governed by the size of the Bean Area canvas defined in the Form window. Contrast this behavior with that of the standard web-deployed Fire plugin, where these 2 parameters define the size of the embedded window.

Using the FireBean with the FBean Package

The following discussion and code snippets assume the reader is already adept in Oracle Forms coding, which is outside the scope of this document. Please refer to the documentation in the Oracle Web Forms installation for specific details on the FBean pacakge.

Instantiating the FireBean

In order to run an embedded Fire session, the FireBean must be registered into the Bean Area of the form:

 FBean.Register_Bean(myFireBean,1,'com.xmarc.jam.FireBean')

Note: In Oracle Forms Builder, the Bean Area's Implementation Class property in the Bean Area's property dialog must be left blank.

To catch events raised in Fire, the FBean package needs to be informed on what to listen out for. Thus to process events, the following FBean method must be called:

 FBEAN.ENABLE_EVENT(myFireBean,1,'actionListener',TRUE);

Calling Fire Commands

Typical Form/Fire interaction is by way of implementing triggers in Forms and having the PL/SQL code behind the triggers invoke the relevent FireBean methods:

--For synchronous execution of a command
FBean.Invoke(myFireBean,1,'execute',cmdArgs);

--For asynchronous execution of a command
FBean.Invoke(myFireBean1,'executeAsync',cmdArgs);

--To evaluate a Fire expression
returnValue := FBean.Invoke(myFireBean,1,'evaluateAsString',cmdArgs);

Handling Raised Events

As noted above, the Xmarc FireBean can also raise events to be handled by the container. When the particular event is raised, the container's WHEN-CUSTOM-ITEM-EVENT trigger will be fired and information about the event may then be retrieved and acted upon. The event name itself is passed in the :SYSTEM.CUSTOM_ITEM_EVENT value, and the payload of the event is passed in the DATA parameter in the parameter list defined by :SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS. Only string datatype is supported by the DATA paramater. An example is given below:

DECLARE
	EventData VARCHAR2(255);
	ParamType NUMBER;
BEGIN
	-- Check if it is the right event
	if :SYSTEM.Custom_Item_Event = 'ACTION_PERFORMED' then
		-- get the DATA parameter
		get_parameter_attr(:SYSTEM.Custom_Item_Event_Parameters,'DATA', ParamType, EventData);
		-- Echo the event data (string data)
		Message('Caught Event data: ' || EventData);
	end if;
END;

Using Fire with Oracle9iDS Forms Developer

A number of prerequisites are required in order to develop Fire-enhanced Web Forms applications using Forms Developer. It is assumed that Oracle 9i Developer Suite has been installed on the client machine. First, a Web Deployed Fire Server must be accessible to the client running Forms Developer. Secondly, in order to workaround an Oracle limitation with multiple signing identities, some modification must be done to the template HTML file and Formsweb.cfg file that reside in forms90/server directory.

Changes to the Template HTML file

Assuming a non-customized Forms Developer install, go to the forms90/server directory and take a copy of the basejini.htm file calling the new version signedjini.htm. Now add the following HTML applet Tag fragment to this file above the line that reads 

 <!-- Registration applet definition (start) -->
 <OBJECT classid="%jinit_classid%"
         CODEBASE="/forms90/jinitiator/%jinit_exename%"
         WIDTH="0"
         HEIGHT="0"
         HSPACE="0"
         VSPACE="0">
     <PARAM NAME="TYPE" VALUE="%jinit_mimetype%">
     <PARAM NAME="CODEBASE" VALUE="%codebase%">
     <PARAM NAME="CODE" VALUE="%pjcRegisterApplet%">
     <PARAM NAME="ARCHIVE" VALUE="%pjcArchive%">
     <COMMENT>
     <EMBED SRC="" PLUGINSPACE="%jinit_download_page%"
            TYPE="%jinit_mimetype%"
            java_codebase="%codebase%"
            java_code="%pjcRegisterApplet%"
            java_archive="%pjcArchive%"
            WIDTH="0"
            HEIGHT="0"
            HSPACE="0"
            VSPACE="0">
     <NOEMBED>
     </COMMENT>
     </NOEMBED>
     </EMBED>
 </OBJECT>
 <!-- Registration applet definition (end) -->

This tag will create a second applet on the page. Because it is the first applet tag on the page, JInitiator will load this applet first and therefore will encounter this applet's signing certificate. At this stage the Xmarc trust dialog will appear waiting for the user to "grant this session". Then once the Forms Applet is loaded the code will have already have been trusted and the Oracle signing restriction by-passed.

Note: the new applet has been assigned a size of 0x0 pixels, so nothing will appear in the page. The user will just see the trust dialog appear (and once only within the same browser session).

Add the necessary Fire Web Deploy parameters into signedjini.htm. These are inserted into the  section as shown below:

<!-- Forms applet definition (start) -->
<OBJECT classid="%jinit_classid%"
        CODEBASE="/forms90/jinitiator/%jinit_exename%"
        WIDTH="%Width%"
        HEIGHT="%Height%"
        HSPACE="0"
        VSPACE="0">
   <PARAM NAME="TYPE" VALUE="%jinit_mimetype%">
   <PARAM NAME="CODEBASE" VALUE="%codebase%">
   <PARAM NAME="CODE" VALUE="oracle.forms.engine.Main" >
   <PARAM NAME="ARCHIVE" VALUE="%archive_jini%" > 
   <PARAM NAME="serverURL" VALUE="%serverURL%">
   <PARAM NAME="networkRetries" VALUE="%networkRetries%">
   <PARAM NAME="serverArgs" VALUE="module=%form% userid=%userid% sso_userid=%sso_userid% %otherParams%">
   <PARAM NAME="separateFrame" VALUE="%separateFrame%">
   <PARAM NAME="splashScreen" VALUE="%splashScreen%">
   <PARAM NAME="background" VALUE="%background%">
   <PARAM NAME="lookAndFeel" VALUE="%lookAndFeel%">
   <PARAM NAME="colorScheme" VALUE="%colorScheme%">
   <PARAM NAME="serverApp" VALUE="%serverApp%">
   <PARAM NAME="logo" VALUE="%logo%">
   <PARAM NAME="imageBase" VALUE="%imageBase%">
   <PARAM NAME="formsMessageListener" VALUE="%formsMessageListener%">
   <PARAM NAME="recordFileName" VALUE="%recordFileName%">
   <PARAM NAME="APPSESSION" value="%xmAppSession%">
   <PARAM NAME="APPSTART" value="%xmAppStart%">
   <PARAM NAME="APPVIEW" value="%xmAppView%">
   <PARAM NAME="FIREBASE" value="%xmFireBase%">
   <PARAM NAME="FIREVERSION" value="%xmFireVersion%">
   <PARAM NAME="LOGGING" value="1">
   <PARAM NAME="DEBUG" value="">
   <COMMENT> 
   <EMBED SRC="" PLUGINSPAGE="%jinit_download_page%" 
          TYPE="%jinit_mimetype%" 
          java_codebase="%codebase%" 
          java_code="oracle.forms.engine.Main" 
          java_archive="%archive_jini%" 
          WIDTH="%Width%"
          HEIGHT="%Height%" 
          HSPACE="0"
          VSPACE="0"
          serverURL="%serverURL%"
          networkRetries="%networkRetries%"
          serverArgs="module=%form% userid=%userid% sso_userid=%sso_userid% %otherparams%"
          separateFrame="%separateFrame%"
          splashScreen="%splashScreen%"
          background="%background%"
          lookAndFeel="%lookAndFeel%"
          colorScheme="%colorScheme%"
          serverApp="%serverApp%"
          logo="%logo%"
          imageBase="%imageBase%"
          formsMessageListener="%formsMessageListener%"
          recordFileName="%recordFileName%"
          appsession="%xmAppSession%"
          appstart="%xmAppStart%"
          appview="%xmAppView%"
          firebase="%xmFireBase%"
          fireversion="%xmFireVersion%"
          logging="1"
          debug="" >
   <NOEMBED> 
   </COMMENT> 
   </NOEMBED>
   </EMBED> 
 </OBJECT>
 <!-- Forms applet definition (end) --

Changes to the Formsweb.cfg file

In addition to the above changes made to the Template HTML file, the Forms Servlet has to be informed that it must use the new template file - signedjini.htm and what values to use for the substitution variables %pjcRegisterApplet% and %pjcArchive%. The baseHTMLjinitiator value is used to identify the custom template.

An example config entry in the formsweb.cfg file might look like this:

[xmarc_app]
pageTitle=Fire Enhanced Oracle9iAS Forms
archive_jini=f90all_jinit.jar,jam.jar
 
pjcRegisterApplet=com.xmarc.jam.RegisterCertificate
pjcArchive=jam.jar
baseHTMLjinitiator=signedjini.htm
width=800
height=600
lookandfeel=Oracle
 
xmAppSession=XmarcExample
xmAppStart=http://host/xmarc/cmds/myapp.fsc
xmAppView=mainpanel
 
xmFireBase=http://host2/webfire6
xmFireVersion=7.1.43

Note: jam.jar has been added to archive_jini. For further details on the various web deploy values (such as AppStart, AppSession etc), click here.

Prev Chapter Next Chapter