W3C W3C Member Submission

Web Services Polling (WS-Polling)

W3C Member Submission 26 October 2005

This version:
Latest version:
Kyle Brown, IBM
Doug Davis, IBM (Editor)
Christopher Ferris, IBM
Anthony Nadalin, IBM


This specification defines a mechanism to deliver messages destined to an unreachable endpoint by allowing the destination to 'poll' the source for messages targeted for it.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

By publishing this document, W3C acknowledges that IBM has made a formal submission to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.

This specification is an initial public draft release and is provided for review and evaluation only. The authors hope to solicit your contributions and suggestions in the near future. The authors make no warrantees or representations regarding the specifications in any manner whatsoever.

Table of Contents

1. Introduction

When sending SOAP messages in an environment where the two endpoints (source and destination) are not able to freely open connection in both directions, delivery of asynchronous messages becomes problematic. Perhaps the most common scenario being where the initiator (client) of a Web service call is behind a firewall so any messages initiated from the service back to the client can not be delivered. Another common case is where the client does not have a SOAP listener (i.e. server) running to receive asynchronous messages.

In both of these cases, in order for the service to deliver a message to the "unreachable" client endpoint it becomes necessary for the client to initiate the connection, thus allowing the message to be sent back on the response flow of the connection.

This specification defines a mechanism through which an endpoint may initiate a connection to another endpoint for the purposes of allowing messages from the destination/service endpoint to be delivered back to the source/client.

1.1 Requirements

This specification intends to meet the following requirements:

1.2 Composable Architecture

By using the XML, SOAP [SOAP 1.1, SOAP 1.2], and WSDL [WSDL 1.1] extensibility models, the Web service specifications (WS-*) are designed to be composed with each other to provide a rich set of tools to provide security in the Web services environment. This specification specifically relies on other Web service specifications to provide secure, reliable, and/or transacted message delivery and to express Web service and client policy.

2. Notations and Terminology

This section specifies the notations, namespaces, and terminology used in this specification.

2.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].

This specification uses the following syntax to define normative outlines for messages:

2.2 XML Namespaces

The XML Namespace URI that MUST be used by implementations of this specification is:


Table 3 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.

Table 3: Prefixes and XML Namespaces used in this specification.

Prefix XML Namespace Specification(s)
s (Either SOAP 1.1 or 1.2) (Either SOAP 1.1 or 1.2)
s11 http://schemas.xmlsoap.org/soap/envelope/ SOAP 1.1 [SOAP 1.1]
s12 http://www.w3.org/2003/05/soap-envelope SOAP 1.2 [SOAP 1.2]
wsa http://schemas.xmlsoap.org/ws/2004/08/addressing WS-Addressing [WS-Addressing]
wsdl http://schemas.xmlsoap.org/wsdl/ WSDL [WSDL 1.1]
wsp http://www.w3.org/2005/08/ws-polling This specification
xs http://www.w3.org/2001/XMLSchema XML Schema [Part 1, 2]

2.3 Compliance

An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein. A SOAP Node MUST NOT use the XML Namespace identifier for this specification (listed in Section 2.2) within SOAP Envelopes unless it is compliant with this specification.

3. Requesting Messages

3.1 GetMessage Request

To request a message from an endpoint, a requestor MAY send a GetMessage request message to the endpoint. The normative outline for a GetMessage request is:

<s:Envelope ...>
 <s:Header ...>
 <s:Body ...>
  <wsp:GetMessage ...>
   <wsa:MessageID>xs:anyURI</wsa:MessageID> ?
   <wsp:To>endpoint-reference</wsp:To> ?
   <wsp:extensions> ... </wsp:extensions> ?

The following describes normative constraints on the outline listed above:

If a SOAP Action URI is used in the binding for SOAP, the value indicated herein MUST be used for that URI.
The Endpoint Reference (EPR) of the source endpoint. This SHOULD contain reference properties to help uniquely identify the source endpoint. While not required, this EPR's Address element will typically be the anonymous URI.
The address of the destination endpoint.
If present, this element contains the WS-Addressing MessageID of a request message previously received by the destination endpoint. By including this element the source is requesting the response message for the original request message with this MessageID and a destination MUST limit its search to just those messages.
If present, this element contains a WS-Addressing EPR. If present this MUST be used as part of the search criteria and only messages originally targeted to this EPR should be returned. In other words, for simple request/response message exchanges, this will contain the wsa:ReplyTo (or wsa:FaultTo) EPR of the original request message. This SHOULD contain reference properties to help uniquely identify the source endpoint.
This is an extensibility mechanism to allow other search criteria to be passed. For example, an XPath query could be used to search for messages that match a certain pattern. At some future time this specification will define such an extension.

Upon receipt of this message, the destination will locate any outgoing message that matches the search criteria. The search criteria MUST include examination of the child elements inside the wsp:GetMessage element. When those optional elements are not present the search algorithm MUST at least include partial examination of the wsa:ReplyTo header and MAY also include the wsa:To header (see Searching For Messages, below).

3.2 Response Message

If a message is found that matches the search criteria then it is sent to the endpoint as specified by the WS-Addressing specification (i.e. to the wsa:ReplyTo EPR). A wsa:RelatesTo header MUST be included in the response message that includes the wsa:MessageID from the GetMessage request message, even if one is already present. The normative outline for the response is:

<s:Envelope ...>
  <s:Header ...>
    <wsa:RelatesTo>xs:anyURI</wsa:RelatesTo> ?
    <wsa:RelatesTo>messageID from GetMessage</wsa:RelatesTo>
  <s:Body ...>

The following describes normative constraints on the outline listed above:

The existence of, and values specified in, the WS-Addressing headers will be determined by the schema and semantics of the original processing used to generate the message being retrieved (including the wsa:To header).
/s:Envelope/s:Header/wsa:RelatesTo (#2)
This MUST contain the wsa:MessageID from the GetMessage request.

If no message is found that matches the search criteria then the NoMessageAvailable message is sent to the endpoint as specified in the wsa:ReplyTo EPR. The normative outline for a NoMessageAvailable response is:

<s:Envelope ...>
 <s:Header ...>
  <wsa:RelatesTo>messageID from GetMessage</wsa:RelatesTo>
 <s:Body ...>
  <wsp:NoMessageAvailable reason="..."? />

The following describes normative constraints on the outline listed above:

If a SOAP Action URI is used in the binding for SOAP, the value indicated herein MUST be used for that URI.
This MUST contain the wsa:MessageID from the GetMessage request.
The address of the source endpoint as specified in the ReplyTo EPR of the GetMessage request.
When no message is found this message Body MUST be used.
This optional attribute is used to indicate the reason no message was returned. The value specified MUST be a QName indicating the reason no message is returned. This specification defines the following "reasons":
This reason code is used when it can be determined that the response message being searched for has already been sent. Note: this will typically be used when a MessageID was used in the GetMessage Body.
This reason code is used when it can be determined that the response message is still in the process of being generated. In other words, the Web service has not completed yet. Note: this will typically be used when a MessageID was used in the GetMessage Body. Whether an endpoint chooses to send this message or wait for the service to complete is an implementation choice.
This reason code is used when the MessageID used in the GetMessage Body is unknown and as such no response message has been found.
This reason code is used when, given the search criteria used by the destination, no message can be found. If a MessageID was used in the GetMessage Body then one of the previous 3 reasons SHOULD be used (if possible). Note: if no "reason" attribute is specified then this, wsp:NoMessageFound, is the default.

3.3 Searching for Messages

When a destination is searching for a message to return to the requestor all of the child elements under the wsp:GetMessage element MUST be used (i.e. a logical AND of the search criteria). It is strongly RECOMMENDED that reference properties be included in EPRs to help uniquely identify messages targeted for a particular endpoint.

A destination MAY choose to include other search criteria. For example, a service endpoint MAY choose to also compare the wsa:To header of the GetMessage request and only locate response messages that were generated from a particular service. Note: see the security section for taking into account the security context when searching.

If more than one message is available the destination is free to use whatever algorithm it deems appropriate for choosing which message to return. For example, a FIFO algorithm may be the best choice but it is not required.

4. “Hold It” URL

4.1 Client requesting service to “hold” the response

WS-Polling defines a special URI that is similar to the anonymous URI defined by WS-Addressing, meaning the client is unable to offer an endpoint for responses:


Use of this URI in the wsa:ReplyTo EPR of a request message will indicate to the service that the client will use WS-Polling to retrieve the response if the response does not come back through some other means (such as the HTTP response flow). When the service receives a request containing this URI in the wsa:RepyTo EPR it can immediately return an HTTP response code of 202 back to the client - with the assumption that the client will poll for the response at some later point in time. However, the service is not required to return immediately if it chooses not to.

One use of this URI would be to allow the client to indicate to the server that it believes the request will be a long running request and therefore the server is free to return immediately with the assurance that the response will be retrieved later.

4.2 Client/Service Handshaking

Unlike the use of a Mailbox (see section 5) where the service does not need to be aware of WS-Polling at all, in order to use this special URL the client must know the service supports WS-Polling. It is assumed that through examination of the WSDL, WS-Policy or some other out of band means, the client can determine whether or not the service supports it (e.g. GetMessage is in the service's PortType). The server's acceptance of this URI in the wsa:ReplyTo indicates that it not only supports WS-Polling but an understanding that the client is responsible for polling for the response if the service chooses to not send the response message back on the original connection.

5. Using a Third-Party Mailbox

5.1 Mailbox

Use of the “Hold It” URL places a burden on the service endpoint. It must be able to "hold-on" to the outgoing messages until the receiver of those messages "polls" for them. For some endpoints this may be problematic. A solution for this would follow the same pattern used in email communications - a SOAP Mailbox. When the "anonymous", or "unreachable", side of the communications sends a message it can use a reachable endpoint (the SOAP Mailbox) as its wsa:ReplyTo EPR - thus allowing the service endpoint to deliver any subsequent messages without the need to persist them in any way.

The original endpoint can now "poll" the Mailbox for messages destined for it. This is akin to a simple mail client polling a POP3 server for email. This shifts the burden of managing potentially large number of messages to an endpoint that is dedicated for that purpose.

Setup and logistics of how to create and manage a SOAP Mailbox is out of scope of this document, however, it will probably follow the same pattern that ISPs currently provide. A user (in this case the user of a SOAP client) will register with a SOAP Mailbox provider, which in turn will provide the SOAP client with the appropriate service-URL/EPR to use in its WS-Addressing EPRs.

5.2 wsp:To Reference Property

Since the wsa:To address of the messages in the Mailbox will contain the Mailbox's endpoint address, the GetMessage's Body wsp:To value will not match it. To solve this problem, WS-Polling defines a new element that is meant to be used as a reference property in EPRs:

<wsp:To> URI of client </wsp:To>

This element should be used as a reference property in the client's wsa:ReplyTo EPR so that upon receipt of a message the Mailbox will use the value in this element/header as the true wsa:To value. In other words, the Mailbox is responsible for using the wsp:To value, when present, instead of the wsa:To value when searching for messages to return. The initiator of the GetMessage request is then responsible for either using the wsp:To value instead of the wsa:To value when dispatching the message, or for replacing the wsa:To with the wsp:To prior to dispatching - this decision is out of scope of this document.

Note: if the client chooses to use the WS-Addressing anonymous URI in the wsp:To element, then some reference properties SHOULD be specified to help uniquely identify the destination of the messages.

6. WS-Polling Headers

WS-Polling defines some SOAP headers that can be included in normal message flows that will enable a more optimized polling scheme.

6.1 StatusRequested Header

The StatusRequested header can be used to indicate that the sender of the message wishes to query for the existence of any messages on the target endpoint that are waiting to be retrieved via a WS-Polling GetMessage request. The normative outline for a StatusRequested header is:

<wsp:StatusRequested ...>
   <wsa:MessageID>xs:anyURI</wsa:MessageID> ?
   <wsp:To>endpoint-reference</wsp:To> ?
   <wsp:extensions> ... </wsp:extensions> ?

The following describes the content model of the StatusRequested header

This header contains the search criteria to be used when determining whether or not messages are available.
The child elements of the StatusRequested header are the same as the child elements of the GetMessage element. They specify the search criteria to be used when the query for pending messages is made. See the GetMessage operation for more details.

As with the GetMessage element, when the optional children elements are not present the search algorithm MUST at least include partial examination of the wsa:ReplyTo header and MAY also include the wsa:To header.

6.2 Status Header

Upon receipt of a StatusRequest header, the receiving endpoint is expected to include a Status header in the response message - if one is generated. The Status header can be used to indicate whether or not there are messages ready to be delivered that satisfy the search criteria in the StatusRequested header. The normative outline for a StatusRequested header is:

<wsp:Status messagesPending="true|false" ...>
   <wsa:MessageID>xs:anyURI</wsa:MessageID> ?
   <wsp:To>endpoint-reference</wsp:To> ?
   <wsp:extensions> ... </wsp:extensions> ?

The following describes the content model of the Status header

This header indicates whether or not there are messages awaiting delivery.
This attribute indicates the results of the query. A value of "true" indicates that there is at least one message available for delivery that matches the search criteria.
The child elements of this header will include the search criteria used to determine if messages are available.

The Status header can be included on any message that is targeted to the correct WS-Polling client - it is not limited to being sent only when a StatusRequested header was included on a request message. For example, an endpoint may choose to include a Status header on the result of a GetMessage request as a means for the WS-Polling client to know if it should immediately poll for more messages.

7. Driving Use-Cases

This section gives a brief overview of some use-cases that were the driving forces behind this specification. They are not intended to limit the use of this specification but rather give insight into some of its possible uses.

7.1 Asynchronous Request/Response with AnonymousURI

Since HTTP is the one of the most common transports currently used for SOAP messaging the inherit limitations of using it behind firewalls will hinder its use for asynchronous message processing. For example, an HTTP connection may timeout before a response message can be returned. If the request message's wsa:ReplyTo EPR used the anonymous URI then the response message would have no way of being returned to the source. By using WS-Polling the source can reestablish a connection with the destination and wait for (i.e. request) the response message.

7.2 WS-ReliableMessaging

When using WS-RM using the anonymous URI in the wsrm:AcksTo EPR can be problematic. By using WS-Polling the "anonymous" side (the client) can establish a new connection allowing the destination/service to send back any response or ACKs. Likewise, using the anonymous URI in the wsa:ReplyTo EPR is problematic, since the RM Destination can not initiate retries to an anonymous EPR. WS-Polling can help this by allowing the use of the "hold-it" URI, or of a Mailbox, and the client polling for responses.

7.3 Unsolicited Messages

In situations where an endpoint needs to deliver unsolicited messages to an endpoint behind a firewall, such as a notification consumer behind a firewall subscribing to a notification broker, the consumer can use WS-Polling to periodically request notifications. This is akin to turning the HTTP flow around - the HTTP response flows would carry the SOAP request messages and the HTTP request flows would carry the responses. Note: many notification systems already have support for notification consumers to poll for messages - in those cases it is expected that WS-Polling might not be used - or those solutions could migrate to WS-Polling once WS-Polling becomes part of the core SOAP stack.

7.4 Non-24/7 Service

A service that can not be available all day, every day, can use a Mailbox as the EPR for its clients. When the system does come up it can then retrieve its incoming messages and process them. From the client's point of view the service is up all of the time.

7.5 Message Flow Rate Control

Some Web Service endpoints, due to resource constraints, may need to have control over the rate at which messages are delivered - by using WS-Polling it can choose when and how often to have incoming messages delivered.

8. Security Considerations

It is strongly RECOMMENDED that the communication between Web services be secured using the mechanisms described in WS-Security [WS-Security, Addendum]. In order to properly secure messages, the body and all relevant headers need to be included in the signature. Specifically, any standard messaging headers, such as those from WS-Addressing [WS-Addressing], need to be signed with the body in order to "bind" the two together.

Different security mechanisms may be desired depending on the frequency of messages. For example, for infrequent messages, public key technologies may be adequate for integrity and confidentiality. However, for high-frequency events, it may be more performant to establish a security context for the events using the mechanisms described in WS-Trust [WS-Trust] and WS-SecureConversation [WS-SecureConversation]. It should be noted that if a shared secret is used it is RECOMMENDED that derived keys be used to strengthen the secret as described in WS-SecureConversation.

Requests for messages which are not available to anonymous parties are strongly RECOMMENDED to require usage of WS-Security so that the requestor can be authenticated and authorized to access the indicated messages. Similarly, integrity and confidentiality SHOULD be used whenever messages have restricted access.

Recipients of messages are RECOMMENDED to validate the signature to authenticate and verify the integrity of the data. Specifically, recipients SHOULD verify that the sender has the right to "speak" for the message.

The following list summarizes common classes of attacks that apply to this protocol and identifies the mechanism to prevent/mitigate the attacks:

The two common uses of WS-Polling require slightly different security solutions. In the case of the client polling the service endpoint, the service endpoint should scope its searching of messages to those that were processed under the same security context as the requesting GetMessage message. In the case of a client polling a Mailbox, it is expected that each soap client that registers with a Mailbox will be issued a unique URL/EPR to be used as its destination address. When the client issues a GetMessage request any number of authentication schemes can be used to verify the identity of the client - once authenticated the Mailbox should then scope its searching of messages to just those that were targeted to that particular client's address.

9. References

[RFC 2119]
S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, RFC 2119, Harvard University, March 1997.
[SOAP 1.1]
D. Box, et al, Simple Object Access Protocol (SOAP) 1.1, May 2000.
[SOAP 1.2]
M. Gudgin, et al, SOAP Version 1.2 Part 1: Messaging Framework, June 2003.
A. Bosworth, et al, Web Services Addressing (WS-Addressing), August 2004.
R. Biloruseets, et al, Web Services Reliable Messaging Protocol (WS-ReliableMessaging), March 2004.
G. Della-Libera, et al, Web Services Secure Conversation Language (WS-SecureConversation), December 2002.
B. Atkinson, et al, Web Services Security (WS-Security), April 2002.
G. Della-Libera, et al, Web Services Trust Language (WS-Trust), December 2002.
[WSDL 1.1]
E. Christensen, et al, Web Services Description Language (WSDL) 1.1, March 2001.
[XML Schema, Part 1]
H. Thompson, et al, XML Schema Part 1: Structures, May 2001.
[XML Schema, Part 2]
P. Biron, et al, XML Schema Part 2: Datatypes, May 2001.

Appendix I - XML Schema

<?xml version='1.0' encoding='UTF-8'?>
    blockDefault='#all' >

  <xs:import namespace="http://schemas.xmlsoap.org/ws/2004/08/addressing"

  <xs:element name='GetMessage'>
        <xs:element ref='wsa:MessageID' minOccurs='0' />
        <xs:element name='To' minOccurs='0'
	<xs:element name='extensions' minOccurs='0' />
      <xs:anyAttribute namespace='##any' processContents='lax'/>

  <xs:element name='NoMessageAvailable' >
      <xs:attribute name='reason' type='xs:QName' />
      <xs:anyAttribute namespace='##any' processContents='lax' />

  <xs:complexType name="StatusRequested">
      <xs:element ref='wsa:MessageID' minOccurs='0' />
      <xs:element name='To' minOccurs='0'
      <xs:element name='extensions' minOccurs='0' />
    <xs:anyAttribute namespace='##any' processContents='lax'/>

  <xs:complexType name="Status">
      <xs:element ref='wsa:MessageID' minOccurs='0' />
      <xs:element name='To' minOccurs='0'
      <xs:element name='extensions' minOccurs='0' />
    <xs:attribute name='messagesPending' type='xs:boolean'
                  use='required' />
    <xs:anyAttribute namespace='##any' processContents='lax'/>


Appendix II - WSDL

    xmlns:xs='http://www.w3.org/2001/XMLSchema' >

        schemaLocation='http://www.w3.org/2005/08/ws-polling.xsd' />

  <wsdl:message name='GetMessage'>
    <wsdl:part name='body' element='wsp:GetMessage'/>
  <wsdl:message name='NoMessageAvailable'
    <wsdl:part name='body' element='wsp:NoMessageAvailable'/>
  <wsdl:message name='GetMessageResponse'>
    <wsdl:part name='body' element='xs:any'/>

  <wsdl:portType name='Polling' >
    <wsdl:operation name='GetMessage' >
      <wsdl:input message='wsp:GetMessage' />
      <wsdl:output message='wsp:GetMessageResponse' />