Developer: Java DOWNLOAD

Integrating Oracle Forms into Oracle ADF Faces
by Wilfred van der Deijl

Oracle JDeveloper & ADF TAGS java, forms, All

Learn a technique for extending existing Forms applications using Oracle ADF components. Published June 2007 Oracle Forms has been Web-enabled for years. It is perfectly possible to run Oracle Forms in a Web browser, and in its 2005 Statement of Direction, Oracle indicated that it remains committed to the development and support of Oracle Forms. On the other hand, there is rapid growth in and adoption of Java/JEE technologies and a general shift toward service-oriented architecture (SOA). With Oracle JDeveloper and Oracle Application Development Framework (ADF), it is possible to build feature-rich JavaServer Faces (JSF) Web applications. This article describes a combination of techniques that enables you to integrate these two worlds. Oracle ADF is an innovative J2EE development framework available in Oracle JDeveloper. It simplifies Java development by minimizing the need to write code that implements well known design patterns and the application's infrastructure. Oracle ADF provides these implementations as part of the framework. This article focuses on ADF Faces, one of the components of the ADF Framework. ADF Faces contains a large set of UI components built on top of the standard JSF APIs that leverage the latest technologies— including partial page rendering and Ajax—to provide a rich, interactive user interface. Although this article assumes the use of ADF Faces, the same techniques can also be used to integrate Oracle Forms with other Web technologies, such as PHP, Oracle Application Express, or .Net ASP. In this article I'll present an extreme example of integrating Oracle Forms and Oracle ADF Faces in such a way that end users won't notice the difference between the Oracle ADF Faces user interface and the pages that incorporate an existing Oracle Forms form. See Figure 1 for a simple example of such integration. Only the multirecord block showing the orders is an existing Oracle Forms form. The rest of the page comprises Oracle ADF Faces components.

You could just as well go with a solution in which users stay with the well-known multidocument interface of Oracle Forms. the form is tightly integrated with the Oracle ADF Faces page. . This integration changes the user experience from what is typical in Oracle Forms to a more classic Web experience. Oracle Forms also passes its context back to Oracle ADF Faces. For some situations. When you scroll through the multirecord Orders block. This proves that the order ID is passed back to Oracle ADF Faces and that Oracle Forms can trigger events (such as the refresh of the detail table) in Oracle ADF Faces. which means that the ID of the selected customer is passed to Oracle Forms to query the appropriate records. The currently selected customer is on the (pure Oracle ADF Faces) Customers tab. it is easy to replace the Oracle Forms form with an Oracle ADF Faces table without users noticing. and status bar are not shown. The menu. What you cannot clearly see in the screen shot is that only orders for a particular customer are shown. The key concept is that Oracle Forms passes context to Oracle ADF Faces. toolbar. with callouts to Oracle ADF Faces pages for specific tasks. In this example. In this example. It enables you to gradually adopt Oracle ADF Faces while still leveraging features of your Oracle Forms applications. toolbar. the Oracle ADF Faces table is on the same page.Figure 1 Oracle Forms form integrated into Oracle ADF Faces This example demonstrates several things: Visually. this extreme integration might be too much and you could leave users with a menu. but it could just as easily have been on a different Web page. the detail Oracle ADF Faces table showing the order lines requeries automatically. and/or status bar if you like.

See Figure 2 for an overview of how an Oracle Forms form runs in the client browser. Oracle Forms (green block) runs as a Java applet (blue block) on a Web page (yellow block) in the client's browser. Including the Applet The first hurdle is to include the actual Oracle Forms form on an Oracle ADF Faces Web page. Oracle Forms uses a Java applet in the client browser. use the easier route of defining a region and reusing it on all of your Oracle ADF Faces pages. First you create a JSPX file that defines the Oracle ADF Faces tags to output the Oracle Forms HTML to the client: <?xml version='1. In this concept.0' encoding='windows-1252'?> <af:regionDef var="regionParams" . you no longer rely on this servlet to supply the necessary HTML. conceptually. The figure shows how. you don't want the user to experience this startup time for each page that includes such a form. which shows that it is possible to raise Oracle Forms events from within Oracle ADF Faces. When a user navigates between Oracle ADF Faces pages and some of them include an Oracle Forms form. Starting this applet takes a couple of seconds. Another thing this screen shot does not show is the elimination of the Oracle Forms applet startup times. Figure 2 Oracle Forms applet on a Web page Typically this entire Web page is served by the Oracle Forms servlet. The HTML required to start the applet needs to be incorporated into true Oracle ADF Faces Web pages. You could create a JSF component to render this HTML and include the component on your Oracle ADF Faces pages.The Oracle ADF Faces page also has a Save Form submit button. For now. That Oracle ADF Faces button sends an event to Oracle Forms to instruct it to perform a commit."> <f:verbatim> .sun. This ability is necessary for passing context (such as the ID of the currently selected record) to the other environment and even to raise events in the other technology. It should be possible for both environments to communicate with each other. register this region in the META-INF/region-metadata.UIXRegion</component-class> <component-extension> <region-jsp-ui-def>/regions/oraFormsRegion. Oracle Forms 10g Release 2 and previous versions do not have a native JavaScript API. Oracle ADF Faces can include JavaScript to call into Oracle Forms. This API gives JavaScript the ability to call public methods of Java classes.xml file: <component> <component-type>com. </f:verbatim> </af:regionDef> Next.lang. This is a feature whose introduction is planned with the release of Oracle Forms 11g.adf. . you can reuse this definition with <af:region> on every Oracle ADF Faces page that needs to embed an Oracle Forms form: <af:region id="oraFormRegion" regionType="com.forms.String</attribute-class> </attribute> </component> Finally. but you can implement this feature yourself in Oracle Forms 10g Release 2 (or previous versions) by using the industry-standard LiveConnect API. but you can add one yourself.example. . The Oracle Forms applet is a Java class.faces. it can be called from JavaScript. and Oracle Forms should be able to execute JavaScript to communicate with Oracle ADF Faces. . and if this class exposes a public method. This new public method can be called from the client-side JavaScript and receive a payload (message) to pass on to Oracle Forms (see step 1 in Figure 3): .oracle.Main. and add a public raiseEvent() method. Sub-class the Oracle Forms applet class oracle.oracleFormRegion"> <f:attribute name="formModuleName" value="orders.component.xmlns:f="http://java. The first technique I describe here is use of an inbound JavaScript API that enables Oracle ADF Faces to raise an event in Oracle Forms and thereby execute PL/SQL code in Oracle Forms.fmx" /> </af:region> The use of <af:regionDef> and <af:region> enables you to define the HTML and JavaScript required to start Oracle Forms only once and reuse it on every Oracle ADF Faces page in which you want to embed an Oracle Forms form.jspx</region-jsp-ui-def> </component-extension> <attribute> <attribute-name>formModuleName</attribute-name> <attribute-class>java. Inbound JavaScript API The key requirement is a technique to link Oracle Forms and Oracle ADF Faces. The Oracle Forms applet as shipped by Oracle does not offer a public" xmlns:af="http://xmlns. { actual HTML and JavaScript goes here } .example. which is implemented by all major browsers. You can achieve this with a JavaScript-based API.oracleFormRegion</component-type> <component-class>oracle. . A simple example is an Oracle ADF Faces Save button that both commits the Oracle Forms form and submits and saves the Oracle ADF Faces input items on the same page.

sendMessageToForms(event. 'commit_form'). if (null != communicator) { communicator. event). which can be included in an Oracle Forms form. . payload). Doing so can be a simple automated task with the Java Development API (JDAPI). String payload) { CommunicatorBean communicator = findFirstCommunicator(). A PJC is a JavaBean that sub-classes oracle. mHandler. Fortunately Oracle Forms offers a framework called Pluggable Java Components (PJCs) for doing something like this. This is not something you can do directly.raiseEvent('do_key'. We can create a generic PJC to handle this inbound JavaScript communication. } } A PJC can trigger an Oracle Forms trigger called WHEN-CUSTOM-ITEM-EVENT (see step 3 in Figure 3): public void sendMessageToForms(String event.formsapplet. payload). String payload) { try { // set properties to pass to Oracle Forms mHandler. Make sure to embed this PJC in each form.document.setProperty(PROP_PAYLOAD.forms. Figure 3 Inbound JavaScript API This public raiseEvent() method still needs to trigger code in the active Oracle Forms form. The public method from the extended Oracle Forms applet can get a handle on the PJC in the active form and pass the payload on to that PJC (see step 2 in Figure 3): public void raiseEvent(String event.ui.VBean.setProperty(PROP_EVENT.

This communication can be accomplished with what we call an outbound JavaScript API. you can use PL/SQL code to inspect the payload of the event and act accordingly: declare BeanEventDetails ParamList. end if. get_parameter_attr(BeanEventDetails. Event). 'Payload'.// trigger WHEN-CUSTOM-ITEM-EVENT trigger in Forms CustomEvent ce = new CustomEvent(mHandler.custom_item_event_parameters). 1. again passing the payload (Step 3).printStackTrace(). get_parameter_attr(BeanEventDetails. ParamType. the PL/SQL code handling the trigger can inspect the payload and act accordingly. 'Event'. dispatchCustomEvent(ce). end. It starts with the client-side JavaScript's calling a public method of the extended Oracle Forms applet and passing a payload (step 1). Payload). This can be used to show details of the selected object in the Web application. This API works with the same PJC we already used for the inbound JavaScript API. . } catch (FException e) { e. Payload varchar2(1000). ParamType number := text_parameter. This completes the path from the client-side JavaScript to the Oracle Forms-side PL/SQL code. Outbound JavaScript API Next you need Oracle Forms to be able to trigger events on the Web page on which it is hosted. you can pass parameters to the PJC (see step 1 in Figure 4): begin -. A typical example might be scrolling through a multirecord block in Oracle Forms while passing the ID of the selected record back to the Web application. end. Using the SET_CUSTOM_PROPERTY built-in from PL/SQL. 'document. EVENT_MSG_TO_FORMS). Event varchar2(1000).getElementById(''frm:ordid''). 'EvalExpression'. } } Finally. The public method then gets a handle on the PJC of the active Oracle Forms form and calls a public method of this PJC to pass the payload (step 2). if event='do_key' then do_key(payload). Finally.PJC'.ordid).value=' || :ord. an API that enables Oracle Forms to execute and evaluate JavaScript from PL/SQL.set the Order ID set_custom_property('BLK_PJC. ParamType. begin BeanEventDetails := get_parameter_list(:system. This can be used to pass context and/or events back from Oracle Forms to the Web application. The PJC subsequently triggers the WHENCUSTOM-ITEM-EVENT trigger.

You can use the same outbound JavaScript API to submit the Web page back to the Web server. Object evalResult = appletWindow. Suspend and Reuse the Applet Oracle Forms uses a Java applet that runs in the Web browser to display the form and handle user interaction. this does not matter.toString()).Figure 4 Outbound JavaScript API In this case. } } This example just sets the value of a (probably hidden) input element on the Web page. return true.getApplet()). the property of the PJC would be the JavaScript to be evaluated or executed. in the architecture this article introduces. The PJC can then get a handle on its containing Java applet (see step 2 in Figure 4). Starting a large Java applet such as an Oracle Forms form can be resource-intensive and can take a couple of seconds. a user can navigate . Object value) { if (PROP_EVAL_EXPR == property) { JSObject appletWindow = JSObject. This is effectively the same as a user's entering the Order ID in a search form and clicking the Submit button.eval(value. because you start the Oracle Forms applet at the beginning of your session and continue working with it for a period of time without navigating to another Web page. This applet offers a method for evaluating the JavaScript as part of the LiveConnect API (see step 3 in Figure 4): public boolean setProperty(ID property. // make result available as PJC property setProperty(PROP_EVAL_RESULT. In a typical Oracle Forms installation. evalResult). However.getWindow(mHandler.

This means that the applet's HTML has to be 100 percent identical for the lifecycle cache to resume an old applet. Payload). This is another reason you want to declare the HTML only once in a JSF region or JSF custom component.4. Using this feature means that the applet is started only once for the entire browser session. Some of these might include an Oracle Forms form. if event='WHEN-APPLET-ACTIVATED' then -. which would defeat the purpose of the legacy lifecycle feature. end. The startup time of the applet is completely eliminated when the user returns to a page that includes an Oracle Forms form.add handling here end if. The name of the actual form to be started can be included in a hidden element on the Web page: . Doing so would require different HTML on each Web page. the applet is kept running in the background and is put into something called the legacy lifecycle cache. you can specify an additional parameter called legacy_lifecycle in the applet's HTML. Act on Applet Reactivation An applet resumes from this cache in exactly the same state it was in when it was suspended. and others might not. no Oracle Forms trigger fires during applet reactivation.custom_item_event_parameters). The applet is reactivated when the user returns to a Web page that includes exactly the same applet declaration. You probably want to add actions to the reactivation of the applet. } This uses the inbound JavaScript API to send an event to Oracle Forms and can be handled in the WHENCUSTOM-ITEM-EVENT trigger of the PJC: declare BeanEventDetails ParamList. That feature requires 100 percent identical HTML to enable reuse of the suspended applet. ""). begin BeanEventDetails := get_parameter_list(:system. raiseEvent("WHEN-APPLET-ACTIVATED". The default behavior of your Web browser and Sun Microsystems' Java Virtual Machine is to destroy the applet when you navigate away from the page. You can override this method as follows: public void show() { super. You cannot pass the names of these forms as normal parameters in the applet's HTML. ParamType. 'Event'. ParamType. 'Payload'. These different pages probably want to call different forms. Instead. Payload varchar2(1000).between Web Need for a Landing Form You can have different Oracle ADF Faces pages in your application that all include an Oracle Forms form. When using Java Virtual Machine version 1. get_parameter_attr(BeanEventDetails. You can circumvent this requirement by always specifying the same "landing form" as the name of the Oracle Forms form. This parameter instructs the virtual machine not to destroy the applet when you navigate away from the page. ParamType number := text_parameter. This means that the Oracle Forms form from the previous Web page is still running. Event varchar2(1000). Event). get_parameter_attr(BeanEventDetails.2 or higher on a client. The deprecated show() method of the Oracle Forms applet is called during applet reactivation. Unfortunately.

execute query (where clause refers :parameter. Again. by evaluating document.getElementById(''frm:oraFormRegion:formname'').value. Once more . This returns control to the endless loop in the landing form.start the form call_form(formName). 1. -.PJC'. 1. :parameter. Visual Integration You can opt to include a single form on an Oracle ADF Faces page and not allow users to navigate to other .PJC'. -.ordid:=orderID.getElementById('formname').fmx"/> The WHEN-NEW-FORM-INSTANCE trigger of the landing form can ascertain which form is actually needed. if (get_custom_property('BLK_PJC. 'EvalResult'). 1.get the order ID set_custom_property('BLK_PJC. which then inspects the hosting Web page again to ascertain which form should be started. This would mean different HTML for each order and would defeat the reuse of the suspended applet. formName := get_custom_property('BLK_PJC. the "real" form is running. customerID := get_custom_property('BLK_PJC. end if. end. 'AppletActive')='FALSE' then -. 'document. end. you can work around this issue with the outbound JavaScript API.PJC'. begin -. The landing form can then start the requested form: declare formName varchar2(1000).value'). 1. 1.PJC'. What if you want to incorporate an Oracle Forms form to edit an order in an Oracle ADF Faces page? You probably want to pass the selected order ID from the Oracle ADF Faces application to Oracle Forms.ordid) do_key('execute_query'). The only way this loop ends is when the applet is no longer active because the user is closing the browser.exit the loop if the user is closing the browser exit. That form should handle the applet reactivation by exiting itself. 'document. 'EvalResult'). When the applet is reactivated from the lifecycle cache.getElementById(''frm:orderID''). end loop.value'). Getting Context into Oracle Forms The legacy lifecycle feature introduces a problem when passing context from the Web application to Oracle Forms.PJC'. The Oracle Forms form can inspect this value during the WHEN-NEW-FORM-INSTANCE trigger and act accordingly: declare orderID number.<input type="hidden" id="formname" value="orders. You can incorporate the order ID (or whatever context you want to pass) as an invisible item on the Oracle ADF Faces pages.get the form name set_custom_property('BLK_PJC. you cannot do this the typical way by adding the parameter in the HTML to include the Oracle Forms applet. 'EvalExpression'. begin while true loop -. using the outbound JavaScript API. 'EvalExpression'.

With the . Another use of this technology is to embed individual Oracle Forms forms in Web pages to complete a BPEL human task. In that scenario. instantly giving users an intuitive Web experience while enabling you to reuse existing forms. These portlets could be used in an Oracle Portal environment or with the just released Oracle WebCenter technology. such as a manager approving or declining a purchase order. This approach enables you to adapt an Oracle ADF Faces front end to your applications one form at a time. toolbar. All application flow control is handled by Oracle ADF Faces. status bar. Oracle BPEL can monitor and control your business process. and Oracle Forms edges. you might want to remove the menu. This is demonstrated by the area boxed in red in Figure 5: Figure 5 Clipped Oracle Forms form with a limited view port Conclusion As you can see. the x and y position of the Oracle Forms applet can be set to negative values relative to the surrounding <div> element. You can use ADF Faces today while protecting your Forms investment of yesterday. and status bar from all Oracle Forms forms. Also. at a certain stage. it is possible to extend an existing Oracle Forms application using ADF Faces. you reuse existing Oracle Forms forms as single objects on Oracle ADF Faces Web pages. The easiest way to achieve all this is by clipping the Oracle Forms applet. A business process might have a human task. You can also use the technique to switch from an Oracle Forms user experience to a more classic Web user experience.Oracle Forms forms. which represents a rectangular area. Surround the applet HTML with a single <div> element. which results in a small viewing window that shows only the relevant portion of the Oracle Forms form. For this. tool bar. Initially. you would visually remove the menu. The integration also enables the building of portlets that embed Oracle Forms forms. You might even go as far as making the users believe it's not even Oracle Forms they are using. The height and width of this <div> can be set smaller than the size of the Oracle Forms applet it contains.

technology from this article. read detailed papers. If you just let the idea sink in and give it some thought. Wilfred van der Deijl is the senior system architect for to get more details on this technique. OraTransplant. you probably can come up with other uses within your own organization. the technology described here is potentially the basis for a whole array of new possibilities. you can get a step-by-step guide to building your own sample integration.oratransplant. . He has more than 12 years of experience with Oracle tools. Go to www. and is a member of Oracle's Customer Advisory Board for Development Tools. He runs an Oracle-related Weblog. As you can see. and get sample applications. you can reuse the existing Oracle Forms form to edit a purchase order in the BPEL human task.

Sign up to vote on this title
UsefulNot useful