Developing with Web Services  

Overview of Web Services, SOAP and WSDL

 

The ADFs take full advantage of using webservices to communicate with ArcGIs Server services. As a developer using the ADFs or ArcGIS Server directly it is important you understand using SOAP and its relationship to the WSDL files provided with ArcGIS. This article will discuss some of the basic concepts of working with Web Services, SOAP, and WSDL provided with ArcGIS Server. Following this article you should read more particular documents that explain how to apply the ideas explained here in relation to a specific ADF.

Web services provide the ability for 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. XML is the format used to hold the information carried between the applications. The XML message is carried using SOAP (Simple Object Access Protocol). SOAP defines the headers and the valid means for passing messages. That passing of messages usually takes place over HTTP but it can actually be over any well know protocol, such as SMTP, FTP, or DCOM. SOAP takes the xml message and wraps it so that it can be routed to the receiving application and appropriaptely 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, like 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 will be listed as being part of MapServerPort. Another property of the web service documented in the WSDL is the protocol over which to send messages and, optionally, the URL for the associated server. The WSDL specification does all of this work in a very generic manner, thereby allowing toolkits in different languages, such as AXIS in Java, to generate code from a WSDL description.

WSDLs and ArcGIS Server

If you look in your installation folder under XmlSchema you will find eight WSDL files. Each one corresponds to a description of a web service that ArcGIS Server is capable of publishing. Each WSDL roughly corresponds to an ArcObject class, for example the MapServer.wsdl corresponds to the MapServer object and the 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 ArcObject. When you open the GeocodeServer.wsdl there are two important sections you need to understand. The first section is inside the <types> element and the second section is inside the <portType> element.

Value Objects

The <types> elements contains all the definition of the data types for the WSDL, also called value objects. In this section you will find the definition for all the elements that will be passed in as parameters to the methods for the web service. The value objects can be composed of other value objects but in the end 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 of the type elements will be Java value objects, much like plain old java objects (POJOs). For example, if you look at PointN in the WSDL, this is a XML representation of a Arcobject Point that is sufficient for web service operations:

<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 which is very similar to a POJO. From the WSDL definition we can see that M, Z, ID, and SpatialReference are not required properties since their minOccurs attribute is equal to 0. Therefore when you need to use a PointN value object you can create it using the default construct, set the X and Y, and then pass 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 are setting the object's properties since they are set locally no remote call is made to the ArcGIS serverl.

Port Usage

Inside the <portType> element is the listing of all the methods that can be called on the web service. For example, one of the calls you can make is ReverseGeocode, which takes a point and figures out the closest address.

<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 a location, which is a point, a boolean to indicate if intersections should be returned, and some properties in a PropertySet

<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 will be generated named GeocodeServerPort which contains all the methods you can call on the ArcGIS Server GeocodeServer object using web services. The GeocodeServerPort object is instantiated in the local JVM but 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 therefore accessing its properties will not require calls to the server. Therefore, the only methods in the Java classes generated from the WSDL which make remote calls will be those methods exposed on a *Port object.

Implications for ArcGIS Server Developer

Using SOAP has several advantages for ArcGIS Server developers. The greatest 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 serious advantage is that the only remote calls are those on the *Port objects. When using ArcGIS Server with the server API, each call to set a variable or execute a 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 greatly increases the performance of your application.

Here is an example which comes from the example below. It 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 would be a remote method call.

// 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 spatialfilter 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 found on the MapServerPort the call to queryFeatureCount goes back
//to the server which can throw an 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 using the Server API. The implications of this for current ArcGIS Server developers is that your code will not translate directly and that you may have to set more values before the method call.

Now that you have basic understanding of the ArcGIS Server web services, you can go on to reading about how these generated Java proxies are used in the Web ADF and the Enterprise ADF. The Javadoc for the generated Java proxies can be found by themselves or as part of the Javadoc for the Web ADF and the Enterprise ADF

The custom command and tool example shows using the Value objects and Port calls.

Links

 

For more information about Web Services, SOAP, and WSDL there is a lot of information available on the Internet. Here are some good introductory and advanced readings:

The WSDL 1.1 Specification

WebServices.xml.com from O'Reilly has interesting articles that cover a wide range of issues using web services

W3 Schools has introductory article on SOAP, WSDL, and Web Services.

Java Web Services by Chappell and Jewell is a good book for Java developers working with Web Services.