Basic WSDL Example: HelloService.wsdl (cont.) - Page 3

message

Two message elements are defined. The first represents a request message, SayHelloRequest, and the second represents a response message, SayHelloResponse:

<message name="SayHelloRequest">
   <part name="firstName" type="xsd:string"/>
</message>
<message name="SayHelloResponse">
   <part name="greeting" type="xsd:string"/>
</message>

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):

<portType name="Hello_PortType">
   <operation name="sayHello">
      <input message="tns:SayHelloRequest"/>
      <output message="tns:SayHelloResponse"/>
   </operation>
</portType>

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.

Request-response

The service receives a message and sends a response. The operation therefore has one input element, followed by one output element (illustrated previously in Example 6-1). To encapsulate errors, an optional fault element can also be specified.

Solicit-response

The service sends a message and receives a response. The operation therefore has one output element, followed by one input element. To encapsulate errors, an optional fault element can also be specified.

Notification

The service sends a message. The operation therefore has a single output element.

These patterns of operation are also shown in Figure 6-3. The request-response pattern is most commonly used in SOAP services.

Figure 6-3. Operation patterns supported by WSDL 1.1

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:

<binding name="Hello_Binding" type="tns:Hello_PortType">

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:

soap:binding

This element indicates that the binding will be made available via SOAP. The style attribute indicates the overall style of the SOAP message format. A style value of rpc 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 of document 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 the rpc 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 value http://schemas.xmlsoap.org/soap/http indicates the SOAP HTTP transport, whereas http://schemas.xmlsoap.org/soap/smtp indicates the SOAP SMTP transport.

soap:operation

This element indicates the binding of a specific operation to a specific SOAP implementation. The soapAction attribute specifies that the SOAPAction HTTP header be used for identifying the service. (See Chapter 3 for details on the SOAPAction header.)

soap:body

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.

TIP:  The choice between the rpc style and the document 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 the rpc style is more in line with the SOAP examples from previous chapters, I have chosen to stick with the rpc style for all the examples within this chapter. Note, however, that most Microsoft .NET WSDL files use the document 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.

Basic WSDL Example: HelloService.wsdl - Page 2
Web Services Essentials
WSDL Invocation Tools, Part I - Page 4