Deploy MapObjects Java in an applet

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 Java Plug-In by Sun. 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 Java Extensions mechanism included with a JRE provides Java applications with immediate access to classes included in the lib/ext directory for the respective 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 applications classpath. Deploying a Java applet using the Java Plug-In usually involves installing a jar or series of 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:

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.

2) Java Installer

A custom Java application is responsible for managing the installation of the jar files associated with and 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 applets jar files on the client machine.

3) Native Installer

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

Additional details on the Java Extensions Mechanism can be found by clicking the link given below in Related Information.



Procedure
In this document, the Raw Java Extensions method for deploying applets is discussed and an example is provided. Note that this method requires minimal development and is freely accessible through the Java Plug-In.

Use the following steps to deploy a MapObjects Java applet using the Java Extensions mechanism (note, this example assumes that you have access to a web server):



The \lib directory under the MapObjects Java installation location contains the libraries (jars, dlls) utilized by a MapObjects Java application. Copy all jar files from this location to a temporary location (e.g. c:\temp\moj). Note that 2 dlls are present in this directory. They are not required for a MapObjects Java applet to function and are relatively large, thus they will not be included.

Unjar each jar file in this location. Use WinZip or the JDK jar (jar -xvf <jar-file>) command.

Navigate to the META-INF directory. Delete only the ESRI.DSA, ESRI.SF, and MANIFEST.MF files.
The following class creates a MapObjects Java applet containing a single ArcIMS Image Service layer from the Geography Network:


import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
import com.esri.mo.ui.bean.*;
import com.esri.mo.ui.tb.*;
import java.applet.Applet;

public class MOJApplet extends JApplet {

  public void init(){

com.esri.mo.ui.bean.Map map1 = new com.esri.mo.ui.bean.Map();
com.esri.mo.ui.bean.Toc toc1 = new com.esri.mo.ui.bean.Toc();

Container contentPane = getContentPane();
JSplitPane jSplitPane1 = new JSplitPane();

setSize(new Dimension(400, 300));

com.esri.mo.ui.bean.Layer layer_img = new com.esri.mo.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);
  
  }
}



Copy and paste the above contents into a new text file and save it as "MOJApplet.java".

Compile MOJApplet.java to create the MOJApplet.class file.

Create a text file named "manifest.txt" and add the following text to it:

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


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


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

jar -cvfm all_unsigned.jar manifest.txt .


The all.jar file will be created and contain all the classes needed for a MapObjects Java application\applet, namely the applet code and core MapObjects Java classes. The manifest file created in step 6 is used to store version information (manifest, specification, and implementation) and well as 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.

Create a temporary directory (e.g. c:\temp\mojapp) to contain the manifest used to locate and install the extensions needed by the MapObjects Java applet.

Create a text file named "manifest.txt" and add the following text to it (replace "hostname" with your web server hostname):

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


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


Create a jar file containing only the custom manifest file created in step 9. Use the following command:

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, 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 check to confirm that the correct extension is accessible and utilized by the application contained in this jar file (mojapp.jar).

In order to use the "Raw" Java Plug-in installer, all jars must be signed. When deploying an applet publicly, you may want to acquire a certificate from a recognized authority (e.g. Verisign) to avoid inconveniencing your clients. In this example, we will create a test certificate to sign our jar files. The keytool utility included with the Java Development Kit will be used to accomplish this task. Open a command window and navigate to the c:\temp directory. Type the following at a command prompt:

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


This creates a keystore file on the c drive called "c:\keystore" in which the test certificate will be stored. A private and public are also created in the keystore.

To create the certificate, type the following at the command prompt:

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


This creates a certificate file "key.cer" in c:\temp. This certificate contains the information to be used as the public key for the Map Objects Java jar files. Add this certificate to the registry on the web server by double-clicking (Windows) or using the following command (UNIX):

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


Sign the jars used by the applet. Navigate to c:\temp\moj and use the following command:

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


This should create a "all.jar" file. Navigate to c:\temp\mojapp and use the following command:

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


This should create a "mojapp.jar" file.

Navigate to c:\website and create a "mojapp" directory (or the location of the "website" virtual directory on your web server). 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:

<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 the "mojapp.jar" contains the syntax mentioned in step 9. As a result, it is responsible for loading all supporting jars.

Move the mojapp.jar and all.jar to c:\website\mojapp directory.

Check the \lib\ext directory under the current JRE (e.g. C:\Program Files\JavaSoft\JRE\1.3.1_02). Make sure the "all.jar" file is not present. If it is, delete it.

Open a browser (preferably Internet Explorer) and load the HTML page "mojapp.html" page (for example, http://hostname/website/mojapp/mojapp.html").

You will be prompted to grant permission to install the "all" extension. Click "Grant this session". Note that you may or may not see a download progress bar, depending on your connection speed.

You may be asked to Grant Permission to the test certificate used to sign the jar files (created in step 11). Click "Grant this session". The MapObjects Java applet should load. If the Java Plug-in console is active, you should see communication between the applet and the Geography Network.