9 Interoperability Guidelines

SOAPBuilders Community

SOAPBuilders is a loosely organized forum of developers working towards a set of tests for interoperability between SOAP implementations. Interoperability is demonstrated by implementing a canonical set of tests that are collectively defined by the participants in the forum.

The tests developed by the SOAPBuilder community are, by and large, based on vendor practices. However, practices shift over time. Clean and well-defined rules organized in a formal manner are needed for Web service vendors, Web service developers, and Web service consumers. See the following Web site for more information on SOAPBuilder tests: http://java.sun.com/webservices/interop/soapbuilders/index.html

WS-Interoperability

The Web Services Interoperability organization (WS-I) is an open industry organization that creates, promotes, and supports generic protocols for the interoperable exchange of messages between Web services. WS-I profiles are guidelines and recommendations for how the standards should be used. These profiles aim to remove ambiguities by adding constraints to the underlying specifications.

WS-I deliverables are profiles, common or best practices, scenarios, testing software, and testing materials. You should design your Web service so that it adheres to WS-I basic profiles. WS-I compliant services agree to clear contracts and have a greater chance of interoperability.

For example, a WS-I basic profile-compliant Web service should use the following features.

• Use HTTP or HTTPS as the transport binding. HTTP 1.1 is preferred over HTTP 1.0.

• Use literal style encoding. Do not use SOAP encoding.

• Use stricter fault message syntax. When a MESSAGE contains a soap:Fault element, its element children must be unqualified.

• Use XML version 1.0.

• The service should not declare array wrapper elements using the convention ArrayOfXXX.

The WS-I Web site provides more information about WS-I profiles, and the rules defined within profiles: http://www.ws-i.org/

Oracle is a member of the WS-I organization and is fully committed to helping our customers achieve interoperability. The Oracle Infrastructure Web Services platform allows a high degree of flexibility to help you create interoperable Web services.

Oracle JDeveloper supports integrated testing of WSDL files and running Web services for WS-I Basic Profile conformance. It delivers an enhanced HTTP Analyzer for monitoring and logging, and provides a built-in analysis and reporting tool to better diagnose interoperability issues. For more information, see the Oracle JDeveloper online help.

Design Your Web Service Top Down

The top-down from WSDL approach enables you to design your Web service from service contracts that are not tied to any platform or language-specific characteristics. Contract-level interoperability can be ensured even before your Web service is implemented. Other Web service platform tools will be able to process your WSDL file and it is less likely that the service will be affected by existing legacy APIs.

Design Your Data Types Using XSD First

If possible, use an XSD schema editor to design your data types with schema types. Resist using platform-specific data types such as the .NET DataSet data type, Java collections, and so on.

Keep Data Types Simple

Avoid unnecessarily complex schema data types such as xsd:choice. Simple types provide the best interoperability and have the added benefit of improved performance.

public class MyAnyType {
    //No member variable
}
 
public class MyPossibleType1 extends MyAnyType {
    //member variable.
}
 
public class MypossibleType2 extends MyAnyType {
    //member variable
}
..

Use Null Values With Care

Decide what you want to do with null values. For example, should an array be allowed to be null? Should you use a null string or an empty string? If you are sending a null value across platforms, will it cause exceptions on the receiver side?

Avoid sending null values if possible. If you must use null values in your application, design your schema types to clearly indicate that a null value is allowed.

Use a Compliance Testing Tool to Validate the WSDL

If your Web service is designed to be WS-I compliant, use the WS-I monitor tool to log messages and the analyzer tool to validate for conformance. You can obtain free downloads of WS-I tools from the following Web site: http://www.ws-i.org/deliverables/workinggroup.aspx?wg=testingtools/

Consider the Differences Between Platform Native Types

Some schema types, such as xsd:unsignedshort and xsd:unsignedint, do not always have a direct native type mapping. For example, there are no Java platform equivalent unsigned types. Schema numeric types such as xsd:double, xsd:float, and xsd:decimal might have different precisions once mapped to their platform native types.

There are also limitations on the xsd:string type. The strings must not contain illegal XML characters and the \r (carriage return) character will typically be mapped to the \n (line feed) character.

Use byte[] instead of xsd:string when you do not know the character set that the source data uses. Binary content is more interoperable than text content.

If you are creating the Web service bottom up from Java classes, you must ensure that you use the closest possible data type. Thus, use Java data types closer to the xsd:type. For example, if you want to use xsd:dateTime to represent a date and time, then use the javax.xml.datatype.XMLGregorianCalendar data type instead of java.lang.Data or java.util.Calendar. The XMLGregorianCalendar data type can return a more precise time because it can store fractional seconds.

If you are creating the Web service top down from WSDL, use mapping files to map the xsd:dateTime to XMLGregorianCalendar if time accuracy is very important.

Avoid Using RPC-Encoded Message Format

By itself, the RPC-encoded message format does not imply that you will not be able to interoperate with other platforms and clients. In many cases, there are RPC-encoded Web services which are in use today. The reason to move away from RPC-encoded message formats is to avoid some of the edge cases where different interpretations of the underlying specification and implementation choices break interoperability. Some examples include the treatment of sparse arrays, multi-dimensional arrays, custom fault code QNames, un-typed payloads, and so on.

Avoid Name Collisions

If you are creating Web services bottom up from Java classes, you can avoid name collisions by using explicit package names in your classes. If you are creating Web services top down from WSDL, you can avoid name collisions by using unique namespace URIs.

Use Message Handlers, Custom Serializers, or Interceptors

You can use message handlers, custom serializers, or interceptors to easily fix some interoperability issues. This idea is to fix the issue on the payload at a very granular level, by intercepting and changing the message either before it encounters the deserializers, or after the payload is generated by the serializers and before it is put on the wire.

Apply WS-* Specifications Judiciously

Many WS-* specifications are in early adoption phase, and could potentially reveal interoperability issues with different stacks. A suggestion would be to make sure that a WS-* feature is absolutely required before applying it. Another suggestion would be to apply features that are most commonly used in the Web services space. For example, if you are in a situation where there are several possible options, such as choosing either Basic Authentication, X.509, or Kerberos for security, then choose the option which is most commonly used in the Web services space.