English

How To: Deploy MapObjects - Java Edition in an applet using the Java Plug-in caching mechanism

Summary

The Java Plug-in is designed to extend the functionality of a Web browser, enabling the browser to run Java applets under a defined, local Java Runtime Environment (JRE) instead of the JRE included with the browser. The Plug-in is installed with a JRE and is designed to work with Internet Explorer, Netscape and Mozilla-based browsers such as Firefox. In addition to providing a number of methods for deploying custom Java applets with the Java Extensions mechanism, the Java Plug-in has the ability to cache data on a client machine.

For more information, refer to the following article, How To: Deploy MapObjects-Java in an applet using the Java Extensions mechanism. The 'Caching Option' enables jar files containing custom Java classes and resources to be versioned and stored on the client machine to improve performance.

There are several parameters that are used within an OBJECT or EMBED tag to enable caching.

  • Parameter: cache_archive
A comma-delimited list of jar files to be cached on the client machine.
<PARAM NAME="cache_archive" VALUE="a.jar,b.jar,c.jar">
When cached, the jar files are stored in a Java Plug-in defined, user specific location on disk. For example:
C:\Documents and Settings\user1\Application Data\Sun\Java\Deployment\cache\javapi\v1.0\jar
  • Parameter: cache_version
A comma-delimited list of version numbers. Each entry should correlate with the jar files listed in the cache_archive parameter.
<PARAM NAME="cache_version" VALUE="0.0.0.1, 0.0.2A.1, 0.3D.22.FFFE">
Each version number is in the form xxxx.xxxx.xxxx.xxxx, where x is a hexadecimal number. The version number is arbitrary and not linked to the jar itself. It is only stored and used by the Java Plug-in cache. When a jar is cached, a respective .idx file is created in the cache location to store jar version and content information.
  • Parameter: cache_archive_ex
Enables the ability to preload jars to be used with an applet.
<PARAM NAME="cache_archive_ex" VALUE="applet.jar;preload, util.jar;preload;0.9.0.AC1, tools.jar;0.9.8.7F">

Additional details on the Caching Option can be found by clicking the link provided in the Related Information section below.

Procedure

The following steps show how to deploy a sample MapObjects - Java Edition applet using the Java applet caching mechanism. Throughout the rest of this article, the acronym 'MOJ' may be used to abbreviate 'MapObjects - Java Edition'. This example requires access to a Web server to see the results.

  1. The lib directory in the MapObjects - Java Edition installation location contains the libraries (JARs, DLLs) utilized by a MOJ application. Copy all JAR files from this location to a temporary location, such as c:\temp\moj. Four DLLs are present in this directory, but they are not required for a MOJ applet to function and will therefore be excluded from this example.
  2. Unarchive each JAR file in this temporary location. Use WinZip or the Java Development Kit (JDK) jar command:
    jar -xvf <jar-file>
  3. Navigate to the META-INF directory. Delete the ESRI.DSA, ESRI.SF, and MANIFEST.MF files.
  4. Archive the com, javax, and META-INF folders in this directory with the following command:
    jar -cvf all_unsigned.jar com javax META-INF
  5. Create a temporary directory (such as c:\temp\mojapp) to contain the applet source code.
  6. The following code creates a MOJ applet containing a single ArcIMS Image Service layer from the Geography Network. Copy and paste the code below into a new text file and save it as 'MOJApplet.java'.
    import java.awt.*;
    import java.awt.event.*;
    import javax.swing.*;
    import com.esri.mo2.ui.bean.*;
    import com.esri.mo2.ui.tb.*;
    import java.applet.Applet;
    
    public class MOJApplet extends JApplet {
    
      public void init(){
    
    	com.esri.mo2.ui.bean.Map map1 = new com.esri.mo2.ui.bean.Map();
    	com.esri.mo2.ui.bean.Toc toc1 = new com.esri.mo2.ui.bean.Toc();
    	
    	Container contentPane = getContentPane();
    	JSplitPane jSplitPane1 = new JSplitPane();
    
    	setSize(new Dimension(400, 300));
    
    	com.esri.mo2.ui.bean.Layer layer_img = new com.esri.mo2.ui.bean.Layer();
    	layer_img.setDataset("2;http://www.geographynetwork.com;ESRI_Pop;ImageServer;
               ESRI_Pop;image");
    	map1.add(layer_img);
    
    	toc1.setMap(map1);
    
    	contentPane.add(jSplitPane1, BorderLayout.CENTER);
    	jSplitPane1.add(map1, JSplitPane.RIGHT);
    	jSplitPane1.add(toc1, JSplitPane.LEFT);
    
    	ZoomPanToolBar zoomPanToolBar1 = new ZoomPanToolBar();
    	zoomPanToolBar1.setMap(map1);
    	contentPane.add(zoomPanToolBar1, BorderLayout.NORTH);
    	setVisible(true);
      
      }
    }
  7. Compile MOJApplet.java to create the MOJApplet.class file.
  8. Archive the contents of the directory:
    jar -cvf mojapp_unsigned.jar .
  9. To use use the applet caching mechanism, all JAR files must be signed. For public deployments, acquire a certificate from a recognized authority such as Verisign to avoid inconveniencing clients. This example demonstrates how to create a test certificate to sign the JAR files. The keytool utility included with the JDK is used to accomplish this task.
  1. Open a command window and navigate to the c:\temp directory.
  2. Type the following at a command prompt to run the keytool utility:
keytool -genkey -dname "cn=Your Team Name, ou=Your Division, o=Your Company, c=location" -alias TestCert
-keypass pw1234 -keystore c:\keystore -storepass pw1234 -validity 1024
  1. Type the following at the command prompt to create the certificate file 'key.cer' in the c:\temp directory. The certificate file contains the information to be used as the public key for the JAR files.
keytool -export -alias TestCert -keystore c:\keystore -file key.cer -keypass pw1234 -storepass pw1234
  1. Add the certificate to the registry on the Web server by double-clicking the file (Windows) or using the following command (UNIX):
keytool -import -trustcacerts -alias TestCert -file /tmp/key.cer -keystore /usr/jdk1.3/lib/security/cacerts
  1. Sign the JARs used by the applet. Navigate to c:\temp\moj and use the following command to create an 'all.jar' file:
jarsigner -keystore c:\keystore -storepass pw1234 -keypass pw1234 -signedjar all.jar all_unsigned.jar TestCert
  1. Sign the application JAR. Navigate to c:\temp\mojapp and use the following command to create a 'mojapp.jar' file:
jarsigner -keystore c:\keystore -storepass pw1234 -keypass pw1234 -signedjar mojapp.jar mojapp_unsigned.jar TestCert
  1. Navigate to the location of the 'website' virtual directory on the Web server (c:\website) and create a 'mojapp' directory. Within this directory, create an HTML page (mojapp.html) that references the main applet class (MOJApplet) and the JAR file (mojapp.jar) containing this class. For example:
<html>
  <object CLASSID="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93" ID="imsSite" WIDTH="500" HEIGHT="300">
     <param NAME="code" VALUE="MOJApplet" >
     <param NAME="archive" VALUE="mojapp.jar" >
     <param NAME="cache_archive" VALUE="all.jar" >
     <param NAME="cache_version" VALUE="1.1.1.1" >
  </object>
</html>
  1. Move the mojapp.jar and all.jar files to c:\website\mojapp directory.
  2. Open Internet Explorer or another browser, and load the HTML page 'mojapp.html'. For example, http://hostname/website/mojapp/mojapp.html
  3. Click 'grant this session' when prompted. This prompt may appear twice; once to install the 'all' extension, and a second time for the test certificate used to sign the JAR files. A download progress bar may or may not appear, depending on the connection speed. The MOJ applet should load. If the Java Plug-in console is active, communication between the applet and the Geography Network should be seen.
Note:
The Java Plug-in must be installed and enabled on the client machine. To automate the Java Plug-in installation process, add the 'codebase' attribute to the OBJECT tag in the HTML document. For example, the following code will install JRE 1.4.0 if the Java Plug-in is not detected:
codebase="http://java.sun.com/products/plugin/autodl/jinstall-1_4_0-win.cab#Version=1,4,0,mn"
The Java Plug-in will evaluate cached jars, download new jars as needed and overwrite existing jars with newer versions or date/time stamps. The cache properties are managed in the Java Plug-in console, which is accessible from the Windows Control Panel.

Related Information