James McCarthy (mailto:jmccarthy@symmetrysolutions.com?subject=Reap), President and CTO, Symmetry Solutions, Inc.
While most Web services are built around remote procedure calls, the WSDL specification allows for another kind of Web services architecture: document style, in which whole documents are exchanged between service clients and servers. In this article, James McCarthy explains what document style is and when you should use it.
Buried deep in the Web Service Definition Language (WSDL) specification is a very subtle switch that can turn the SOAP binding of a Web service from a remote procedure call to a pass-through document. The style attribute within the SOAP protocol binding can contain one of two values: rpc or document. When the attribute is set to document style, the client understands that it should make use of XML schemas rather than remote procedure calling conventions. This article will provide a description of this WSDL switch, describe its benefits, and explain when you should use pass-through documents.
Setting your service to use document style
First, let's briefly touch on a few point about WSDL to understand how this subtle change occurs. WSDL is an XML specification that is used to describe network services and the protocol-specific requirements for reaching an endpoint (the service). WSDL describes services in abstract terms; through an extensible binding definition, it is able to define the protocol and data format specifications for calling a service in concrete terms. The following grammar, taken directly from the WSDL specification, shows the extensibility elements contained within a binding:
Listing 1. WSDL grammar for extending elements within a binding
<wsdl:definitions .... >
<wsdl:binding name=3D"nmtoken" type=3D"qname"> *
<-- extensibility element (1) --> *
<wsdl:operation name=3D"nmtoken"> *
<-- extensibility element (2) --> *
<wsdl:input name=3D"nmtoken"? > ?
<-- extensibility element (3) -->=20
</wsdl:input>
<wsdl:output name=3D"nmtoken"? > ?
<-- extensibility element (4) --> *
</wsdl:output>
<wsdl:fault name=3D"nmtoken"> *
<-- extensibility element (5) --> *
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
< /wsdl:definitions>
The WSDL specification (see the Resources section below for a link) currently describes three binding extensions: HTTP GET/POST, MIME, and SOAP version 1.1. The binding extensions defined in HTTP GET/POST and MIME are used to define the requirements to communicate with standard Web applications that may or may not return XML documents. When sending or returning an XML document, the HTTP GET/POST binding extension is implicitly document style.
The SOAP binding extension is used to define a service that supports the SOAP envelope protocol. The SOAP envelope is a simple schema that is designed to contain an XML message, providing an application-specific header and a body portion of the message. The SOAP binding extension allows the WSDL document to declare the requirements of a SOAP message so that the application is able to properly communicate with the service. The SOAP extension allows the style of the SOAP message to be declared as either document or RPC. If the style attribute is declared in the soap:binding element, then that style becomes the default for all soap:operation elements that do not explicitly declare a style attribute. If the style attribute is not declared in the soap:binding element, then the default style is document. Here is an explicit declaration of document style:
Regardless of the declaration within the soap:binding element, the soap:operation element can override the declaration for each operation, like so:
In a SOAP message for which document style is declared, the message is placed directly into the body portion of the SOAP envelope, either as-is or encoded. If the style is declared as RPC, the message is enclosed within a wrapper element, with the name of the element taken from the operation name attribute and the namespace taken from the operation namespace attribute.
Benefits of document style
No one can dispute that the ability to invoke a cross-platform remote procedure call using XML is extremely useful and is a compelling argument for using Web services. But if Web services were constrained exclusively to RPC messaging, the reach of the technology would be limited. Fortunately, developers have a choice of using either RPC or document style messaging and are able to use the right technology for the tasks they face.
With document style, you can make full use of XML
The XML specification was developed to allow ordinary data that is usually locked up in a proprietary format to be described in an open format that is human readable, self-describing, and self-validating. When a Web service uses document messaging, it can use the full capabilities of XML to describe and validate a high-level business document. When a service uses RPC message formatting, the XML describes the method and the parameters encoded for the method call and cannot be used to enforce high-level business rules. In order to enforce these rules, the RPC message must include an XML document as a string parameter and hide the validation within the method being called. For this reason, some of the benefits of XML are lost, or at least hidden within the back-end application.
Document style does not require a rigid contract
Another reason to use document messaging is that a remote procedure call is meant to be relatively static and any changes to the interface would break the contract between the service and the application. If a service is widely distributed, then it is likely that a large number of applications have produced stub code from its WSDL document. Changing the WSDL would cause all of the applications that rely on a specific method signature to break and a lot of support lines to ring. Good design dictates that the method signature of an RPC message service should never change. With document messaging, the rules are less rigid and many enhancements and changes can be made to the XML schema without breaking the calling application.
Document style is better suited for asynchronous processing
When businesses are using a Web-based application to exchange information over the Internet, the application should be able to use a guaranteed delivery mechanism to improve its reliability, scalability, and performance. To achieve this, an application will generally use asynchronous message queues. Since a document message is usually self-contained, it is better suited for asynchronous processing and can be placed directly into the queue. The reliability of the application is improved because the message queue guarantees the delivery of the message even if the target application is not currently active; performance is improved because the Web application simply delivers the document to a queue and is then free to perform other tasks; and scalability is improved because the document is offloaded to one or more instances of an application that handles its processing.
Document style makes object exchange more flexible
The design of a business document is often very well suited to object-oriented architectures. As a result, two applications may be designed to exchange the state of an object by using XML. In contrast with object serialization, in an object exchange, each end of the exchange is free to design the object as it sees fit as long as the exchange conforms to the agreed upon XML document format. One reason for not using object serialization is to support client-side and server-side implementations of an object. Many current industry-specific XML schemas are designed as client/server architectures in which the processing that is done at the client is separate from the processing intended at the server. As is often the case, the client is simply requesting or saving information in a specific document format that is persisted at the server. Certainly, this type of exchange could be done using an RPC message, but the encoding scheme of such a message places constraints on the design of the object at each end. These constraints are not a problem with document style.
When to use document style
When should you use document style? The short answer: Anytime you are not interfacing to a preexisting remote procedure call, the benefits of document style may outweigh the extra effort that is often required to interface to the service. A caveat: The effort to build a service that uses document messaging is usually greater than the effort required to build an RPC message service. This extra effort usually involves the design of an XML schema or support for a preexisting schema, as well as the extraction of relevant information from a document. The schema design is important because the XML parser uses the schema to validate the document, supporting the intended business rules. Additional effort is required by the service to extract relevant information from the document to be used while handling the request. In contrast, an RPC message only requires the design of the method interface, from which it will automatically marshal and unmarshal the parameters.
When making your decision to publish a service, you might want to consider the following questions. I'll examine the consequences of your answers in the following sections.
Is this service interfacing to a preexisting procedure call and is the procedure call stateless?
Is the service to be used only within your organization, or by outside users as well?
Is one of the parameters simply an XML document specification?
Does the service require a request/response architecture?
Do the parameters represent complex structures that may benefit from an XML document schema for validation?
Can all of the information that needs to be exchanged be reasonably contained in memory?
Use document style when maintaining application state
You should consider a document architecture for your service if multiple procedures must be called in a particular sequence to maintain application state. If multiple procedure calls are required, then the procedure is not stateless and the service must maintain application state. Maintaining state within a Web service can be difficult; in the case of a remote procedure call, very few client platforms will generate stub code that is able to support state information. One possible solution is to use document architecture and pass the contents of an entire transaction within the document. In this case, the service will perform the calls to ensure that the proper sequence is maintained inside the service and state information is not maintained beyond a single transaction. If state information is still required, it can be built in to the resulting document, or the client application can maintain a token that identifies its state to the service.
Use document style to publish services for outside partners
If an application is being published outside of the organization, the publisher has very little control over who is relying on the service and what the consequences will be if any changes are made. In such cases, it may be more advantageous to use document messaging and support a common exchange protocol such as ebXML. Common exchange protocols are evolving to improve the management of external exchanges so that new trading partner agreements can be rapidly deployed. Also, if your service does not require a request/response architecture, then common exchange protocols are better designed to handle authentication, reliable message delivery, and asynchronous request/response.
Use document style to ease validation and use of complex documents
If your service is using a string parameter to pass or return an XML document, or if one of its parameters is an object with a complex structure that requires custom handling, then document messaging may be the better alternative. Hiding the true meaning of a parameter within a string can often lead to valid calls with invalid parameters. If the service publishes an XML document schema, then it is easier to validate against that schema prior to calling the service. A complex structure is often used to pass hundreds of pieces of information making up a complete transaction. When dealing with complex structures, a remote procedure service may have to deal with custom marshaling code while the application is still responsible for meticulously validating each element of the structure. If document messaging is used, then the application programmer can offload validation to the document designer using an XML schema, and no custom marshaling code is required.
Use document style to minimize in-memory processing
One final consideration when choosing between document and RPC messaging is the amount of information that may need to be handled. Since most if not all of the implementations that marshal parameters in RPC messaging perform this operation in-memory, memory constraints may make RPC messaging unfeasible. Many document-messaging services are able to choose between DOM and SAX handling of the document and as a result are able to minimize in-memory processing. This is particularly critical for a Web service that may be required to handle thousands of requests, many simultaneously.
Conclusion
When designing your next Web service, you need to consider all of the options that the current WSDL specification gives you. Before starting with a procedural interface, consider how the service will be used, who will be using it, and the type and volume of information that needs to be exchanged. Designing and developing a document style Web service may require a little more effort, but in many cases the effort will pay off in the quality of information and the reliability of the exchange.
Resources
"Deploying Web services with WSDL," Bilal Siddiqui (developerWorks, November 2001) is a good introduction to the Web services and Web Services Description Language.
Check out the specifications for WSDL and SOAP.
The XMethods site is hosting a demo Web service that is built using document style.
Check out the latest on IBM's Web Services initiative.
No comments:
Post a Comment