Best Practices and Pitfalls

When implementing Web services, particularly if it is already known that they are going to be used in a mixed-mode environment, there are a number of best practices that can be followed to ensure smooth interoperability. These include the following:

Data Type Definitions and Interoperability Testing

It is important to define the data types to be exchanged early on in the integration cycle. Knowing what data types work and what types don't in the early stages of integration mitigates risks and also helps define the integration architecture and design with greater consistency. It is also important to carry on interoperability testing at every stage of the integration life cycle especially if the integration encompasses multiple Java EE .NET applications.

Keep Types SimpleAvoid Advanced XML Schema Constructs

The XML Schema standard is very complex and difficult to implement. Moreover, XML Schema processing is quite time-consuming, so many frameworks sacrifice full XML Schema support for performance. Some advanced XML Schema constructs (for example, choice) are quite hard to express in a programming language, and few Web services frameworks support them. So the key success factor in Web services interoperability is to use basic data types, such as primitive data types, arrays, and structures. As a best practice, decompose the complex types in your interfaces into simple and clean interfaces with basic datatypes that are XSD-compliant. Also avoid using specific techniques (for example, INOUT parameter passing) that aren't widely supported.

Provide XML Schema Definitions for All Data Types

One common problem in today's frameworks is their limited ability to import multiple XML Schema and WSDL documents. It's always a good idea to provide complete XML Schema and WSDL definitions in one WSDL file rather than importing them from various locations. Specifically, the Microsoft .NET Framework is sensitive to XML Schema import functions.

Here is an example: If the need to include multiple WSDL and XML Schema files in a Microsoft .NET service is discovered, it is easier to pass the XML Schema definitions together with the WSDL definition to the command line MS Microsoft .NET WSDL compiler rather than trying to import the schemas into the WSDL file:

wsdl.exe/language:CS /protocol:SOAP MyService.wsdl MySchema.xsd JavaCollections.xsd 

WS-I Compliance

For better interoperability, it is recommended to adhere to the Web services interoperability guidelines in WS-I Basic Profile, discussed previously. Check the www.ws-i.org site for more details.

Multiple WSDL Bindings

Some frameworks generate multiple WSDL bindings that allow access to a Web service through multiple methods (that is, HTTP GET, HTTP POST, and SOAP). The client-side framework needs to know which binding to use, so specification of further parameters (usually the fully qualified name of the service and the name of the WSDL port) is needed when generating the programming language bindings from the WSDL document.

Default Document Style with Literal Encoding

Some Web services frameworks, including MS Microsoft.NET, generate, by default, a document style Web service, using literal encoding. Although the Web service uses document/literal, the Microsoft .NET Framework makes the service appear to be RPC style to Microsoft .NET clients. This isn't necessarily so for other Web service frameworks, and many users may find it difficult to access the Web service using an RPC style client. So if you're writing an RPC Web service, force your framework to generate the RPC style WSDL.

For example, use the [SoapRpcService] directive in your MS Microsoft .NET RPC Web service implementations, as shown here:

<%@ WebService Language="C#"  %> using System.Web.Services; using System.Web.Services.Protocols; using System.Web.Services.Description; [SoapRpcService] public class MSNetStockService {   [WebMethod]   public double getQuote(string symbol) {     if(symbol == "SUNW") {       return 10;     }     if(symbol == "BEAS") {       return 11;     }     if(symbol == "MSFT") {       return 50;     }     return 0;   } } 

Use Unique SOAPActions for Your Methods

If you start your Web service development with a WSDL document definition, consider using unique SOAPAction attributes for all your methods in the WSDL binding. Some frameworks rely on SOAPAction when routing SOAP messages to the Web service implementation's methods.

For example, consider the following WSDL binding for a stock quote service:

<binding name="MSNetStockServiceSoap"         type="tns:MSNetStockServiceSoap">   <soap:binding transport="http://schemas.xmlsoap.org/soap/http"        style="rpc" />   <operation name="getQuote">     <soap:operation soapAction=http://tempuri.org/getQuote          style="rpc" />     <input>       <soap:body use="encoded" namespace="http://tempuri.org/"        encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />     </input>     <output>       <soap:body use="encoded" namespace="http://tempuri.org/"        encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />     </output>   </operation> </binding> 

Consider MTOM When Handling Attachments

There are many formats that have been bandied about to handle attachments in Web services. These include SOAP with Attachments (SwA), Direct Internet Message Encapsulation (DIME), and Message Transmission Optimization Mechanism (MTOM) [W3CMTOM]. The former, while powerful, were unable to encapsulate the needs of security, being incompatible with WS-Security, the standard specification for using security within SOAP messages. MTOM, on the other hand, overcame this flaw and was moved into recommended status by the W3C. MTOM is supported in the Microsoft Web Services Enhancements (version 3.0).

Using MTOM in .NET Web services is very straightforward and is all configuration-drivenmeaning that an existing Web service code does not need to be changed. Assuming WSE 3.0 is installed, the web.config file for the application is amended to enable MTOM. For example, if all incoming and outgoing SOAP messages are to be MTOM-encoded, the following sections will be in the web.config file:

<configuration>   <configSections>     <section name="microsoft.web.services3" type="Microsoft.Web.Services3.Configuration.WebServicesConfiguration,         Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral,         PublicKeyToken=xxxxx" />   </configSections>   <system.web>     <webServices>       <soapServerProtocolFactory           type="Microsoft.Web.Services3.WseProtocolFactory,             Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral,             PublicKeyToken=xxxxx" />     </webServices>   </system.web>   <microsoft.web.services3>     <messaging>       <mtom serverMode="always" />     </messaging>   </microsoft.web.services3> </configuration> 

Once the web.config is configured for WSE 3.0 and MTOM, Web method can be built in the Web service that returns a binary file as an array of bytes with a Web method like this

[WebMethod] public byte[] GetFileBinary(String fileName) {   StringBuilder filePath = new StringBuilder();   filePath.Append(AppDomain.CurrentDomain.BaseDirectory);   filePath.Append("App_Data\");   filePath.Appent(filename);   return File.ReadAllBytes(filePath.toString()); } 

When using MTOM, the attachment appears within the body of the SOAP response. To call this from Java using JAX-WS, the GetFileBinary method is used.

ServiceFactory serviceFactory = ServiceFactory.newInstance(); Service service =   (Service)serviceFactory.createService(     new URL("http://localhost/binread/reader.asmx?WSDL"),            Service.class); ServiceSoap soap = service.getServiceSoap(); SOAPBinding binding = (SOAPBinding)((BindingProvider)soap).getBinding(); binding.setMTOMEnabled(true); byte[] fileData = soap.getFileBinary("Myfile.jpg"); FileOutputStream fStream =    new FileOutputStream("C:\\MyFile.jpg"); fStream.write(fileData); fStream.flush(); fStream.close(); 

The JAX-WS Soap binding object now supports a flag that allows MTOM to be enabled using the setMTOMEnabled flag. Once this is set, then it becomes a simple matter of calling the Web method and using a FileOutputStream to get the response.

Long Running B2B Transactions

Web services, while enormously useful, are not magic bullets that can tie all business processes together into a cohesive whole. There are a number of pitfalls that might be encountered when using them. One such pitfall is when there is a long running transaction, particularly one that requires maintenance of state during the transaction lifecycle. When using synchronous Web services, state isn't maintainedand as such these transactions become infeasible. Also many business transactions require asynchronicitythe callee returns to the caller at the end of the transaction once it is complete, which, depending on the transaction, can take milliseconds or can take years. For synchronous applications and Web services to wait for the completion of longer running services, resources would have to be used to maintain the long connections, which is infeasible, expensive, and prone to error.

Design Difficulties

In mixed-mode systems, there are interoperability challenges when passing complex data types between Web services implemented on .NET and those implemented using the various Java EE methodologies and application servers. One approach to ease this is to do contract-first design and implementation where the WSDL that describes the Web service is agreed upon by parties from both development teams and becomes the specification for developing the Web service and its clients. Coding from a WSDL-first approach can be difficult and tedious, as WSDL is intended to be a machine-readable, machine-producible format. Typically design tools such as Visual Studio.NET encourage the developer to build his or her logic in code such as C#, and it handles generation of the WSDL that describes this code when the service runs. However, following this easier approach (having the machine produce the WSDL) can lead to many interoperability challenges.

Debugging and Maintenance

Synchronous Web services pass messages to each other using XML encoded as SOAP. This is designed to be a machine-readable format containing service invocation via method calls and returned data in consistent packaging. When developing synchronous Web services, particularly ones in mixed-mode architectures containing .NET, Java EE, or other runtime operation platforms, the process of debugging and doing root cause analysis of failures is a difficult one. Consider the case where a .NET client calls a Java EE application server and there is a failure. There is no consistent application execution stack that the whole application can be debugged to. The caller can validate that he sent out a SOAP packet, and the receiver can validate that he received a SOAP packet, but when something goes wrong, the tendency is there to blame the other party, but it is difficult to verify exactly where the problem lies.

Performance and Stability

Web services give businesses tremendous flexibility in exposing their business assets in a machine-readable way that is easy to integrate. But this comes at a costperformance. The overhead of exposing access to assets through a Web service stack involves the development of an application or layers of applications that access that information, encoding the response as XML/SOAP, and handling requests from incoming clients to get the information, encode it, and return it. This is problematic because first, it is slower than direct access to the asset (such as through a JDBC/ADO.NET connection to a database), and second, it doesn't take advantage of the automatic scaling or connection pooling provided by enterprise resource assets such as databases. Note that the Web service code itself can take advantage of these when accessing the Resource tier, but its external interface to the clients cannot unless it is explicitly coded to do so (further decreasing performance and increasing complexity) or it is configured to run on a system that provides these services.