•  Print this page
    Print this page

Java Web Start
 
 
With Java Web Start users can automatically download and launch rich desktop applications written to the Java 2 SE platform by only clicking on a link on a website. Besides downloading the application, Java Web Start also automatically download and install a revision of the J2SE platform if an application requests a version that is not installed on the client system.

The link on the website points to a special JNLP (Java Network Launching Protocol) launch file.

The application (for example a game) must be packaged in jar files and are created with the J2SE SDK. The jar files can contain native libraries and resource files such as images and properties files.

To make use of Java Web Start the following is required:
  • The client machine requires support for the Java Runtime Environment (JRE), version 1.2.2 or higher.
  • The Web server where the application is deployed must be configured with support for a new MIME type.
Java Web Start (JAWS) is available for Windows 98/NT/2000/ME/XP, Solaris, and Linux.

More information about Java Web Start can be found at:
http://java.sun.com/products/javawebstart/developers.html

Quick guides







Setup Java Web Start



Information
none

Operating system used
Windows XP Home Edition Version 5.1 SP 2

Software prerequisites
Java 2 Standard Edition (J2SE) SDK, version 1.2.2 or higher.

Procedure
  1. Configure your web server to support the application/x-java-jnlp-file MIME type.

    For example if you use the Apache web server add the following line in the
    ..\Apache Group\Apache2\conf\mime.types file:

    application/x-java-jnlp-file jnlp

  2. Before you can deploy your application on the web server you must package your application code into jar files. In this example my application is packaged into one jar file called bouncing.jar. The bouncing application is using the JOGL packages
    (jogl.jar, jogl-natives-solsparc.jar, jogl-natives-win32.jar, jogl-natives-macosx.jar,
    jogl-natives-linux.jar).

  3. If your application runs with all permissions, you must sign all of your jar files, or Web Start will refuse to run the program. In addition, all of the jar files must be signed using the same key, and every jar can only be signed once. In this example, the following jar files must be signed:

    bouncing.jar
    jogl.jar
    jogl-natives-solsparc.jar
    jogl-natives-win32.jar
    jogl-natives-macosx.jar
    jogl-natives-linux.jar

    Note: The "Bouncing of the Wall" (bouncing.jar) application has been created by following an excellent tutorial found at www.genedavissoftware.com.

  4. The jogl*.jar files are already signed. You need to "unsign" them first.
    To unsign a jar file, you need to do the following:

    • Create a temp directory and copy the signed jar file (for example jogl.jar) into this directory. For example:

      mkdir temp
      copy jogl.jar temp
      cd temp

    • Unjar the jar file using the following command:

      jar xvf jogl.jar

    • Delete the signed jar file.

      del jogl.jar

    • Delete the META-INF directory.

      rmdir /S /Q META-INF

    • Package the jar file using the following command:

      jar cvf jogl.jar .

    Note: To automate the above mentioned steps, dos batch scripts has been written to unsign jar files. Download the three files and read the "Usage text" found in start_unsign.bat.

    start_unsign.bat
    unsign_jar.bat
    signed_jars.txt

  5. To sign the jar files, the following must be done:

    Step 1: Create a keystore
    • Open a dos window and enter the following command:

      keytool -genkey -keystore myKeyStore -alias myAlias

      You should see and do the following:

      Enter keystore password: mysecret
      What is your first and last name?
         [Unknown]:  Robert Lie
      What is the name of your organizational unit?
         [Unknown]:  Research and Development
      What is the name of your organization?
         [Unknown]:  Mobilefish.com
      What is the name of your City or Locality?
         [Unknown]:  Zaandam
      What is the name of your State or Province?
         [Unknown]:  Noord-Holland
      What is the two-letter country code for this unit?
         [Unknown]:  NL
      Is CN=Robert Lie, OU=Unknown, O=Mobilefish.com, L=Zaandam,
      ST=Noord-Holland, C=NL correct?          [no]: yes

      Enter key password for <myAlias>
            (RETURN if same as keystore password):      [Press Enter button]

    • The file myKeyStore is created.

    • [OPTIONALLY] If you want to list the contents of the keystore, use this command:

      keytool -list -v -keystore myKeystore -storepass mysecret

      You should see the following:

      Keystore type: jks
      Keystore provider: SUN

      Your keystore contains 1 entry

      Alias name: myalias
      Creation date: 30-nov-2004
      Entry type: keyEntry
      Certificate chain length: 1
      Certificate[1]:
      Owner: CN=Robert Lie, OU=Research and Development, O=Mobilefish.com, L=Zaandam,
      ST=Noord-Holland,C=NL
      Issuer: CN=Robert Lie, OU=Research and Development, O=Mobilefish.com, L=Zaandam,
      ST=Noord-Holland, C=NL
      Serial number: 41acf44c
      Valid from: Nov 30 23:29:32 CET 2004 until: Mon Feb 28 23:29:32 CET 2005
      Certificate fingerprints:
         MD5: A0:86:55:57:6F:E8:21:59:A4:62:AA:80:F3:A6:5E:51
         SHA1: 01:A5:05:C7:F2:3E:E6:F1:17:B4:35:CB:2D:DE:00:2E:2C:FD:98:E9

      *******************************************
      *******************************************

    Step 2: Create a self-signed test certificate.
    • Open a dos window and enter the following command:

      keytool -selfcert -alias myAlias -keystore myKeyStore -storepass mysecret

    • [OPTIONALLY] If you want to store the myKeyStore file in CVS do not for get to check it in as a binary file!

      cvs add -kb -m"Demonstration KeyStore" myKeyStore

    Step 3: Sign the JAR file with the test certificate.
    • Open a dos window and enter the following command:

      jarsigner -keystore myKeyStore -storepass mysecret bouncing.jar myAlias

      The bouncing.jar file is now signed with the test certificate.

      The META-INF directory contains the files .SF and .DSA and the manifest files has been modified.

      In this example, do not forget to sign the following jar files
      (use the same jarsigner command):

      jogl.jar
      jogl-natives-solsparc.jar
      jogl-natives-win32.jar
      jogl-natives-macosx.jar
      jogl-natives-linux.jar

      Note 1:
      A self-signed test certificate should only be used for internal testing, since it does not guarantee the identity of the user and therefore cannot be trusted. A trust-worthy certificate can be obtained from a certificate authority, such as VeriSign or Thawte, and should be used when the application is put into production.

      Note 2:
      If you want to give the signed jar file another name you should use the following command:

      jarsigner -keystore myKeyStore -storepass mysecret -signedjar signed_bouncing.jar bouncing.jar myAlias



    • [OPTIONALLY] If you want verify if a jar file is signed, use this command:

      jarsigner -verify -verbose -certs bouncing.jar

      You should see the following:

       493 Tue Dec 21 13:45:42 CET 2004 META-INF/MANIFEST.MF
       511 Tue Dec 21 13:45:44 CET 2004 META-INF/MYALIAS.SF
       1072 Tue Dec 21 13:45:44 CET 2004 META-INF/MYALIAS.DSA
       0 Wed Dec 01 19:35:30 CET 2004 META-INF/
       0 Wed Dec 01 19:35:30 CET 2004 com/
       0 Wed Dec 01 19:35:30 CET 2004 com/mobilefish/
       0 Wed Dec 01 19:35:30 CET 2004 com/mobilefish/jogl/
       0 Wed Dec 01 19:35:30 CET 2004 com/mobilefish/jogl/demo10/
      sm455 Wed Dec 01 19:35:30 CET 2004 com/mobilefish/jogl/demo10/
      Bouncing$1.class
        
       X.509, CN=Robert Lie, OU=Research and Development, O=Mobilefish.com,
      L=Zaandam, ST=Noord-Holland, C=NL
        
      sm395 Wed Dec 01 19:35:30 CET 2004 com/mobilefish/jogl/demo10/
      Bouncing$2.class
        
       X.509, CN=Robert Lie, OU=Research and Development, O=Mobilefish.com,
      L=Zaandam, ST=Noord-Holland, C=NL
        
      sm1878 Wed Dec 01 19:35:30 CET 2004 com/mobilefish/jogl/demo10/
      Bouncing.class
        
       X.509, CN=Robert Lie, OU=Research and Development, O=Mobilefish.com,
      L=Zaandam, ST=Noord-Holland, C=NL
        
      sm1676 Wed Dec 01 19:35:30 CET 2004 com/mobilefish/jogl/demo10/
      BouncingDisplay.class
        
       X.509, CN=Robert Lie, OU=Research and Development, O=Mobilefish.com,
      L=Zaandam, ST=Noord-Holland, C=NL
        
      s = signature was verified
      m = entry is listed in manifest
      k = at least one certificate was found in keystore
      i = at least one certificate was found in identity scope

      jar verified.

      Note: This jar contains unsigned entries which are not integrity-checked. Re-run with -verbose to list unsigned entries.

  6. Now you can deploy your application jar file (bouncing.jar) and jogl*.jar files on the webserver. In this example the signed jar files are deployed in the following directories:

    <docroot>/download/webstart/bouncing/bouncing.jar
    <docroot>/download/webstart/lib/jogl.jar
    <docroot>/download/webstart/lib/jogl-natives-solsparc.jar
    <docroot>/download/webstart/lib/jogl-natives-win32.jar
    <docroot>/download/webstart/lib/jogl-natives-macosx.jar
    <docroot>/download/webstart/lib/jogl-natives-linux.jar

  7. Create a JNLP file for your application. Here below you can find the bouncing.jnlp file.
    This file is put in directory <docroot>/download/webstart/bouncing/bouncing.jnlp.

    <?xml version="1.0" encoding="utf-8"?>
    <!-- Web Start Deployment Template -->
    <jnlp spec="1.0+"
        codebase="http://www.mobilefish.com/download/webstart/bouncing"
        href="bouncing.jnlp">

    <information>
        <title>Bouncing Of The Wall</title>
        <vendor>www.mobilefish.com</vendor>
        <homepage href="http://www.mobilefish.com"/>
        <description>Bouncing Of The Wall</description>
        <description kind="short">
           Small ball bounces inside a rectangle.
        </description>
        <icon href="../image/logo_48x48.gif"/>
        <icon kind="splash" href="../image/loading.jpg"/>
        <offline-allowed/>
    </information>

    <security>
        <all-permissions/>
    </security>

    <resources>
        <j2se href="http://java.sun.com/products/autodl/j2se" onclick="javascript:mytracker(this.href);" version="1.4+"/>
        <jar href="bouncing.jar"/>
    </resources>

    <resources os="Windows">
        <j2se href="http://java.sun.com/products/autodl/j2se" onclick="javascript:mytracker(this.href);" version="1.4+"/>
        <jar href="../lib/jogl.jar"/>
        <nativelib href="../lib/jogl-natives-win32.jar"/>
    </resources>

    <resources os="SunOS" arch="sparc">
        <j2se href="http://java.sun.com/products/autodl/j2se" onclick="javascript:mytracker(this.href);" version="1.4+"/>
        <jar href="../lib/jogl.jar"/>
        <nativelib href="../lib/jogl-natives-solsparc.jar"/>
    </resources>

    <resources os="Linux">
        <j2se href="http://java.sun.com/products/autodl/j2se" onclick="javascript:mytracker(this.href);" version="1.4+"/>
        <jar href="../lib/jogl.jar"/>
        <nativelib href="../lib/jogl-natives-linux.jar"/>
    </resources>

    <resources os="Mac OS">
        <j2se href="http://java.sun.com/products/autodl/j2se" onclick="javascript:mytracker(this.href);" version="1.4+"/>
        <jar href="../lib/jogl.jar"/>
        <nativelib href="../lib/jogl-natives-macossx.jar"/>
    </resources>

    <application-desc main-class="com.mobilefish.jogl.demo10.Bouncing"/>

    </jnlp>

    Note 1:
    The icon and splash images must be .jpg or .gif images.

    Note 2: The recommended size of to the icon image is 48x48.

  8. Verify if your JNLP file is correct. This can be done by starting the Java WebStart application (javaws), located in the J2SE SDK and adding your JNLP file. For example:

    cd C:\Tools\java\j2sdk1.4.2_01\jre\javaws
    javaws http://www.mobilefish.com/download/webstart/bouncing/bouncing.jnlp

  9. Create a web page that launches the application and the page must include a link to the JNLP file. For example:

    <a href="http://www.mobilefish.com/download/webstart/
    bouncing/bouncing.jnlp" >Start Bouncing application</a>


    When you click on the link, you should see the following:

    • The jar files are loaded.

      Java Web Start loading screen.

    • A security warning will be displayed because the application is requesting unrestricted access to your local machine and network. The warning "Failed to verify the authenticity of this certificate" is caused by the self-signed jar files.

      Java Web Start security warning.

    • Press the Start button to install and run the "Bouncing Of The Wall" application.

      Java Web Start Bouncing application.

    • A popup window will be displayed asking if an icon can be installed on your desktop.

      Java Web Start desktop integration.

    • Decide which option you want.
      When you now close the "Bouncing Of The Wall" window and click on the link:


      .. then the splash image will be displayed and the application is started.
      All files are retrieved from the Java Web Start cache.

  10. If your application contains some errors you need to clear the Java Web Start cache.
    The cache is located at (Windows XP):

    C:\Documents and Settings\your_name\.javaws\cache

    To clear the cache, do the following:

    • Start the Java Web Start Application Manager
      (C:\Program Files\Java\j2re1.4.2_01\javaws\javaws.exe) or double click desktop icon

      Java Web Start Application Manager

    • Select File | Preferences

    • Select tab Advanced and press button "Clear Folder".

      Clear cache

  11. If you start the Java Web Start manager (javaws.exe), you can see which application is installed in the webstart cache.

    Java Web Start display installed applications.