.4Deploying and Managing Server Object Extensions

Summary Once SOE's are developed, you need to go through three steps to prepare your SOE for consumption by a client application, deployment, registration, and enablement. Fortunately, all three of these steps are automated or wizard driven for you which simplifies the process altogether. In this topic we will discuss all three steps required to prepare your SOE for consumption. After reading this topic you will be able to easily go through the steps in preparation for client applications to consume your SOE.

In order for clients to interact with SOE’s, the SOE needs to go through the following three steps:
  1. Deploy SOE to ArcGIS Server
  2. Register SOE to a Map Service Server Object Type
  3. Enable the SOE as a capability on a running Map Service

Deploy SOE to ArcGIS Server


To create a valid SOE for deployment you must package your entire SOE classes, interfaces, and configuration files into a Java Archive (JAR) file.  This is easily done inside of your Eclipse developer IDE by right clicking on your SOE project folder and selecting ‘Export’.  This will bring up the Export wizard of which you can choose ‘Jar file’ under the ‘Java’ folder. 
The next step in the wizard allows you to select the files you would like to include in the Jar file and select the export destination. 
Be sure to drill down into your project folder structure to ensure all your intended files are included in the Jar and select your deployment directory as your export destination. 

Optionally, you can use the Java Jar command to create the SOE Jar library and manually copy the resulting Jar file to the deployment directory.  Typical usage of the command to combine files into a Jar file is:
jar cf HelloWorldSOE.jar *.class
If your SOE is dependant on any third party jars, you will need to create a custom manifest file that includes the dependant jar libraries in the 'Class-Path' header entry.  An example custom manifest file is offered below: 
Manifest-Version: 1.0
Class-Path: jar1-name jar2-name directory-name/jar3-name
Your Jar file command would change to include the manifest file: 
jar cfm <jar-file-name> <manifest-file-name> <packagename>/*.class
For a complete reference on the Java Jar command visit the Java Jar tutorial. 
For a complete reference on adding classes to the Jar files classpath visit the Java Adding Classes to the JAR File's Classpath tutorial. 

AutoDeploy

Once your SOE is exported to a jar file, it needs to be deployed to ArcGIS.  ArcGIS Server has an autodeploy mechanism on all SOE's deployed to the '<ARCGIS-SERVER-HOME>'\java\lib\ext\' directory.  This simplifies deployment as any SOE's that are copied to this folder are automatically recognized by ArcGIS Server withouth the need to restart the server. To deploy the SOE, copy the jar file to '<ARCGIS-SERVER-HOME>'\java\lib\ext\' folder.  Your SOE is now deployed to ArcGIS Server. 

Register SOE with Map Server Object

The ArcGIS Server for Java Manager administration application is used to manage your SOE's by providing registration and unregistration features integrated into the application.  ArcGIS Server Manager for Java will automatically recognize all SOE's that are auto-deployed to the '<ARCGIS-SERVER-HOME>'\java\lib\ext\' directory.  This greatly simplifies the management of deployed SOE's. 
 

Register SOE

Use the following steps in ArcGIS Manager to register your SOE’s.
  1. Open up ArcGIS Manager in your web browser and log in with an 'agsadmin' account.
  2. Under 'GIS Server', select 'Manage Extensions' to see a list of deployed SOE's. 
  3. Your list of deployed SOE's will show up in the main manager pane
 
 
  1. Under Status, a check appears on SOE's that are already registered and an exclamation triangle appears on SOE's that have not been registered. 
  2. Click on the 'Register' link next to your SOE.
  3. Once complete, Manager will return a message indicating that your SOE has been successfully registered and the status icon will change to a check. 

Unregister SOE

To unregister your SOE, simply click on the Unregister link next to a registered SOE.  YOu will be prompted with a dialog to ensure you want to proceed. 
Click Yes, if you are sure you want to unregister the SOE and Manager will return a message indicating that your SOE has been successfully unregistered. 
The Manage Extensions page in ArcGIS Server Manager for Java lists extension modules.  Extension Modules are Jar files that are deployed to ArcGIS Server.  When you click the + icon next to your SOE extension module, you will see a hyperlink of all the SOE's included in your module.  The hyperlink displays your SOE metadata, e.g., capabilities, properties, etc.  Below is a basic metadata dialog initiated when clicking on a SOE hyperlink. 

SOE Manager Tool

The SOEManager tool is no longer required for ArcGIS Server for Java administrators as the registration process has been integrated into ArcGIS Server Manager as described in the section above.  The tool however is still provided for a couple of reasons:
  1. Administrators who want to have a non-UI, or silent, registration experience.
  2. Administrators who are registering Java SOE's on ArcGIS Server for .NET.  ArcGIS Server Manager for .NET does not support registration of SOE's and consequently administrators who want to deploy, register, and enable SOE's on .NET Server will have to use SOEManager tool for registration. 
The following section on SOEManager tool is optional reading for those effected by the 2 scenarios described above. 
The ArcGIS Server for Java product provides a tool to manage your SOE add/remove process with respect to Server Object Types, e.g. Map Server.  The SOEManager tool is located in '%AGSSERVERJAVA%\java\tools\soemanager'.  In that folder structure you will find the Jar file and batch file to execute the tool. 
The SOEManager tool serves two purposes:
  1. To add a SOE as extension to MapServer service type.
  2. To remove a SOE as extension to MapServer service type.
The batch script file requires the following 6 parameters to execute:
  1. Operation (-a / -r): The “–a”  option allows you to add your SOE to MapServer service type, while the  “–r” option allows you to remove SOE from MapServer service type.
  2. Server Name:  Name of the ArcGIS server
  3. Domain Name:  Name of user’s domain
  4. User Name
  5. User password
  6. Jar file containing the SOE

Usage for the soemanager script is as follows:
 
Usage: soemanager [-a | -r] [server name] [domain name] [username] [password] [j
ar file containing SOE(s)]
[-a] - Adds SOE to map service  |  [-r] - Removes SOE from map service
[server name] - Specifies name of ArcGIS Server
[domain name] - Specifies domain name for user
[username] - Specifies user name
[password] - Specifies user password
[jar file containing SOE(s)] - Specifies the jar file that contains one or more
SOEs
Run the soemanager script to add our HelloWorldSOE with the appropriate credentials for your server environment.  An example to add the SOE is offered below: 
soemanager -a <servername> <domain> <user> <password> HelloWorldSOE.jar
Where <servername>, <domain>, <user>, <password> are replaced with the credentials for your server and agsadmin account. 

SOE Enablement


Enablement of your SOE is done in ArcGIS Server’s administration consoles, either ArcCatalog or ArcGIS Server Manager when you create your ArcGIS Map Service.  Once you have successfully added your SOE to Map Server Object, it will be listed under Map Service Capabilities list from which you can enable/disable it on the Map Server Object.  The following walks you through enablement in the respective administration consoles. 

ArcCatalog


Use the following steps in ArcCatalog to enable your SOE’s. 
  1. Open ArcCatalog and create add a new service by right clicking your ArcGIS Server administrative connection and selecting ‘Add New Service’.
  2. This brings up the ‘Add New Service’ dialog.  Create a new MapService and select ‘Next’.
  3. The next dialog has you input your map document and select output/cache directory options.  Fill those in appropriately and select ‘Next’.
  4. The next dialog allows you to choose capabilities on your service.  You should see your SOE listed where you can select the SOE by checking the box next to it your extension.  . 
  5. Complete the rest of the dialogs as appropriate to complete the new service creation process.

Once complete, your SOE is enabled on the Service you created. 

ArcGIS Server Manager

Use the following steps in ArcGIS Manager to enable your SOE’s. 
  1. Open up ArcGIS Manager in your web browser and log in with an 'agsadmin' account. 
  2. Under 'Services', Select 'Add New Service' to start the New Service wizard. 
  3. Add a 'Map Document' and appropriate 'Output Directory' and click 'Next'. 
  4. This brings up the 'Capabilities' page which allows you to choose capabilities on your Map Service.  You should see your SOE listed where you can select the SOE by checking the box next to it your extension. 
  1. Complete the rest of the dialogs as appropriate to complete the new service creation process.
Once complete, your SOE is enabled on the Service you created. 
Be aware that all SOE's registered through the SOE Manager will show up as a capability on all Server Object types it was registered with.  So if you have created a SOE that works specifically with a particular Map Service it will show up as a capability on all Map Services.  This may cause errors if you enable the SOE on a Map Service it was not intended for.  If you would like your SOE to be useable across all Map Services you must ensure the code is reusable without modification to perform regardless of what particular Map Service it is enabled on.  Our HelloWorldSOE is an example of a reuseable SOE as it can be enabled on any Map Service.  If your SOE depends on a specific Feature Type or Feature Layer being present, you will have to manage your SOE appropriately as to ensure it is not enabled on a Map Service that does not offer the specific Feature Type or Feature Layer your SOE is dependant on. 

SOE Removal Process

The soemanager script can be used to remove your SOE from a Map Server Object.  In order to fully purge your SOE from the full ArcGIS Server lifecycle you must go through the following workflow: 
  1. Stop all running Map Services through an administrative client like ArcGIS Manager. 
  2. Run soemanager script to remove the SOE. 
  3. Delete the SOE jar file from the '<ARCGISHOME>'\java\lib\ext\' directory. 
  4. Restart all appropriate Map Services.
We will use our HelloWorldSOE example to show the usage of the soemanager script to remove your SOE:
[XML] 
soemanager -r <servername> <domain> <user> <password> HelloWorldSOE.jar
Where <servername>, <domain>, <user>, <password> are replaced with the credentials for your server and agsadmin account.