ArcGIS Server SOAP API

Summary At 9.3.1 we have released a new ArcGIS Java Web Services (AgsJWS) Toolkit based on JAXB to replace the SOAP API which was based on Axis. The benefit of this new toolkit is better performance and more robust SOAP communication. The SOAP API based on the Axis toolkit is still supported at 9.3.1, but users are encouraged to migrate to the new AgsJWS toolkit to take advantage of the performance and feature gains. The documentation in this section is based on the Axis toolkit and while we are able to maintain backward compatibility in the new AgsJWS toolkit, it is strongly advised that you read the Migration to 9.3.1 document in the Getting Started section to manage any discrepancies.

WSDLs
SOAP requests and responses

Consuming SOAP services
Consuming ArcGIS Server services using the SOAP API

ArcGIS Server Web services implementation
Consuming ArcGIS Server Web services
ArcGIS Server proxies and value objects

Overview

The ArcGIS Server SOAP application programming interface (API) is an Extensible Markup Language (XML)-structured language for communicating with ArcGIS Server services based on the SOAP standard. Server objects and some server object extensions have a defined set of SOAP elements and attributes, known as a schema, they can utilize to process SOAP requests and generate SOAP responses. Since this capability is enabled at the server object level, as a developer, you can interact with a server object using SOAP without using a Web service. ArcGIS Server Web services expose this capability via a Web service endpoint; however, the SOAP request and response are still handled by the server object or server object extension directly. The easiest way to work with the SOAP API is to use a SOAP toolkit to generate SOAP proxies and value objects in the native development environment. Instead of managing SOAP strings directly, you can use the native proxy and value objects to work with ArcGIS Server services via a Web service endpoint or via the sever object manager (SOM).

The SOAP API is designed to make stateless use of ArcGIS Server services. As a result, methods on the stateless ArcObjects interfaces implemented by a server object or extension mirror the methods on a SOAP proxy. For example, both the MapServer SOAP proxy and the IMapServer ArcObjects Component Object Model (COM) interface expose the exportMapImage method. While the protocol and types are different, the usage is generally the same. A call to the ExportMapImage method generates a new map image without inherently storing or changing the state of the map server object. A list of the complimentary SOAP proxy and ArcObjects COM interfaces are provided in the ArcGIS Server Web services implementation section of this topic.

ArcGIS Server connections

ArcGIS Server services can be made accessible via local and Internet connections. Local connections are established by using ArcObjects in a client application to connect to the SOM. Internet connections are established by using native objects in a client application to connect to a Web service endpoint. "Native object" means an object managed solely in the native development environment, such as .NET or Java. Local connections offer the ability to work with services, namely server objects and server contexts, using the ArcObjects API and the SOAP API. Stateful changes to a service (server object) can only be made using the ArcObjects API and requires a local connection. Internet connections only offer the ability to work with services using the SOAP API, so all service interaction is stateless. In general, ArcGIS Server connections in client applications can be summarized as follows:

Internet connections always use the SOAP API and define a connection using a uniform resource locator (URL) to a Web service endpoint. Internet connections can be used by both internal (local area network [LAN]) and external (Internet) clients.
Local connections always use the ArcObjects API and may use the SOAP API, depending on the client application. Connections are defined using the name of the SOM machine with optional identity credentials. Local connections can only be used by LAN clients.

Internet and LAN connections are shown in the following diagram.

Diagram of local and Internet connection types.

Both connection types can be used to consume ArcGIS Server services in pre-created application clients, such as ArcMap, ArcCatalog, and ArcGIS Explorer. The Web Application Developer Framework (ADF) and ArcGIS Server Manager also enable the use of ArcGIS Server services without explicitly defining the API you're using. The API becomes important for application developers to determine the capabilities and limits when working with ArcGIS Server services. As a result, working with the SOAP API requires developer level skill and knowledge for a number of Web service standards and specifications in addition to ArcGIS Server service capabilities.

Web service standards

The ArcGIS Server SOAP API rests on two standard XML-based specifications: Web Service Description Language (WSDL) and SOAP. WSDL is a specification used to describe networked XML-based services. Although the term "Web Service" is part of the moniker, WSDL is not restricted to traditional Hypertext Transfer Protocol (HTTP)-based Web services. In general, WSDL provides a simple way for service providers to describe the basic format of requests to their services, regardless of the underlying protocol. One of those protocols, and by far the most popular, is SOAP. SOAP is used to describe the format of a message sent to a networked service. SOAP messages can be transmitted to a service via a number of transport protocols, including HTTP and Distributed Component Object Model (DCOM).

ArcGIS Server SOAP implementation

SOAP support for server objects and server object extensions is defined at the ArcObjects level, so at some point in the communication cycle, ArcObjects must be used. Two basic ArcObjects interfaces are used to interact with the SOAP API: IServiceCatalogAdmin and IRequestHandler. Updated versions of both interfaces are available—for example, IServiceCatalogAdmin2 and IRequestHandler2. IServiceCatalogAdmin is used to obtain a WSDL for server objects, server object extensions, and ServiceCatalog. ServiceCatalog is a well-known service managed internally by the SOM and is used to obtain a list of services and their properties from an ArcGIS Server site using the SOAP API. IRequestHandler is used to process SOAP requests and generate SOAP responses. Interaction with an ArcGIS Server service via the SOAP API rests on the implementation and use of the IRequestHandler interface. The following ArcGIS Server services and extensions provide a WSDL and implement the IRequestHandler interface, thus they can be utilized via the SOAP API.

Service type	ArcObjects server object or extension type
Map service	MapServer
Geocode service	GeocodeServer
Geodata service	GeodataServer
Geoprocessing service	GPServer
Globe service	GlobeServer
Network Analysis	NAServer

WSDLs

The SOM is responsible for providing the WSDL for a service type to a client. The WSDL for each supported service type is stored in the <ArcGIS Install>\XMLSchema folder using the server type name with the file extension .wsdl. The content for each WSDL is provided via the following links:

Using the ArcObjects API and the IServiceCatalogAdmin interface on the ServiceCatalog object, you can gain access to the WSDL for each service type. The ServiceCatalog (Catalog) WSDL is returned by the getCatalogDescriptionDocument() method, and each service type (e.g., MapServer, GeocodeServer) WSDL is returned by the getDescriptionDocument() method. The byte array returned from either method contains the WSDL document referenced by the links above as shown in the following code sample. The IServiceCatalogAdmin interface is included in the com.esri.arcgis.server package.

[Java]


        ServerInitializer initializer = new ServerInitializer();
initializer.initializeServer(domain, username, password);

ServerConnection gisconnection = new ServerConnection();
gisconnection.connect(myserver);
// Get reference to the ServerObjectManager class.
IServerObjectManager som = gisconnection.getServerObjectManager();

IServerContext serverContext = som.createServerContext("usa", "MapServer");
IServiceCatalogAdmin2 isc = (IServiceCatalogAdmin2)serverContext.createObject
    (ServiceCatalog.getClsid());
// Catalog WSDL.
byte[] bitscatalog = isc.getCatalogDescriptionDocument("Catalog", "http://localhost")
    ;
String catalog_wsdl = new String(bitscatalog, "UTF8");
System.out.println(catalog_wsdl);

// Service WSDL.
byte[] bitsservice = isc.getDescriptionDocument("usa", "MapServer", 
    "http://localhost");
String service_wsdl = new String(bitsservice, "UTF8");
System.out.println(service_wsdl);

SOAP requests and responses

All SOAP requests to ArcGIS Server services are handled by the server object via the implementation of the IRequestHandler interface. As a result, using the ArcObjects API, an ArcGIS Server client can use the IRequestHandler interface to submit a SOAP request and return a SOAP response. The IRequestHandler interface defines the HandleStringRequest method to process SOAP string requests and generate SOAP string responses. The following code sample illustrates how to query interface to the IRequestHandler interface from a MapServer object, create the SOAP string request to get the default map name, and submit the request with a capability list to return a SOAP string response. The IRequestHandler interface is included in the com.esri.arcgis.system package and is referenced via the ESRI.ArcGIS.esriSystem namespace.

[Java]


        IRequestHandler irh = (IRequestHandler)serverContext.getServerObject();
String soap_request = "<?xml version='1.0' encoding='utf-8' ?>";
soap_request += 
    "<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:tns='http://www.esri.com/schemas/ArcGIS/9.2'>";
soap_request += "<soap:Body>";
soap_request += "<tns:GetDefaultMapName>";
soap_request += "</tns:GetDefaultMapName>";
soap_request += "</soap:Body>";
soap_request += "</soap:Envelope>";
String soap_response = irh.handleStringRequest("map,query,data", soap_request);

Creating and parsing SOAP strings can be a labor intensive process. Using the raw WSDL to determine how to create SOAP requests and process SOAP responses can be a daunting task. As a result, ESRI has leveraged existing technology standards coupled with developer environment utilities to make this process easier. The following sections illustrate the technologies and utilities provided.

Consuming SOAP services

Developer environments, such as .NET and Java, provide SOAP toolkits to generate local native objects as value objects and a proxy class. The WSDL provides the client what it needs to generate the proxy and value objects; thus, no proprietary components related to the Web service are necessary. This concept is shown in the following diagram.

Diagram of a SOAP toolkit with value objects and a proxy object.

Value objects are objects that store values or properties. Depending on the WSDL, there can be many different types of value objects. On the other hand, there is only one proxy class per SOAP service type. The proxy has both properties and methods. The methods are designed to create and submit a SOAP request and return a SOAP response. The proxy uses the value objects to construct (serialize) a SOAP request as shown in the following diagram. The proxy also deserializes the SOAP response and constructs value objects to be used by the client, so working with a rich client object environment makes it easier to consume and utilize a SOAP service because you are using native objects to store properties (value objects) and manage SOAP requests and responses (proxy) on the client.

Diagram showing serializing and deserializing a proxy object and an end point object.

Consuming ArcGIS Server services using the SOAP API

ArcGIS Server developers who want to use the SOAP API will use the pre-generated ArcGIS Server SOAP proxies and value objects included with the Web ADF in the arcgis_agsws_stubs.jar file. For each server type that supports SOAP, a proxy class is provided. For example, for the MapServer type, there is a class called MapServerBindingStub. The Web service proxy works with ArcGIS Server Web services using SOAP over HTTP and requires a URL endpoint. An example of this is shown in the following diagram.

Diagram showing consumption of ArcGIS Server services using the SOAP API.

ArcGIS Server Web services implementation

In ArcGIS Server for Java, ArcGIS Server Web services are deployed as a compiled Java class that contains an HTTP Handler. The HTTP Handler uses IServiceCatalogAdmin and IRequestHandler internally to expose the SOAP API over HTTP. The ArcGIS Server Web service application manages all interaction with the SOAP API via ArcObjects. This means ArcObjects COM proxies do not need to be on the client. In fact, no ESRI software is required on the client to consume ArcGIS Server Web services. Only the ability to submit and receive SOAP strings over HTTP is required. The development environment (e.g., .NET, Java, Perl, and so on) determines how this capability is implemented; however, the ArcGIS Server Web service must receive a SOAP request and return a SOAP response. This also means that the deployment environment of an ArcGIS Server Web service does not dictate which development environments can consume it. An ArcGIS Server Web service can be exposed as a Java Web service on any Java Web server and be consumed by a Microsoft .NET application because the communication protocol is based on common standards (SOAP and HTTP).

Consuming ArcGIS Server Web services

ArcGIS Server Web services use the following URL pattern:
http://<Web Server Hostname>:<port number>/<ArcGISInstance>/services/<ServiceName>/<ServiceType>

<Web Server Hostname> is the host name of the Web server on which the ArcGIS Server Web services application is deployed.

<ArcGIS Instance> is the name of the virtual directory in which the services are made available. Each instance is associated with one SOM.

<ServiceName> is the name of the ArcGIS Server service.

<ServiceType> is the server object or server object extension type. This type must provide a WSDL and implement IRequestHandler to be utilized via SOAP.

The WSDL for a server object or extension provides the necessary information to determine how to interact, via SOAP, with the Web service. The WSDL for a server object or extension type can be returned by adding "&wsdl" to the URL.

ArcGIS Server proxies and value objects

The proxy classes and value objects for each ArcGIS Server service type are generated using the service-specific WSDL. There is one proxy class for each service type. The capabilities of an ArcGIS Server service using the SOAP API are defined by the methods of the SOAP proxy. The SOAP API is designed to work with ArcGIS Server services in a stateless manner, thus the proxy class provides methods to initiate stateless requests to an ArcGIS Server service and return results. The capabilities of the SOAP proxy mirror the stateless ArcObjects interfaces implemented by the server object. For example, the MapServer SOAP proxy shares the same methods as the stateless ArcObjects interfaces implemented by the ArcObjects MapServer object: IMapServer and ITiledMapServer. The ArcGIS Server SOAP proxy uses value objects when calling a method and returning results. As a result, SOAP value objects and ArcObjects types used by the stateless interfaces will share a common naming scheme, but are different object types. The value objects are native Java objects, while the server object interfaces reference COM objects on the geographic information systems (GIS) server. For example, the MapServer SOAP proxy and IMapServer ArcObjects interface share the method exportMapImage. However, the SOAP proxy takes two input parameters, native Java objects of type MapDescription and ImageDescription. The IMapServer ArcObjects interface takes two input parameters—interface references to COM objects available on the GIS server of type IMapDescription and IImageDescription. The MapServer proxy returns a native Java MapImage value object, while IMapServer returns an IMapImage reference to a COM object on the GIS server.

The following table provides the SOAP API proxy class names for the ArcGIS Server service types and their complimentary stateless interfaces in the ArcObjects API. The SOAP API proxy classes in the Web ADF are contained in the com.esri.arcgisws package. This package is located in arcgis_agsws_stubs.jar.

ArcObjects server type	SOAP API proxy class	ArcObjects API stateless interfaces
MapServer	MapServerBindingStub	IMapServer, ITiledMapServer
GeocodeServer	GeocodeServerBindingStub	IGeocodeServer
GPServer	GPServerBindingStub	IGPServer
GeodataServer	GeodataBindingStub	IGeodataServer
GlobeServer	GlobeServerBindingStub	IGlobeServer
NAServer	NAServerBindingStub	INAServer

The following code sample illustrates a SOAP proxy class initialization with an ArcGIS Server map service.

[Java]


        String endpoint = "http://husker:8399/arcgis/services/usa/MapServer";
MapServerBindingStub mapserver = new MapServerBindingStub(new java.net.URL(endpoint),
    null);