This document was published with ArcGIS 9.3.1.
A 9.3 version also exists.
A 9.3 version also exists.
In this topic
Overview
Web services allow applications to communicate using messaging over many different protocols. Because Web services provide a means to communicate between applications that are written both in the same programming language as well as in different programming languages, a language-neutral means of communication was needed. Extensible Markup Language (XML) is the format used to hold the information carried between the applications. The XML message is carried using SOAP. SOAP defines the headers and the valid means for passing messages. That passing of messages usually takes place over Hypertext Transfer Protocol (HTTP); however, it can be over any well known protocol, such as Simple Mail Transfer Protocol (SMTP), File Transfer Protocol (FTP), or Distributed Component Object Model (DCOM). SOAP takes the XML message and wraps it so that it can be routed to the receiving application and appropriately processed.
WSDL, on the other hand, describes what a Web service does, what methods it contains, what parameters and types it knows how to use, and which ports it is using for communication. The WSDL defines the valid contents of the XML messages to be passed over SOAP. The WSDL acts as a specification, similar to Interface Definition Language (IDL), to describe the interfaces and parameters on a Web service. The methods available are usually grouped together in a port, which can be thought of as a view to Web services where different operations are exposed. A WSDL can contain one or more ports. The WSDLs provided by ESRI have only one port per WSDL. For example, all the methods exposed for the MapServer WSDL are listed as part of the Map Server Port.
Another property of the Web service documented in the WSDL is the protocol over which to send messages and, optionally, the uniform resource locator (URL) for the associated server. The WSDL specification does this work in a generic manner, allowing toolkits in different languages, such as AXIS in Java, to generate code from a WSDL description.
WSDLs and ArcGIS Server
There are eight WSDL files in your installation folder under XmlSchema. Each one corresponds to a description of a Web service that ArcGIS Server is capable of publishing. Each WSDL roughly corresponds to an ArcObjects class—for example, MapServer.wsdl corresponds to the MapServer object, and GeodataServer.wsdl corresponds to the GeodataServer object. Because Web services usually only send text messages (XML) between applications, there are differences in method signatures and data types between the WSDL and the corresponding ArcObjects object. There are two important sections in GeocodeServer.wsdl. The first section is in the <types> element and the second section is in the <portType> element.
Value objects
The <types> element contains the definitions of the data types for the WSDL, also called value objects. The definitions for all the elements that will be passed in as parameters to the methods for the Web service are in this section. The value objects can be composed of other value objects; however, the final types must be valid XML schema data types, such as String, Long, Int, or Date. When the Java toolkit converts from WSDL to Java classes, all the type elements will be Java value objects, much like Plain Old Java Objects (POJOs). For example, PointN in the WSDL is an XML representation of an ArcObjects point that is sufficient for Web service operations as shown in the following code sample.
[Java]
< xs: complexType name = "PointN" > < xs: complexContent > < xs: extension
base = "Point" > < xs: sequence > < xs: element name = "X" type =
"xs:double" / > < xs: element name = "Y" type = "xs:double" / > < xs:
element name = "M" type = "xs:double" minOccurs = "0" / > < xs: element
name = "Z" type = "xs:double" minOccurs = "0" / > < xs: element name =
"ID" type = "xs:int" minOccurs = "0" / > < xs: element name =
"SpatialReference" type = "SpatialReference" minOccurs = "0" / > < / xs
: sequence > < / xs: extension > < / xs: complexContent > < / xs:
complexType >
The Javadoc for the class generated using the AXIS toolkit shows a Java class that is similar to a POJO. From the WSDL definition, you can see that M, Z, ID, and SpatialReference are not required properties since their minOccurs attribute is equal to zero. Therefore, when you need to use a PointN value object, you can create it using the default construct, setting X and Y, then passing it as a parameter. There is no need to create the object on the Server Context; it is created on the local machine. When you set the object's properties, no remote call is made to the ArcGIS serverl since the properties are set locally.
Port usage
The listing of all the methods that can be called on the Web service is in the <portType> element. For example, one of the calls you can make is ReverseGeocode, which takes a point and determines the closest address as shown in the following code sample.
[Java]
< operation name = "ReverseGeocode" > < input message = "e:ReverseGeocodeIn"
/ > < output message = "e:ReverseGeocodeOut" / > < / operation >
There is a definition for the input message (the input parameters) and the output message (the returned values) in another section of the WSDL. In this case, they are defined earlier in the file as <message> elements, which are then mapped to <types>. Through this mapping, you can see that a ReverseGeocode input message contains both a Boolean point location, indicating if intersections should be returned, as well as properties in a PropertySet as shown in the following code sample.[Java]
< xs: element name = "ReverseGeocode" > < xs: complexType > < xs: sequence >
< xs: element name = "Location" type = "Point" / > < xs: element name =
"ReturnIntersection" type = "xs:boolean" / > < xs: element name =
"PropMods" type = "PropertySet" / > < / xs: sequence > < / xs:
complexType > < / xs: element >
When the WSDL is used to generate Java proxies through AXIS, a class is generated named GeocodeServerPort that contains all the methods you can call on the ArcGIS Server GeocodeServer object using Web services. The GeocodeServerPort object is instantiated in the local Java Virtual Machine (JVM); however, any method call on this class will execute a remote call to the server. Any object returned from the server will be a value object, and accessing its properties will not require calls to the server. Therefore, the only methods in the Java classes generated from the WSDL that make remote calls are those methods exposed on a *Port object.
Implications for ArcGIS Server developers
Using SOAP has several advantages for ArcGIS Server developers. The main advantage is that the value objects are Java objects in the local JVM. Because they reside in the local JVM, and they are pure Java, they are easier to debug and work with in general. Another advantage is that the only remote calls are those on the *Port objects. When using ArcGIS Server with the server application programming interface (API), each call to set a variable or execute a geographic information system (GIS) operation is a remote call. Because the value objects are in the local JVM, all calls to their mutators are local calls. When you call one of the methods on a *Port object, you pass the value object as a parameter. The returned objects are also value objects, so retrieving values from this object are local calls as well. This overall reduction in remote calls increases the performance of your application.
The following code sample uses value objects and the MapServerPort to query the count of features in a layer in the map. Using the Server API, every method call, from creating the envelope to the query feature count call, is a remote method call.
[Java]
// The envelope is a value object, so this constructor is not a remote call.
EnvelopeN env = new EnvelopeN(webExtent.getMinX(), webExtent.getMinY(),
webExtent.getMaxX(), webExtent.getMaxY(), null, null, null, null, null);
// Make a spatial filter value object with the required parameters. None of these method calls are remote.
SpatialFilter spatialFilter = new SpatialFilter();
spatialFilter.setFilterGeometry(env);
spatialFilter.setSpatialRel(EsriSpatialRelEnum.esriSpatialRelIntersects);
spatialFilter.setWhereClause("");
spatialFilter.setSearchOrder(EsriSearchOrder.esriSearchOrderSpatial);
spatialFilter.setSpatialRelDescription("");
spatialFilter.setGeometryFieldName("");
int layerId = layer.getId();
//Because queryFeatureCount is on MapServerPort, the call to queryFeatureCount goes back
//to the server, which can throw a RemoteException.
try
{
numberOfFeatures = mapServer.queryFeatureCount(mapServer.getDefaultMapName()
, layerId, spatialFilter);
}
catch (RemoteException e){}
There are also some drawbacks, especially for current ArcGIS Server programmers. Because of the requirements of the WSDL using simple types and the way different toolkits generate default values, some of the generated objects need more properties set before the methods will work. For example, using an Element for custom graphics needs to have its color set when using SOAP but not when using the Server API. The implications of this for current ArcGIS Server developers is that your code will not translate directly, and you may have to set more values before the method call.
See Also:
ArcGIS Web Services Java API specificationADF package summary
WSDL 1.1 specification
O'Reilly Web services
W3 Schools SOAP tutorial
W3 Schools WSDL tutorial
W3 Schools Web Services tutorial
Java Web Services book