- WSDL Basics
- WSDL Elements
- The Extensible WSDL Framework
- Importing WSDL Elements
- WSDL-Related Namespaces
- Extensions for Binding to SOAP
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
The Extensible WSDL Framework
Like SOAP and the other XML integration framework technologies, WSDL is an extensible framework. The bindings for SOAP, for example, extend WSDL, as do the bindings for HTTP GET and POST and MIME. In this way, WSDL separates the abstract definition of end points and messages from their concrete network deployments, or data format bindings, which permits reuse of the abstract definitions.
Note
WSDL is completely extensible to multiple formats and protocols
The three major elements of WSDL that can be defined separately are
-
Types
-
Operations
-
Binding
As noted previously, WSDL has seven parts, but they are contained within these three main elements, which can be developed as separate documents and then combined or reused to form complete WSDL files. The major elements are divided according to their level of abstraction in the stack representing a Web service.
The data type declarations are the most abstract element of a service, defining the data items—the XML documents—to be exchanged by a Web service. The data types can be defined once, like include files, and referenced within any of the operations. The operations on the data types represent the next level of abstraction, defining the way data is passed back and forth. The binding, the final level of abstraction, defines the transport used to pass the message.
Defining Message Data Types
At its most abstract level, a Web service consists of an XML document sent to and/or received from a remote software program. The first job in defining a Web service, therefore, is to identify the data requirements for the software program implementing the Web service functionality.
Note
Web service processing includes an XML mapping phase
A Web service needs to define its inputs and outputs and how they are mapped into and out of services. WSDL types take care of this. Types are XML documents, or document parts. WSDL allows the types to be defined in separate elements so that the types are reusable with multiple Web services.
Note
WSDL uses basic XML schema types by default
Data types address the problem of how to identify the data types and formats you intend to use with your Web services. Type information is shared between sender and receiver. The recipients of messages therefore need access to the information you used to encode your data and must understand how to decode the data.
Types are typically defined using XML schemas; like other parts of WSDL, however, the types portion is completely extensible, and other type systems can be used instead. For example, if you know that the target of a particular instance of a Web service is a CORBA object, you can use the CORBA type system instead of the XML schema type system. You could also simply introduce another standard self-describing encoding, such as Abstract Syntax Notation One (ASN.1). This may be useful for local area network applications of WSDL, for which optimizing or bypassing the mapping stage—into and out of XML schema types—would be helpful.
Another option is to hard code the type definitions within the Web Services Description language file. Types can be defined within the WSDL element or inside other files referenced within that element.
Because XML is inherently flexible, transformable, and extensible, the XML data defined for a Web service does not have to exactly match the data required by the program behind it; in fact, it probably should not. As long as the data can be manipulated in the mapping stage, it can be defined using a level of abstraction or format different from the original application. Because it's not executable by itself, a Web service includes a mapping stage, during which the XML data is mapped to the software program, as well as an execution stage, during which the program itself is run.)
A mapping stage is required to transform the XML data and the XML schema representation of a service into the software program that is executing it. The requirements for the message data and operations part of WSDL therefore are that they express enough of the data and semantics of the software program to allow a bridge to be constructed to it over the network using the capability of the transformation and mapping phase at each end.
Note
WSDL is a loose representation of an object or a database system
As shown in Figure 3-4, one or more individual data types are mapped into messages. The same message can be mapped into multiple operations. Types are typically any of the XML schema-supported data types, such as integer, string, Boolean, or date, and can include complex types, such as structures and arrays, including those defined for SOAP. The data types are therefore either simple schema types or schemas that define complex types. As in the other areas of WSDL, types are not restricted to XML schemas, because no one expects a single type of system to be capable of describing all possible message formats for the Web.
)
Figure 3-4. Data types are mapped to messages.
The following example illustrates the type and message definitions for a Skateboots.com purchase order service that returns the total value of one or more purchase orders. The XML schema data types used in the WSDL file are mapped to messages using the schema element names.
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="PurchaseOrderService"
targetNamespace="PurchaseOrderService"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="PurchaseOrderService"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsd1="PurchaseOrderService-xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<types>
<schema targetNamespace="PurchaseOrderService-xsd"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
<complexType name="PurchaseOrder">
<all>
<element name="CompanyName" type="xsd:string"/>
<element name="Items" type="xsd1:ArrayOfItem"/>
<element name="Address" type="xsd1:Address"/>
</all>
</complexType>
<complexType name="Item">
<all>
<element name="Price" type="xsd:float"/>
<element name="PartID" type="xsd:string"/>
<element name="Description" type="xsd:string"/>
<element name="Quantity" type="xsd:int"/>
</all>
</complexType>
<complexType name="ArrayOfItem">
<complexContent>
<restriction base="SOAP-ENC:Array">
<attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="xsd1:Item[]"/>
</restriction>
</complexContent>
</complexType>
<complexType name="Address">
<all>
<element name="State" type="xsd:string"/>
<element name="PostalCode" type="xsd:string"/>
<element name="City" type="xsd:string"/>
<element name="Line2" type="xsd:string"/>
<element name="Country" type="xsd:string"/>
<element name="Line1" type="xsd:string"/>
</all>
</complexType>
<complexType name="ArrayOfPurchaseOrder">
<complexContent>
<restriction base="SOAP-ENC:Array">
<attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="xsd1:PurchaseOrder[]"/>
</restriction>
</complexContent>
</complexType>
</schema>
</types>
<message name="postPurchaseOrderRequest">
<part name="order" type="xsd1:PurchaseOrder"/>
</message>
<message name="postPurchaseOrderResult">
<part name="return" type="xsd:float"/>
</message>
<message name="postPurchaseOrdersRequest">
<part name="orders" type="xsd1:ArrayOfPurchaseOrder"/>
</message>
<message name="postPurchaseOrdersResult">
<part name="return" type="xsd:float"/>
</message>
When using SOAP, a message is carried as the payload of the SOAP request or response. That is, the WSDL message definition does not include any information that is mapped to the SOAP envelope, headers, or fault code. In other words, you can say that WSDL targets a layer of abstraction entirely above that of SOAP.
Note
Information in WSDL does not map to SOAP headers
Defining Operations on Messages
The next level of abstraction, operations, addresses the requirement of a Web service to identify the type of operations being performed on behalf of a given message or set of messages. The operation is defined so that the Web service knows how to interpret the data and what, if any, data is to be returned on the reply.
Note
Once you have the data, define the operations
Operations are defined in correspondence to common message patterns, such as one-way and request/response. WSDL does not include specific definitions for other operations, but more complicated interactions can be constructed by combining these basic types. For example, something like the cooperating partner profile specification from ebXML could be used to define a sequence of one-way and request/response operations in support of a complex message pattern interaction.
As shown in Figure 3-5, operations can group messages for input and output to match the pattern of the request/response message.
)
Figure 3-5. Operations group message types to match the message pattern.
WSDL has four types of operations:
-
One-way: Similar to fire-and-forget, but more simply it means that the message is sent without a requirement to return a reply.
-
Request/response: Similar to an RPC-style interaction; the sender sends a message, and the receiver sends a corresponding reply. (Some protocols may not guarantee that a response is returned for every request.)
-
Solicit response (no definition yet): A simple request for a response with no input data. It's a request to get a message and does not involve sending a message, in the sense of a WSDL message consisting of one or more defined types. It's the reverse of the one-way operation.
-
Notification (no definition yet): This type of operation defines multiple receivers for a message, similar to a broadcast, and often involves a subscription mechanism, as in publish/subscribe, to set it up.
Note
Operations match request/response and other message patterns
Operations allow sequences of messages to be correlated into specific patterns without having to introduce a more complex flow specification. Operations are not the same as methods on objects, although certainly the input and output parameters defined for operations will normally map to method input and output arguments when the services are implemented using an object-oriented technology such as .NET, EJB, or CORBA.
Note
Operations correlate messages into specific patterns but not flows
Operations may include optional fault messages, although their content is outside the scope of the specification. The following example illustrates a request/response operation definition for the Skateboots.com service.
<portType name="PurchaseOrderPortType">
<operation name="postPurchaseOrder">
<input message="tns:postPurchaseOrderRequest"
name="postPurchaseOrder"/>
<output message="tns:postPurchaseOrderResult"
name="postPurchaseOrderResult"/>
</operation>
<operation name="postPurchaseOrders">
<input message="tns:postPurchaseOrdersRequest"
name="postPurchaseOrders"/>
<output message="tns:postPurchaseOrdersResult"
name="postPurchaseOrdersResult"/>
</operation>
</portType>
Input and output messages are defined for the request and response operations, using the message definitions created in the previously shown elements of the WSDL file.
Request/response operations do not require use of the RPC attribute in the SOAP binding (see Extensions for Binding to SOAP later in this chapter), although it's probably a good idea. It's good programming practice to preserve within the SOAP binding, for example, the signature of an object to which the Web service is mapped. The parameterOrder attribute lists message part names, and the order of the messages must match those of the RPC signature.
Note
Although not required, it's good to map operations to SOAP correspondingly
There is no syntax to define a return value, but if a part name appears in both the input and the output messages it's an in/out parameter; if it's on input only, it's an input parameter. This convention makes it easier to map WSDL operations onto RPC bindings—for example, the RPC binding for SOAP.
SOAP also has a document binding, and Web services interactions will likely include both. For example, a purchase order is shared between the buyer and the seller of goods. Both the buyer and the seller may first exchange a copy of the same document. They may exchange information dynamically over the Web to fill in the fields on the form, such as available inventory, ship date, quantity discount, and so on. This will allow a more dynamic, real-time negotiation between buyer and seller to set the terms and conditions of a sale, based on a shared document.
Operations put input/output messages in correspondence, although it varies by transport what type of guaranteed correlation is available; SOAP does not require correspondence, although HTTP GET and POST do. Today, separate services have to be defined if you want to advertise both a document-oriented and a procedure-oriented service, but it seems likely that these may be combined in a future version of WSDL.
Mapping Messages to Protocols
After the data types and the operation types are defined, they have to be mapped onto a specific transport protocol, and an end point, or address to which the data is sent and at which it's possible to find and invoke the particular operation, must be identified. This operation is required because the same data types and operations can be mapped onto multiple transports, such as SOAP, BEEP, IIOP, JMS, and others, and a Web service can live at potentially multiple end-point addresses. This part of the WSDL solves the problem of how a transport expects to understand the data being passed—for example, it may be serialized according to the SOAP specification—and where to find the service—at an Internet IP address, intranet, LAN, and so on.
Note
Now map messages to transports and end points
First, operations are grouped into port types, as shown in the previous example. Each port type is then mapped to one or more specific ports representing the various transports over which a service might be available; for example, a port type might be mapped to specific ports for HTTP GET and POST, SOAP, or MIME. Transport binding extensions are then mapped to each specific port in order to define the information necessary to offer a given service over a specific transport.
The transport binding extensions underneath the data types, operation types, and port types identify the receiver of the data and the operation to be performed. So for any given Web service, it's both necessary and possible to define the data, the operation on the data, and the place to which the data is sent and how.
Port Types
A port type is a logical grouping of operations, similar to type libraries in .NET, classes in Java, or an object's IDL (Interface Definition Language) in CORBA. If an operation is analogous to a method on an object and if messages are analogous to input and output arguments, a port type is analogous to an object definition that potentially contains multiple methods. But these analogies are not exact, because WSDL is extensible and is intended to provide a level of abstraction greater than what's provided by any of these object-oriented systems.
Note
Port types identify to whom the message is sent and how
In other words, WSDL is an independent data abstraction that can be used for much more than simply mapping into and out of .NET, EJB, or CORBA objects. But when working with these object-oriented systems, it helps to understand the parts of WSDL that correspond to parts of these systems.
The request/response style uses different message definitions for the input and output messages; as with document passing, the one-way style uses a single type as a complete document. Both types of interactions can be defined within a given port type.
As shown in Figure 3-6, a port type represents a collection of operations, in the same way that an object represents a collection of methods. For Web services, the mapping between a port type and an object type or a class is quite natural. But because Web services are defined at a high level of abstraction, mappings can also be made to documents and procedure-oriented technologies.
)
Figure 3-6. A port type represents a collection of operations.
Note
A port type is a collection of operations
Ports
A port is used to expose a set of operations, or port types, over a given transport. The port types can be grouped for one or more bindings, which is how the services are connected over the network. A port identifies one or more transport bindings for a given port type. To continue the comparison with object-oriented systems, a port is analogous to the transport. For example, a common transport for CORBA is IIOP; for EJB, it's RMI (remote method invocation) or RMI/IIOP; and for COM, it's DCOM, which is based on Distributed Computing Environment (DCE) RPC.
Note
Ports are transport specific
These systems do not provide a truly equivalent definition mechanism with which to define a particular transport, although EJB and CORBA systems certainly can be and have been mapped to a variety of transports. But the mapping is not considered part of the object definition.
With WSDL, however, it's necessary to advertise within the service definition which transport bindings are available for a given collection of operations. The sending or discovering system at a remote network end point will typically access a published WSDL file via HTTP as a typical document GET operation but may then wish to negotiate with the receiver or publisher of the Web service to interact on a different transport that provides additional functionality.
Figure 3-7 illustrates the concept of a port in WSDL, which puts together the operations, the binding, and a URL defining a specific IP address at which the Web services implementation can be found. The following example illustrates the SOAP binding for the operations in the Skateboots.com purchase order.
)
Figure 3-7. In WSDL, a port combines operations, binding, and a network address.
<binding name="PurchaseOrderBinding" type="tns:PurchaseOrderPortType">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http/"/>
<operation name="postPurchaseOrder">
<soap:operation
soapAction="PurchaseOrderService/postPurchaseOrder"
style="rpc"/>
<input name="postPurchaseOrder">
<soap:body
encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/"namespace="PurchaseOrderService"
use="encoded"/>
</input>
<output name="postPurchaseOrderResult">
<soap:body
encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/"namespace="PurchaseOrderService"
use="encoded"/>
</output>
</operation>
<operation name="postPurchaseOrders">
<soap:operation
soapAction="PurchaseOrderService/postPurchaseOrders"
style="rpc"/>
<input name="postPurchaseOrders">
<soap:body
encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/"namespace="PurchaseOrderService"
use="encoded"/>
</input>
<output name="postPurchaseOrdersResult">
<soap:body
encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/"namespace="PurchaseOrderService"
use="encoded"/>
</output>
</operation>
</binding>
Note the use of the SOAP Action, the SOAP encoding, and the RPC interaction style.
The transport binding can be done per operation. Ports by definition include the transport binding or bindings, which in the case of the SOAP binding includes a declaration of whether the interaction is request/response (RPC) or document passing (DOCUMENT). This is the SOAP binding style. Several other extensions to WSDL are defined specifically for use with SOAP, such as a way to define the SOAP Action7 and input and output messages.
Note
Transport bindings are done for operations
<soap:operation
soapAction=http://www.iona.com/GetLastTradePrice"/>
<input>
<soap:body use="literal"
namespace="http://www.iona.com/stockquotes.xsd"/>
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
</input>
<output>
<soap:body use="literal"
namespace="http://www.iona.com/stockquotes.xsd/>
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
</output>
</operation>
The SOAP encoding optionally can be used with WSDL, as shown in the example, and both options are explicitly supported. (See Extensions for Binding to SOAP later in this chapter for further information on the SOAP binding extensions.)
Bindings can be defined for other transports, such as SMTP, and extensions included specifically for them. The separation of the transport binding extensions from the definition of the port type allows one Web service to be available over multiple transports without having to redefine the entire WSDL file. Again, because it is designed to be completely extensible, WSDL allows other binding extensions to be used, such as for example for IIOP, .NET, JMS, MQ Series, and so on.
Note
Bindings can be defined for multiple transports
Services
As shown in Figure 3-8, the service part of WSDL encloses one or more port types, similar to the way in which an object class can contain multiple objects. The following example illustrates the service binding for the Skateboots.com purchase order totaling service:
<service name="PurchaseOrderService">
<port binding="tns:PurchaseOrderBinding"
name="PurchaseOrderPort">
<soap:address
location="http://localhost:9000/
xmlbus/container/PurchaseOrder/
PurchaseOrderService/
PurchaseOrderPort"/>
</port>
</service>
)
Figure 3-8. A service is a collection of port types.
Note
Services group operations in the same way that objects or classes group methods
Note the definition of the service address (in this case a locally hosted address).
The service allows a given end point in a remote application to choose to expose multiple categories of operations for various kinds of interactions. For example, one category might contain a set of document-oriented interactions to asynchronously exchange and complete a purchase order for a future shipment. Another category might contain a set of RPC-oriented interactions to synchronously interact on an order for immediate shipment. In the former case, access to real-time inventory data is not required; but in the latter case, it is.
Putting It All Together
Once all the parts and elements of WSDL are defined, the WSDL file is complete and can be placed in a directory accessible to the Web via a URL. (WSDL files are typically generated, so don't worry too much about their individual complexity; the main point is to understand how WSDL solves particular problems.)
Figure 3-9 illustrates the two types of operations, or usage patterns, for Web services defined in the WSDL specification: request/response and one-way messages. For the request/response operation, an input message is sent to the receiving SOAP handler as a part of an HTTP request, and an output message is returned via HTTP response. For the one-way operation, an input message is sent to a MIME handler on a different port identified by the same service.
)
Figure 3-9. WSDL defines messages, operations, ports, and transports for SOAP and MIME.