Deploying a 10.1.2 UIX Application to a 10.1.3.x OC4J Instance

A developer's guide for deploying existing 10.1.2 UIX applications to 10.1.3 versions of OC4J


Written by Ric Smith, Oracle Corporation
10.1.3.x August, 2006

Introduction

10.1.2 UIX applications are certified to run on 10.1.3 application servers. The following how-to demonstrates the steps necessary configure a 10.1.3 application server to run UIX applications along side 10.1.3 ADF applications. For those customers running both 10.1.2 and 10.1.3 instance of the application server, this will allow you to consolidate your 10.1.2 UIX applications and 10.1.3 ADF applications to run on a single version of the application server. You can view the certification matrix on OTN for further information regarding other runtime environments certified to run ADF and/or UIX applications. The ADF UIX roadmap is also a valuable resource, outlining guidelines for future UIX ADF Development.

Configuring OC4J 10.1.3

Copy Jar files

To configure a 10.1.3 OC4J instance to run a UIX application you need access to the <JDEV_HOME>/BC4J/lib directory within a 10.1.2 JDeveloper install. You can download a copy of JDeveloper 10.1.2 from the OTN product download page . Under your 10.1.3 application server home, locate the <ORACLE_HOME>/BC4J/lib directory and create a subdirectory named 1012. You should now have a directory structure on the machine hosting your 10.1.3 application server that resembles the following: <ORACLE_HOME>/BC4J/lib/1012. The 1012 directory will be used to store the jar files you will copy from your 10.1.2 JDeveloper install. These jar files will be used to create a shared library for UIX applications running on your 10.1.3 application server. Copy the jar files listed below from the <JDEV_HOME>/BC4J/lib directory of your 10.1.2 install to the <ORACLE_HOME>/BC4J/lib/1012 directory that you created on your 10.1.3 application server.

  • adfm.jar
  • adfmtl.jar
  • adfmweb.jar
  • bc4jct.jar
  • bc4jctejb.jar
  • bc4jdomorcl.jar
  • bc4jimdomains.jar
  • bc4jmt.jar
  • bc4jmtejb.jar
  • collections.jar
Next, under the <ORACLE_HOME>/BC4J/jlib of your 10.1.3 application server install create a 1012 subdirectory, such that the final directory structure appears as follows: <ORACLE_HOME>/BC4J/jlib/1012. From your 10.1.2 <JDEV_HOME>/BC4J/lib directory copy the bc4jhtml.jar file to the <ORACLE_HOME>/BC4J/jlib/1012 directory on your 10.1.3 application server. From your 10.1.2 BC4J/lib directory, copy the adfmtl.jar to the <ORACLE_HOME>/BC4J/jlib/1012 directory on your 10.1.3 application server.

Edit server.xml

Locate the server.xml file in your 10.1.3 application server install under <ORACLE_HOME>/j2ee/home/config. Add the following shared library definition to the server.xml file, replacing all occurrences of <ORACLE_HOME> with the actual path to your 10.1.3 install (e.g. /apps/oracle/products/10.1.3/infra). The XML fragment below defines a global shared library that you will reference from your orion-application.xml file in your UIX application.

   <shared-library name="adf.oracle.10.1.2.lib" version="10.1.2" library-compatible="true">
       <code-source path="<ORACLE_HOME>/BC4J/lib/1012"/>
       <code-source path="<ORACLE_HOME>/jlib/share.jar"/>
       <code-source path="<ORACLE_HOME>/jlib/regexp.jar"/>
       <code-source path="<ORACLE_HOME>/ord/jlib/ordim.jar"/>
       <code-source path="<ORACLE_HOME>/ord/jlib/ordhttp.jar"/>
       <code-source path="<ORACLE_HOME>/jlib/ojmisc.jar"/>
       <code-source path="<ORACLE_HOME>/jlib/jdev-cm.jar"/>
       <code-source path="<ORACLE_HOME>/lib/xsqlserializers.jar"/>
       <import-shared-library name="oracle.xml"/>
       <import-shared-library name="oracle.jdbc"/>
       <import-shared-library name="oracle.gdk"/>
       <import-shared-library name="oracle.cache"/>
       <import-shared-library name="oracle.dms"/>
       <import-shared-library name="oracle.sqlj"/>
       <import-shared-library name="oracle.toplink"/>
       <import-shared-library name="oracle.http.client"/>
       <import-shared-library name="oracle.xml.security"/>
       <import-shared-library name="oracle.expression-evaluator"/>
   </shared-library>

Deploying from JDeveloper 10.1.2

ADF Toy Store Demo

To demonstrate the deployment process let's use a robust UIX application, ADF Toy Store, as a concrete example. You can download the application from here (2.4MB) and the instructions for setting up the demo within JDeveloper 10.1.2 can be found here.

Modifying an orion-application.xml descriptor

To deploy the Toy Store to a 10.1.3 OC4J instance you need to modify the orion-application.xml descriptor. Typically, when generating an ear file from JDeveloper this descriptor is created for you and the default file does not need to be altered for most deployments. However, to deploy to a UIX application to a 10.1.3 OC4J instance a modification must be made that adds a reference to the shared library that you created earlier and removes the ADF 10.1.3 libraries from the classpath of the UIX application. Note, the ADF Toy Store Demo already contains an orion-application.xml. The following section will show you how to modify this file and add the META-INF directory containing the file to the deployment profile. These procedures should translate to your current application deployment. For more information on creating deployment profiles for J2EE applications in JDeveloper 10.1.2, consult the JDeveloper online documentation.

Once you have configured the Toy Store Demo, open JDeveloper 10.1.2 and choose Open from the File menu. Navigate to <Project directory>\adftoystore\META-INF in the Open dialog and choose the orion-application.xml file, then click Open.

Add the following XML fragment to the orion-application.xml file, directly above the data-sources tag.

      <imported-shared-libraries>
         <import-shared-library name="adf.oracle.10.1.2.lib"/>
         <remove-inherited name="adf.oracle.domain"/>
      </imported-shared-libraries>

Your orion-application.xml file should now contain the following:

     <?xml version = '1.0' encoding = 'windows-1252'?>
     <!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd">
     <orion-application>
        <imported-shared-libraries>
        <import-shared-library name="adf.oracle.10.1.2.lib"/>
        <remove-inherited name="adf.oracle.domain"/>
        </imported-shared-libraries>
        <data-sources path="./data-sources.xml"/>
     </orion-application>

Modifying the deployment profile

Next, you must add the META-INF directory that contains the orion-application.xml to the deployment profile so that it is deployed to the 10.1.3 application server. To do so, double click the ADFToyStore.deploy profile located under the resources node in the ToyStoreViewController project from within the Application Navigator tab.

Click the File Groups node in the left most region of the War Deployment Profile Properties dialog and click New.

In the Create File Group dialog, name the file group you intend to create META-INF and choose Packaging for the Type of file group. Then, click OK.

Add the META-INF directory under your adftoystore project directory as a contributor to the file group you just created. Click Contributors under the META-INF file group, remove all default values and click Add. In the Add Contributor dialog, click Browse and select <Project directory>\adftoystore\META-INF in the file system navigator.

Finally, close the War Deployment Profile Properties dialog by clicking OK. Your deployment profile now includes the custom orion-application.xml file you created earlier.

Deploying to 10.1.3

To deploy your UIX application to a 10.1.3 application server you must create an ear file using JDeveloper and deploy the file to the OC4J instance using the Application Server Control. To generate the ear file, right-click the ADFToyStore.deploy profile in the application navigator of your JDeveloper 10.1.2 install and choose Deploy to Ear file from the context menu. An ADFToyStore.ear file will be created in the <Project directory>\adftoystore\deploy directory. Note: Deployment directly from JDeveloper 10.1.2 to the 10.1.3 application server is not supported.

Deploy the ear file to the 10.1.3 OC4J instance by using the Application Server Control by opening http://<server name>:<port>/em in a web browser. After logging into the administration console, click the Applications tab and click Deploy. In Step 1 of 3, choose the Archive is present on local host. Upload the archive to the server where Application Server Control is running radio button. Click Browse and use the file system navigator to select the ear file in the <Project directory>\adftoystore\deploy directory.

Then, click Next. In Step 2 of 3, set the Application Name to ADFToyStore, accept all defaults, and click Next.

Accept all of the defaults in Step 3 of 3 and click Deploy. After the deployment completes click Return and you will be forward back to the main screen of the Application Server Control. The ADFToyStore application should have a green arrow (  ) under the status column.

Test the application by accessing the following url via a web browser: http://<server name>:<port>/ADFToyStore.

Summary

Configuring and deploying a UIX application to a 10.1.3 application server can be accomplished with relative ease. Thus, 10.1.2 and 10.1.3 ADF applications can now coexist in harmony on your 10.1.3 application server.

 
false ,,,,,,,,,,,,,,,