This chapter describes how to run ADF Swing applications with Java Web Start in JDeveloper. Java Web Start is a tool for deploying the ADF Swing application to a web server from which users can download and run the application on their client machines.
This chapter contains the following sections:
Section 11.2, "How to Define ADF Business Components Runtime Properties"
Section 11.3, "How to Set Up Runtime Configuration Information"
Section 11.4, "How to Create a Java Web Start JNLP Definition"
Section 11.5, "What Happens When You Create a JNLP Definition"
Section 11.6, "How to Run ADF Swing Applications with Java Web Start in JDeveloper"
Java Web Start is an application deployment software that lets you maintain ADF Swing applications on the web server. Once deployed, users can use Java Web Start to download the application to run on their client machines. Before you deploy your ADF Swing application or applet to the web server, you can simulate the user's experience of running the application with Java Web Start within JDeveloper and Integrated WebLogic Server. Then you can use JDeveloper's Java EE web deployment process to move the entire production application to the web server.
Java Web Start is an application deployment technology. JDeveloper supports the creation of the XML-based JNLP (Java Network Launching Protocol) definition upon which the Java Web Start technology is based. With Java Web Start and the Create Java Web Start File dialog in JDeveloper, you can set up ADF Swing applications and applets to be maintained on the web server, but to be downloaded and run on client machines.
To launch ADF Swing applications with Java Web Start in JDeveloper, you must download and install the Java Web Start software at this web site http://www.oracle.com/technetwork/java/javase/tech/index-jsp-136112.html. Users of your ADF Swing application will also be required to install the software on their machines.
Unlike the applet approach to deploying web-centric Java applications, Java Web Start does not rely on the web browser to perform the downloading of the application JAR files. Instead, Java Web Start downloads the application resources after the Java Web Start JNLP descriptor is downloaded through the web browser. The JNLP descriptor causes Java Web Start to launch and perform the actual downloading.
The technologies involved are:
Web server -- stores the JNLP-enabled JSP files, JAR files for client, middle tier, and runtime libraries.
Application server (optional) -- needed only if the middle tier runs remotely with respect to client. For example, in the case of EJB session beans.
Web browser (optional) -- downloads JSP page, which launches Java Web Start. Java Web Start then downloads the dependent resources and launches the application or applet. Java Web Start can also run independently without the browser, using a command like:
javaws http://localhost/myapp/test.jnlp
Web browser --- optional, but convenient to launch Java Web Start and initiate the download. Used when an HTML file contains a link to the JNLP-enabled JSP page. The user follows the link, which behind the scenes causes Java Web Start to run.
With the Java Web Start software installed once on the user's machine, individual users can run ADF Swing applications and applets simply by clicking on a web page link (the appropriate files are generated by the ADF Swing dialog). Once the application is running, the web browser can be closed, and the application continues to function.
If the application is not present on their computer, Java Web Start automatically downloads all necessary files from the web server where the application libraries reside. It then caches the files on the client computer so the application is always ready to be relaunched anytime either from an icon on your desktop or from the browser link. The most current version of the application is always presented to the user since Java Web Start performs updates as needed.
JDeveloper provides Integrated WebLogic Server. You can use it to simulate the process of deploying the Web Application Archive and downloading for use with Java Web Start. JDeveloper follows the Java EE deployment profile conventions for archiving components that run on the client machine (simple archive) and components that are deployed to the web server (Web Application Archive).
After you complete the Create Java Web Start File dialog, you need to run the Ant build file ctbuild.xml to complete the JDeveloper setup and sign the JAR files.
Note:
You will not be required to deploy the generated client_war.deploy profile to use Integrated WebLogic Server. JDeveloper provides a default web.xml definition to locate the contents of the public_html directory in your JDeveloper mywork folder.
Once you have signed your JAR files, you can launch the Java Web Start software in JDeveloper using the generated.jsp file. Java Web Start downloads the components identified by the .jnlp file. Another definition in the .jnlp file determines whether the ADF Swing is to run as an application or a secure applet. Once you have launched Java Web Start and the downloading is complete, you can close your web browser and continue to run the application or applet.
When you are ready to deploy to the Oracle WebLogic Server, you must set up the context roots for the various runtime libraries required by the ADF Swing application using the previously generated ctbuild.xml archive file. These libraries are required to run the application and they have to be accessible through HTTP. (One context root, for example, is bc4j and this enables the bc4jmt.jar file to be downloaded as http://mymachine:8888/bc4j/lib/bc4jmt.jar).
To deploy an ADF Swing application to the Oracle WebLogic Server you use the generated client_war.deploy file to set up classes.
When you run ADF Swing forms to access the model layer, your data model project for ADF Business Components must contain a runtime configuration (bc4j.xcfg) file that specifies the application module connection for your deployment scenario.
When you want to run your ADF Swing application within JDeveloper, the application will use the default local configuration.
Later, you can edit the runtime configuration to update the connection information when you change or create a new ADF Business Components deployment scenario.
Note:
If you do not create an application module runtime configuration, the bc4j.xcfg file in your data model project defines a default configuration that lets you run ADF Swing forms within JDeveloper. The default configuration local is also called local mode deployment because it assumes the business components and the ADF Swing application run in the same VM.
In the Applications window, expand the model package in the Application Sources folder for the data model project and double-click the application module node.
In the overview editor, click the Configurations navigation tab and click Create new configuration object.
In the Edit Configuration dialog, click the Application Module tab and choose the middle-tier server type and a previously defined connection.
Click Help for further details.
In the Applications window, expand the model package in the Application Sources folder for the data model project and double-click the application module node.
In the overview editor, click the Configurations navigation tab and then select the configuration to edit from the list and click Edit.
In the Edit Configuration dialog, click the Application Module tab and choose the middle-tier server type and a previously defined connection.
Click Help for further details.
If you changed the deployment platform specified by the configuration file by choosing a different Middle Tier Server Type option in the Edit Configuration dialog, then you must update the data model project to add the libraries for the new platform:
Create a deployment archive for your data model project.
In the Applications window, expand the deployment archive folder.
To update the libraries, choose Deploy to projectname.jar on the Common and Middle Tier archives.
Note:
Configurations are accessed through the ADF data control for the application module, but the configuration information is recorded in the bc4j.xcfg file. This file is hidden in the Applications window and visible by right-clicking the application module and choosing Configurations.
When you want to refer to the new configuration in your user interface project, you must edit the DataBindings.cpx file.
To reference a data model configuration in the ADF Swing client:
Locate the DataBindings.cpx node in the user interface project folder.
Select the DataBindings.cpx node and display the Structure window.
In the Structure window, expand the dataControlUsages node and select the AppModuleDataControl node.
In the Properties window, expand the Other section and select the desired configuration from Configuration field dropdown list.
Before you use can run an ADF Swing application, you must set up runtime configuration information for your application. Your application needs these files to determine a runtime configuration:
An ADF Business Components configuration file (bc4j.xcfg) in your data model project that specifies the application module connection and deployment scenario for the business components.
A client data model definition file (DataBindings.cpx) in your user interface project that specifies the application module and ADF Business Components runtime configuration your ADF Swing forms will use.
There are two ways to use the runtime information:
When you want to test your ADF Swing application in JDeveloper
When you want to deploy your ADF Swing application for production
You will want to create a separate ADF Business Components configuration and client data model definition for each case.
To set up runtime configuration information for ADF Swing applications:
Create the ADF Business Components runtime configuration (in the bc4j.xcfg file) that specifies the application module connection and deployment scenario for the business components.
For more information, see Section 11.2, "How to Define ADF Business Components Runtime Properties."
Create an ADF Swing data model definition that specifies the application module and business component runtime configuration your ADF Swing forms will use.
For more information, see Section 2.6, "How to Create a Client Data Model Definition."
Run a ADF Swing wizard to generate ADF Swing forms or data panels.
In the Data Model page of the wizard, select the previously created client data model definition.
For more information, see Section 2.1.1, "ADF Swing Design Time Wizards."
Note:
You can also click New to create a data model definition based on another application module and runtime configuration that you select.
You use the Create Java Web Start File dialog to create a JSP page that the user conveniently runs from their web browser to dynamically generate the JNLP definition. Users launch the JNLP file to initiate downloading of the application to their client machine.
Note:
Before you can use the Create Java Web Start File dialog, you must set up runtime configuration information for your application. During development, use the default local mode deployment configuration to avoid potential security conflicts that occur in the remote deployment scenario.
For more information, see Section 11.3, "How to Set Up Runtime Configuration Information."
To create the JNLP definition for your application or applet:
In the Applications window, right-click the ADF Swing user interface project for which you want to generate a JNLP definition and choose New > From Gallery.
In the New Gallery, expand Client Tier, select ADF Swing, and then Java Web Start (JNLP) Files for ADF Swing, and click OK.
In the Create Java Web Start File dialog, specify the properties of the JNLP file and click OK.
Note:
If you are planning to run the ADF Swing application using EJB as the business service, then you must replace the weblogic.jar reference in the JNLP definition with wlclient.jar instead. Edit the JNLP definition in the files described below to make this substitution. If you attempt to run the ADF Swing application with the downloaded weblogic.jar file, you may see the oracle.jbo.JboException: JBO-29000: STRINGMANAGER: Message file: 'oracle.jbo.CSMessageBundle' not found. exception.
Your ADF Swing user interface project contains:
webstart.jsp -- dynamically generate the JNLP file that describes the client and ADF Business Components archive files and whether the ADF Swing is an applet or an application.
webstartmt.jsp -- an extension to the first .jsp file. Dynamically generates the JNLP file that describes the ADF Business Components runtime libraries required for a specific deployment scenario.
ctbuild.xml file -- an Ant-based makefile that helps you to create signed archive files for the client side and the ADF Business Components middle-tier classes.
client_war.deploy file -- use to generate the WAR file deployment profile.
web.xml file -- defines the deployment descriptors for the project files.
webstart.html file -- use to launch your application using Java Web Start.
If you want to require authentication of JAR files for added security when deploying your application to Oracle WebLogic Server, open a command prompt window and create the certificate:
keytool -export -alias yourkeyname -file mykey.cert
where yourkeyname is the name of the key that you will use to sign the JAR.
For more information about the Key and Certificate Management Tool, see http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html.
You are now ready to create the Web Archive before running the ADF Swing application. For more information, see "How to Create an ADF Swing Web Archive for Java Web Start" in Developing Applications with Oracle JDeveloper.
To support downloading of files from the web server through Java Web Start, the Create Java Web Start File dialog generates:
ctbuild.xml Ant build file -- use the build file to generate these application resources:
client.jar -- contains the ADF Swing application source files
mymt.jar -- contains the ADF Business Components source files
client_war.deploy profile -- use to deploy the contents of the public_html directory in your JDeveloper mywork folder. It therefore contains the client.jar, mymt.jar, and either a static JNLP file or JSP files.
Additionally, the JNLP definition is generated dynamically through a .jsp file:
webstart.jsp -- lets you dynamically generate the JNLP file that describes the client and ADF Business Components archive files and whether the ADF Swing is an applet or an application.
webstartmt.jsp -- an extension to the first .jsp file. Dynamically generates the JNLP file that describes the ADF Business Components runtime libraries required for a specific deployment scenario.
Before you deploy your ADF Swing application or applet to a production web server, you can use Integrated WebLogic Server in JDeveloper to simulate the user's experience of running the application with the Java Web Start software.
Note:
You cannot debug a ADF Swing application in JDeveloper while running with Java Web Start.
You must create a deployment profile to set up Integrated WebLogic Server with your application libraries and JAR files. Java Web Start relies on the JNLP file that you generate to identify which files to download and how to launch the application. For more information, see Section 11.4, "How to Create a Java Web Start JNLP Definition."
Set up runtime configuration information for the business components deployment scenario you choose.
For more information, see Section 11.3, "How to Set Up Runtime Configuration Information."
Note:
Choose the default local runtime configuration when you just want to test the business components using local-mode deployment. This option uses the same VM to run the ADF Business Components and ADF Swing libraries.
Archive the application components using the ctbuild.xml Ant makefile generated by the ADF Swing Java Web Start wizard.
For more information, see "How to Create an ADF Swing Web Archive for Java Web Start" in Developing Applications with Oracle JDeveloper.
Note:
The build file generates two signed archive files in your project's public_html directory: client.jar and mymt.jar.
To run the ADF Swing application using Java Web Start:
Install the Java Web Start software on your machine.
In your user interface project, right-click the local.html file and choose Run local.html to launch your web browser with this page.
Click the Launch ADF Swing Project link to run your application using the Java Web Start software.
You can close your browser once Java Web Start completes the download and launches the application. Java Web Start lets you run both applications and secure applets.
The next time you run the application, Java Web Start will download only those source files or libraries that have changed from the previous download.
Note:
If you attempt to run the ADF Swing application and have created a JNLP definition for Oracle WebLogic Server deployment, using weblogic.jar, you may see the oracle.jbo.JboException: JBO-29000: STRINGMANAGER: Message file: 'oracle.jbo.CSMessageBundle' not found. exception. This exception occurs when running Java Web Start on Oracle WebLogic Server with EJB as the business service. You must replace the weblogic.jar reference in the JNLP definition with wlclient.jar instead. You can edit the JNLP definition to make this substitution.