Deployment guide


Summary
ArcGIS Engine Java applications can be deployed using standard Java deployment technologies; executable Java Archive (JARs) files, the Java Web Start application, and launching scripts.

In this topic


Prerequisites

The ArcGIS Engine Runtime and Java Runtime Environment (JRE) is a complete runtime environment for ArcGIS Engine Java applications.
When an ArcGIS Engine Runtime and a supported JRE are installed on a system, any ArcGIS Engine Java application can execute on that system. An ArcGIS Desktop installation also acts as an ArcGIS Engine Runtime—any ArcGIS Engine Java application can run on a computer with ArcGIS Desktop and a supported JRE installed.
The following are the recommended methods for deploying ArcGIS Engine Runtime:
Java desktop applications are deployed using the following technologies:
These deployment technologies require access to arcobjects.jar. For more information, see Bootstrapping arcobjects.jar in this topic.

Executable JAR

An executable JAR is a type of Java archive that packages together the application code (class files) and resources (images, sound, and so on) in a single executable file that can be used to launch the application by double-clicking the file or using the Java –jar <filename.jar> command.
Executable JARs make it easy to package, distribute, install, and launch Java applications. They also reference classes in other JAR files specified in the Class–Path header of the JAR's manifest. This can be used to specify the location of arcobjects.jar if it is relative to the location of the application JAR. For example, if you are placing your executable JAR relative to %AGSENGINEJAVA%, you can use the Class–Path header to refer to the location of arcobjects.jar.
For more information on using the Class–Path header field in the manifest, see the Java tutorial, Packaging Programs in JAR Files on the Sun Developer Network (SDN) Web site.

Creating an executable JAR

To create an executable JAR, compile the Java code to generate class files and create a manifest file containing the following code example:
[Java]
Manifest - Version: 1.0 Main - Class: com.vendor.application.Main Class - Path: .. /
    .. /  < relative path to >  / arcobjects.jar
  • End the name of the file with the .mf suffix and end the file with a blank line. If the relative path to arcobjects.jar is not known when the executable JAR is created, bootstrap arcobjects.jar. For more information, see Bootstrapping arcobjects.jar in this topic.
  • Type the following code example to create the JAR file. The input files must include class files, images, or sounds that the program uses.
[Java]
jar - cmf manifest - file app.jar input - files
  • Type the following code example to view the contents of the JAR:
[Java]
jar - tvf jar - file
  • Execute the application using the following code example or double-click the JAR file:
[Java]
java - jar app.jar

Java Web Start application

Create a JAR file of the application using the previous instructions and use the bootstrapping mechanism explained previously to locate arcobjects.jar. The arcobjects.jar file is treated as a run time component and should not be bundled with your application or downloaded as a resource.jar from the Web Start application. Do the following if you created app.jar:
[Java]
keytool - genkey - keyalg RSA - keystore keystore.ks - alias myalias
  • Sign the JAR file—Using the jarsigner utility and the keystore file previously generated, sign the JAR file. See the following code example (myalias is the alias and mypass is the password for the keystore):
[Java]
jarsigner - keystore keystore.ks - storepass abc123 - keypass mypass app.jar myalias
The following code example shows a sample .jnlp file:
[XML]

**********************************************************************************************************************<jnlp spec="1.0" codebase="http://EDN:8080/examples/demos/" href="enginedemo.jnlp">
  <information>
    <title>ArcGISEngine Java
    </title>
    <vendor>Environmental Systems Research Institute</vendor>
    <icon href="images/arcgis_globe.gif"/>
    <icon kind="splash" href="images/arcgis_globe.gif"/>
    <offline-allowed/>
    <description>Demo</description>
  </information>
  <security>
    <all-permissions/>
  </security>
  <application-desc main-class="com.example.Demo"/>
  <resources>
    <j2se version="1.4+"/>
    <jar href="jar/jintegra.jar"/>
    <jar href="jar/arcobjects.jar"/>
  </resources>
  <component-desc/>
</jnlp>

**********************************************************************************************************************
  • Serve the .jnlp file using a server—Create a link on your Web page and point to the .jnlp file to which your users connect and launch ArcGIS Engine applications using Java Web Start. For more information, see the Java Web Start reference documentation on the SDN Web site.

Bootstrapping arcobjects.jar

The ArcGIS Engine Java library is installed with ArcGIS Engine at %AGSENGINEJAVA%/java/lib/arcobjects.jar. It is recommended that ArcGIS Engine Java applications use this JAR file and do not redistribute arcobjects.jar with their applications. Using the pre-installed arcobjects.jar ensures version compatibility and keeps the size of application JARs as small as possible.
Since all ArcGIS Engine Java applications reference class files from the arcobjects.jar library, arcobjects.jar should be present in the Java classpath when the applications are run. In some cases, the location of arcobjects.jar is not known relative to the application JAR. This is the case with Web Start applications and executable JARs. In such cases, the following helper utility can dynamically load arcobjects.jar from its location on disk.
To use this utility, add the following Java class to your application and make it the entry point in your application. Invoke your application's main method from the bootstrapper's main method:
[Java]
//Replace the following line with the name of your main application.
App.main(args);
No change is required in your main application. Make sure that the first call in the other Java class is still the EngineInitializer call.
See the following code example:
[Java]
//Bootstrapper.java. 
import java.io.File;
import java.io.IOException;
import java.lang.reflect.Method;
import java.net.URL;
import java.net.URLClassLoader;
import com.esri.arcgis.geometry.Point;
import com.esri.arcgis.system.AoInitialize;
import com.esri.arcgis.system.EngineInitializer;
import com.esri.arcgis.system.esriLicenseProductCode;
public class Bootstrapper{
    public static void main(String[] args)throws Exception{
        bootstrapArcobjectsJar();
        //Replace the following line with the name of your main application.
        // App.main(args);
        Globe3DEventBug.main(args);
        System.out.println("done.");
    }

    public static void bootstrapArcobjectsJar(){
        String arcEngineHome = System.getenv("AGSENGINEJAVA");
        String jarPath = arcEngineHome + "java" + File.separator + "lib" +
            File.separator + "arcobjects.jar";

        File f = new File(jarPath);

        URLClassLoader sysloader = (URLClassLoader)ClassLoader.getSystemClassLoader()
            ;
        Class sysclass = URLClassLoader.class;

        try{

            Method method = sysclass.getDeclaredMethod("addURL", new Class[]{
                URL.class
            }
            );
            method.setAccessible(true);
            method.invoke(sysloader, new Object[]{
                f.toURL()
            }
            );

        }
        catch (Throwable t){

            t.printStackTrace();
            System.err.println("Could not add arcobjects.jar to system classloader");

        }
    }
}
The following error may appear, while bootstrapping arcobjects.jar. This happens because the Java Security Manager prevents the code in arcobjects.jar from setting system properties. As a work-around, you may need to disable the security manager for your application by calling System.setSecurityManager(null) at the beginning of your application. 
[Java]
java.security.AccessControlException: access denied(java.util.PropertyPermission
    ARCGIS_NATIVE_MODE write)

Launching scripts

Java applications are commonly started using shortcuts to launch scripts. On Windows, batch files can be used to launch ArcGIS Engine Java applications. Create a batch file with the following code example, and save it with the .bat extension:
[Java]
java � � �classpath "%AGSENGINEJAVA%/java/lib/arcobjects.jar;app.jar"
    com.vendor.application.Main
When running the batch file, the Java application will be launched. For graphical user interface (GUI) applications, use javaw.exe instead of java.exe. This prevents an additional command window from opening when the batch script is run. Shell scripts can similarly be used on UNIX.