Deployment Toolkit 101

Contents

• What is the Deployment Toolkit
• When was the Deployment Toolkit introduced and where can I find it
• Using the Deployment Toolkit
• Deploying an applet using the runApplet function
• Specifying deployment options as attribute and parameter name-value pairs
• Using jnlp_href parameter to specify deployment options in a JNLP file
• Specifying attribute and parameter name-value pairs as well as JNLP file
• Deploying a Java Web Start application using the createWebStartLaunchButton function
• Specifying a minimum JRE version
• Running on any JRE version
• Working around the problem of specifying absolute URL for JNLP file
• Changing the Launch button of your Java Web Start application
• Detecting the client JRE version using the versionCheck function
• Related Reading

What is the Deployment Toolkit or DT as it is affectionately referred to?

The Deployment Toolkit is a set of JavaScript functions that can help developers easily deploy applets and Java Web Start applications (aka rich internet applications, RIAs) consistently across various browser and operating system configurations. As a developer, you now do not have to worry about handling the idiosyncracies of different clients. Just use the functions in the Deployment Toolkit - it takes care of all the underlying issues for you and generates the correct HTML.

Note:

• We will use the phrase "rich internet applications" or "RIAs" in places where some functionality applies to both applets and Java Web Start applications.
• Depending on the type of browser, you may not be able to see the HTML generated by the Deployment Toolkit when you try to view source for the page. To view the generated HTML, try saving the HTML page after its been loaded, or, use a tool such as Firebug (Mozilla Firefox add-on)

When was the Deployment Toolkit introduced and where can I find it?

The Deployment Toolkit was introduced in Java SE 6u10. It can be found at http://java.com/js/deployJava.js or https://www.java.com/js/deployJava.js

The http://java.com/js/deployJava.txt file contains the un-minimized version with comment blocks describing functions and usage.

Now that the introductions are done, let's move on to the details.

Using the Deployment Toolkit

Deploying an applet using the runApplet function

Use the runApplet function to deploy your applet. The runApplet function ensures that the required minimum version of the Java Runtime Environment (JRE) exists on the client and then runs the applet. It generates an <applet> tag with the information provided.

Function signature: runApplet: function(attributes, parameters, minimumVersion)

Parameters:

• attributes: The attribute names and values of the generated <applet> tag
• parameters: The names and values of the <param> tags in the generated <applet> tag
• minimumVersion: The minimum version of JRE required to run this applet

Usage:

• Specifying deployment options as attribute and parameter name-value pairs

  The attributes and parameters passed as name-value pairs are written out as attributes and nested <param> tags in the generated <applet> tag.

  // launch the Java 2D applet on JRE version 1.6.0 or higher with one parameter (fontSize)
  <script src="http://java.com/js/deployJava.js"></script>
  <script>
      var attributes = {codebase:'http://java.sun.com/products/plugin/1.5.0/demos/jfc/Java2D',
                        code:'java2d.Java2DemoApplet.class',
                        archive:'Java2Demo.jar',
                        width:710, height:540} ;
      var parameters = {fontSize:16} ;
      var version = '1.6' ;
      deployJava.runApplet(attributes, parameters, version);
  </script>
  	

• Using jnlp_href parameter to specify deployment options in a JNLP file

  The attributes and parameters (jnlp_href in this case) passed as name-value pairs are written out as attributes and nested <param> tags in the generated <applet> tag. It is better to specify the applet's width and height as attributes, as shown below.

  <script src="http://java.com/js/deployJava.js"></script>
   <script> 
  		var attributes = { code:'java2d.Java2DemoApplet', width:710, height:540} ; 
  		var parameters = {jnlp_href: 'java2d.jnlp'} ; 
  		deployJava.runApplet(attributes, parameters, '1.6'); 
  </script>
  		

• Specifying attribute and parameter name-value pairs as well as JNLP file

  Applets deployed using JNLP will run only if the end user has the next generation plug-in running on his / her browser (next generation plug-in introduced in Java SE 6u10). If you would like your applet to run on the old plug-in also, specify deployment options using attribute and parameter name-value pairs as well as JNLP file.

  <script src="http://java.com/js/deployJava.js"></script>
  <script>	
  		var attributes = {codebase:'http://java.sun.com/products/plugin/1.5.0/demos/jfc/Java2D',
                          code:'java2d.Java2DemoApplet.class', archive:'Java2Demo.jar', 
                          width:710, height:540} ; 
  		var parameters = {fontSize:16, jnlp_href:'java2d.jnlp'} ; 
  		var version = '1.6' ; 
  		deployJava.runApplet(attributes, parameters, version);  	
  </script>
  

  If you are now wondering what happens if some deployment options have different values in the attributes name-value pairs and in the JNLP, read more about how final deployment information is determined.

Deploying a Java Web Start application using the createWebStartLaunchButton function

Use the createWebStartLaunchButton function to deploy a Java Web Start application. The createWebStartLaunchButton function generates a link (HTML anchor tag - <a> ) to the Java Web Start application's JNLP file.

This generated anchor tag is the Java Web Start application's button. When the end user clicks the Launch button, it ensures that an appropriate JRE is installed and then launches the Java Web Start application.

Function signature: createWebStartLaunchButton: function(jnlp, minimumVersion) or createWebStartLaunchButton: function(jnlp)

Parameters:

• jnlp: The url of the JNLP file containing deployment information for the Java Web Start application. This needs to be an absolute path.
• minimumVersion: The minimum version of JRE required to run this application

Usage:

• Specifying a minimum JRE version that is required to run the application

  <script src="http://java.com/js/deployJava.js"></script>
  <script>
      var url = "http://java.sun.com/javase/technologies/desktop/javawebstart/apps/notepad.jnlp";
      deployJava.createWebStartLaunchButton(url, '1.6.0');
  </script>
      

  Note: Running on any JRE version - Use the createWebStartLaunchButton: function(jnlp) function if your application does not have a minimum JRE requirement.

• Working around the problem of specifying absolute URL for JNLP file

  The requirement of an absolute URL for the JNLP file of a Java Web Start application means that the web page is no longer easily portable between, for example, development, test and production environments. Obviously, the JNLP file path will be different in these environments and you should not have to change the url at each step. Applets do not have this problem because applets determine the codebase relative to the page in which they are embedded. You can simulate this behaviour with some JavaScript, such that the JNLP file's path is relative to the location of the web page from which the Java Web Start application will be launched. Here is some sample code:

  <script src="http://java.com/js/deployJava.js"></script>		
  <script >
      var dir = location.href.substring(0,location.href.lastIndexOf('/')+1);
      var url = dir + "notepad.jnlp";
      deployJava.createWebStartLaunchButton(url, '1.6.0');
  </script>
  
      

Changing the Launch button of your Java Web Start application

You can change your Java Web Start application's Launch button, if you don't like the default button or you have another button that you have standardized on.

Use the deployJava.launchButtonPNG variable to point to the location of your image.

Variable: deployJava.launchButtonPNG

Usage:

• Providing an alternate image url. In this example, the Launch button will now be an image of our own Duke waving

  		
  <script src="http://java.com/js/deployJava.js"></script>
  <script>
      deployJava.launchButtonPNG='http://java.sun.com/products/jfc/tsc/articles/swing2d/WatermarkDemo/duke_wave.png'
      var url = "http://java.sun.com/javase/technologies/desktop/javawebstart/apps/notepad.jnlp";
      deployJava.createWebStartLaunchButton(url, '1.6.0');
  </script>
      

Detecting the client JRE version using the versionCheck function

There are many good reasons to be able to check if a particular version of the JRE is available on a client machine. For example, you may want to launch a different version of your RIA depending on the client's JRE version, or you may want to redirect the user to a different page etc.

Use the versionCheck function to check if a particular version or range of JRE versions is installed on the client.

Function signature: versionCheck: function(versionPattern)

Parameters:

• versionPattern: String specifying the version or range of versions to check for, such as such as "1.4", "1.5.0*" (1.5.x family), and "1.6.0_02+" (any version greater than or equal to 1.6.0_02).

Usage:

• Creating a different user experience depending on the client's JRE version. In this example, we create a Launch button for the application only if the client's JRE version is greater than or equal to 1.6.0. If not, we redirect them to java.sun.com.

      
  <script src="http://java.com/js/deployJava.js"></script>
  <script>
      if (deployJava.versionCheck('1.6.0+')) {            
          var url = "http://java.sun.com/javase/technologies/desktop/javawebstart/apps/notepad.jnlp";
          deployJava.createWebStartLaunchButton(url, '1.6.0');
      } else {
          document.location.href="http://java.sun.com";
      }
  </script>		
  		

Related Reading

Deployment
• Deploying An Applet In Under Ten Minutes - Java Tutorials Blog
• Deployment Advice

Java Network Launch Protocol (JNLP)
• JNLP File Syntax
• Editing a JNLP file in Netbeans IDE (although this tutorial is written in the context of Java Web Start applications, most of the information is still relevant)
• JNLP Support in the New Java Plug-in

Next Generation Java Plug-in aka New Java Plug-in
• Release Notes for the Next-Generation Java™ Plug-In Technology JDK 6u10

As always, we welcome feedback. Tell us about other things you'd like information about!

-- Sowmya Kannan

Posted at 02:40PM Apr 02, 2009 by The Java Tutorial Team  |  Comments[7]