Simple SOE Walkthrough

Eclipse SOE Plug-in Template Walkthough

The ArcGIS Server for Java Eclipse plug-in provides code templates and wizards to help stub out your SOE’s. Let’s walk through a Hello World SOE by creating a simple SOE class, HelloWorldSOE custom interface, IHelloWorldSOE. This will introduce you to the basic plug-in template wizard components which support the development pattern we introduced in the section prior.

Step 1: Create a Java Project

Start Eclipse and create a new Java Project.

'File -> New -> Project'
Select 'Java -> Java Project' in the New Project wizard and click 'Next'.
Enter a project name in the 'Project Name' field, for example "Hello World SOE".
Click 'Finish' and the new project is created and shown in your project explorer.

Step 2: Create a new SOE and custom interface

With your project selected, right click your source folder, typically 'src' and select 'New -> Other …' from the context window.
Under ESRI templates, there is an ArcGIS Extension folder and a Server sub-folder which lists the ‘Server Object Extension’ as one of its wizards.

Select 'Sever Object Extension' and click 'Next' in the wizard to get started. This opens the 'New Server Object Extension' dialog. In this dialog we create our new Java SOE class infrastructure. There is also an option to implement the IObjectActivate interface to allow you to invoke custom logic upon Server Object context creation and/or create a custom user defined interface that your SOE can implement. You may recall that this pattern allows you to define the business logic of your SOE as an interface for clients to work with.
Under 'Create a new Java Class' enter a package name, for example 'demo', and enter 'HelloWorldSOE' in the Name field. Our Hello World demo will not have any custom logic on invoke of the context so we'll not select 'Customize activation and deactivation behavior'. We will however create a custom interface. Type in 'IHelloWorldSOE' in the 'Create Custom Inteface(s)' text box and click 'Add' to have the interface added to the SOE. At ArcGIS 10, the dialog supports multiple custom interfaces to be generated by the wizard. While technically SOE's have always supported multiple interface implementations, you had to manually create any additional interfaces in prior releases. Click Next.

The next step in the wizard allows us 'Add Properties/Capabilites' to our SOE. 'Enable SOAP Support' implies exposing our SOE as a Web Service by extending SOAPRequestHandler. 'Enable REST Support' implies implementing IRESTRequestHandler interface and exposing our SOE as a REST Web Service. We will not be enabling Web Service support through SOAP or REST in our simple Hello World SOE, so leave all the check boxes empty and click 'Finish'.

A dialog may come up asking you if you would like to add the ArcGIS Library to your build path. Select 'OK' to add the required arcobjects.jar to your projects build path.

The custom ArcGIS Extension Interface, IHelloWorldSOE, and SOE class, HelloWorldSOE, are created for you with all interfaces stubbed out for you and appropriately annotated. At this point you can start to stub out the business logic of your SOE in preparation for deployment with ArcGIS Server.

Step 3: Define the custom interface

An implementer of the SOE should define a custom interface that describes an API for clients to call methods on it. Java SOE’s support Java and ArcObjects data types as well as arrays of Java and ArcObjects data types. You can use these as input and return parameters when you stub out your interface definition to be implemented by your SOE class.

To qualify as being part of an ArcGIS Java Extension the custom interface must be decorated with the @ArcGISExtension annotation. Your Eclipse wizard should have generated the following code output.

[Java]


        package demo;

import com.esri.arcgis.interop.extn.ArcGISExtension;

@ArcGISExtension public interface IHelloWorldSOE{}

We will add a single helloWorld(); method

[Java]


        package demo;

import com.esri.arcgis.interop.extn.ArcGISExtension;

@ArcGISExtension public interface IHelloWorldSOE{
    // Add this method signature
    public String helloWorld();
}

Step 4: Implement the custom interface in the SOE

Now that we have added a method to our custom interface, our SOE should generate an error inside of Eclipse telling us that we need to implement the method we just created in our custom interface.

We can easily resolve this issue by implementing the method in our SOE. Right click the error message in the Eclipse Problems console and select 'Quick Fix' from the context menu. A Quick Fix dialog appears, select 'Add unimplemented methods' and click 'OK'.

This should result in the following code for our HelloWorldSOE class:

[Java]


        package demo;

import java.io.IOException;
import com.esri.arcgis.interop.AutomationException;
import com.esri.arcgis.interop.extn.ArcGISExtension;
import com.esri.arcgis.interop.extn.ServerObjectExtProperties;
import com.esri.arcgis.server.IServerObjectExtension;
import com.esri.arcgis.server.IServerObjectHelper;
import com.esri.arcgis.system.ILog;
import com.esri.arcgis.system.ServerUtilities;

@ArcGISExtension @ServerObjectExtProperties(displayName = "Hello World SOE",
    description = "My first Server 10 SOE")

public class HelloWorldSOE implements IServerObjectExtension, IHelloWorldSOE{
    private IServerObjectHelper soHelper;
    private ILog serverLog;
    public HelloWorldSOE()throws Exception{
        super();
    }

    /****************************************************************************************************************************
     * IServerObjectExtension methods:
     * This is a mandatory interface that must be supported by all SOEs. 
     * This interface is used by the Server Object to manage the lifetime of the SOE and includes 
     * two methods: init() and shutdown(). 
     * The Server Object cocreates the SOE and calls the init() method handing it a back reference 
     * to the Server Object via the Server Object Helper argument. The Server Object Helper implements 
     * a weak reference on the Server Object. The extension can keep a strong reference on the Server 
     * Object Helper (for example, in a member variable) but should not keep a strong reference 
     * on the Server Object. 
     *    
     * The log entries are merely informative and completely optional. 
     ****************************************************************************************************************************/
    /**
     * init() is called once, when the instance of the SOE is created. 
     */
    public void init(IServerObjectHelper soh)throws IOException, AutomationException{
        /*
         * An SOE should get the Server Object from the Server Object Helper in order to make any 
         * method calls on the Server Object and release the reference after making the method calls.
         */
        this.soHelper = soh;
        this.serverLog = ServerUtilities.getServerLogger();
    }
    /**
     * shutdown() is called once when the Server Object's context is being shut down and is 
     * about to go away.
     */
    public void shutdown()throws IOException, AutomationException{
        /*
         * The SOE should release its reference on the Server Object Helper.
         */
        this.soHelper = null;
        this.serverLog = null;
    }
    @Override public String helloWorld(){
        // TODO Auto-generated method stub
        return null;
    }
}

Change the helloWorld() method signature to the following code snippet to return a string declaring Hello World!

[Java]


        @Override public String helloWorld(){
    String message = "Hello World from our first SOE";
    return message;
}

Congratulations, you have just created your first SOE and custom interface. As you can see, SOE's by themselves simply implement custom business logic, they need to extend a Server Object and be consumed by a client application to be useful. The next two sections will detail how we deploy, register, enable, and consume our Hello World SOE.