This guide will assist you in writing ESJMap based java applications.
Upon installing Xmarc'c Enterprise Spatial Product Suite into your installation directory (referred to as <XMARC_ROOT> from now on), note the highlighted sub-directory. This is the directory where the ESJMap API class library, esjmap.jar, resides.
You will need to ensure that your CLASSPATH environment setting includes this jar file when building ESJMap based applications - but more on this later.
You will need the following products:
Please refer to the relevent web server and/or servlet engine documentation for installation intructions. It will be assumed that these products have been installed and configured.
You will need to ensure that your classpath environment variable has been configured correctly in order to compile and run your ESJmap java application. This typically involves setting CLASSPATH to include esjmap.jar. For example, on a Microsoft-based platform, you would set CLASSPATH as follows:
set CLASSPATH=.;<XMARC_ROOT>\es\es_jmap\esjmap.jar
Let's look at building and deploying, a very simple JMap applet - our version of "Hello World". It will be assumed that you are familar with writing Java applets. The following discussion is based on the code example below:
import javax.swing.JApplet;
import java.awt.SystemColor;
import java.awt.BorderLayout;
import com.xmarc.es.*;
public class helloworld extends JApplet {
ESMapWindow mapwin;
ESLegendWindow legend;
ESToolBar toolbar;
public void init() {
String szESMSVCURL = getParameter("esm_svc_url"); // ESM Service URL (from HTML page)
String szESMCollection = getParameter("esm_collection"); // ESM Collection
String szESMLocation = getParameter("esm_location"); // ESM Location
getContentPane().setLayout(new BorderLayout()); // Set layout style as Border (default is FlowLayout)
mapwin = new ESMapWindow(); // Create a new ESM Map Window
mapwin.setServiceURL(szESMSVCURL); // Set ESM Service URL
mapwin.setSiteLocation(szESMLocation); // ESM Location to use for data services
mapwin.setCollection(szESMCollection); // Assign the ESM Collection
setBackground(SystemColor.control); // Background color eg; (Color.green)
toolbar = new ESToolBar(); // new toolbar
legend = new ESLegendWindow(120); // new ES Legend Window (120 Pixels wide)
getContentPane().add("North", toolbar); // add toolbar to applet
getContentPane().add("West", legend); // add legend to applet
getContentPane().add("Center", mapwin); // add main ESM Map Window
mapwin.refresh(); // start everything off
}
}
As you can see, all we do is override the init() method in the Appplet class. Here, we set up where to locate the ESM metadata service (i.e. the ESM Service URL, the ESM Collection name and the ESM Location name). We then create a window for the data to be displayed in, create an ES Toolbar object and an ES Legendbar object. These are then simply added into the applet's frame.
To build this applet (assuming your path environment is set correctly to locate javac), issue the following command:
javac helloworld.java
from the command line in the same directory as the source file. The esj_quick_start.html compiler will create a new file called helloworld.class in the current directory.
In order to test the applet we will need to create an HTML file which includes this applet:
<HTML>
<APPLET CODE="helloworld.class" ARCHIVE="esjmap.jar" WIDTH=640 HEIGHT=480>
<PARAM NAME="esm_svc_url" VALUE="http://svr1/xmarc/Broker?service=ESM2_SVC">
<PARAM NAME="esm_collection" VALUE="Default">
<PARAM NAME="esm_location" VALUE="Web">
</APPLET>
</HTML>
As you can see, this assumes the Web services are registered to the web server running on the host "svr1".
To deploy the application on the Internet or Intranet, you will need to add the above HTML file to your Web server's directory, along with esjmap.jar and any other resources you reference from within your Java applet code.
Note: The ESM service and any data service(s) will also need to be registered to the same Web server due to the browser applet security model which specifies that any data sources that an applet requires must be loaded from the same Web server that delivered the applet.
If all goes according to plan, you should see a similar result to the figure below (assuming you are hitting the TUTORIAL data services):
Note: colors and symbologies will depend on how you have configured the ESM service via the ESM Admin tool.
As noted at the beginning, building ESJMap applications/applets requires JDK 1.3 or later. This will have implications when deploying applets, as not all browsers are created equal. If you were to hit the above URL using Microsoft's Internet Explorer (actually, the ESJMap API would need to be packaged as a CAB file rather than a JAR file in order for Internet Explorer to attempt a download and run the helloworld.class applet) you will not get the desired result due to the JVM version (which is 1.1.x based) that Microsoft uses within Internet Explorer.
A solution to this problem is by way of a browser's plug-in technology. By using a Java Plug-in we can guarentee the applet will execute within the correct JVM environment. Refer to Sun's Java Plug-in Product for further details.
To allow us to deploy the helloworld applet to a wider audience that includes Internet Explorer users, we need to alter our HTML code. This task is simplified by using a utility that is provided along with Sun's JDK 1.3.1 or later, called HTML Converter. The figure shown below shows the HTML Converter program in action.
Note: the value for the "Template File:" field has been set to "Standard (IE & Navigator) for Windows & Solaris Only).
Our sample HTML code after the conversion process is shown below:
<HTML>
<!--"CONVERTED_APPLET"-->
<!-- HTML CONVERTER -->
<OBJECT
classid = "clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
codebase = "http://java.sun.com/products/plugin/autodl/jinstall-1_4-windows-i586.cab#Version=1,4,0,0"
WIDTH = 640 HEIGHT = 480 >
<PARAM NAME = CODE VALUE = "helloworld.class" >
<PARAM NAME = ARCHIVE VALUE = "esjmap.jar" >
<PARAM NAME = "type" VALUE = "application/x-java-applet;version=1.4">
<PARAM NAME = "scriptable" VALUE = "false">
<PARAM NAME = "esm_svc_url" VALUE="http://svr1/xmarc/Broker?service=ESM2_SVC">
<PARAM NAME = "esm_collection" VALUE="Default">
<PARAM NAME = "esm_location" VALUE="Web">
<COMMENT>
<EMBED
type = "application/x-java-applet;version=1.4"
CODE = "helloworld.class"
ARCHIVE = "esjmap.jar"
WIDTH = 640
HEIGHT = 480
esm_svc_url ="http://svr1/xmarc/Broker?service=ESM2_SVC"
esm_collection ="Default"
esm_location ="Web"
scriptable = false
pluginspage = "http://java.sun.com/products/plugin/index.html#download">
<NOEMBED>
</NOEMBED>
</EMBED>
</COMMENT>
</OBJECT>
<!--
<APPLET CODE = "helloworld.class" ARCHIVE = "esjmap.jar" WIDTH = 640 HEIGHT = 480>
<PARAM NAME = "esm_svc_url" VALUE="http://svr1/xmarc/Broker?service=ESM2_SVC">
<PARAM NAME = "esm_collection" VALUE="Default">
<PARAM NAME = "esm_location" VALUE="Web">
</APPLET>
-->
<!--"END_CONVERTED_APPLET"-->
</HTML>
Although significantly more complicated than our original HTML code, this file will now support a variety of browsers runining on various operating systems including requests originating from Microsoft Internet Explorer browsers. The above code will cause Sun's JVM plug-in to be installed on the client's machine (in an identical manner as say Adobe's Acrobat Reader program is installed, to allow you to view .pdf files). See here for more details on the whole process.
Click here to goto the Java documentation for the ESJMap API.