Deploy MapObjects-Java in an applet using the Java Extensions mechanism

Summary

Distributing Java applets in Web browsers is a common method used to provide a feature-rich Web client with a wide range of development capabilities. To execute a Java applet, Web browsers can utilize either the Java virtual machine (JVM) inherent to the browser or the Java Plug-In by Sun Microsystems. While most Web browsers contain a JVM, they are often outdated, limiting applets to a Java development environment many versions prior to the current release. To remedy this situation, Sun introduced the Java Plug-in to integrate the latest Java runtime environment (JRE) with multiple browser versions. In addition to extending the functionality of Java applets in a browser, it also introduced new methods for deploying classes included with custom applets. Since the Java Plug-in must be able to access applet classes on the client machine, it must provide a method for retrieving and deploying those classes locally. This method is called the Java Extensions Installation and is a new feature in the Java Plug-in version 1.3.

The JRE's Java Extensions mechanism provides Java applications with immediate access to classes included in the lib/ext directory of the JVM. Classes referenced in this directory must be included in a *.jar (Java archive) file. When a Java application or applet utilizing the respective JVM is executed, these classes are automatically appended to the beginning of the application's classpath. Deploying a Java applet using the Java Plug-in involves installing one or more JAR files on the client. Installing these files in a JRE's lib/ext directory allows the applet to utilize the Java Extensions mechanism.

The Java Extensions Installation included with the Java Plug-in supports three different methods for installing applet-specific classes in a JRE's lib/ext folder:

Method #1: Raw Java Extensions

The Java Plug-in is directly responsible for installing the appropriate JAR files needed by an applet. Each JAR file referenced by the applet includes a MANIFEST file to provide download instructions. Note that each JAR file must be signed with a digital certificate.

Method #2: Java Installer

A custom Java application is responsible for managing the installation of the JAR files associated with an applet. The Java application is bundled and distributed as a JAR file itself. This option provides the developer with the ability to manage the installation of an applet's JAR files on the client machine.

Method #3: Native Installer

A custom, operating system-specific wrapper (*.exe) is included in a JAR file and is responsible for copying the appropriate JAR files to the client machine. The installation is managed using the third-party application's API.

Additional details on the Java Extensions mechanism can be found by clicking the link in Related Information section at the end of this article.

Procedure

1. The \lib directory under 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 (e.g., c:\temp\moj). Note that four DLLs are present in this directory. They are not required for a MOJ applet to function, thus they will not be included.
2. Unarchive each JAR file in this location. Use WinZip or the JDK jar command:
   
   

   Code:
   jar -xvf <jar-file>

   
   
3. Navigate to the META-INF directory. Delete the ESRI.DSA, ESRI.SF, and MANIFEST.MF files.
4. Create a text file named "manifest.txt" and add the following text to it:
   
   

   Code:
   Manifest-Version: 1.0
   Extension-Name: all 
   Specification-Vendor: ESRIMOJ_SPEC
   Specification-Version: 1.0 
   Implementation-Vendor-Id: MOJ2002 
   Implementation-Vendor: ESRIMOJ_IMP
   Implementation-Version: 1.0

   
   
   

   Note:
   Be sure to press return after the last line, otherwise the last line will not be included.

   
   
5. Archive the contents of this directory and include the custom manifest file created in the previous step. Use the following command (be sure to include the last period):
   
   

   Code:
   jar -cvfm all_unsigned.jar manifest.txt .
   

   
   The all.jar file is created and contains all the classes needed for a MOJ application\applet, namely the applet code and core MOJ classes. The manifest file created in Step 6 is used to store version information (manifest, specification, and implementation) as well as to identify the creator in the META-INF\manifest.mf within the JAR. In addition, the all.jar file is assigned an extension name 'all'. The extension name and specification\implementation versions will be used by the Java Extensions mechanism to locate the proper JAR (extension) and version needed by an applet.
6. Create a temporary directory (for example, c:\temp\mojapp) to contain the applet source code and manifest used to locate and install the extensions needed by the MOJ applet.
7. The following class 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'.
   
   

   Code:
   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);
     
     }
   }

   
   
8. Compile MOJApplet.java to create the MOJApplet.class file.
   
9. Create a text file named 'manifest.txt' and add the following text to it (replace 'hostname' with the Web server hostname):
   
   

   Code:
   Manifest-Version: 1.0
   Main-Class: MOJApplet
   Extension-List: all
   all-Extension-Name: all
   all-Specification-Version: 1.0
   all-Implementation-Version: 1.0
   all-Implementation-Vendor-Id: MOJ2002
   all-Implementation-URL: http://hostname/website/mojapp/all.jar

   
   
   

   Note:
   Be sure to press return after the last line, otherwise the last line will not be included.

   
   
10. Create a JAR file containing only the custom manifest file created in the previous step. Use the following command:
    
    

    Code:
    jar -cvfm mojapp_unsigned.jar manifest.txt

    
    The manifest file created in Step 9 is used to store the class name where the init method resides (Main-Class) and the extensions needed by this JAR file (Extension-List) in the META-INF\manifest.mf within the JAR. If multiple extensions are needed, then a space-separated list should be included under the Extension-List parameter. Note that each extension will also be referenced by a name, version, id, and URL. The Implementation-URL parameter is used to locate the JAR file to be used as an extension. The Extention-Name, Specification_Version, and Implementation-Version are all checked to confirm that the correct extension is accessible and utilized by the application contained in this JAR file (mojapp.jar).
11. To use the 'Raw' Java Plug-in installer, all JARs must be signed. When deploying an applet publicly, acquiring a certificate from a recognized authority (such as Verisign) is recommended to avoid inconveniencing clients. This example demonstrates how to create a test certificate to sign the JAR files. The keytool utility included with the Java Development Kit will be used to accomplish this task.
    
    A. Open a command window and navigate to the c:\temp directory.
    
    B. Type the following at a command prompt to create a keystore file 'c:\keystore' in which the test certificate will be stored. Private and public keys are also created in the keystore.
    
    

    Code:
    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

    
    C. Type the following at the command prompt to create a certificate file 'key.cer' in c:\temp. This certificate contains the information to be used as the public key for the MapObjects—Java JAR files.
    
    

    Code:
    keytool -export -alias TestCert -keystore c:\keystore -file key.cer -keypass pw1234 -storepass pw1234

    
    
12. Add the certificate to the registry on the Web server by double-clicking (Windows) or using the following command (UNIX):
    
    

    Code:
    keytool -import -trustcacerts -alias TestCert -file /tmp/key.cer -keystore /usr/jdk1.3/lib/security/cacerts
    

    
    
13. Sign the JARs used by the applet.
    
    A. Navigate to c:\temp\moj and use the following command to create an 'all.jar' file:
    
    

    Code:
    jarsigner -keystore c:\keystore -storepass pw1234 -keypass pw1234 -signedjar all.jar all_unsigned.jar TestCert

    
    B. Navigate to c:\temp\mojapp and use the following command to create a 'mojapp.jar' file:
    
    

    Code:
    jarsigner -keystore c:\keystore -storepass pw1234 -keypass pw1234 -signedjar mojapp.jar mojapp_unsigned.jar TestCert

    
    
14. Navigate to the location of the 'website' virtual directory on your Web server and create a 'mojapp' directory . Within this directory, create an HTML page (mojapp.html) that references the main applet class (MOJApplet) and JAR file (mojapp.jar) containing this class. For example:
    
    

    Code:
    <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" >
      </object>
    </html>

    
    Remember that the manifest file for 'mojapp.jar' contains the syntax mentioned in Step 9. As a result, it is responsible for loading all supporting JARs.
15. Move the mojapp.jar and all.jar files to the c:\website\mojapp directory.
16. Check the \lib\ext directory under the current JRE (for example, C:\Program Files\JavaSoft\JRE\1.3.1_02). Make sure the 'all.jar' file is not present. If it is, delete it.
17. Open a browser, preferably Internet Explorer, and load the HTML page 'mojapp.html' page (for example, http://hostname/website/mojapp/mojapp.html).
18. Click 'Grant this session' when prompted. Note that a download progress bar may or may not appear, depending on the connection speed.
19. If asked to Grant Permission to the test certificate used to sign the JAR files (created in step 11), click 'Grant this session'. The MOJ applet should load. If the Java Plug-in console is active, communication between the applet and the Geography Network should be seen.
20. Note that 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 your HTML document. For example:
    
    

    Code:
    codebase="http://java.sun.com/products/plugin/autodl/jinstall-1_4_0-win.cab#Version=1,4,0,mn"

    
    This code will install JRE 1.4.0 if the Java Plug-in is not detected. See the 'Java Plug-in Developer Guide - Using Tags' link below for additional information.