WSDL is a specification defining how to describe web services in a common XML grammar. WSDL describes four critical pieces of data:
- Interface information describing all publicly available functions
- Data type information for all message requests and message responses
- Binding information about the transport protocol to be used
- Address information for locating the specified service
In a nutshell, WSDL represents a contract between the service requestor and the service provider, in much the same way that a Java interface represents a contract between client code and the actual Java object. The crucial difference is that WSDL is platform- and language-independent and is used primarily (although not exclusively) to describe SOAP services.
Using WSDL, a client can locate a web service and invoke any of its publicly available functions. With WSDL-aware tools, you can also automate this process, enabling applications to easily integrate new services with little or no manual code. WSDL therefore represents a cornerstone of the web service architecture, because it provides a common language for describing services and a platform for automatically integrating those services.
[WSDL是一种规范,它定义了服务端和客户端进行通信(或调用)的细则。因此,只要知道服务端提供的WSDL,可以使用多种工具生成客户端调用的代码框架,从而调用服务端所提供的服务]
This chapter covers all aspects of WSDL, including the following topics:
- An overview of the WSDL specification, complete with detailed explanations of the major WSDL elements
- A basic WSDL examples to get you started
The WSDL Specification
WSDL is an XML grammar for describing web services. The specification itself is divided into six major elements:
-
The
definitions
element must be the root element of all WSDL documents. It defines the name of the web service, declares multiple namespaces used throughout the remainder of the document, and contains all the service elements described here. [定义:定义了web service的名称及声明了所需要的命名空间]
-
The
types
element describes all the data types used between the client and server. WSDL is not tied exclusively to a specific typing system, but it uses the W3C XML Schema specification as its default choice. If the service uses only XML Schema built-in simple types, such as strings and integers, thetypes
element is not required. A full discussion of thetypes
element and XML Schema is deferred to the end of the chapter. [类型:定义了通信(或调用)过程中所需的数据结构]
-
The
message
element describes a one-way message, whether it is a single message request or a single message response. It defines the name of the message and contains zero or more messagepart
elements, which can refer to message parameters or message return values. [消息:定义了单向 通信所需要的信息,包换消息名称及参数,参数即上面的'types'(类型)。如果一次调用有返回结果,刚需要定义两条message]
-
The
portType
element combines multiplemessage
elements to form a complete one-way or round-trip operation. For example, aportType
can combine one request and one response message into a single request/response operation, most commonly used in SOAP services. Note that aportType
can (and frequently does) define multiple operations. [端口类型:它包含多个操作,每个操作包含一次完整的调用所需的信息,包含一条(无返回)或两条(有返回)message(消息)。]
-
The
binding
element describes the concrete specifics of how the service will be implemented on the wire. WSDL includes built-in extensions for defining SOAP services, and SOAP-specific information therefore goes here. [绑定:描述了服务的实现方式,它可以是SOAP,或HTTP GET,或HTTP POST等]
-
The
service
element defines the address for invoking the specified service. Most commonly, this includes a URL for invoking the SOAP service. [服务:定义了调用服务的地址]
definitions
types
message
portType
binding
service
To help you keep the meaning of each element clear, Fig ure 1-1 offers a concise representation of the WSDL specification. As you continue reading the remainder of the chapter, you may wish to refer back to this diagram.
|
In addition to the six major elements, the WSDL specification also defines the following utility elements:
-
The
documentation
element is used to provide human-readable documentation and can be included inside any other WSDL element. -
The
import
element is used to import other WSDL documents or XML Schemas. This enables more modular WSDL documents. For example, two WSDL documents can import the same basic elements and yet include their ownservice
elements to make the same service available at two physical addresses. Note, however, that not all WSDL tools support the import functionality as of yet.
documentation
import
TIP: WSDL is not an official recommendation of the W3C and, as such, has no official status within the W3C. WSDL Version 1.1 was submitted to the W3C in March 2001. Original submitters included IBM, Microsoft, Ariba, and a half dozen other companies. Most probably, WSDL will be placed under the consideration of the new W3C Web Services Activity's Web Services Description Working Group, which will decide if the specification advances to an official recommendation status. The WSDL Version 1.1 specification is available online at http://www.w3.org/TR/wsdl .
Basic WSDL Example: HelloService.wsdl
To make the previously described WSDL concepts as concrete as possible, let's examine our first sample WSDL file.
Example 1-1 provides a sample HelloService.wsdl document.
The service provides a single publicly available function, called sayHello. The function expects a single string parameter, and returns a single string greeting. For example, if you pass the parameter world
, the service returns the greeting, "Hello, world!"
Example 1-1: HelloService.wsdl
The WSDL elements are discussed in the next section of this chapter. As you examine each element in detail, you may want to refer to Figure 1-2 , which summarizes the most important aspects of Example 1-1 .
|
definitions
The definitions
element specifies that this document is the HelloService . It also specifies numerous namespaces that will be used throughout the remainder of the document:
The use of namespaces is important for differentiating elements, and it enables the document to reference multiple external specifications, including the WSDL specification, the SOAP specification, and the XML Schema specification.
The definitions
element also specifies a targetNamespace
attribute. The targetNamespace
is a convention of XML Schema that enables the WSDL document to refer to itself. In Example 1-1 , we specified a targetNamespace
of http://www.ecerami.com/wsdl/HelloService.wsdl . Note, however, that the namespace specification does not require that the document actually exist at this location; the important point is that you specify a value that is unique, different from all other namespaces that are defined.
Finally, the definitions
element specifies a default namespace: xmlns=http://schemas.xmlsoap.org/wsdl/ . All elements without a namespace prefix, such as message
or portType
, are therefore assumed to be part of the default WSDL namespace.
message
Two message
elements are defined. The first represents a request message, SayHelloRequest, and the second represents a response message, SayHelloResponse :
Each of these messages contains a single part
element. For the request, the part specifies the function parameters; in this case, we specify a single firstName
parameter. For the response, the part specifies the function return values; in this case, we specify a single greeting
return value.
The part
element's type
attribute specifies an XML Schema data type. The value of the type
attribute must be specified as an XML Schema QName--this means that the value of the attribute must be namespace-qualified. For example, the firstName
type
attribute is set to xsd:string
; the xsd
prefix references the namespace for XML Schema, defined earlier within the definitions
element.
If the function expects multiple arguments or returns multiple values, you can specify multiple part
elements.
portType
The portType
element defines a single operation, called sayHello . The operation itself consists of a single input
message (SayHelloRequest ) and a single output
message (SayHelloResponse ):
Much like the type
attribute defined earlier, the message
attribute must be specified as an XML Schema QName. This means that the value of the attribute must be namespace-qualified. For example, the input
element specifies a message
attribute of tns:SayHelloRequest
; the tns
prefix references the targetNamespace
defined earlier within the definitions
element.
WSDL supports four basic patterns of operation:
-
One-way
-
The service receives a message. The operation therefore has a single
input
element. -
The service receives a message and sends a response. The operation therefore has one
input
element, followed by oneoutput
element (illustrated previously in Example 1-1 ). To encapsulate errors, an optionalfault
element can also be specified. -
The service sends a message and receives a response. The operation therefore has one
output
element, followed by oneinput
element. To encapsulate errors, an optionalfault
element can also be specified. -
The service sends a message. The operation therefore has a single
output
element.
Request-response
Solicit-response
Notification
These patterns of operation are also shown in Figure 1-3 . The request-response pattern is most commonly used in SOAP services.
|
binding
The binding
element provides specific details on how a portType
operation will actually be transmitted over the wire. Bindings can be made available via multiple transports, including HTTP GET, HTTP POST, or SOAP. In fact, you can specify multiple bindings for a single portType
.
The binding
element itself specifies name
and type
attributes:
The type
attribute references the portType
defined earlier in the document. In our case, the binding
element therefore references tns:Hello_PortType
, defined earlier in the document. The binding element is therefore saying, "I will provide specific details on how the sayHello operation will be transported over the Internet."
SOAP binding
WSDL 1.1 includes built-in extensions for SOAP 1.1. This enables you to specify SOAP-specific details, including SOAP headers, SOAP encoding styles, and the SOAPAction
HTTP header. The SOAP extension elements include:
-
This element indicates that the binding will be made available via SOAP. The
style
attribute indicates the overall style of the SOAP message format. Astyle
value ofrpc
specifies an RPC format. This means that the body of the SOAP request will include a wrapper XML element indicating the function name. Function parameters are then embedded inside the wrapper element. Likewise, the body of the SOAP response will include a wrapper XML element that mirrors the function request. Return values are then embedded inside the response wrapper element. -
A
style
value ofdocument
specifies an XML document call format. This means that the request and response messages will consist simply of XML documents. The document style is flatter than therpc
style and does not require the use of wrapper elements. (See the upcoming note for additional details.) -
The
transport
attribute indicates the transport of the SOAP messages. The valuehttp://schemas.xmlsoap.org/soap/http
indicates the SOAP HTTP transport, whereashttp://schemas.xmlsoap.org/soap/smtp
indicates the SOAP SMTP transport. -
This element indicates the binding of a specific operation to a specific SOAP implementation. The
soapAction
attribute specifies that theSOAPAction
HTTP header be used for identifying the service. (See Chapter 3 for details on theSOAPAction
header.) -
This element enables you to specify the details of the input and output messages. In the case of HelloWorld, the
body
element specifies the SOAP encoding style and the namespace URN associated with the specified service.
soap:binding
soap:operation
soap:body
TIP: The choice between the
rpc
style and thedocument
style is controversial. The topic has been hotly debated on the WSDL newsgroup (http://groups.yahoo.com/group/wsdl ). The debate is further complicated because not all WSDL-aware tools even differentiate between the two styles. Because therpc
style is more in line with the SOAP examples from previous chapters, I have chosen to stick with therpc
style for all the examples within this chapter. Note, however, that most Microsoft .NET WSDL files use thedocument
style.
service
The service
element specifies the location of the service. Because this is a SOAP service, we use the soap:address
element, and specify the local host address for the Apache SOAP rpcrouter
servlet: http://localhost:8080/soap/servlet/rpcrouter
.
Note that the service element includes a documentation
element to provide human-readable documentation.
Note : The full version of this paragraph can be seen at: http://oreilly.com/catalog/webservess/chapter/ch06.html , part of the content is modified to provide integrety as a standalone reference.