Packaging and Deployment

This chapter will describe the steps involved in packaging and deploying a Aria application. It will cover topics such as running from the command line, from a website using Java webstart, creating native executables and installation wizards.

Package your project

For convenience, it can be useful to create a batch file which will package all of the resource and class files and install them into a single jar file. So, by creating the following batch file in the root of a Aria project all of the project files can be merged into a single jar.

Sample jar script

 # Create the file with a mainfest file
 c:\j2sdk1.4.2_03\bin\jar cvf bundle.jar META-INF/MANIFEST.MF 
 # navigate to the resources directory and jar it's contents. 
 # Repeat this for all resource files
 cd resources
 c:\j2sdk1.4.2_03\bin\jar uvf ../bundle.jar *.*
 cd ..\pages
 c:\j2sdk1.4.2_03\bin\jar uvf ../bundle.jar *.*
 cd ..\images
 c:\j2sdk1.4.2_03\bin\jar uvf ../bundle.jar *.*
 cd ..\classes
 c:\j2sdk1.4.2_03\bin\jar uvf ../bundle.jar *.*
 # Extract the contents of the jars which need to be included
 # in the application into a tmep directory and jar them.
 cd ..\lib
 rd temp
 md temp
 cd temp
 ########## STARTED EXTRACTING JARS ############
 c:\j2sdk1.4.2_03\bin\jar xvf ../AriaRuntimeCommon.jar
 ########## FINISHED EXTRACTING JARS ###########
 c:\j2sdk1.4.2_03\bin\jar uvf ../../bundle.jar *.*
 cd..\..

The first line in this script references a file called META-INF/MANIFEST.MF which looks like...

The manifest file

 Manifest-Version: 1.0
 Main-Class: org.formaria.swing.Applet

This file simply tells the jar that the org.formaria.swing.Applet class needs to be loaded when the jar file is run. Note that the startup file is not specified in which case the Applet class looks for and uses the startup.properties file if it is present.

You should now be able to run the application simply by double-clicking the jar file.

Running a Aria application from the command line

Again, it is easier to create a batch file to launch the application. So, by creating a file ` run.bat ' in the root of the Aria project folder, the application can be launched using the jar which was created in the previous section

Launch Aria with the command line

 java.exe -cp bundle.jar org.formaria.swing.Applet startup.properties

The startup.properties parameter is not necessary if the startup file is called ` startup.properties '.

If you do not wish to bundle all of your jars into a single jar you may wish to create the following file to launch the application.

Specify the jars separately

 java -cp .;.\lib\AriaRuntimeCommon.jar;.\bundle.jar;
     org.formaria.swing.Applet startup.properties

In this case you will want to modify the bundle.bat file so as to remove the commands which jar the contents of the dependancies. The following lines should be removed from the bundle.bat file.

Lines to be remove from the bundle.bat file

 # cd ..\lib
 # rd temp
 # md temp
 # cd temp
 ########## STARTED EXTRACTING JARS ############
 # c:\j2sdk1.4.2_03\bin\jar xvf ../AriaRuntimeCommon.jar
 ########## FINISHED EXTRACTING JARS ###########
 # c:\j2sdk1.4.2_03\bin\jar uvf ../../bundle.jar *.*
 

Running a Aria application using Java Web Start

Java Web Start is used where applications need to be deployed over the internet but do not run within the confines of a web browser. The client machine which attempts to run the application must have a valid Java runtime installed

Java Web Start reads the contents of a JNLP file which resides on a webserver in order to initialise an application. Before the application can be used, however, the jar file which is to be used needs to be signed with a code signing digital certificate. This certificate will be registered to your company name and can be purchased from one of the following.

Alternatively you can create your own test certificate using the tools supplied with the JDK (the keytool tool with the -selfcert option). Once the certificate has been created you need to import it into your keystore, if you don't already have a keystore then you will need to create one.

Generate a new keystore for you certificates

 c:\jdk1.5.0\bin\keytool 
	-genkey 
	-alias my_keystore 
	-keypass mykeypassword 
	-keyalg RSA 
	-keystore mycompany.keystore 
	-storepass mystorepassword

The new keystore will be created in the current working directory. Next, to start the process of signing you need to generate a certificate signing request:

Generate a certificate signing request

 c:\jdk1.5.0\bin\keytool 
	-certreq 
	-alias my_keystore 
	-keystore mycompany.keystore 
	-file certreq.txt

The output file certreq.txt needs to be sent to the signing authority by cutting and pasting the content into the forms provided on the authorities website (the process may differ from company to company). Using the new certificate the jar file can be signed using the JDK. When the process is complete you should then receive a new certificate from the signing authority. The new certificate needs to be imported into your keystore:

Import the new certificate

 c:\jdk1.5.0\bin\keytool -alias my_keystore -keypass mykeypassword -keystore mycompany.keystore -storepass mystorepassword -import -file cert.txt -trustcacerts

The keystore is now ready for use and you can sign the bundle.jar file using the following command, so that a new version of the jar, bundleS.jar , is output.

Signing the jar file

 jarsigner 
	-keystore mycompany.keystore 
	-signedjar bundleS.jar bundle.jar

The signed jar can now be deployed to a webserver along with a JNLP file. For the new bundleS.jar file the JNLP file might look like...

A sample JNLP file

 <jnlp spec="1.0+" codebase="http://www.mydomain.com/demo/">
   <information>
     <title>Aria Application</title>
     <vendor>My Company Ltd</vendor>
     <homepage href="http://www.mydomain.com/demos" />
     <description kind="">Some application</description>
     <description kind="tooltip">Aria Application</description>
     <offline-allowed />
   </information>
   <resources>
     <j2se version="1.4+" />
     <jar href="lib/AriaRuntimeCommonS.jar" main="true" download="eager"/>
    <jar href="lib/bundleS.jar"/>
  </resources>
   <application-desc main-class="org.formaria.swing.Applet">
     <argument>startup.properties</argument>
   </application-desc>
   <security>
     <all-permissions />
   </security>
 </jnlp>

In this example the JNLP file can be invoked by referencing http://www.mydomain.com/demos/aria.jnlp

The .jnlp extension needs to be included in the mime types for the webserver it is running on if not already done so. The method of doing this varies accross webservers so the documentation for the webserver should be referred to.

Note that in the above example the Aria jars are also listed, but you could just include everything in the one jar file. However, leaving the Aria code in separate jars means that you can reuse the jars in other applications and if the same URL is used then the jars will not need to be downloaded again by the user's system. Also note that all the jars need to be signed by the same certifcate (i.e. your certificate) and therefore the Aria jars are not supplied in a signed form. Finally, the main="true" attribute tells JWS that the jar contains the entry point, or main method, which is used to start the application.

NetBeans 5.0 supports an add-on module to edit JNLP files. Check the NetBeans Update Center for details.

Setting up a JWS extension

If you have more than one application based upon Aria you may wish to share the core jars between applications, so that they are not repeatedly downloaded for each application. The JNLP specification allows resources to be specified as an extension, and the extension can contain the common jars (with the restriction that the jar containing the main method must be referenced in the primary JNLP file).

A sample JNLP file

 <?xml version="1.0" encoding="utf-8"?> 
 <jnlp spec="1.0+" codebase="http://www.mydomain.com/demo/">
   <information>
     <title>Aria Application</title>
     <vendor>My Company Ltd</vendor>
     <homepage href="http://www.mydomain.com/demos" />
     <description kind="">Some application</description>
     <description kind="tooltip">Aria Application</description>
     <offline-allowed />
   </information>
   <resources>
     <j2se version="1.4+" />
     <jar href="lib/AriaRuntimeCommonS.jar" main="true" download="eager"/>
     <extension name="Aria" href="aria.jnlp"/>
     <jar href="lib/bundleS.jar"/>
  </resources>
   <application-desc main-class="org.formaria.swing.Applet">
     <argument>startup.properties</argument>
   </application-desc>
   <security>
     <all-permissions />
   </security>
 </jnlp>
 
 <?xml version="1.0" encoding="utf-8"?> 
 <jnlp spec="1.0+" codebase="http://www.mydomain.com/demos/" href="aria.jnlp"> 
   <information> 
     <title>Aria</title> 
     <vendor>Formaria Ltd.</vendor> 
     <homepage href="http://www.mydomain.com/demos"/> 
     <offline-allowed/> 
  </information> 
   <resources> 
     <jar href="lib/AriaRuntimeCommon.jar" main="false"/>
    <jar href="lib/jxl.jar"/>
   </resources> 
   <component-desc/> 
 </jnlp> 

Deploying a webstart application via CD

Once you have created and deployed a JWS applicationit is possible to put that application on CD so that the features of JWS are available to anyone who has installed from CD. The result is that you can distribute your application via CD or other routes, install that application onto the desktop and into the JWS cache so that the application will run in an off-line mode and so that when on-line it will check for updates.

To install into the JWS cache it is necessary to import the jar files. Assuming you have copied your server's version of the application jnlp and jar files, you then need to create an additional file ( install.bat or install.cmd on Windows):

Import the jars into the JWS cache

 @echo off
 SET DRIVE=%0
 SET DRIVE=%DRIVE:~1,1%
 c:\jdk1.5.0\bin\javaws 
	-codebase file:///%DRIVE%:/myapp/ 
	-import %DRIVE%:/myapp/myApp.jnlp

Once this command file is run the files will be imported into the JWS cache and depending on the content of the JNLP file, desktop and menu shortcuts may be setup.

You will probably want to add an auto install option to your CD, and if so, you should use the installer to kick of the above commands and possible start the application following successful installation.

This installation mechanism has been packaged in an installed for CDs. Please contact Formaria for futher details.

Running a Aria application from a web page

Using the bundle.jar file from the first section in this chapter, a web page can be created which will start it as an applet. This assumes that the project was written using the AWT packages and not the swing packages.

Applet tag for the applet

 <APPLET style="height=100" archive="../lib/bundle.jar" 
		width=100 code=org.formaria.awt.Applet>
   <PARAM NAME="startfile" VALUE="startup.properties">
 </APPLET>

It is possible to start an application written with the Swing packages as an applet by using the object tag

Starting a swing application from a browser

 <Object
    classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    codebase="http://java.sun.com/products/plugin/1.1/jinstall-11-win32.cab#Version=1,3,0,0"
    width=50 height=50>
 
    <param name="code" value="org.formaria.swing.Applet.class">
    <param name="codebase" value="./lib/bundle.jar/">
    <param name="startfile" value="startup.properties">
 </object>

Creating a setup for your Aria application

There are a number of ways of deploying your Aria application from custom written deployments to third pary installers. In this section, however, the installer which will be used is izPack, an open source installer which can be downloaded from http://www.izforge.com/izpack/

The version of izPack being used in this section is 3.6.1. For other versions or more advanced information please visit the izforge website.

Setup izPack by downloading the IzPack-install-3.6.1.jar file and double-clicking it to install. For these examples it is assumed that izPack is installed into c:\programmer\IzPack

For convenience it is easier to create an izPack directory under the Aria project root directory. Within this directory the following izPack configuration xml file can be created.

The izPack configuration file

 <?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
 <installation version="1.0">
     <info>
         <appname>Aria Installation</appname>
         <appversion>1.0</appversion>
         <authors>
             <author name="Joe Bloggs" email="joe.bloggs@mydomain.org"/>
         </authors>
         <url>http://www.mydomain.net/</url>
     </info>
 
     <guiprefs width="640" height="480" resizable="no"/>
 
     <locale>
         <langpack iso3="eng"/>
     </locale>
 
     <resources>
         <res id="LicencePanel.licence" src="Licence.txt"/>
         <res id="InfoPanel.info" src="Readme.txt"/>
         <res id="shortcutSpec.xml" src="shortcutSpec.xml"/>
     </resources>
 
     <native type="izpack" name="ShellLink.dll"/>
 
     <panels>
         <panel classname="HelloPanel"/>
         <panel classname="InfoPanel"/>
         <panel classname="LicencePanel"/>
         <panel classname="TargetPanel"/> 
         <panel classname="PacksPanel"/>
         <panel classname="InstallPanel"/>
         <panel classname="ShortcutPanel"/>
         <panel classname="FinishPanel"/>
     </panels>
 
     <packs>
         <pack name="Base" required="yes">
             <description>The base files</description>
             <file src="Licence.txt" targetdir="$INSTALL_PATH"/>
             <file src="../bundle.jar" targetdir="$INSTALL_PATH"/>
         </pack>
     </packs>    
 </installation>
 

The info section of the file contains some basic information about the application being deployed. The guiprefs section will specify the size of the installation application. The locale can be modified to handle multiple languages.

The panels section specifies the screens which will make up the installation application. If there is a licence file for the application it can be specified here otherwise the LicencePanel node can be removed. Similarly, the InfoPanel displays a readmed for the application you are installing and can be removed if not appropriate.

Now all that is left to do is to create the installation jar file. This is done by creating a batch file in the izPack directory as follows:

Create the installation jar file

 "c:\Programmer\izpack\bin\compile" install.xml -b . -o install.jar -k standard

When run, the batch file will create the install.jar file. When double-clicked this file will start the installation script.

This jar file will only run if the Java runtime is installed on the machine. It is possible to automate the installation of the Java runtime by downloading the izpack-launcher-1.1.zip from the izforge website. All that is required then is to copy the dist/launcher-Win32.exe and the src/launcher.ini files to the izPack directory. The launcher.ini file is then modified to reflect the name of the installation jar.

The modified Launcher.ini file

 # Global entries, can be overriden by specific ones.
 jar = install.jar
 download = http://www.java.com/
 
 # Win32 specific entries
 [win32]
 jre = jre/setup.exe

The download key specifies the source from which the Java runtime can be obtained in the event that it cannot be found on the system

The jre key specifies the subdirectory which contains the Java runtime which has been distributed with the setup. This setup for the Java runtime would typically be included when a CD installation is being distributed.