Building Web Start Applications

These steps configure a NeXtMidas application to run from WebStart:

  1. Create a Default JNLP File
  2. Customize the JNLP File
  3. Create an HTML file to reference the JNLP
  4. Create and Sign Application Jars
  5. Upload the Files
  6. Applying Custom Environment Settings
  7. Increased Java Web Start Security Restrictions

Create a Default JNLP File

WebStart applications require a JNLP (Java Network Launching Protocol) file that specifies what command to run and which libraries to run it. The JNLP specification is available from http://www.oracle.com/technetwork/java/javase/javawebstart/index.html

The NeXtMidas generate macro generates the JNLP file required to run a command via WebStart. The generate command takes a command name to run and a list of option trees which is required to run the command. The following line creates a .jnlp file that runs shellgui and puts it in the /home/smith/public_html/shellgui directory. (Note: The blank fourth argument is a pipe delimited list of option trees required to run the command). 

generate,jnlp,shellgui,,/home/smith/public_html/shellgui

The generate command creates a default JNLP file and a manifest specifying the files uploaded to the web server to run the WebStart application. Next, this file is customized before it is used.


Customize the JNLP File

The "codebase" attribute

The codebase attribute of the jnlp tag in the JNLP file must point to the URL of the directory from where the files are being deployed. This URL is not the path on the file system, but the URL viewed from a browser's perspective. This generally should be pointed to NMROOT that visible from the web server.

The "href" attributes

The href attribute of jnlp tag points to the JNLP file itself. All href attributes (in JNLP file) can and should generally be a relative link from the codebase URL.

For example, the top of your JNLP file should look similar to this
      <?xml version="1.0" encoding="utf-8"?>
      <jnlp spec="1.0+" codebase="http://webserver.hostname/nmroot" href="htdocs/demo.jnlp">

NeXtMidas System Properties for Web Start

Java system properties are set in the property tag within the resources tag.

The "AUX" Property

NeXtMidas uses an AUX path to define the standard locations for files. The write aux specifies the default location for creating new files, and the read aux specifies a set of default locations for reading files. While running under WebStart, the default values for the write aux is "ram:" and the default value for the read aux is "ram:|DAT|99".

To customize the default values, modify the generated JNLP file to contain a property tag with the name "AUX", and change the value set to: write path, space, read path. This string is passed verbatim to the AUX command when the application runs(see HELP AUX for details).

In this example, the following property tag sets the write aux to "RAM" and the read path to "RAM|DAT". Notice, the two arguments in the value are contained within a single string: 

<property name="AUX" value="RAM   RAM|DAT"/>
The "HOME" Property

The default homepath for executing NeXtMidas under WebStart is your homepath on the executing machine. It's probably best to keep this default homepath. Although you can set the HOME property to specify a local directory or other resource (such as ram:), you must be careful when using this option because the HOME directory must exist on the client machine.

The "OPTS" Property (i.e. set PATH)

Set the PATH with the specified option trees.
Note, that the option tree's jar file should be included via the jar tag, e.g.

        <property name="OPTS" value="UCL,DSP,SYS"/>
        <jar href="jars/nxm-dsp.jar"/>
        <jar href="jars/nxm-ucl.jar"/>

The "NONATIVE" Property

Generally set to "true" to disable loading of native code since native libraries may not be built for client's specific machine and architecture.

The "ENV.THEME" Property

Set the default THEME (Look and Feel) for this Web Start application. This is similar to running ENV SET THEME themeName or LOOKANDFEEL themeName. Since NeXtMidas 2.9.3.

The "ENV.STYLE" Property

Set the default STYLE (TDB) for this Web Start application. This is similar to running ENV SET STYLE styleName command. Since NeXtMidas 2.9.3.


Create an HTML file to reference the JNLP

To create an HTML file that links the Web page to the .jnlp file, the HTML file should contain an href tag that points to the JNLP file. The following example launches the shellgui application created earlier: 

<a href="shellgui.jnlp">Launch NextMidas Shellgui</a>

Create and Sign Application Jars

For each option tree required by the WebStart application, there must be a signed Jar file with the required classes to run the application. The following commands generate and sign the Jar file for the SYS option tree: 

generate jars sys /home/smith/public_html/shellgui

This creates a signed Jar file called nxm-sys.jar and places it in the given directory. The /sign flag signs the Jar with the keystore located in the $NMROOT/nxm/sys/cfg directory. Signing the Jar is a security measure required by WebStart.

In addition to the option tree jars, the application also requires all the Jar files included in the $NMROOT/nxm/sys/jars directory. These Jars are automatically copied to $NMROOT/jars when the SYS tree is compiled with MAKE. To sign these files and put them into the deployment directory, execute the following command from the Jars directory (substitute each Jar name for jarname.jar where appropriate): 

generate jars jarname.jar /home/smith/public_html/shellgui

NeXtMidas allows the use of a custom keystore instead of the default keystore packaged with each release. See external documenation on using tools such as java's keytool for generating a keystore. The following command will generate and sign the Jar nxm-sys.jar using a custom keystore. 

generate jars sys /home/smith/public_html/shellgui /home/smith/mykeystore mystorepass myalias

Upload the Files

Upload the generated files to the server that is serving the files. A list of all the uploaded files are located in the <appname>.manifest file that was created previously (see Create a Default JNLP File). Make sure your HTTP server on the host machine is configured to return a MIME type of 'application/x-java-jnlp-file' for all files ending with .jnlp. See Apache setup for more details.


Note: Applying Custom Environment Settings

NeXtMidas under Web Start currently does not execute the SYS/cfg/nmstartup.mm since it generally has settings specific for that server's machine and not the client's machine. To set custom NeXtMidas environment options, either include it at the top of your macro or in the option tree's optstart.mm macro. See Option Tree Structure for more info.

Note: Increased Java Web Start Security Restrictions

The following error message may appear when attempting to run the Webstart application:

Application Blocked by Security Settings
Your Security Settings have blocked a self-signed application from running.

Recent versions of Java have increased Webstart security restrictions. If you are using JDK 7u40 or greater, the following may be required: