9.2 Message Patterns in WSDL

The W3C WSDL Specification defines four message patterns to support four types of operations:

• Request-response

• One-way

• Notification

• Solicit-response

Given the definition of the input and output messages for the operation in the WSDL file, HydraExpress generates the appropriate code for all four message patterns.

This section discusses each message pattern, with an introduction to the WeatherSummary.wsdl that is used for illustration. It also includes a brief discussion on synchronous and asynchronous behavior as it relates to message patterns.

The Weather Summary service represents a centralized provider of weather condition data for some number of zip code locations in some area.

• A client, or individual, requests weather data based on a zip code, and the service provides it, through the request-response operation.

• Participating zip code locations send updated weather data to the service when local conditions change, using the one-way operation.

• Clients can subscribe to receive notification of changed conditions through the notification operation.

• Finally, the service periodically polls the client to confirm that the client wishes to continue receiving notifications, through the solicit-response operation.

To complete this scenario, there should be another request-response operation that allows a zip code location to either subscribe or unsubscribe from the notification service, receiving a confirmation message in reply. This operation has been left out for the sake of simplicity.

The request-response operation includes one input element, which is the client's request to the server, followed by one output element, which is the server's response back to the client.

Figure 1: The Request-response message pattern

In WeatherSummary.wsdl, the request-response operation is defined by the getSummary operation:

...
    <operation name="getSummary">
      <input message="tns:getSummary"/>
      <output message="tns:getSummaryResponse"/>
    </operation>
...

The operation getSummary contains an input message getSummary, which is the client request, and an output message getSummaryResponse, which is the server response. The contents of these messages are then defined in the WSDL's message element:

<message name="getSummary">
  <part name="zipcode" type="xsd:string"/>
</message>

<message name="getSummaryResponse">
    <part name="weatherData" type="wsx:WeatherSummary"/>
</message>

The message getSummary contains one part, a zipcode of type xsd:string. The client request thus provides a zipcode to the server.

The message getSummaryResponse contains one part, a weatherData object of type wsx:WeatherSummary. Based on the zipcode, the server return an XML WeatherSummary element for the location specified by the zipcode.

A WeatherSummary element is a complex type defined by an embedded XML Schema in the types element of the WSDL file. See Section 6.3.2, "The Generated Data Types."

The implementation of this pattern occurs in the client-side WeatherSummaryClient.cpp, a sample implementation that uses the generated class in WeatherSummaryProxy.cpp, and in the server-side WeatherSummaryImp.cpp, the server implementation that receives the request and sends a response.

For more information on the request-response pattern, see the examples discussed in Part I, "Getting Started," as well as those in Part IV, "Extending your Applications."

The one-way operation includes one input element, which is the client's request to the server. No response is expected.

Figure 2: The One-way message pattern

In WeatherSummary.wsdl, the one-way pattern is defined by the operation updateWeather:

    <!-- One-way -->
    <operation name="updateWeather">
      <input message="tns:updateWeather"/>
    </operation>

The operation updateWeather consists of one input message containing several parts.

 <message name="updateWeather">
    <part name="host" type="xsd:string"/>
    <part name="port" type="xsd:string"/>
    <part name="transportName" type="xsd:string"/>
    <part name="weatherData" type="wsx:WeatherSummary"/>
 </message>

The message contains a WeatherSummary element that provides updated weather conditions for the zip code.

The implementation of this pattern occurs in the client-side WeatherSummaryClient.cpp, a sample implementation that uses the generated class in WeatherSummaryProxy.cpp, and in the server-side WeatherSummaryImp.cpp, the server implementation that receives the request.

The notification operation includes one output element, which is the server's message to the client.

Figure 3: The Notification message pattern

In WeatherSummary.wsdl, the notification pattern is defined by the operation weatherNotification:

    <!-- Notification -->
    <operation name="weatherNotification">
      <output message="tns:getSummaryResponse"/>
    </operation>

The operation consists of one output message from the server to one or more clients.

<message name="getSummaryResponse">
    <part name="weatherData" type="wsx:WeatherSummary"/>
</message>

The message contains a WeatherSummary element with updated weather conditions for the zip code specified in the WeatherSummary element.

HydraExpress uses special notification architecture to support this pattern. This architecture is described in Chapter 13, "Asynchronous Messaging."

This pattern is implemented on the server side by WeatherSummaryImp.cpp which makes the call to the weatherNotification() operation method in the server-side notification proxy WeatherSummaryNotificationProxy.cpp, and on the client side in WeatherSummaryNotificationImp.cpp, which sets up a listener on the client to receive the notification.

For an additional examples on the notification pattern, see Chapter 10,

The solicit-response operation includes one output element, which is the server's request to the client, followed by one input element, which is the client's response back to the server.

Figure 4: The Solicit-response message pattern

In WeatherSummary.wsdl, the solicit-response pattern is defined in the operation weatherUpdateRenew.

!-- Solicit-response -->
    <operation name="weatherUpdateRenew">
      <output message="tns:RenewRequest"/>
      <input message="tns:RenewResponse"/>
    </operation>

This operation consists of one output message RenewRequest and one input message RenewResponse defined below.

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

This is the request message from the server to the client containing a simple string asking if the client wishes to renew the subscription to weather updates.

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

This is the response message from the client back to the server, also containing a string, to either affirm or deny the renewal of weather updates.

This pattern requires the server to initiate a message and the client to receive one, so it uses the notification architecture to support this pattern. This architecture is described in Section 9.3, "Architecture of the Notification Classes."

This operation is implemented on the server side in WeatherSummaryImp.cpp, which makes the call to the notification proxy in WeatherSummaryNotificationProxy.cpp to send the renewal request to the client. On the client side, the class in WeatherSummaryNotificationImp.cpp sets up a listener, receives the message, and sends a response.

The request-response and the solicit-response patterns are generally synchronous, as their usage usually assumes that the requestor will receive an immediate response.

The one-way and the notification patterns are inherently asynchronous in that the requestor expects no response.

While one of the strengths of WSDL is that it allows any mix of message patterns and transports in a single service, it is important to be aware that the behavior of a service is tied to the type of transport being used. For example, an asynchronous service will not behave asynchronously if it is sent using a synchronous transport, such as HTTP. This is because HTTP requires a response as a receipt.

For this reason, it may be wise to build one-way and notification messages asynchronously even though no response is required, in order to avoid having the client block for a transport receipt. In addition, using the asynchronous methods for one-way and notification builds more responsiveness and adaptability into your program without much more complication.

For a general discussion on building services asynchronously, see Chapter 13, "Asynchronous Messaging."

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.