Developing SOE SOAP Web Services
In order to expose your Server Object Extension (SOE) as a SOAP Web Service you must go through the following workflow:
- Extend SOAPRequestHandler class
- Generate Web Service artifacts
Extend SOAPRequestHandler
All SOE SOAP Web Services must extend the SOAPRequestHandler base class. The SOAPRequstHandler has a handleStringRequest() method implementation of the IRequestHandler interface which takes SOAP requests and invokes the method from the base class.
The SOAPRequestHandler class is introduced with ArcGIS 10 ArcObjects to simplify development of SOE's exposed as Web Services. The SOAPRequestHandler class implements the IRequestHandler interface and through the handleStringRequest() method it automatically reads SOAP requests and generates SOAP responses. This allows you as the developer to concentrate on implementing your SOE business logic without regard to the complexities of SOAP request/response handling.
Generate Web Service artifacts
Two types of artifacts are required to support all SOE SOAP Web Services:
- Web Service Description Language (WSDL) file
- Web Service Stubs
WSDL is a XML based specification that describes the interfaces and instances of Web Services. A WSDL description of a service describes the interface to the service, the data types used as parameters and return types, and where the service is located.
Web Service Stubs are delegation objects for clients to invoke your Web Service. Tools are provided in the ArcObjects Eclipse plug-in that will generate the stubs automatically for you based on the WSDL for your Web Service.
Support for Java and ArcObject Types
With ArcGIS 10 the types supported by SOE SOAP Web Services has expanded beyond primitives into Java and ArcObjects as parameters and return types. There are some limitations in supporting these types as noted below:
Java type limitations:
- A Java type must not have an argument constructor explicitly defined.
- A Java type must have getters and setters for all its private members.
- A Java type must not have an ArcObject type as its member.
ArcObject type limitations:
- Only ArcObjects that correspond to objects defined in ArcGIS Java Web Services (AgsJWS) API are supported. Please consult the AgsJWS API javadoc for a list of allowed ArcObject types.
Capabilities
Capabilities, in the context of SOEs, are abstract concepts, in that, they don't necessarily have specific physical representations in the form of SOE methods. Capabilities allow developers to aggregate capabilities of a SOE and allow administrators to enable/disable such capabilities based on criteria. An example would be the Map Server object, which provides 3 Capabilities called Map, Query and Data. Admin clients applications such as ArcCatalog and ArcGIS Manager allow administrators to select/deselect these Capabilities on the Map service. Each capability is independent of the other and selecting one capability has no effect on others.
The lack of a specific physical representation of an capability allows developers some flexibility in mapping Capabilities to an SOE's methods. An capability can have one to one or one to many mapping with SOE methods, based on the design of the SOE.
If an capability is not permitted, then an exception can be thrown in the SOE method which will trickle down to the client application as a SOAP fault.
The following are some important points about Capabilities:
- Capabilities are completely optional. In absence of Capabilities, SOE administrators will not be able to select/unselect capabilities of the SOE, but web services client applications are still able to call all your SOE methods.
- Capabilities in the context of SOEs should not be confused with WSDL operations. The Capabilities defined in WSDL file point to the SOE's methods, where as Capabilities defined in the ServerObjectExtProperties annotation are abstract and could map to SOE methods in different ways, as described above.
Web Service Tools
The ArcObjects Java Developer Kit provides an Eclipse plug-in which offers all the tooling required to develop SOE SOAP Web Services. The tooling provided simplifies development as you don't have to write a complex application to dynamically read SOAP requests and generate SOAP responses. You can simply develop all the functionality of your Web Service and then generate the WSDL and stubs which will interpret requests and forward them to the service implementation. Once the service implementation obtains a result, it returns it to the stub to generate the appropriate SOAP response.
To get started using the SOE Web Service tooling, first install the ArcObjects Eclipse Plug-in as all tooling is provided with the ArcObjects Developer Kit and Eclipse plug-in. Once installed, you can create a Java Project inside of Eclipse and use the ArcGIS Extension SOE template to create your SOE. In order to expose your SOE as a SOAP Web Service you will need to follow the custom ArcGIS extension interface pattern by adding a Custom Interface as shown in the SOE dialog below (this is mandatory for all SOAP supported SOE's):
You will notice a new checkbox labeled 'Support Fast Map Services'. At ArcGIS 10 SOE's now support Fast Map Services or MSD's. If you select this option the appropriate annotation will be set to 'true'.
After clicking 'Next >', the following dialog has two tabs, 'Web Support' and 'Web Capabilities'. If you select 'Enable SOAP Support' the generated SOE class will extend the SOAPRequestHandler class as described above.
You can select the Web Capabilities tab in this dialog to add capabilities to your SOE. This will ensure that the appropriate annotations will be generated in your SOE.
After clicking 'Next >', the following dialog allows you to add properties to your SOE and choose to generate a Visual Java class to edit properties in ArcCatalog.
Clicking Finish will generate your SOE ready for Web Service exposure. At this point you are ready to implement your SOE business logic. Once your SOE is complete, you need to generate a WSDL file and Web Service stubs.
Generate WSDL and Stubs
Before we can generate our Web Service artifacts we need to create our SOE Jar file as this will be used as input into our WSDL and Stub generation tools. Create your SOE jar file using Eclipse Export wizard or the Java Jar command and save the jar file in a folder location in your project. We don't want to save the Jar to ArcGIS Server's SOE deployment folder yet as we need to generate our Web Service artifacts first. You can create a 'lib' and 'res' folder in your project workspace to house the SOE jar file and WSDL file respectively. Once the Jar is created you select 'ArcGIS > Generate Stubs for SOE…' from the Eclipse tool bar to start the Web Artifact generation process.
This will open up the 'Generate Stubs for SOE' dialog where you can browse to the SOE jar file and an output directory for generated artifacts.
Once you have appropriately populated the text boxes with your SOE jar file and output directory you can click 'OK' to start the tooling process. The wizard will generate a stubs jar for use in your client application and a wsdl file in the root directory of your SOE jar file and a copy in the directory you provided to the wizard. Now you can open the wsdl file for viewing.
You can do view the WSDL using the Eclipse WSDL design editor if you have Eclipse Web Tools Project (WTP) installed or optionally open the WSDL source file in a text editor.
Deployment
Deploying your SOE SOAP Web Service is the same as deploying a typical SOE. Please refer to the Deploying and Managing SOE's doc.