In Chapter 3, we talked about the two models for using SOAP: the document exchange model and RPC. In Chapter 4, we introduced SOAP encoding, which defines a serialization mechanism for exchanging application data. Encoding and how it is used in each model are some of the biggest challenges to interoperability.

In SOAP 1.1, the RPC model requires the SOAP server to map data from a given native type into the XML encoding for that type and convert the encoding back from the XML encoding to the native type. RPC method calls are also encoded into XML, with method names mapped to the SOAP body child tags and arguments to child tags of the method name. Mapping between a number of type systems and XML is a difficult challenge, and not all languages can be mapped equally well. Toolkits may map to and from any given programming language’s type system differently.

There is no default encoding in SOAP. SOAP 1.1 defines a SOAP encoding style, often called Section 5 encoding (since it appears in Section 5), specifying how to express complex programming language types in XML. Section 5 encoding provides simple (scalar) and compound (composed of multiple parts) type categories and a set of rules for serialization. The specification also allows other encoding styles through the encodingStyle attribute, which can be used with “any element, and is scoped to that element’s contents and all child elements not themselves containing such an attribute, much as an XML namespace declaration is scoped” (Section 4.1.1). The encodingStyle attribute identifies serialization rules. Serialization is discussed in more detail in Section 9.4 later in this chapter.

SOAP 1.1 provides an optional encoding mechanism called literal encoding. With literal encoding, an XML document is sent as the payload. In contrast, with the standard encoding style, application data such as primitive types, methods, and objects, are serialized to XML. In this case, the XML payload is not really a document. The distinction between literal and encoded SOAP bindings in 1.1 is another source of problems. For example, Apache SOAP defaults to Section 5 encoding, while ASP.NET uses literal encoding. To get them to interoperate, one side must specify the encoding explicitly rather than use its default. ASP.NET can be forced to use Section 5 encoding by applying the SoapRpcService attribute to the class containing the web methods. To force Apache SOAP to use literal encoding, you must specify that the method takes a single parameter of type org.w3c.dom.Element as an argument and returns a response of the same type. You must then create an XML tree for the input parameter and modify the XML tree for the response.

In contrast with RPC, the document exchange model does not inherently require encoding. With the XML Schema Recommendation, a native XML type system can be used as well, so Section 5 encoding or another specialized encoding is not required.

In summary, there are four common combinations of style and encoding. Both ends must agree on a particular combination. For example, a server that supports only document exchange using the literal encoding won’t be able to communicate with a client that wants to use RPC with Section 5 encoding. Here’s a summary of the possible combinations:

SOAP 1.1 defines a way to type each value explicitly through the xsi:type attribute. The xsi:type attribute is optional and generally not required if the type being used is made known through the use of a schema, WSDL, or another form of metadata exchange. The specification states:

If one implementation expects type information, it probably won’t be able to process a message from an implementation that doesn’t include it. For example, earlier versions of Apache SOAP required explicit declaration of element datatypes. Because they did not use an external data typing mechanism (such as WSDL), the early Apache releases required explicit typing to determine how to map into native datatype representations.

While Apache tools required explicit typing of RPC parameters, earlier Microsoft implementations didn’t support it at all. They relied on WSDL, which created a significant interoperability problem. As of Apache 2.1, a workaround for this problem has been provided. To deserialize a parameter in a SOAP-RPC, the SOAP engine requires notification of the type for each parameter (since no metadata is available to the SOAP engine). Because Apache does not support WSDL, if explicit typing (the xsi:type attribute) is not used, explicit mapping is an option. The element name of the parameter can be used as the schema type, so the engine can associate a Java type for mapping. This association requires the user to tell Apache SOAP what the deserializer is for each type. We will talk about custom types and serialization when we get to Section 9.4.

Microsoft’s BizTalk Framework 2.0 specification now supports the xsi:type attribute.

Implementations often define proprietary datatypes beyond the primitive types specified by SOAP. An implementation that uses only the SOAP-defined types has much greater interoperability potential.

SOAP 1.1 does not specify an order for data serialization. Implementations can choose the order, which can cause problems between implementations.

The SOAP 1.1 specification leaves the use of this element open for interpretation. For example, it is defined in the context of the HTTP header as a URI identifying the “intent of the message.” This definition could be interpreted as the intended target for the message or the name of the target service. Another interpretation extends SOAPAction to accommodate different versions of the service. Service versioning is an interoperability issue in its own right, which we’ll discuss in the context of WSDL later in this chapter. The fact is that there are currently several different interpretations of how SOAPAction should be used.

In addition, the use of SOAPAction for transports other than HTTP, or between transports, is not specified in SOAP 1.1. Providing equivalent functionality for other protocols is up to the implementation, regardless of which interpretation is applied. As a rule, if another protocol is used, interoperability issues are likely to arise until standards are defined that explicitly specify bindings to other protocols.

The functionality that SOAPAction provides is useful. Being able to identify, route, or dispatch requests without having to parse XML is a good idea. The problem is in the implementation. In retrospect, it was probably not a good idea to overload the Action verb in HTTP. If SOAP is truly designed to be layered upon multiple protocols, then what’s needed is some sort of metadata that provides SOAPAction-like functionality. Then the binding to a particular protocol can map this metadata to whatever headers it likes: SOAPAction, SOAPRouting, SOAPDispatch, SOAPMethod, etc. To extend the scope of bindings for SOAP 1.2, the XMLP group defines a Transport Binding Framework. This framework defines a convention that describes binding property and feature types, a Message Exchange Pattern (MEP), and an HTTP binding based on the description convention and the MEP.

Even if HTTP is the protocol of choice, there is additional confusion about how SOAPAction works. Section 6.1.1 states:

In essence, the specification allows two ways to declare the intent (whatever “intent” is interpreted to mean) of a message: through SOAPAction or through the HTTP Request-URI. To add to the confusion surrounding SOAPAction, if a SOAP server requires a null value, HTTP clients that cannot set a null HTTP header value will have problems. Also, no distinction is made between an empty string (“”) and a null value, so both interpretations can be valid. SOAPAction is definitely a can of worms for interoperability.

The XMLP group has debated whether to keep SOAPAction in 1.2 or deprecate it. The current wording in the SOAP 1.2 draft Part 2, Adjuncts, Section 8.5.5 is:

This wording does not guarantee full interoperability between implementations without prior negotiation, but does improve the current state of affairs.

Not all SOAP implementations support multireference values. Nonetheless, some implementations, including Microsoft’s .NET Framework, do employ them. The .NET Framework uses multireference values to represent every element of an array.

The SOAP 1.1 specification does not define the order in which either SOAP headers or the SOAP body should be processed. Currently, each SOAP processor determines the processing order. This determination can lead to interoperability issues in scenarios involving intermediaries, in areas such as error processing, or in consistent, predictable service behavior across SOAP processors.

SOAP is designed to be extensible through the definition of additional headers. While extensibility is good, it also opens up the potential for abuse. Mandatory headers can be defined that can turn on or off the processing of other headers. Parties can define headers that are not standardized or widely supported. For example, BizTalk Server defines proprietary headers. The BizTalk Framework 2.0 specification defines BizTags, a set of XML tags used to indicate document handling. BizTags can be mandatory or optional; they are used to create SOAP headers in an XML BizTalk business document. BizTalk Framework 2.0 compliant servers, or BFC Servers, must be able to process headers composed of BizTags. However, SOAP servers that are not BFC-aware are not likely to understand BizTags or BizTalk-defined header extensions.

Section 7 of the BizTalk Framework specification defines five BizTag header extensions used to specify document routing, identification and other document properties, requested delivery services, a catalog of document contents and attachments, and tracking of the full business process context to which the document belongs. Each extension is comprised of BizTag elements and attributes (such as to or from, which are used in the endpoints header extension). These header extensions include:

Processing and understanding these header extensions is mandatory for a BFC server, and most, when present, require mustUnderstand="1". The exception is the manifest extension, which becomes mandatory when the document is part of a compound package. In this case, it must be present and mustUnderstand="1" is required. If the manifest header is used only to verify package integrity or catalog what is contained in the document, processing its contents is not required.

The following example, extracted from the BizTalk Framework 2.0 specification, illustrates the endpoints header extension:

<SOAP-ENV:Header>
  <eps:endpoints SOAP-ENV:mustUnderstand="1"
      xmlns:eps="http://schemas.biztalk.org/btf-2-0/endpoints"
      xmlns:agr="http://www.trading-agreements.org/types/">
    <eps:to>
      <eps:address xsi:type="agr:department">Book Orders</eps:address>
    </eps:to>
    <eps:from>
      <eps:address xsi:type="agr:organization">Book Lovers</eps:address>
    </eps:from>
  </eps:endpoints>
</SOAP-ENV:Header>

Services incorporating such proprietary header definitions are not fully interoperable with clients or other servers that don’t understand them. While they’ll probably be able to fail in a predictable and understandable fashion through the SOAP Fault, they won’t get past that level.

SOAP 1.1 specifies a content type of text/xml in the HTTP header. This type designation is problematic, though. MIME user agents that do not support text/xml explicitly treat it as text/plain, displaying the XML MIME part as plain text. This plain text display is not appropriate for casual users (not programmers) who can’t be expected to take interest in the contents of a SOAP document. The XMLP group has agreed that text/xml should not be used. One proposal is to use a media type of application/soap, for which application is the MIME media type name and soap is the MIME subtype name. An extension mechanism may be provided; for example, application/soap+xml could be used to describe SOAP1.2 messages serialized as XML. Because SOAP 1.2 is based on the XML Infoset, alternate serializations of messages are permitted. The application/soap+xml content type would identify SOAP messages using XML 1.0 serialization.

Whatever the outcome of the XMLP discussions, text/xml will not be supported in SOAP 1.2.

SOAP 1.1 defines a mustUnderstand attribute, which we discussed in Chapter 4. Apache SOAP does not support the mustUnderstand attribute. It offers a workaround; an attribute in the deployment descriptor tells the runtime (per-service) whether to fault if any mustUnderstand headers are present. This workaround is supported only for RPC-style SOAP.

SOAP 1.1 defines values for the mustUnderstand attribute as 0 (false) or 1 (true). Some implementations have used the values false or true. The SOAP 1.2 draft indicates that true or 1 may be used (and because the value is defined as Boolean, one would assume 0 or false are also valid). This definition may present a problem with backward compatibility for some implementations. The use of unique namespaces for each version of SOAP should prevent most interoperability problems in this regard, however.

There have been some differences in the interpretation of how a given actor should verify that it understands all headers with mustUnderstand equal to 1 or true. One interpretation is that all mustUnderstand headers should be checked prior to processing. A second interpretation is that mustUnderstand headers can be checked and processed individually. The outcome from these varying approaches can also differ. XMLP has proposed the following change to clarify this processing order:

In SOAP 1.1, the actor attribute provides a targeting capability. An actor is of the type anyURI and can have more than one URI identifier. The target, or final recipient, can be designated in two ways: explicitly as the next actor or by the absence of an actor. Providing multiple ways to identify the targeted destination can result in confusion and interoperability between implementations.

There is semantic confusion about SOAP 1.1’s definitions for the designated roles of actors. The terms (default actor, anonymous actor, ultimate recipient, and endpoint) are not commonly understood and are often used interchangeably. For example, the lack of consensus about what the term “endpoint” means is a problem: does it designate a final destination, or can an intermediary be considered an endpoint? This lack of semantic consensus has resulted in misunderstandings between implementations.

WSDL works well with Java and the .NET programming languages, but does not work as well with dynamic languages such as Python or Perl. This may be because participants from these development environments were not involved in the initial development of the WSDL specification. WSDL has since been submitted to the W3C, so it will hopefully be modified to become a more useful standard across environments.

WSDL allows <wsdl:documentation> elements to occur at numerous places in a WSDL document. Depending on how a toolkit works, it may map WSDL documentation in various ways. For example, Systinet’s WASP maps WSDL to Java by generating a Java interface from the WSDL portType, so the portType documentation element is used for the interface’s javadoc. Methods are generated from portType and its operations, so the corresponding documentation element is the documentation used for a method’s javadoc.

Because this behavior is not standardized, toolkits may map documentation elements differently.

Web services tools generate WSDL based on nonstandardized language mappings. The way a SOAP/XML schema library reads a WSDL document and matches return values can vary based on the implementation. Furthermore, not all toolkits support the same set of options in the WSDL standard.

A WSDL file may require some minor customization to function on a specific platform or with a specific toolkit, depending on the implementation. For example, Microsoft SOAP Toolkit 2.0 used a namespace of wsdlns when generating a WSDL. The proxy generator tool in IBM’s Web Services Toolkit did not recognize this namespace. To make the tool work, wsdlns had to be deleted in the tool’s local copy of the WSDL.

Initially, incompatibilities existed between the SOAP::Lite WSDL reader for Perl and the .NET WSDL generator. The SOAP::Lite reader expected all XSD type information to be contained in a namespace xsd. A .NET-generated WSDL file required modification to change the XML namespace from:

xmlns:s=http://www.w3.org/2001/XMLSchema

to:

xmlns:xsd=http://www.w3.org/2001/XMLSchema

The XSD namespace version of this declaration can also be problematic and may require modification in the local copy of the WSDL. For example, if the tool uses the 1999 XSD, it will not understand the 2001 XSD. We’ll go into more detail about XSD versions later.

Although you would think otherwise, you can’t assume that tools from the same vendor will always interoperate. Problems have been reported when reading a WSDL document between .NET Beta 2 and the SOAP Toolkit Version 2.

Toolkits may add value by hiding interoperability problems from the developer. To do this, they must map between the vendor-specific features and misfeatures of different web service platforms. Hiding interoperability problems isn’t as good as eliminating them, but it’s still a valuable service.

Versioning of WSDL (and of web services in general) is not well understood and there isn’t much agreement about how it should work. Currently, WSDL supports implicit versioning through unique namespaces.

One opinion is that WSDL, similar to a CORBA IDL, represents an immutable contract, and a new web service requires a new WSDL document, not just a new version of an existing WSDL. Others feel that a WSDL document can be versioned to support the enhancement of a web service, allowing one document to support multiple versions of the web service. Depending on how support is implemented, interoperability can be impacted severely. Migration to newer versions of web services can also cause problems, creating registry and implementation interoperability issues.

Endpoints are defined through portTypes and operations. However, WSDL does not provide a standard way to pass this information over the wire. For example, the BizTalk Framework 2.0 defines endpoints in a BizTalk header extension, explained in more detail in the SOAP section of this chapter. Implementations that do not support BizTalk will not understand endpoints defined through this mechanism.