SOAP toolkits

SOAP web services are designed to share application logic with remote clients, regardless of the deployment environment of the service and the development environment of the client. Web services achieve this by provides a set of communication and messaging standards. Both services and clients must support these standards to effectively communicate with one another. The SOAP messaging specification provides a standard protocol to package communication content for distribution over a network. In general, a client generates a SOAP message (an XML string) and sends it to a service for processing. The service in turn generates results, packs it in a SOAP message and sends the response to the client. As discussed in the overview topic, each service type maintains a WSDL which defines the operations and complex types exposed by the service. Logically, the service is an object with methods (operations) used to interact with the service. The methods have both inputs and outputs defined as objects that store values (thus the term "value objects"). These objects are defined in the WSDL and can be primitive types, such as string or integer, or complex types explicitly designed to support service operations.

However, most developers do not want to parse a WSDL to determine how to work with a service. Plus, creating and parsing SOAP messages from scratch would be very labor intensive. In many cases, a developer is already working in an IDE using a full-featured, stable, object-oriented language to create a client application, so it would be beneficial to leverage the IDE and language capabilities. This is precisely the environment for which SOAP services were designed. The WSDL already defines the proxy behavior and strong types necessary to use the service, the only item needed is a utility to convert the proxy and types into a set of native classes for a development environment. SOAP toolkits are designed to do just this. In general, they use a WSDL to generate native classes, one proxy class with methods, and any number of value object classes to support the proxy. "Native" means the classes are generated in the client's development environment for which the SOAP toolkit was designed. Each development environment may have many SOAP toolkits to choose from. The Microsoft .NET SDK includes the Wsdl.exe tool and exposes it for use in Visual Studio IDE. The Java Platform has a bevy of toolkits including Apache Axis and The Mind Electric GLUE. PHP toolkits include PHP-SOAP and NuSOAP. Python toolkits include Zolera SOAP Infrastructure (ZSI) and Soaplib.

Note:

ArcGIS Server web services support WSDL 1.1 and SOAP 1.1 specifications. SOAP toolkits must also support the same specification versions to work with ArcGIS Server web services.

The native proxy class generated by a toolkit is responsible for serializing an operation and input arguments (value objects) into a SOAP message. The native development environment dictates how the SOAP message is transmitted to the web service. This native logic is packaged within the proxy class generated by the SOAP toolkit. The response from the web service is a SOAP message which is deserialized by the proxy to construct results in the form of one or more native objects.

In general, SOAP toolkits make it easier to consume SOAP web services by leveraging the capabilities of the client development environment to construct, transmit and process SOAP messages. This SDK provides a comprehensive discussion of ArcGIS Server web services as a set of proxy classes, one for each ArcGIS Server service type, and the complex value object types that support their use. Note, once a the proxy class and value objects have been generated for a service type, they can be reused with other services of the same type - merely change the web service endpoint (URL) to the service you want to work with.

In most cases, you as a developer will start working with ArcGIS Server web services by using a SOAP toolkit to generate the native client proxies and value objects. There are a number of topics to help you get started:

1. All the tutorials start by using a SOAP toolkit to generate native clients classes. For .NET developers, start with the basic walkthough which adds a web reference to consume a map service.
2. In most development environments, SOAP toolkits can be used to generate native classes for multiple service types at the same time and share common native class types (value objects). Read the discussion on shared value objects and traverse the appropriate tutorials.
3. Some development environments support invoking operations asynchronously, in which case the SOAP toolkit constructs the appropriate methods on the proxy to support asynchronous call patterns. Read the respective discussions for both Microsoft .NET and the Java Platform, both of which provide the foundation on which to build and manage asynchronous communication patterns.