JaVa
   

Describing Functional Characteristics of Services

Functional characteristics of a Web service pertain to the service interface (the "how") and its deployment information (the "where"), which together provide the requisite information for invoking the service. Service-oriented architectures are not a new concept, and consequently, published services have in the past had their functional characteristics described using different standards. Readers who have worked with CORBA and COM will remember respective interface definition languages that described the methods and method signatures of CORBA and COM components. EJB and RMI programmers may know that a Java remote interface served a similar purpose in distributed Java computing environments. WSDL serves a similar function for Web services. A WSDL service description is the XML grammar and vocabulary to describe a Web service. The WSDL specification was submitted to the W3C in the fall of 2000. The entire WSDL note is available at www.w3.org/TR/wsdl.

WSDL Document Overview

Minimally, the consumer will need to know the service's signature (what goes in and what comes out), its location, and the wire protocol to be used to send the invocation message. A WSDL document provides this information. The information is organized in two logical sections, shown in Screenshot: abstract descriptions and concrete descriptions.

Java Click To expand
Screenshot: WSDL document— a conceptual representation

Abstract Descriptions

Consider a Java object with just one public method. When another object interacts with it by invoking its public method, the interaction can be characterized as a series of message exchanges. The object accepts the incoming message, may return an outgoing message, and may throw an exception message. Each type of message can be described further by listing the data types and the order of its parameters. Now consider a Java object with multiple methods, each of which defines one possible interaction with the object. In each interaction, up to three messages may be exchanged. Each message can be further described by describing the data types exchanged. When the object has multiple methods, it is possible that some methods exchange the same messages (two methods could have the same return value; i.e., the same "output" message) and that some data types are common across messages. To represent the information about the object without duplicating information (normalized form), one would

  1. Describe all the data types used in all messages.

  2. List all messages that can be exchanged and represent the message as a set of data types.
  3. Describe each method (interaction with the object) as a collection of input, output, and exception type messages.
  4. Describe what the object does as a collection of possible interactions.

For a Web service, these descriptions would need to be captured in a platform- and language-independent manner, which is the way a WSDL document organizes information. In WSDL, each of these four abstract descriptions is an element in the XML. The four elements are listed here and are covered in detail later in this chapter.

  1. types: contain the platform- and language-independent data type definitions

  2. messages: contain input and output parameters for the service and describe different messages the service exchanges
  3. operations: represents a particular interaction with the service and describes the input, output, and exception messages possible during that interaction
  4. portTypes: uses the messages section to describe function signatures (operation name, input and output parameters) and represents a set of operations supported by the service

Concrete Descriptions

Each Web service or "endpoint" runs on a network address. The Web service also understands a particular protocol, or format, in which messages and data are sent to it . These aspects of the service description are specific to the implementation of the service and are thus logically grouped into one category. In short, the concrete descriptions define the implementation-specific descriptions for the Web service. Two significant elements in the WSDL XML fall into this category, each of which is covered in detail later in this chapter.

  1. bindings: specifies binding of each operation in the portTypes section.

    It associates the abstract descriptions of a portType (i.e., a portType's operations, messages, and data types) with a network protocol.

  2. services: In addition to protocol-specific information, the WSDL document should also describe where the service is deployed. The association between a binding and the network address at which it can be found is defined by a port. The service element is a collection of ports, and a port describes a network location for a binding.

The logical separation of abstract information (such as methods, parameters, and error messages) from information that changes with implementation type (such as transport protocols) allows reuse of abstract definitions of the service across different implementations of the service. As an example, the same service may be exposed as an HTTP service and an SMTP service. In both cases, the service performs the same function, so the abstract description of the service and its methods can be reused, and only the concrete, implementation-specific information needs to be changed across the two instances of the service.

WSDL and Dynamic Interactions

A practical way to understand the role of the seven key elements in a WSDL document is to keep in mind the service consumer's interaction with the service. This is illustrated in Screenshot.

Java Click To expand
Screenshot: Dynamic interaction of a service and its consumer

A Web service exposes groups of business operations for service consumers to use. Operations are grouped to form portTypes. To perform an operation, consumers send an input message containing input data. They receive an output message containing the data that results from processing the input or a fault message in case of any problem in processing. The input and output messages may have multiple data items in them; each is called a part. The wire protocol used for the invocation and the format of the input and output messages on the wire for that protocol are specified in a binding. The service exposes itself to the consumers though one or more ports, where each port specifies a network address giving the service's location. and the binding to XML Schema use with that port. A service may render itself though several ports, where each port has a different binding (e.g., the same service may expose itself via SOAP/HTTP and SOAP/SMTP). Screenshot is a logical class diagram that shows the relationship among the seven key elements that make up the abstract and concrete descriptions. Each binding references a portType, the operations in that portType, and the messages that constitute the operation. Each portType contains zero or more operations, each with an input and output message. Each message has zero or more parts, and each part is of some data type. The data type could be an inbuilt type in the standard (e.g., xsd:string) or a custom type defined in the types definition.

Java Click To expand
Screenshot: A logical class diagram of the key WSDL elements

Although the above overview of a WSDL document's elements may be confusing to the first-time reader, the following section, which explains WSDL document organization using a Java example, should help clarify the document's structure and form. A comforting thought for Java developers is that WSDL documents are well-formed XML documents, so a majority of the programmatic tasks associated with WSDL are tool driven. For example, tools automatically generate WSDL given a Java interface, and vice versa.

Elements of a WSDL Document

This section examines the WSDL document specification in greater detail. A Web service provided by Flute Bank is used to illustrate the different elements of a WSDL document. Flute Bank, beyond providing simple account-related services, also has the infrastructure to support online bill payments. The online bill payment system is offered to Flute's customers as a value-added service and is also available to other banks and financial institutions. In keeping with this chapter's goal of focusing on WSDL, the bill payment service illustrated is deliberately kept simple. The service assumes that payees or merchants have been registered with the bank and that Flute Bank's customers may only schedule new payments or view scheduled payments. If you were to write a Java RMI object for this service, it would look similar to Listing 5.1. The interface contains three methods:

Listing 5.1: Flute Bank's bill payment service illustrated as Java Interface
package com.fluteblank.billpayservice;
import java.util.*;
import java.rmi.Remote;
import java.rmi.RemoteException;
public interface BillPay extends Remote {
public PaymentConfirmation schedulePayment( Date date, String nickName, double amount)
 throws ScheduleFailedException,
 RemoteException;
public PaymentDetail[] listScheduledPayments() throws RemoteException;
public double getLastPayment(String nickname) throws RemoteException;
}




Java End example

Listing 5.2 shows the WSDL document that describes the same service. It also shows the mapping of BillPay interface elements to the corresponding WSDL elements.

Listing 5.2: Flute Bank's bill payment service WSDL document
<?xml version="1.0" encoding="UTF-8"?>
<definitions 
targetNamespace="http://www.flutebank.com/xml"
xmlns:tns="http://www.flutebank.com/xml"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
 <types>
 <schema targetNamespace="http://www.flutebank.com/xml"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://www.flutebank.com/xml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soap-enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns="http://www.w3.org/2001/XMLSchema">
 <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
 <complexType >
 <complexContent>
 <restriction base="soap-enc:Array">
 <attribute ref="soap-enc:arrayType"
 wsdl:arrayType="tns:PaymentDetail[]"/>
 </restriction>
 </complexContent>
 </complexType>
 <complexType >
 <sequence>
 <element type="dateTime"/>
 <element type="string"/>
 <element type="string"/>
 <element type="double"/>
 </sequence>
 </complexType>
 <complexType >
 <sequence>
 <element type="int"/>
 <element type="string"/>
 <element type="double"/>
 </sequence>
 </complexType>
 <complexType >
 <sequence>
 <element type="string"/>
 <element type="string"/>
 </sequence>
 </complexType>
</schema>
</types>
 <message name="BillPay_getLastPayment">
 <part name="String_1" type="xsd:string"/>
 </message>
 <message name="BillPay_getLastPaymentResponse">
 <part type="xsd:double"/>
 </message>
 <message name="BillPay_listScheduledPayments"/>
 <message name="BillPay_listScheduledPaymentsResponse">
 <part type="tns:ArrayOfPaymentDetail"/>
 </message>
 <message name="BillPay_schedulePayment">
 <part name="Date_1" type="xsd:dateTime"/>
 <part name="String_2" type="xsd:string"/>
 <part name="double_3" type="xsd:double"/>
 </message>
 <message name="BillPay_schedulePaymentResponse">
 <part type="tns:PaymentConfirmation"/>
 </message>
 <message >
 <part type="tns:ScheduleFailedException"/>
 </message>
<portType >
 <operation parameterOrder="String_1">
 <input message="tns:BillPay_getLastPayment"/>
 <output message="tns:BillPay_getLastPaymentResponse"/>
 </operation>
 <operation parameterOrder="">
 <input message="tns:BillPay_listScheduledPayments"/>
 <output message="tns:BillPay_listScheduledPaymentsResponse"/>
 </operation>
 <operation 
 parameterOrder="Date_1 String_2 double_3">
 <input message="tns:BillPay_schedulePayment"/>
 <output message="tns:BillPay_schedulePaymentResponse"/>
 <fault 
 message="tns:ScheduleFailedException"/>
 </operation>
</portType>
 <binding type="tns:BillPay">
 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
 style="rpc"/>
 <operation >
 <input>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://www.flutebank.com/xml"/>
 </input>
 <output>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://www.flutebank.com/xml"/>
 </output>
 <soap:operation soapAction=""/>
 </operation>>
 <operation >
 <input>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://www.flutebank.com/xml"/>
 </input>
 <output>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://www.flutebank.com/xml"/>
 </output>
 <soap:operation soapAction=""/>
 </operation>
 <operation >
 <input>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://www.flutebank.com/xml"/>
 </input>
 <output>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://www.flutebank.com/xml"/>
 </output>
 <fault >
 <soap:fault encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://www.flutebank.com/xml"/>
 </fault>
 <soap:operation soapAction=""/>
 </operation>
</binding>
 <service >
 <port binding="tns:BillPayBinding">
 <soap:address location="http://www.flutebank.com:0090/billpayservice/services/
 BillPay"/>
 </port>
 </service>
</definitions>




Java End example

XML Schema

Java mappings to WSDL and vice versa are prescribed by the JAX-RPC specifications and are covered in detail in . Screenshot provides an overview of how the different elements of the BillPay service WSDL correspond to the conceptual WSDL model introduced earlier.

Java Click To expand
Screenshot: BillPayservice service WSDL mapped to the WSDL conceptual model

The root element of a WSDL document is a definitions element, under which the rest of the XML elements are defined. The definitions element contains the relevant namespace declarations like http://schemas.xmlsoap.org/wsdl/, which describe the schemas being used for the document. Screenshot shows the with the first level of elements under the root element of definitions. The following sections examine these individual elements in detail.

Java Click To expand
Screenshot: The definitions element

Defining the Data Types for the Service: The types Element

The types element, shown in Screenshot, lists all user-defined data types used by the service. Although this example uses XML Schema definition (XSD), it is possible to use some other type system in a WSDL document. The WSDL specification recognizes that a single type system may not be able to describe all message formats and makes it possible to use other type definition languages via an extensibility mechanism. For all practical purposes, the types element can be thought of as the location where the schemas used are defined and referenced. XSD is also the canonical type system in a WSDL document. XSD is introduced in Appendix A, and the full XML Schema specification can be found at www.w3.org/XML/Schema.

Java Click To expand
Screenshot: The types element

The bill payment service contains two complex types, PaymentDetail and PaymentConfirmation. As an example, the schema definition for PaymentConfirmation user-defined is shown again on the following page:

<complexType >
 <sequence>
 <element type="dateTime"/>
 <element type="string"/>
 <element type="string"/>
 <element type="double"/>
 </sequence>
</complexType>


This corresponds to a Java bean:

package com.flute.webservice;
import java.util.*;
public class PaymentDetail extends Exception {
private String payeeName;
 private String account;
 private double amt;
 private Date date;
public PaymentDetail() {
}
public PaymentDetail(String payeeName, String account, double amt, Date date) {
 this.payeeName = payeeName;
 this.amt = amt;
 this.account = account;
 this.date = date;
}
public String getAccount() {
 return account;
}
...
other getters and setters for bean properties.


Like the Java-WSDL mappings, the exact semantics of mapping the XML to Java and vice versa are also prescribed by the JAX-RPC specification and are covered in detail in .

The WSDL specification does specify the special handling of arrays, which are described using the SOAP encoding (http://schemas.xmlsoap.org/soap/encoding). As of the time of writing the WSDL 1.1 specification, the XSD specification did not describe the mechanism to provide default values to array types, so WSDL introduces the arrayType attribute. Details of WSDL handling of array types can be found in the WSDL and XSD specifications.

Describing the Exchange: The message Element

When a Flute Bank customer invokes a method on the Flute Bank bill payment service, a series of messages is exchanged between the consumer and the service. For example, when the listScheduledPayments method is invoked, a message is sent from the consumer to the service; then the service may return an exception or a message with an array of scheduled payments. An interaction between a service consumer and the service usually entails a set of messages sent back and forth. All possible messages that can be exchanged between the service consumer and the service are listed in the WSDL document using message elements. A message element contains the abstract definition of the message content. The content of a message depends on the nature of the interaction between the consumer and the service. For example, in an RPC style interaction, a message sent by a consumer of a service may consist of zero or more parameters, so the message can be described by listing its parameters. An asynchronous message may consist of name-value pairs. In general, a message may be thought of as consisting of one or more logical parts. As Screenshot shows each part can be associated with a type, listed in the types element.

Java Click To expand
Screenshot: The message element
Java Start Sidebar

The WSDL wsdl:input, wsdl:output, and their corresponding wsdl:message elements map to Java arguments and method return values.

Java End Sidebar

In the example that follows, SchedulePaymentResponse represents a message sent by the bill payment service to a service consumer, to indicate the result of scheduling a payment. (This is the result of the service's having received a SchedulePayment message.) The message has only one part, named result. The type associated with that part is defined as an XSD complex type, PaymentConfirmation, in the types element of this document.

<message >
 <part type="ns2:PaymentConfirmation"/>
</message>


Each message has a name attribute that should provide a unique name to each message in the enclosing WSDL. Each message element has zero or more part elements. The part element has a name attribute to provide a unique name to each part and a type element, which associates the part with an XSD type (complex type or simple type). CORBA developers may recall the concept of in, out, and inout parameters. Like IDL, operations in WSDL may take out or inout parameters as well as in parameters. An out type is a variable that is initialized and set in the service and sent back to the client. An inout type is initialized in the client and set but possibly reset in the service and sent back. In other words, if an operation receives a parameter expected to change as a result of the operation, it is termed an inout parameter. As a general rule in WSDL, if a part name appears in

Java Start Sidebar

The concept of in, out, and inout parameters is tied to holder classes. Holder classes and these parameter types are covered in detail in .

Java End Sidebar

In many cases, the service will expect the parameters in a certain order, which consumers need to know. For this reason, the operation node described later in the port has an attribute called parameterOrder—a comma-separated list of parameters in the order in which they occur in the method signature. The fragment below is an example of how this is done.

<message name="BillPay_schedulePayment">
 <part name="Date_1" type="xsd:dateTime"/>
 <part name="String_2" type="xsd:string"/>
 <part name="double_3" type="xsd:double"/>
</message>
// other code ...
 <portType >
 <operation parameterOrder="Date_1 String_2
 double_3">
// other code ...
 </operation>
 </portType>


Describing Service Interactions: The operation Element

An operation defines an interaction (resulting in the exchange of one or messages) between a service consumer and a service in the abstract. The operation element is a container for all abstract messages that can be exchanged for a particular interaction with the service.

Java Start Sidebar

The WSDL operation element is analogous to and maps to a Java method declaration.

Java End Sidebar

An operation contains an input, an output, and one or more fault elements that reference the message elements described earlier. The fault elements represent the abstract message format for any errors or exceptional messages that may result as output of the operation.

Java Start Sidebar

The WSDL fault element is analogous to and maps to Java exceptions in a method declaration.

Java End Sidebar
<operation parameterOrder="Date_1 String_2 double_3">
 <input message="tns:BillPay_schedulePayment"/>
 <output message="tns:BillPay_schedulePaymentResponse"/>
 <fault 
 message="tns:ScheduleFailedException"/>
</operation>


As mentioned earlier, a service consumer and the service can have different types of interactions. Screenshot shows the schema for the operation element and the four different types of abstract operations.

Java Click To expand
Screenshot: The schema for the operations element
  • One-way. A one-way operation is one in which a message is sent to the service but no response is generated in return. A one-way message is useful to model "fire and forget" type messages, where the work done by the consumer of the message is asynchronous to the sender. In WSDL, a one-way operation does not have an output element. Screenshot shows the grammar for a one-way message. Note that this example is not a part of the bill payment service WSDL. Java Click To expand
    Screenshot: A one-way operation

    <operation >
     <input message="tns:logActivity"/>
    </operation>
    


  • Request-response. In a request-response type interaction, shown in Screenshot, the consumer sends a message to the service and waits for a response. The service may respond to the waiting requestor with a return message signifying the result of the request or with a fault message signifying that something went wrong. Java Click To expand
    Screenshot: A request-response operation

  • Flute Bank's bill payment service WSDL has the following operation:
    <operation >
     <input message="tns:schedulePayment"/>
     <output message="tns:schedulePaymentResponse"/>
     <fault message="tns:scheduleFailedException"
     />
     </operation>
    


    The input and output elements specify the abstract message that correspond to the request and the response respectively. The fault element specifies any error or exception messages that may result.

  • Solicit-response. A solicit-response-style operation, shown in Screenshot, has the reverse message flow of a request-response operation. The Web service sends a message to the client (output message) and receives a message from the client in response (input message). The grammar for this type of operation is similar to that of the request-response, except that the output element comes before the input element. Java Click To expand
    Screenshot: A solicit-response operation

    <operation >
     <output message="tns:schedulePaymentResponse"/>
     <input message="tns:schedulePayment"/>
     <fault message="tns:scheduleFailedException"
     />
    </operation>
    
    


  • Notification. In a notification-style operation, shown in Screenshot, the Web service notifies a client when an event occurs in which the client has registered interest. In such an interaction, from the viewpoint of the Web service, there is no input message, just an output message. As Flute Bank does not offer any notifications in the bill payment service, the grammar for a notification operation shown below is not a part of the bill payment service WSDL example. Java Click To expand
    Screenshot: A notification operation

    Java Start Sidebar

    WSDL provides the mechanism to describe different types of operations but does not define how, for example, solicit-response and notification messages are to be implemented in a Web service architecture. One approach might be to indicate, in the WSDL describing the service, how a service consumer is to handle these types of operations (e.g, explicitly describe how a callback or notification message can be correlated to the request). A better approach is to describe, in a separate specification, the different message exchange patterns that can be used in a Web service architecture—that is, describe message exchange patterns in the abstract. Protocol specifications like SOAP can then specify how that particular protocol supports all or some of the abstract message exchange patterns (i.e., how it provides a concrete implementation for each abstract message exchange pattern). WSDL operation bindings can then simply refer to the particular concrete pattern the protocol describes.

    SOAP 1.2 and WSDL 1.2 specifications propose a somewhat similar solution. More information on the future of message exchange patterns can be found at www.w3.org/2002/ws/cg/2/07/meps.html.

    Java End Sidebar
    <operation >
     <output message="tns:stockUpdate"/>
    </operation>
    


Describing Groups of Operations: The portType Element

The portType element combines all the abstract information that together describes what the service offers—its abstract interface. So the portType element is a container for operations, which in turn is a container for messages. Although a WSDL document can contain one or more portType elements, it is good practice to have just one occurrence of the portType element within a WSDL document—that is, to describe only one Web service interface within a WSDL document (this practice is similar to the practice of keeping only one Java interface definition in a physical class file). The name attribute of the portType element must be unique within the WSDL document. As Screenshot shows, each port type contains a set of operations, and each operation describes the messages exchanged between the service and the service consumer.

Java Click To expand
Screenshot: The portType element
Java Start Sidebar

The WSDL portType is analogous to a Java interface declaration.

Java End Sidebar

Implementation Details: The binding Element

All the WSDL document elements described thus far have described the abstract nature of the service. Before a consumer can interact with a service, some details of the service's implementation have to be known. Operations of the service with a list of messages exchanged during the operation only partly describe the service. The wire protocol and invocation style the service implementation understands affect how data is marshaled and unmarshaled over the wire. As Screenshot shows, binding associates the concrete implementation information about messages, data types, and operations to the corresponding abstract notions.

Java Click To expand
Screenshot: The binding element

Each portType can have one or more binding elements that associate the portType to specific protocols for invoking the service. SOAP over HTTP may be the most popular protocol today for implementing RPC-style Web services, but it's not the only one. One could implement a Web service that understands SOAP over SMTP or HTTP/GET, and so on. The important thing is that the list of protocols the Web service community may support is not finite. So, how do we bind an abstract service definition to a concrete protocol in WSDL and accommodate all possible protocol bindings without having to change the WSDL standards every time a new binding is supported? WSDL provides a mechanism to incorporate protocol-specific information using the extensibility elements, which provide the concrete grammar for each message within every operation. The WSDL specification currently defines binding extension endpoints that understand SOAP over HTTP, HTTP GET/POST, and MIME.

In the example below (a fragment of Listing 5.2), the bill payment service port type is bound to SOAP over HTTP.

<binding type="tns:BillPay">
 <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>
 <operation >
 <input>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://com.flute.webservice/billPay"/>
 </input>
 <output>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://com.flute.webservice/billPay"/>
 </output>
 <soap:operation soapAction=""/>
</operation>
 <operation >
 <input>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded"
namespace="http://com.flute.webservice/billPay"/>
 </input>
 <output>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://com.flute.webservice/billPay"/>
 </output>
 <fault >
 <soap:fault 
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://com.flute.webservice/billPay"/>
 </fault>
 <soap:operation soapAction=""/>
</operation>
</binding>


The name attribute provides a unique name to the binding. The type attribute associates the binding to a portType. WSDL defines three bindings that describe how a service that exposes itself physically using one of these bindings can be invoked:

  • SOAP bindings describe how a service can be consumed using SOAP messages.

  • MIME bindings describe how a service can be consumed by sending MIME messages.
  • HTTP bindings describe how a service can be consumed by sending HTTP GET requests and POST messages.

SOAP Binding WSDL 1.1 has built-in facilities that allow SOAP-specific details to be specified in the WSDL document itself. These SOAP-specific elements are collectively referred to as SOAP binding extensions, because they are specified using the WSDL extension mechanism, covered later in the chapter.

  • soap:binding. The soap:binding element signifies that the binding is for SOAP protocol format. This element should be present if using the SOAP binding.

<binding type="tns:BillPay">
 <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>
<!--other elements>
</binding>



The style attribute indicates the style of operations to follow: rpc style or document style. An RPC style invocation signifies that operations take input parameters and return an output result. A document-centric style signifies document-oriented messages, where entire XML documents are passed as input and output to the service. The transport attribute indicates the underlying transport protocol to be used for SOAP—that is, the value http://schemas.xmlsoap.org/soap/http indicates HTTP transport; http://schemas.xmlsoap.org/soap/smtp indicates SMTP transport.

  • soap:operation. The soap:operation extension's soapAction attribute specifies the value to be put in the SoapAction header.

    <soap:operation soapAction=""/>
    


A SOAP message header may contain a SOAPAction field, as a way to inform the SOAP processing node of the intent of the SOAP message. The SOAPAction element is required for SOAP over HTTP and must be specified, even if the value of SOAPAction is an empty string (""), as in this example. This is not uncommon; for most SOAP requests sent over HTTP, HTTP Request-URI already provides the intent of the SOAP message to the SOAP processing node, so the SOAPAction attribute is left empty. The SOAPAction attribute, explained in detail in , must not be specified for any other binding.

  • soap:body. The soap:body element specifies how message parts are to be assembled in the SOAP body element. soap:body elements are used to map the abstract input and output messages to their SOAP-protocol-specific implementations. Error messages are handled differently—see the soap:fault extension description.

Within the soap:body element, the use attribute determines whether the data is encoded (use="encoded") using an encodingStyle ("http://schemas.xmlsoap.org/soap/encoding") or whether the XML can be validated using a schema (use="literal"). In Listing 5.2, the operations of the BillPayservice are described as RPCs, and the message parts of the operations are encoded using the SOAP encoding rules. That is, the BillPayservice methods take in typed parameters, and the service understands how to serialize and deserialize these message parts using the SOAP encoding rules. Typically, operations that are document style will not have the data encoded; rather, it is sent as a literal, so the XML can be validated against a schema. So the most common forms are document style with no encoding (doc/literal) and RPC style with encoding (rpc/encoded). It is uncommon, but not impossible, to have an operation with the other allowed combinations of style and use (rpc/literal and doc/encoded). The style and use attributes are explained in detail in a later section.

  • soap:header. Any headers to be transmitted as part of the SOAP header are defined in the soap:header element. The optional headerfault element, shown in Screenshot, is used to transmit error information corresponding to the message defined in soap:header. The SOAP specification requires that errors pertaining to headers be returned in the header section, not in the body of the SOAP message. Java Click To expand
    Screenshot: The SOAP header

  • soap:fault. What happens when a Java service method throws an exception? How is that to be handled and transmitted over the wire to the service consumer? The soap:fault extension element is used to describe the fault message. As the example shows, the soap:fault extension has the same attributes as a soap:body.
<fault >
 <soap:fault 
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" use="encoded"
 namespace="http://com.flute.webservice/billPay"/>
</fault>


MIME Binding WSDL also provides a way to bind abstract messages to MIME types. Specifically, WSDL supports the following MIME types:

  • Multipart/related

  • app/x-www-form-urlencoded
  • Text/xml

In the BillPayservice example, the only data types used for input and output were simple or complex types. If the services wanted to return some binary data (e.g., a GIF/JPEG image), the message would contain a binary part. The following WSDL fragments represent a new BillPay service method, getFluteLogo, that returns a string and a GIF image logo.

<message name= "getFluteLogo">
 <part type="xsd:string"/>
 <part type="xsd:binary"/>
</message>


In the binding element, the following operation would also have to be added:

<operation >
 <soap:operation soapAction=""/>
 <output>
 <mime:multipartRelated>
 <mime:part>
 <soap:body use="encoded" namespace="http://www.flute.com/billPay"
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
 </mime:part>
 <mime:part>
 <mime:content part="logo" type="image/gif/"/>
 </mime:part>
 </mime:multipartRelated>
 </output>
</operation>


The multipartRelated element, shown in Screenshot, consists of individual part elements. Therefore, in the code example above, the MIME binding appears as multiple parts: one is the image, and the other is the returned String in the soap body.

Java Click To expand
Screenshot: The multipartRelated element

HTTP Bindings Thus far we have discussed how WSDL can be used to describe SOAP-based Web services. WSDL also defines a binding for invoking operations using only HTTP GET or POST requests. This is a rarely used aspect but is useful when exposing only parts of a Web service that typically accept limited parameters and return read-only results. For example, a free StockQuote service provided by Flute Bank on its Web site may require only the ticker symbol as the input. Simply sending an HTTP GET or POST request to the service should return the appropriate response. That is, pointing to http://www.flutebank.com/services/stockquote/getQuote.jsp?ticker=FLUT will return a response like this:

<?xml version="1.0" encoding="UTF-8"?>
<stockquote xmlns:tns="http://www.flutebank.com/xml">
<symbol>FLUT</symbol>
<high>36.98</high>
<low>22.00</low>
<currentask>35.00</currentask>
<tick>up</tick>
<marginable>yes</marginable>
<lasttrade>
 <number>2888</number>
 <price>34.99</price>
</lasttrade>
</stockquote>


These HTTP bindings in WSDL are more for backward compatibility with the early generation of Web services, which used this approach. We recommend using SOAP bindings rather than plain HTTP bindings.

Bindings and Style/Use

A Web service can expose its operations as RPC style operations or as document style operations. For a SOAP message, the style of invocation affects the body of the message. In RPC style (Screenshota), the client invokes a method on the server by sending all the information necessary for that method execution in the body of the SOAP message. The client receives a response message in the same fashion. In document style (Screenshotb), the client and server communicate using XML documents. The client sends an XML document, such as a purchase order. The server processes the document and returns another XML document, say an invoice, as a result. The document represents a complete unit of information and may be completely self-describing.

Java Click To expand
Screenshot: (a) RPC and (b) document styles

Encoding refers to how data is serialized and sent over the wire. The parties can agree on a predefined encoding scheme or use an XML schema directly in the data to define the data types. The message with the former notation is said to be an encoded message; the latter is said to be a literal message. For encoded messages, the rules to encode and interpret a SOAP body are in a URL specified by the encodingStyle attribute. A literal message indicates that the rules to encode and interpret the SOAP body are specified by a XML schema. Thus there are four combinations of style and encoding:

  • RPC/encoded

  • RPC/literal
  • Document/encoded
  • Document/literal

The style attribute of the soap:binding element and use attribute of the soap:body element in the WSDL file can be used to describe these four combinations of invocation mentioned previously, as shown in Listings 5.3 through 5.6.

Listing 5.3: WSDL for RPC/encoded style
<binding type="tns:BillPay">
 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
 style="rpc"/>
 <operation >
 <soap:operation soapAction=""/>
 <input>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://com.flute.webservice/billPay"/>
 </input>
 <output>
 <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
 use="encoded" namespace="http://com.flute.webservice/billPay"/>
 </output>
</operation>
</binding>




Java End example
Listing 5.4: WSDL for RPC/literal style
 <binding type="tns:BillPay">
 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
 style="rpc"/>
 <operation name="getMonthlyReport">
 <soap:operation soapAction=""style="rpc"/>
 <input>
 <soap:body use="encoded" namespace="http://com.flute.webservice/billPay"
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding"/>
 </input>
 <output>
 <soap:body use="literal"
 namespace="http://com.flute.webservice/types/output.xsd"/>
 </output>
 </operation>
<operation name="getWeeklyReport ">
 <soap:operation soapAction="" style="rpc"/>
 <input>
 <soap:body use="encoded" namespace="http://com.flute.webservice/billPay"
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding" />
 </input>
 <output>
 <soap:body use="literal"
 namespace="http://com.flute.webservice/types/output.xsd"/>
 </output>
 </operation>
</binding>



Java End example
Listing 5.5: WSDL for document/encoded style
<binding type="tns:BillPay">
 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
 style="document"/>
 <operation >
 <soap:operation soapAction=""/>
 <input>
 <soap:body encodingStyle="http://com.flute.webservice/encoding/"
 use="encoded" namespace="http://com.flute.webservice/billPay"/>
 </input>
 <output>
 <soap:body encodingStyle="http://com.flute.webservice/encoding/"
 use="encoded" namespace="http://com.flute.webservice/billPay"/>
 </output>
</operation>
</binding>



Java End example
Listing 5.6: WSDL for document/literal style
package com.flutebank.billpayservice;
<binding type="tns:BillPay">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http"
 style="document"/>
<operation >
 <soap:operation soapAction=""/>
 <input>
 <soap:body use="literal"
 namespace="http://com.flute.webservice/types/input.xsd"/>
 </input>
 <output>
 <soap:body use="literal"
 namespace="http://com.flute.webservice/types/output.xsd"/>
 </output>
 </operation>
</binding>



Java End example

examines invocation and encoding styles in greater detail and discusses the implications for selecting one combination over another, best practices, and implementation techniques.

Describing the Physical Service: The port and service Elements

As mentioned earlier, a porttype—that is, an abstraction of the service—can be bound to multiple protocol-specific implementations, with each implementation running on a specific network address. The port specifies the location that processes a particular encoding scheme—in short, the port element identifies the network address of the endpoint. There is one port element for each binding element.

<service >
 <port binding="tns:BillPayBinding">
 <soap:address location="www.localhost:8080"/>
 </port>
</service


In a WSDL document, a service element acts as a container for one or more ports, as Screenshot shows. The notion of a service as a collection of ports is useful, because the same service could be implemented using different protocols. In such a case, there would be one portType element, multiple binding elements, one port for each binding, and one service element to combine all the ports in the WSDL document. Although a WSDL document can contain more than one service element, it is not recommended or terribly useful.

Java Click To expand
Screenshot: The service element

Referencing Other Descriptions: The import Element

Within a WSDL document, a service's interface is described using the types, messages, portTypes, and binding elements, and the service's implementation details are described using the port, address, and service elements. It is possible, and desirable, to author a WSDL description by separating the service's interface description from its implementation description. The service implementation WSDL document should refer to (or import) the reusable service interface description document. The WSDL import element provides a means to refer to one WSDL document from another. The import element is used to associate a namespace with a document location.

<import namespace="uri" location="uri"/>


Separation of the interface definition from deployment information is particularly important when registering Web services in a registry, such as Universal Description, Discovery and Integration (UDDI), which allows software to be categorized by function. Typically, industry consortiums will devise common service definitions for that industry and make them publicly available, by registering these service definitions as UDDI tModels. Service creators access the UDDI registry for service interface definitions, then create and deploy Web services conforming to the interface definition. The WSDL document describing the implemented Web service will import the service interface definition to which it was built. Detailed information on UDDI appears in .

Java Start Sidebar

The WSDL import element is analogous to the import statement in Java.

Java End Sidebar

Extending WSDL

We briefly touched upon the concept of extensibility while discussing types and bindings. Let us look at this in further detail. The WSDL specification allows the WSDL defined elements to be extended. In fact, the SOAP-specific elements discussed earlier, such as soap:header,soap:body, and soap:fault are examples of this mechanism, where the WSDL binding element has been extended to include SOAP protocol-specific information. Such elements that extend the WSDL specified elements are called WSDL extensibility elements. The specification defines specific elements of the WSDL document under which such elements may be added; these are listed in Table 5.1. For example, the port element can be extended by protocol-specific elements, which allows additional location information to be specified. soap:address does exactly this.

Table 5.1: WSDL Elements that May Be Extended

Location

Examples of extensibility

definitions

Introduce additional information or definitions that apply to the entire WSDL structure

types

Specify the data types in a format other than schemas

service

Introduce additional information or definitions for the service

port

Specify protocol-specific details about the address for the port

binding

Introduce information that applies to all operations in the portType being bound, such as quality of service details

operation

Provide protocol-specific information that applies to both the input and output messages, e.g., soap:operation

input

Introduce information about the input message, e.g., the soap:body with its use attribute

output

Introduce information about the output message, e.g., the soap:body with its use attribute

fault

Introduce additional information for the fault message, e.g., soap:fault

Architects can add their own extensibility elements to a WSDL document describing value-added features, but they should be aware that not all service consumers will know how to interpret these nonstandard extensions, which have to be explained to them manually. Moreover, general-purpose WSDL tools and utilities will not know how to make use of these nonstandard extensions—which are, however, useful in providing extra information to service consumers. As an example, the WSDL document fragment below shows that the BillPay service operation listScheduledPayments may include additional information about the hours of the day between which a financial service will be available or the minimum time a particular operation takes to execute, and so on.

<definitions 
 xmlns:ext="" ... >
<binding type="tns:BillPay">
 <operation >
 <ext:responseTime min="100" average="150" maximum="250"/>
 <ext:operationAvailability starttime="800" endtime="2300"/>
 <soap:operation soapAction=""/>
 <input>
 <soap:body use="encoded"
 namespace="http://www.flutebank.com/xml"/
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 </input>
 <output>
 <soap:body use="encoded"
 namespace="http://www.flutebank.com/xml"/
 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 </output>
 </operation>
</definitions>



WSDL Usage Patterns

So far, we have examined the structure and content of a WSDL document. This section explains how such a document can be used in a Web services app. apps that use WSDL fall into two broad categories: service consumers and service providers.

Service Consumers

As in RMI or EJB environments, before clients can invoke a method exposed by an RPC-style Web service, they must know the following:

  • The location of the service

  • The protocol the service understands (so the request can be marshaled correctly)
  • The service's methods and method signatures

A WSDL document describing the service contains this information. The physical WSDL file can be obtained either from a reference in the UDDI registry where the service is registered, from a well-known URL, or by any other mechanism previously agreed upon by the service producer and consumer (such as email).

Service Producers

A service producer is responsible for implementing and exposing the service on the network. A service producer may

  • Take an existing implementation and expose it as a Web service by implementing a layer of SOAP interfaces. Examples of this scenario are exposing existing Java apps with a layer of SOAP interfaces.

  • Import a WSDL describing the interface to which the service must conform, generate the outline code from it, fill in the appropriate pieces of implementation, and deploy the service.
  • On both the producer and consumer sides, vendor tools associated with the vendor's runtime environment play a significant role. Screenshot indicates this relationship. Java Click To expand
    Screenshot: Vendor tool tasks

The vendor's tools are responsible for importing the WSDL and creating the specific language bindings (e.g., Java, C#, C++, VB, etc.) that are then deployed in the language-specific container (e.g., Java servlet, ASP, Perl, etc.) Compliance with standards and specifications such as JAX-RPC should be an important factor in deciding on vendors, because tools play a critical part in generating the bindings, as Screenshot shows. For example, the tools parse the WSDL and generate the appropriate Java data types in the types element as well as in the method signatures, parameters, and returns from the operations and bindings. If the data type mapping is not compliant with that specified in JAX-RPC, the app will not be portable or vendor-neutral.

Java Click To expand
Screenshot: Tasks performed by Hvendor tools for WSDL

Some of the things to check for compliance to standards when a vendor tool imports WSDL are

  • Mapping parameter to data types; for example, XML Schema namespace to Java package name, XML Schema data type to Java types

  • Mapping portTypes to interfaces and classes
  • Generating bindings based on the style and use elements (RPC/encoded, RPC/literal, document/encoded, document/literal)
  • Importing endpoint information for use by generated client proxies

The same is true for service providers. The tools must be capable of crossing the language implementation-to-specification bridge transparently, using the information outlined above to generate a WSDL-compliant document. In short, architects should choose the vendor runtime and implementations with care.

Java Start Sidebar

JWSDL JSR-110, Java API for WSDL, proposes that a standard API be defined for programmatic creation, manipulation, and parsing of WSDL documents. JWSDL will be useful for creating tools to manipulate (generate/edit) WSDL and possibly for future tools that generate stubs for invoking services on the fly.

Java End Sidebar

Early or Late Binding

In , we introduced the concept of early and late binding. This describes the time at which consumers discover type information and other details of the service they want to interact with. Once the WSDL document that contains this information is available, consumers can use a few architectural patterns based around the concept of binding when invoking the service.

Early Binding

For service consumers who intend to use a Web service, one alternative is to import the WSDL into the development environment, where vendor-provided tools generate artifacts that the consumer can use (we just looked at the critical role vendor tools play in this step). Consumers can then directly use these artifacts (stubs, data type mappings, generated code, etc.) for all subsequent interactions with the service, eliminating the need for inspecting WSDL each time the service is invoked. Such an approach is termed early binding. This approach is best suited for services whose location and functional interface are not volatile. An example of early binding is the consumption of RPC style services described by WSDL. WSDL can generate the necessary client-side stub proxy classes. The exact mechanism for this generation is specific to the vendor's runtime implementation. For example, the XML RPC compiler (xrpcc) tool of the JAX-RPC reference implementation reads an XML configuration file to generate the client-side code, as Screenshot shows. The configuration file is an XML file that provides xrpcc with information regarding the package name to be used for the generated classes and the location of the WSDL document. xrpcc is covered in detail in .

Java Click To expand
Screenshot: xrpcc can read an XML configuration file to generate client-side code.
Java Start Sidebar

Service consumers can be designed using three approaches: client-side stubs, dynamic invocation interface (DII), or dynamic proxies. The coding model, architecture, and usage scenarios for these modes can be found in . You are encouraged to follow up the reading of the subsequent Late Binding section below with the Service Consumers section in .

Java End Sidebar
xrpcc -client -d <destination directory-s <source directory> <configuration file>
<?xml version="1.0" encoding="UTF-8"?>
 <configuration xmlns="http://java.oracle.com/xml/ns/jax-rpc/ri/config">
 <wsdl location=
 packageName="com.flute.webservice">
 </wsdl>
</configuration>


Early binding has essentially the following three variations, based on when the abstract and concrete definitions described in the WSDL are used by the consumer. Keep in mind that the portType defines the functional signature of the service.

  • Static compile-time binding. Both the abstract and concrete descriptions in WSDL are known, and the concrete descriptions are used directly. For example, port, portType, and the location are known and set at compile time. Typically, the consumer is developed using stubs. The client code is generated using vendor tools based on the WSDL portType, and the location is set in the stub by the same tools or by the service consumer For example, Flute Bank always buys office supplies from OfficeMin, because of a long-term contract, and the portType is standardized as part of the service level agreement with OfficeMin.

  • Static deploy-time binding. This is similar to static compile-time binding, with the difference that though the functional signature (portType) of the service is known at development time, the location is not set until the service is deployed. This means that at deployment, the consumer or an administrator for the consumer looks up the WSDL, selects a port, and gets a location from it. Typically, the consumer is developed using stubs generated at compile time. For example, Flute Bank develops a client to order office supplies from OfficeMin's Web service that it distributes to all its branches. The branches can then set the location to point to the closest store location during deployment.
  • Static runtime binding. The functional signature (portType) is known and set at development time; however, the consumer doesn't know the service's location. This means that during deployment or at runtime, the consumer looks up the WSDL, selects a port, and obtains its location. As in the previous scenarios, such a consumer would also typically be developed using stubs. For example, Flute Bank doesn't have a contract with any supplier for office supplies. Every time an order for office supplies totaling more than a certain amount is placed, the service polls vendors from the prescreened vendor list for the lowest rate. This clearly requires standardization on the portTypes between organizations that want to form ad hoc relationships. In some vertical industries, such as finance, hotels, and travel, these types of interfaces already exist, and it seems reasonable that in the future some of them will migrate to the Web service paradigm.

Web services being developed today that use WSDL typically use static compile-time bindings and static deploy-time bindings. Organizations form business relationships with their partners and formalize the WSDL as a part of the service level agreement. The description of the service is not expected to change, and if it needs to, appropriate out-of-band measures can be taken as part of change control.

Late Binding

Another way to invoke a Web service is to download and examine the WSDL on the fly at runtime and dynamically invoke the service. This is a more robust way of invoking services that change unpredictably or that have variable characteristics. Although this method may, in general, have slower performance than an equivalent early binding implementation, changes to the consumed Web service will have less impact on the consumer, due to the loose coupling between the two. Dynamic invocation interface (DII) and dynamic proxies actively use WSDL for this purpose, where the client needs minimal information about the service at compile time, and some of it is actually extracted at runtime by pointing to a URL where the WSDL is located.

Java Start Sidebar

Service consumers can be programmed using three approaches: client-side stubs, DII, or Dynamic proxies. All three modes and examples of their usage can be found in .

Java End Sidebar

Similar to its early binding peers, late binding can also be described on the basis of the functional signature (portType) and network address (location) in two variations:

  • Dynamic binding. Neither the service's functional signature (portType) nor its network address (location) is known or set at compile time. Consumers are responsible for locating a service they want to use, introspecting the portType, and subsequently invoking the service. Either dynamic invocation interface or dynamic proxies generated on the fly can be used in this case. For example, Flute Bank does not have a contract with any supplier for office supplies. Every time an order for office supplies totaling more than a certain amount is placed, the service polls vendors from the prescreened vendor list for the lowest rate. However, unlike the previous example, it needs to inspect the WSDL and then look for certain method signatures or variations of the same and their locations.

  • Dynamic binding with known location. This is a variation of the above, where location is known but the functional signature of the service (portType) is not. In such cases consumers query the location for supported portTypes or supply the location with a portType, to check if it is supported. For example, Flute Bank always sends its quarterly report to the Securities and Exchange Commission but does not know the format, which changes every quarter.

The kinds of late binding offered by dynamic invocation interface and dynamic proxies are supported by specifications like JAX-RPC and its vendor implementations. However, the dynamic binding architectural patterns outlined are not yet practical. The mechanics of such a dynamic invocation are relatively easy to address. Considerably harder to solve are issues regarding how consumers are billed for service usage and are able to automatically select a particular service over other functionally equivalent services.

Both patterns for consuming Web services have their respective strengths and are suitable for use under different circumstances. Generally, however, because of the current maturity of vendor products and the issues yet unresolved with respect to late binding, we believe architects should first investigate early binding as the pattern of interaction.

WSDL and Server-Side Java Classes

In general, a service producer who decides to implement a Web service corresponding to a WSDL service description in Java will use the runtime vendor tools to generate the corresponding bindings for that runtime. For example, the Java WSDP reference implementation, the xrpcc, can be used to generate all necessary server-side Java ties and classes for the reference implementation. It is important to keep in mind that these classes are not portable and are specific to the vendor's runtime.

xrpcc -classpath %classpath% -client -keep -d <destination directory-s
 <source directory> <configuration file>


The command for using xrppc for generating server-side ties and support classes differs from the previous usage in just one flag: -server instead of -client.

Generating WSDL from Java

Java programmers who have little interest in understanding the details of a WSDL document will be encouraged to know that there are tools to generate a WSDL document, given a Java remote interface. Current tools will, however, generate only WSDL that describes an RPC style invocation for SOAP-based Web services. The xrppc utility can be used to generate a WSDL document with SOAP-HTTP binding, given a Java remote interface, using the following command:

xrpcc -classpath %classpath% -server -keep -d <destination directory>
 <configuration xml file>


where the configuration file looks like the following XML document:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://java.oracle.com/xml/ns/jax-rpc/ri/config">
 <service 
 targetNamespace="http://com.flute.webservice/billPay"
 typeNamespace="http://com.flute.webservice/types"
 packageName="com.flute.webservice">
 <interface name="com.flute.webservice.BillPay"
 servantName="com.flute.webservice.BillPayImpl"/>
 </service>
</configuration>


The configuration file provides the namespace to be used in the resulting WSDL document, the name of the remote interface for which the WSDL file will be generated, and the name of the generated implementation class.


JaVa
Comments