Deploying ADF JClient Applications Built on TopLink or EJB to Java Web Start

An Oracle JDeveloper How To Document
Written by Aminur Rashid and Ralph Gordon
October 2004

Content

      Prerequisites
      Introduction
      Create the JClient Application
      Prepare the Java Web Start Deployment Files
      Conclusion

Prerequisites

This document assumes the following:

  • That you have created a JDeveloper 10g workspace that contains a TopLink project. [ 2]
  • That you ran the keytool utility provided by the Java SDK to create a keystore and password. [ 3]
  • That you ran the create_jclient_ear.bat file to create the Enterprise Archive (EAR) file bc4jlibs.ear with signed JARs in the <JDeveloper Home>/BC4J/jlib directory. [ 3]
  • Optionally, that you deployed the bc4jlibs.ear file to the Oracle JDeveloper 10g embedded OC4J server (when you are ready to test outside of JDeveloper's embedded OC4J server). [ 3]
  • That the database schema used with the TopLink business service is the default "Scott" schema.

Introduction

Java Web Start is part of the Sun Microsystems J2SE 1.4 platform and provides a standard deployment solution for Java Swing–based applications. Java Web Start utilizes the Java Network Launching Protocol (JNLP) technology, a web-centric protocol for provisioning and running J2SE-based applications. It provides the benefits of client-side software distribution, while permitting centralized software management. It’s an easy, robust, and secure way to deploy applications to the Internet and intranet.

The Oracle Application Development Framework (Oracle ADF) in Oracle JDeveloper 10g allows the Oracle ADF JClient developer to build applications based on business services like ADF Business Components, OracleAS TopLink, Enterprise Java Beans, Web Services, and others. The particular choice of business service to use with ADF JClient requires different setups when deploying the application to Java Web Start.

This document describes the process for deploying to Java Web Start when you want to create an Oracle ADF JClient application in Oracle JDeveloper 10g with either TopLink or Enterprise Java Beans as the business service layer. For a complete overview of ADF JClient and Java Web Start, please see the white paper “Deploying Oracle ADF JClient Applications with Java Web Start ” available on http://otn.oracle.com [ 3]

The first part of this document discusses deploying ADF JClient to Java Web Start, with OracleAS TopLink as a business service. The last part provides a brief description of how to achieve the same deployment using Enterprise Java Beans as the business service for ADF JClient applications.

Create the JClient Application

In order to make the TopLink business objects available to the JClient design time, you must create an Oracle ADF data control. Data controls can be accessed from the Data Control Palette [Ctrl+Shift+D] in the JDeveloper 10g IDE. If you are new to TopLink in JDeveloper, please refer to the TopLink tutorial [ 2] and learn how to make a TopLink project available as ADF data controls.

The following is a list of individual steps required to build a simple ADF JClient form on top of an TopLink data model:

  1. Create an empty project in the JDeveloper workspace containing the TopLink project.

  2. In TopLink project, right-click the bean node ( Xxx.java ) and choose Crea te Data Control .

  3. In TopLink project, right-click the TopLink Mappings node and choose G enerate toplink-deployment-descriptor.xml to create an empty JClient panel and name it Panel1.java.

  4. Create a new empty project in the same workspace for the JClient project.

  5. Right-click the JClient project node and choose New to create an empty JClient panel and name it Panel1.java.

  6. Drop a ScrollPane from the JDeveloper Component Palette [Ctrl+Shift+P] onto the panel.

  7. Open the Data Control Palette and drag and drop Table and Navigation Bar components bound to a return node of the desired bean. Compile the project and run the panel to test the application.

Prepare the Java Web Start Deployment Files

To deploy the ADF JClient application with TopLink business objects to Java Web Start, you must create signed JAR files for the client libraries. You will modify a generated ANT file for this purpose.

  1. Select the JClient project node and choose New from the right-click menu to open the New Gallery.

  2. In the New Gallery, in the Categories list, expand the General node, and select Ant. In the Items list, select Empty Buildfile. Click OK.

    If you don't see the option Ant under General category, change the Filter By selection box to show All Technologies.

  3. You must edit the created ANT file build.xml to create and sign the application archive (JAR) files. As an example, the build file may look as follows, with the text in bold indicating the lines that need hand editing:

                                       
                                      
    <project  
                                      
    name="
                                      
    myproject"  
                                      
    basedir="."  
                                      
    default="jar">
      
                                      
    
     <!--CHANGE THESE SIGNING PROPERTIES: the values should match the key and password that
                                        
    you created using the keytool utility. For a detailed explanation, see the Java Web
    Start deployment Whitepaper on OTN [
    3]--> <property name="alias" value=" mykey"/> <property name="storepass" value=" welcome"/> <!--CHANGE THE VALUE TO YOUR JDEVELOPER HOME--> <property name="jdevhome.dir" value=" /D:/deliver"/> <!--CHANGE THE VALUE TO YOUR PROJECTS. 1)Client project (e.g ..../TopLinkWebStart/Project2)
    and 2) TopLink project(e.g..../TopLinkWebStart/Project1) --> <property name="ct.proj.dir" value=" /D:/deliver/jdev/mywork/TopLinkWebStart/Project2"/> <property name="mt.proj.dir" value=" /D:/deliver/jdev/mywork/TopLinkWebStart/Project1"/> <!--classes dir for mt and ct--> <property name="ct.classes.dir" value="${ct.proj.dir}/classes"/> <property name="mt.classes.dir" value="${mt.proj.dir}/classes"/> <!-- jar names for the client and middle tier classes--> <property name="ct.jar.name" value="${ct.proj.dir}/public_html/client.jar"/> <property name="mt.jar.name" value="${ct.proj.dir}/public_html/mymt.zip"/> <target name="init"> <mkdir dir="${ct.proj.dir}/public_html"/> </target> <target name="jar" depends="init"> <jar jarfile="${ct.jar.name}"> <fileset dir="${ct.classes.dir}"> <patternset> <exclude name=".jsps/**/*"/> <exclude name="connections.xml"/> </patternset> </fileset> </jar> <jar jarfile="${mt.jar.name}"> <fileset dir="${mt.classes.dir}"> <patternset> <exclude name="connections.xml"/> <include name="**/*"/> </patternset> </fileset> </jar>
    <!--Will copy TopLink JAR files--> <copy todir="${ct.proj.dir}/public_html"> <fileset dir="${jdevhome.dir}/toplink/jlib/"> <include name="toplink.jar"/> </fileset> <fileset dir="${jdevhome.dir}/BC4J/lib/"> <include name="adfmtl.jar"/>
    </fileset> </copy> </target> <target name="sign" depends="jar"> <signjar jar="${mt.jar.name}" alias="${alias}" storepass="${storepass}"/> <signjar jar="${ct.jar.name}" alias="${alias}" storepass="${storepass}"/> <signjar jar="${ct.proj.dir}/public_html/toplink.jar" alias="${alias}" storepass="${storepass}"/> <signjar jar="${ct.proj.dir}/public_html/adfmtl.jar" alias="${alias}" storepass="${storepass}"/> </target> <target name="clean"> <delete file="${mt.jar.name}"/> <delete file="${ct.jar.name}"/> </target> </project>
  4. Once created, select build.xml in the Application Navigator and choose Build Target and sign from the right-click menu. ADF JClient requires all client-side files to be signed.

Before the user can run the deployed ADF JClient application, you must create a JSP file that will dynamically create the Java Web Start Java Network Launching Protocol (JNLP) file and start Java Web Start on the client. The JNLP file will reside in the src folder of your JClient project.

  1. Select the JClient project node and choose New from the right-click menu to open the New Gallery.

  2. In the New Gallery, in the Categories list, expand the Web Tier node, and select JavaServer Pages (JSP). In the Items list, select JSP Page. Click OK.

    If you don't see the category Web Tier, change the Filter By selection box to show All Technologies.

  3. To follow the example in this document, name the JSP file webstartLocal.jsp.

  4. Add the following code base for the JNLP file to the new JSP page:

      
                                      
    <%@  
                                      
    page   
                                      
    contentType  
                                      
    ="application/x-java-jnlp-file;charset=windows-1252" %>
      
                                      
    <%!
         String getContextRoot(String uri, String servletPath)
         {
            
                                      
    int index = uri.indexOf(servletPath);
            
                                      
    if ( index != -1)
            {
               
                                      
    return uri.substring(0,index);
            }
               
                                      
    return  
                                      
    "";
         }
      
                                      
    %>
    
     <%
            
               
                                      
    //   build code base for JNLP tag
              StringBuffer buf  =  
                                      
    new StringBuffer();
              buf.append(  
                                      
    "http://");
              buf.append(request.getServerName());
    
               
                                      
    int DEFAULT_PORT = 80;
               
                                      
    if (request.getServerPort() != DEFAULT_PORT) 
              {
                      buf.append(':');
                      buf.append(request.getServerPort());
              }
              buf.append(getContextRoot(request.getRequestURI(),request.getServletPath()));
      
                                      
    %>
                                    
  5. Edit the JSP source code as follows and enter the <jnlp> tag:

                                       
    <?xml  
                                        
    version=
                                        
    "1.0"   
                                        
    encoding=
                                        
    "windows-1252"?>
    <jnlp  
                                        
    spec=
                                        
    "1.0"  
                                        
    codebase =
                                        
    "<%= buf.toString() %> ">
                                      
                                    
  6. Provide the <information> and <security> tags for the JNLP file:

        
                                      
    <information>
           
                                      
    <title>TopLink Web Start Project
                                      
    </title>
           
                                      
    <vendor>Oracle Corporation
                                      
    </vendor>
           
                                      
    <description>First TopLink Java Web Start Project
                                      
    </description>
        
                                      
    </information>
        
                                      
    <security>
           
                                      
    <all-permissions/>
        
                                      
    </security>
                                    
  7. Add entries for required libraries (JAR) to the JNLP file. TopLink libraries can be added by including the following lines in the JSP source code:

                                       
       <resources>  
           <j2se  
                                      
    version="1.3+"/>
        
                                      
       <jar  
                                      
    href="client.jar"/>
        
                                      
      <!-- Entries added to include TopLink JAR files -->
                                        
    <jar href="mymt.zip" /> <jar href="toplink.jar" /> <jar href="adfmtl.jar" />
  8. Create a reference to the extension descriptors, which we will create in the next step. An extension descriptor typically describes a component that must be used in order to run the application:

                                       
        
                                      
      <!-- You will create the file localmt.jarp in the following steps. -->
                                      
    <extension name="common" href = "localmt.jsp" /> </resources>
  9. Create a reference to the application main class and edit the value (shown in bold) to supply the package name:

                                       
      <!-- CHANGE TO SUPPLY THE CLASS PACKAGE NAME. For example, "mypackage2.JPanel2" -->  
       
                                      
    <application-desc  
                                      
    main-class="
                                      
    your_package.your_main_class"/>
    </jnlp>
                                    
  10. Using the New Gallery, create a new JSP file and name it localmt.jsp to match the name of the extension descriptor mentioned in the JNLP file (this saves you from having to change the JSP name reference in the JNLP file). Edit the JSP file and delete the default content generated by JDeveloper. Copy the following lines from webstartLocal.jsp to the top of the new JSP file:

                                       
    <%@  
                                      
    page   
                                      
    contentType  
                                      
    ="application/x-java-jnlp-file;charset=windows-1252" %>
                                       
    <%!
             String getContextRoot(String uri, String servletPath)
            {
             
                                      
    int index = uri.indexOf(servletPath);
             
                                      
    if ( index != -1)
            {
                     
                                      
    return uri.substring(0,index);
            }
              
                                      
    return  
                                      
    "";
            }
                                       
    %>
    
    <%
            
             
                                      
    //   build code base for JNLP tag
            StringBuffer buf  =  
                                      
    new StringBuffer();
            buf.append(  
                                      
    "http://");
            buf.append(request.getServerName());
    
             
                                      
    int DEFAULT_PORT = 80;
             
                                      
    if (request.getServerPort() != DEFAULT_PORT) 
            {
                    buf.append(':');
                    buf.append(request.getServerPort());
            }
            buf.append(getContextRoot(request.getRequestURI(),request.getServletPath()));
                                       
    %>
    
    
      
                                      
                                      
    <?xml  
                                        
    version=
                                        
    "1.0"   
                                        
    encoding=
                                        
    "windows-1252"?>
     <jnlp  
                                        
    spec=
                                        
    "1.0"  
                                        
    codebase =
                                        
    "<%= buf.toString() %> ">
                                      
         
                                      
                                         
    <information>
           
                                        
    <title>TopLink Web Start Project
                                        
    </title>
           
                                        
    <vendor>Oracle Corporation
                                        
    </vendor>
           
                                        
    <description>First TopLink Java Web Start Project
                                        
    </description>
      
                                        
      </information>
      
                                        
      <security>
           
                                        
    <all-permissions/>
         
                                        
    </security>
                                      
                                    
  11. Add the <resources> and <component-desc> tags and close the <jnlp> tag. Inside the <resources> tag add the libraries required to run a TopLink project:

         
                                      
    <resources>
             
                                      
    <j2se  
                                      
    version="1.3+"/>
             
                                      
    <jar  
                                      
    href="/BC4J/jlib/adfjclient.jar" />
             
                                      
    <jar  
                                      
    href="/BC4J/lib/adfm.jar" />
             
                                      
    <jar  
                                      
    href="/BC4J/lib/bc4jct.jar" />
             
                                      
    <jar  
                                      
    href="/BC4J/lib/bc4jdomorcl.jar" />
             
                                      
    <jar  
                                      
    href="/BC4J/lib/bc4jmt.jar" />
             
                                      
    <jar  
                                      
    href="/BC4J/lib/collections.jar" />
             
                                      
    <jar  
                                      
    href="/sqlj/lib/runtime12.jar"/>
             
                                      
    <jar  
                                      
    href="/jdbc/lib/classes12.jar" />
             
                                      
    <jar  
                                      
    href="/jdev/lib/jdev-rt.jar" />
             
                                      
    <jar  
                                      
    href="/lib/xmlparserv2.jar" />
         
                                      
    </resources>
         
                                      
    <component-desc/>
      
                                      
    </jnlp>
                                    

To run the webstartLocal.jsp from Oracle JDeveloper, choose Run from the right-click menu. This will start the JClient application with Java Web Start.

Note: If your default browser is Internet Explorer, the browser may prompt you to download the JSP rather than run it. This is a known issue with Internet Explorer version 6 and earlier. To address this problem, you can create a static JNLP file or you may set JDeveloper tool's preferences to launch another browser. The JClient Java Web Start Wizard lets you generate static JNLP files that you can modify to include the JNLP definitions as shown in the previous steps.

Web Start Support for Application built on EJB

The deployment scenario for ADF JClient with Enterprise Java Bean business objects is similar to the TopLink example explained above.

  1. The following JAR files, already included in the bc4jlibs.ear file, need to be referenced in the Java Web Start JNLP file:

                                       
      <resources>
                     
                                      
    <j2se  
                                      
    version="1.3+"/>
                     
                                      
    <jar  
                                      
    href="/j2ee/home/lib/ejb.jar" />
                     
                                      
    <jar  
                                      
    href="/j2ee/home/lib/jmxri.jar" />
                     
                                      
    <jar  
                                      
    href="/j2ee/home/oc4jclient.jar" />
                     
                                      
    <jar  
                                      
    href="/j2ee/home/lib/jms.jar" />
                     
                                      
    <jar  
                                      
    href="/j2ee/home/lib/jta.jar" />
                     
                                      
    <jar  
                                      
    href="/diagnostics/lib/ojdl.jar" />
                     
                                      
    <jar  
                                      
    href="/j2ee/home/lib/servlet.jar" />
      
                                      
     </resources>
                                    
  2. An additional JAR file adfmejb.jar, which is not part of bc4jlibs.ear, needs to be added. The adfmejb.jar file can be added through an entry in the ANT build file build.xml:

                                       
    <copy  
                                      
    todir="${ct.proj.dir}/public_html">
             
                                      
    <fileset  
                                      
    dir="${jdevhome.dir}/BC4J/jlib/">
                     
                                      
    <include  
                                      
    name="adfmejb.jar"/>
             
                                      
    </fileset>
                                       
    </copy>
                                    
  3. To make sure the file gets signed, add the following tag element to the same build file:

    <signjar jar="${ct.proj.dir}/public_html/adfmejb.jar" alias="${alias}" storepass="${storepass}"/>

  4. Reference the adfmejb.jar file in the the dynamically created JNLP file by adding the following line to the localmt.jsp file:

    <jar href="adfmejb.jar" />

  5. Create a file jndi.properties in the src folder of your ADF JClient project and add it to the JDeveloper project tree. Adding the jndi.properties file to the project ensures that it gets deployed with your compiled application classes.

The jndi.properties file contains environment settings for the Java Naming and Directory Interface (JNDI) server used to access the EJB business objects. ADF JClient uses the information of the jndi.properties file to establish an intial context to the JNDI server. The jndi.properties file, used to store the property settings, will externalize the JNDI provider–specific information, allowing you to change the JNDI provider without having to change the application code.

A sample jndi.properties file for Oracle Containers for J2EE (OC4J) looks like the following :

     
                              
java.naming.provider.url=ormi://hostName/EJBContextRoot
     
                              
java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory
     
                              
java.naming.security.principal=userName(e.g system)
     
                              
java.naming.security.credentials=password(e.g welcome)
                            

Conclusion

Although JDeveloper 10g does not provide a wizard to create Java Web Start deployment profiles for business service projects other than ADF Business Components, it is possible to manually create deployment profiles for TopLink and Enterprise Java Beans business service projects.

References

[1] http://otn.oracle.com/software/products/jdev/index.html

[2] http://otn.oracle.com/products/jdev/collateral/tutorials/9050/toplinkdatabinding_tut.html

[3] Deploying Oracle ADF JClient Applications with Java Web Start

v1.0 October-2004

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