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

<PARAM NAME="cache_archive" VALUE="a.jar,b.jar,c.jar">

• Parameter: cache_version

<PARAM NAME="cache_version" VALUE="0.0.0.1, 0.0.2A.1, 0.3D.22.FFFE">

• Parameter: cache_archive_ex

<PARAM NAME="cache_archive_ex" VALUE="applet.jar;preload, util.jar;preload;0.9.0.AC1, tools.jar;0.9.8.7F">

Procedure

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

3. 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

10. 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

11. 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

12. 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

13. 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>

14. Move the mojapp.jar and all.jar files to c:\website\mojapp directory.
15. Open Internet Explorer or another browser, and load the HTML page 'mojapp.html'. For example, http://hostname/website/mojapp/mojapp.html
16. 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"