Adding properties to Java SOEs

Summary
Properties allow server administrators to modify how an SOE behaves when enabled on a particular service.

Properties are typically created and initialized as attributes of the @ServerObjectExtProperties annotation during SOE creation time (if using Eclipse wizard). During SOE development, these properties need to be woven into the SOE’s business logic for them to have any influence on the SOE’s runtime behavior. Post-deployment, as an ArcGIS Server administrator, you can modify values of these properties, thereby influencing execution of your SOE’s business logic.
The following will walk you through creating a REST SOE that has one property and one subresource. The value of this property will define the runtime behavior of the subresource.
 
  1. Create a REST SOE called “SimpleRESTSOEWithProperties” using the Eclipse SOE creation wizard. To learn more about creating a REST SOE using the Eclipse SOE creation wizard, see the “Developing REST SOEs Using Java” topic.
 
  1. On the second page of the SOE creation wizard, ensure that the “REST Support” tab is visible, check the “Enable REST Support” check box and add one subresource called “layers”. At run time, this subresource will return information about all layers in the map service. Click Next.
 
  1. Select the “Properties” tab and check the “Add properties” check box. This displays a dialog box to add properties, as follows:
 
 
  1. Click Add to add a property called layerType. Provide a default value “feature”. The value of the layerType property will dictate the type of layer returned by the “layers” subresource.
 
 
 
  1. Click “OK”.
  2. Uncheck the “Customize property page for ArcGIS Server Manager” check box. By unchecking this check box, you indicate that you do not want to create a custom property page for ArcGIS Server Manager. To learn more about such property pages, see the “Creating Custom Property Pages for Manager” topic.
  3. Uncheck the “Create a Java Swing” check box. By unchecking this check box, you indicate that you do not want to create a property page for ArcGIS for Desktop (ArcMap/ArcCatalog). To learn more about such property pages, see the “Creating Custom Property Pages for ArcMap” topic.
  4. Click "Finish". The wizard will now generate code for SOE based on choices you made in the wizard.
  5. Inspect the Java SOE class called SimpleRESTSOEWithProperties.java. Note that the ServerObjectExtProperties annotation now includes an attribute called properties, which has a name=value pair corresponding to the “layerType” property you created in the Eclipse wizard.
[Java] 
@ServerObjectExtProperties(displayName = "Simple REST SOE With Properties",
    description = "Simple REST SOE With Properties", properties = {
    "layerType=feature"
}

)
  1. Add a global member to the SimpleRESTSOEWithProperties SOE class called “layerType”.
[Java] 
private String layerType;
  1. Initialize the SOE.
[Java] 
public class SimpleRESTSOE implements IServerObjectExtension, IRESTRequestHandler{
    private static final long serialVersionUID = 1L;
    private IServerObjectHelper soHelper;
    private ILog serverLog;
    private IMapServerDataAccess mapServerDataAccess;
    private IMapLayerInfos layerInfos;

    public SimpleRESTSOE()throws Exception{
        super();
    }

    /**
     * init() is called once, when the instance of the SOE is created.
     */
    public void init(IServerObjectHelper soh)throws IOException, AutomationException{
        this.soHelper = soh;
        this.serverLog = ServerUtilities.getServerLogger();
        this.mapServerDataAccess = (IMapServerDataAccess)this.soHelper
            .getServerObject();

        IMapServer3 ms = (IMapServer3)this.soHelper.getServerObject();
        IMapServerInfo mapServerInfo = ms.getServerInfo(ms.getDefaultMapName());
        this.layerInfos = mapServerInfo.getMapLayerInfos();

        serverLog.addMessage(3, 200, "Initialized " + this.getClass().getName() + 
            " SOE.");
    }

    /**
     * shutdown() is called once when map service is shutting down
     */
    public void shutdown()throws IOException, AutomationException{
        serverLog.addMessage(3, 200, "Shutting down " + this.getClass().getName() + 
            " SOE.");
        this.soHelper = null;
        this.serverLog = null;
        this.mapServerDataAccess = null;
    }
  1. Scroll down to the construct() method. This method takes in an IPropertySet as its parameter. This property set is hydrated at run time when you modify the SOE’s properties in ArcGIS Server Manager or ArcMap, and is later passed on to the construct() method. This method, therefore, holds the logic that handles the change in behavior of the SOE at run time.
  1. Modify the construct() method to capture the “layerType” property from the property set.
[Java] 
public void construct(IPropertySet propertySet)throws IOException{
    // Retrieve layer type.
    this.layerType = (String)propertySet.getProperty("layerType");
}
  1. Copy the following code snippet into your SOE class. This method returns layer information for layers of the type indicated by the layerType property. It’s called when the “layers” subresource is invoked by end users in the Services Directory or a client web app.
[Java] 
public byte[] getLayersInfo()throws Exception{
    String aoLayerType = "";
    if (this.layerType.equalsIgnoreCase("feature")){
        aoLayerType = "Feature Layer";
    }
    else if (this.layerType.equalsIgnoreCase("raster")){
        aoLayerType = "Raster Layer";
    }
    else if (this.layerType.equalsIgnoreCase("dataset")){
        aoLayerType = "Network Dataset Layer";
    }
    else{
        return ServerUtilities.sendError(1, 
            "Propety layerType has invalid value. Acceptable values are \"feature\", \"raster\", and \"dataset\".", null).getBytes("utf-8");
    }

    int layerTypeCount = 0;
    JSONObject json = new JSONObject();
    JSONArray layerArray = new JSONArray();
    for (int i = 0; i < layerInfos.getCount(); i++){
        IMapLayerInfo layerInfo = layerInfos.getElement(i);
        String lType = layerInfo.getType();
        if (lType.equalsIgnoreCase(aoLayerType)){
            JSONObject layerJSON = new JSONObject();
            layerJSON.put("name", layerInfo.getName());
            layerJSON.put("type", lType);
            layerJSON.put("id", layerInfo.getID());
            layerJSON.put("description", layerInfo.getDescription());
            layerArray.put(layerTypeCount, layerJSON);
            layerTypeCount++;
        }
    }
    json.put(this.layerType + " layerCount", layerTypeCount);
    json.put("layersInfo", layerArray);
    return json.toString().getBytes();
}
  1. Export your Java SOE using the “Export SOE” wizard. To learn more about use of this wizard, please see the “Developing REST SOEs Using Java” topic.
  2. Deploy your Java SOE using ArcGIS Server Manager.
  3. Enable your Java SOE on a map service. When the SOE is highlighted, the Properties section displays the layerType property with the default value you set in the Eclipse wizard.

 
 
  1. Save and restart the map service and open it in the Services Directory. Click the SOE in the “Supported Resources” section, then click the “layers” subresource. It displays all layers of type feature.
 
  1. Edit the map service again and modify the layerType property value to “raster”. Save and restart the map service.
 
  1. Access the “layer” subresource on the SOE. It should now display only layers of type raster.
 
 
The Java ArcObjects SDK includes a sample called SimpleRESTSOEWithProperties, which demonstrates development and use of properties in SOEs.
 
As mentioned earlier, SOE property values could be edited in ArcMap or ArcGIS Server Manager. To learn how to edit property values in ArcMap, see the “Creating custom property pages for ArcMap” topic.
 
Manager, too, provides a property editing experience in the Capabilities section of the map service properties, as mentioned previously. However, by default, Manager renders simple text boxes that administrators can use to edit property values. If more advanced UI controls are desired, such a custom property page must be created and packaged along with the SOE. To learn more, see “Creating Custom Property Pages For Manager”.





Development licensingDeployment licensing
ServerServer