This document provides an example and procedure for how to deploy a Nexaweb Desktop Client Java application from a web server using Java Web Start.

Using Java Web Start to launch a Nexaweb Desktop Client application allows you to store the Nexaweb Desktop Client application on a different server from which users connect to download the application.

Nexaweb Desktop Client use with Java Web Start is known to work with JDKs 1.4-1.6.

Before using Nexaweb Desktop Client with Java Web Start, consider the following performance issues:

• Size of application determines how long application takes to download to client
• Network security related configurations can effect the amount of time it takes for application to download to client

Running an Application From Java Web Start

To begin understanding how to deploy a Nexaweb Desktop Client application using Java Web Start, we recommend you download and run the WebStart test application. This example uses Tomcat as the web server.

To run the application, follow these steps:

1. Copy the myCharts.war file into the tomcat\webapps directory.

2. Start Tomcat: Go to tomcat\bin and double click on startup.

3. Enter the following URL in the address bar of a Web Browser:
    http://localhost:8080/myCharts/NexawebWebStartDemo.jnlp.
    A Java Loading dialog appears indicating that the Java Web Start is loading.
    The Desktop Client Launch dialog appears, indicating that the Nexaweb Desktop Client launcher
    (in this example, NexawebWebStartLauncher.jar) is loading.

    A security warning dialog appears similar to the following:

 This warning appears as the Nexaweb Desktop Client application launcher copies the unsigned application JAR
 (NexawebWebStartDemo.jar) file onto the system.

4. Click Run.
    A Connected to Server dialog appears similar to the following:

This dialog indicates that the Nexaweb Desktop Client has server connectivity.

5. Click OK.
    A Client version was switched . . . dialog appears.
    Because the complete application has not yet downloaded from the server, this indicates that the current local
    desktop client application is not synchronized with the version on the server. You see this message the first time 
    you launch a desktop client application on a client system.

6. Click OK.
    The complete myChart desktop client application downloads from the server and the application starts 
    similar to the following:

After launching the program, notice the following:

• The JAR files for this application (NexawebWebStartDemo.jar, NexawebWebStartLauncher.jar), JNLP file, and configuration files (myCharts\WEB-INF\nexaweb-desktop-client.xml, manifest.mf) appear in the myCharts directory in the web server webapps directory.
• The unpacked Nexaweb Desktop Client application files appear in the NexawebDesktopClient directory that the launch application created on the local system.
• The launch application created Nexaweb Desktopclient desktop-short-cut and program start entries on the local system.

After the initial installation, you can start the application using the DesktopClient Launcher desktop short-cut or by selecting the the Nexaweb DesktopClient item from the Programs menu. When the application starts, it checks to see whether the system has network connectivity, and displays a dialog similar to the following:

Click OK and the application updates from the server, if necessary.  

Setting Up Java Web Start Launch

To deploy a Nexaweb Desktop Client application using Java Web Start, you need to do the following:

• Create a Java Network Launching Protocol (JNLP) file.
• Create a launch application for the Desktop Client environment and package it in a JAR file.
• Package the minimum Nexaweb Desktop Client application in a JAR file.

Creating a JNLP File

A JNLP file describes how to download and launch an application from a web server.

To deploy a Nexaweb Desktop Client application using Java Web Start, you must create a JNLP file with the minimal information specified in the following example of the JNLP file created for the myCharts application:

<jnlp spec="0.2 1.0"
     codebase=http://localhost:8080/myCharts
     href="NexawebWebStartDemo.jnlp">
    <information>
      <title>DesktopClient Launcher</title>
      <vendor>Nexaweb</vendor>
      <homepage href="http://www.nexaweb.com"/>
      <description>
         A demo application for Nexaweb Desktop Client
      </description>
      <description kind="short">
         Nexaweb Desktop Client short Description
      </description>
      <offline-allowed/>
     <shortcut>
         <desktop/>
         <menu submenu="Nexaweb Desktopclient"/>
     </shortcut>
    </information>
    <resources>
      <j2se version="1.3+" 
            href="http://java.sun.com/products/autodl/j2se"/>
      <j2se version="1.3+"/>
      <jar href="NexawebWebStartLauncher.jar" 
           main="true" download="eager"/>
    </resources> 
    <application-desc main-class="NexawebWebStartLauncher">
         <argument>http://localhost:8080/myCharts/</argument>
         <argument>NexawebWebStartDemo.jar</argument>
         <argument>c:/NexawebDesktopClient</argument>
         <argument>Applications/myCharts</argument>
    </application-desc>
    <security>
      <all-permissions>
    </security>
 </jnlp> 

The following table provides descriptions of the elements and attributes required in the JNLP XML file:
Note: For more information on these or other JNLP file elements, see http://java.sun.com/products/javawebstart/download-spec.html.

 To create a JNLP File, follow these steps:

1. Copy the JNLP file from the myCharts directory in your web servers webapps directory.

2. Open the JNLP file with an XML or text editor.

3. Specify values for your application in the elements included in the sample JNLP file.

4. Save the JNLP file with a name unique to your application.
 

Creating a Launch Application

You must create your own launch application to retrieve your Nexaweb Desktop Client application JAR files from the web server. Java Web Start calls the launch application when a user launches the application on a client. After creating the launch application, you must package it in a JAR file.

The launch application does the following:

• Locates Nexaweb Desktop Client application JAR files on the web server (in this example, NexawebWebStartDemo.jar)
• Retrieves and saves JAR files onto the client
• Unpacks the JAR files
• Finds main entries for the application JAR files
• Invokes main method to start Desktop Client application

You can view the code for the NexawebWebStartLauncher application in its entirety by opening the NexawebWebStartLauncher.class file in your web servers webapps directory \myCharts\NexawebWebStartLauncher.jar.

The launcher application must include the following line to release the system security manager: System.setSecurityManager(null)

Although this may pose a security threat, it is required in order to run a Nexaeb Desktop application launched with Java Web Start.

The following shows the main method for this application that invokes the Desktop Client application:

public static void main(String args[]) throws Exception { 

     NexawebWebStartLauncher nwsl = new NexawebWebStartLauncher
    (args[0].trim(), args[1].trim(), args[2].trim(), args[3].trim());

     System.setSecurityManager(null);

     if (!nwsl.launcherFileExists()){
           nwsl.createNexawebDesktopEnv();
           nwsl.unzipNexawebDesktopEnv();
     }
     nwsl.startNexawbApp();

}

Packaging the Nexaweb Desktop Java Client Application

To package the Nexaweb desktop client application, you must complete the following major steps:

• Edit the application web.xml file
• Test launch the application
• Package the minimum Nexaweb desktop client application in a JAR file
• Package the launcher application in a JAR file
• Sign the JAR files

Editing web.xml

You must edit the Desktop Client application's web.xml file so that the web server can receive JNLP and JAR file requests.

To edit the web.xml file, follow these steps:

1. Locate the Nexaweb Desktop Client Application's web.xml file under:
project-root/Webcontent/WEB-INF.

2. Double click on the file to open it.

3. Add the following mime-mapping elements to the file:

<mime-mapping>
   <extension>jar</extension>
   <mime-type>application/java-archive</mime-type>
 </mime-mapping>
 <mime-mapping>
   <extension>jnlp</extension>
   <mime-type>application/x-java-jnlp-file</mime-type>
 </mime-mapping>

4. Save and close the file. 

Test Launching the Application

Create a .bat file similar to the following in order to test that the Desktop Client Application launches on its own prior to packaging it:

java -classpath nexaweb-desktop-client-launcher.jar com.nexaweb.client.desktop.launcher.Launcher Applications/DesktopClient

After creating the .bat file, run it to test that the Desktop Client Application launches on its own.

Packaging

Java Web start is a secure sandbox; therefore, you must package the launcher application and the minimum Nexaweb desktop client application in JAR files. You must save all of the JAR files on the same server.

The minimum Nexaweb desktop client application requires the following:

• Nexaweb-desktop-client.xml file
• Version.txt file
• Desktop client directory struture

When you run a Nexaweb desktop client application in Nexaweb studio, Nexaweb Studio creates the required desktop directory structure similar to the following:

Add this directory structure to the minimum Nexaweb desktop client JAR file, so this directory structure exists on the local system when the server later downloads the rest of the application to the local system.

Signing JARs

 For local file system access, you must sign on the server-side all JAR files for your Desktop Client application.

To sign JAR files on the server-side:

1. Generate keys by enter the following command at a web server command prompt window:
     keytool -genkey -keystore nxWS.keys -alias http://www.nexaweb.com/ -validity 365

2. Sign NexawebWebStartLauncher.jar by enter the following command at a web server command prompt window:
     jarsigner -keystore nxWS.keys -storepass 123456789 NexawebWebStartLauncher.jar http://www.nexaweb.com/