Implement the SOI's interfaces
This topic illustrates key components in an SOI class structure. The pattern for developing server object interceptors (SOIs) is to create a Java class that implements the following interfaces:
IServer
interface provides theObject Extension init()
andshutdown()
methods that are called when your service starts and shuts down.IRest
interface provide theRequest Handler handle
method that intercepts the HTTP REST requests and responses through the service.RESTRequest() IRequest
andHandler2 IRequest
interfaces provide theHandler handle
andBinary Request() handle
methods that handle SOAP requests.String Request() IWeb
provides theRequest Handler handle
method that handles the OGC requests.String W e b Request()
SOI class annotation
After the SOI class is created from the template, the annotation, interfaces, and methods required for the SOI class are automatically implemented. The following SOI class annotation with several properties automatically populated is used to help the server administrator identify and understand the SOI deployed in ArcGIS Server Manager.
displayName defines the SOI name that appears under Service > Capabilities tab on ArcGIS Server Manager.
description displays after the Help button of the extension is clicked on Site > Extensions tab on ArcGIS Server Manager. See the enable extensions section.
interceptor indicates that this is a class for an SOI.
servicetype defines the type of services that this SOI can be enabled with. By default,
Map
is set for this attribute. Starting with 10.8.1,Service Image
is also supported for SOIs to work with image services.Service supportsSharedInstances is an optional attribute indicating whether this SOI supports shared instances and whether this SOI can be enabled when the service is set to use shared instances. By default, it's always
false
, which forbids the SOI to be enabled with shared instances. If the SOI follows the best practices for extensions with shared instances, this attribute can be set totrue
and the SOI can be used with a service set for shared instances. The supportsSharedInstances attribute is introduced at 10.8.1.
SOI initialization
The initialization logic of the SOI is defined in theinit()
method, which contains the following boilerplate code:
After the SOI is enabled with a map service and service restarts, the first method that will be triggered in the SOI is thisinit()
method.IServer
helps hold the reference to the current server object, which is aMap
object providing service data access, layer properties, and access to other service information. SOIHelper
provides access to REST request schema and REST request handler.
The Server
method returns ILog
, allowing the SOI to write server logs that can be viewed by the server administrator. You may also refer to the SimpleSOI sample (\<Installation folder of ArcGIS Enterprise SDK>\Samples\Java\serverobjectinterceptors\SimpleSOI) for the complete SOI code.
SOI request handler
The SOI class implements several interfaces, which handle different types of requests, such as REST, SOAP, and OGC requests. For example, thehandle
method is implemented by IRESTRequest
for REST request. This method is called every time a service operation is performed through REST endpoint.
The REST request sent to a map service carries lots of information, including request headers, output format, request parameters, operation name, and other service information. Request headers are returned by request
. The output format is returned by output
, which can be JSON, GeoJSON, image, and so on, depending on the specific operation. Request parameters are passed in as operation
. The capabilities
, resource
, and operation
variables are usually used to locate the specific service operation to intercept.
The handle
method in the above code is used to process the REST request and generate a byte-array response. Right now, this code doesn't modify any request or response, and just let through the request as default.
To modify the request, you can modify the request parameters, such as changing certain operation
parameters and passing the updated parameters to the rest
method.
To modify the response, you can customize the return byte array object. For example, if the result of a map service query is a JSON, you can first get a byte array object from the rest
method, and then convert this byte-array object to a JSON object and customize the JSON object based on your business logic. Finally, you can pack the updated JSON object back to a byte array and return it for the above handle
method. Additionally, you can also provide your custom response headers by assigning response
.
Similarly, you can use the handle
method to intercept SOAP XML requests, the handle
for certain requests sent from ArcMap and other ArcObjects-based clients, and the handle
method for OGC service requests.