How to create a console based HelloWorld application with ArcObjects—ArcObjects 10.4 Help for Java

Summary

This topic shows you how to create a console based Java ArcObjects application. It also provides instructions for compiling and running ArcGIS Engine applications using the ArcObjects application programming interface (API) without an integrated development environment (IDE).

Console based HelloWorld application

The following code example is for an ArcObjects application that prints the active data frame in a map document (.mxd file) to the console window:

[Java]


        // Example 1: Hello ArcObjects!
import java.io.IOException;
import com.esri.arcgis.system.AoInitialize;
import com.esri.arcgis.system.EngineInitializer;
import com.esri.arcgis.system.esriLicenseProductCode;
import com.esri.arcgis.system.esriLicenseStatus;
import com.esri.arcgis.carto.MapServer;
public class EngineHelloWorld{
    public static void main(String[] args){
        try{
            //Step 1: Initialize the Java Componet Object Model (COM) Interop.
            EngineInitializer.initializeEngine();

            //Step 2: Initialize an ArcGIS license.
            AoInitialize aoInit = new AoInitialize();
            initializeArcGISLicenses(aoInit);

            //Step 3: Invoke ArcObjects.
            MapServer mapServer = new MapServer();

            String DevKitInstallDir = System.getenv("AGSDEVKITJAVA");

            mapServer.connect(DevKitInstallDir + 
                "/java/samples/data/mxds/brazil.mxd");

            String name = mapServer.getDefaultMapName();

            System.out.println("Hello, ArcObjects!: " + name);

            //Step 4: Release the license.
            aoInit.shutdown();
        }
        catch (IOException ex){
            System.out.println(ex.getMessage());
            System.out.println("App failed.");
        }
    } //End of method main.

    //License initialization 
    static void initializeArcGISLicenses(AoInitialize aoInit){
        try{
            if (aoInit.isProductCodeAvailable
                (esriLicenseProductCode.esriLicenseProductCodeEngine) ==
                esriLicenseStatus.esriLicenseAvailable){
                aoInit.initialize
                    (esriLicenseProductCode.esriLicenseProductCodeEngine);
            }
            else if (aoInit.isProductCodeAvailable
                (esriLicenseProductCode.esriLicenseProductCodeBasic) ==
                esriLicenseStatus.esriLicenseAvailable){
                aoInit.initialize(esriLicenseProductCode.esriLicenseProductCodeBasic)
                    ;
            }
            else{
                System.err.println(
                    "Engine Runtime or Desktop Basic license not initialized.");
                System.err.println("Exiting application.");
                System.exit( - 1);
            }
        }
        catch (Exception e){
            e.printStackTrace();
        }
    } //End of method initializeArcGISLicenses
} //End of class:EngineHelloWorld.

Analyzing the program

Initialize the Java COM Interop—It is essential to initialize ArcObjects Java applications to set up the communication between the native COM ArcObjects components and corresponding Java classes through the Java COM Interop, which the EngineInitializer class performs.
Initialize a valid License—The initialize() method of the AoInitialize object establishes permissions to access appropriate ArcObjects through licensing and checking out extensions. ArcObjects based applications can run against the ArcGIS Engine Runtime license or if available and coded appropriately, an ArcGIS Desktop license, such as Basic, Standard, or Advanced. For more licensing information, see Licensing and deployments.
Invoke ArcObjects—A simple ArcObject, MapServer (com.esri.arcgis.carto) is created. The MapServer ArcObject provides programmatic access to the contents of a map document (.mxd file) on disk and creates images of the map contents based on user requests.

In this example, the connect method of the MapServer class is invoked to initialize the map server with a map document (.mxd file) stored at the specified path. Another simple method, getDefaultMapName, is invoked on the MapServer ArcObject that returns the active map name (i.e. the name of the active data frame).

Release the license—It is good programming practice to release the license. The shutdown method of the AoInitialize releases resources and informs ArcObjects that its services are no longer needed. Also, AoInitialize is a singleton class; therefore, do not worry that you're shutting down a different system than the one you initialized earlier. However, as shown in the code segment above, save a reference to the first AoInitialize object and use it to invoke the shutdown method.

In the example program, the caught exception is an IOException. Nearly all ArcObjects exceptions thrown in Java are an IOException or AutomationException, which is a subclass of IOException.

Compiling and running the application

The ArcObjects Java application can be compiled and run like any other Java application. The following initial steps are required to successfully compile and run any ArcObjects Java application:

The Java compiler needs to be aware of the location of the referenced ArcObjects classes. The ArcGIS Engine Runtime as well as ArcGIS Desktop contains all the ArcObjects classes packaged into a set of Java Archive (JAR) files (arcobjects.jar). Depending on the product you have installed on your machine, this .jar file is typically located in either the <AGSDESKTOPJAVA>\java\lib or <AGSENGINEJAVA>\java\lib folder or potentially both if you have both products installed. You need to include this .jar file in your classpath when compiling the ArcObjects Java application. Assuming you have ArcGIS Engine Runtime and a supported JDK installed, to compile the ArcObjects application, run the following command:

On Windows platforms execute:

javac EngineHelloWorld.java -cp "%AGSENGINEJAVA%\java\lib\arcobjects.jar"

On UNIX platforms, source the init_devkit script (.sh or .csh, located in your <DevKitInstallDir>) to automatically setup the necessary environment variables and execute:

javac EngineHelloWorld.java -cp "$AGSENGINEJAVA\java\lib\arcobjects.jar"

The same applies to the Java interpreter (i.e. Java Runtime Environment or JRE):

On Windows platforms run the following command:

java -cp "%AGSENGINEJAVA%\java\lib\arcobjects.jar;." EngineHelloWorld

On Unix platforms, run the following command at your command line or shell:

java -cp "$AGSENGINEJAVA\java\lib\arcobjects.jar:." EngineHelloWorld

Output of the program

Finally, if you see the Hello, ArcObjects!: Geography output when running the ArcObjects application from your console, you have created your first non-visual ArcObjects application. Geography is the active data frame for the brazil.mxd map document.

Development licensing	Deployment licensing
Engine Developer Kit	ArcGIS for Desktop Basic
	ArcGIS for Desktop Standard
	ArcGIS for Desktop Advanced
	Engine