[Source: http://dev2dev.bea.com:80/webservices/WS-Acknowledgement-0_9.html]
Web Service Acknowledgement Protocol (WS-Acknowledgement) 0.91February 26 2003 Authors Ruslan Bilorusets, BEA Systems Yaron Goland, BEA Systems Mark Nottingham, BEA Systems David Orchard, BEA Systems Abstract This specification describes the Web Service Acknowledgement Protocol (WS-Acknowledgement), which is designed to support Reliable message exchange between services by providing for at-least-once and exactly-once SOAP message transfer guarantees. Notice, Disclaimer and License © 2002-2003, BEA Systems, Inc. All rights reserved. If you would like to copy or re-distribute this specification to others, or to prepare and distribute implementations of this specification, you may do so by accepting BEA's standard, royalty-free Web Services Specification License for this specification. Please visit WS-Acknowledgement-License.csp to review and accept the license terms and conditions. The furnishing of this specification does not grant you any rights or licenses, either expressly or by implication, in any intellectual property owned or controlled by BEA or any other party, whether necessary to implement the specification or otherwise. This specification is provided on an "AS IS" basis, with all faults. BEA hereby disclaims all warranties, WHETHER express, implied or statutory, including, but not limited to, any warranties of merchantability, fitness for a particular purpose, title OR non-infringement. Introduction The WS-Acknowledgement protocol is designed to enable WS-Acknowledgement senders to request explicit acknowledgement from WS-Acknowledgement receivers that a WS-Acknowledgement Request MessageWS-Acknowledgement Request Message has been received. An Acknowledgement message only acknowledges the receipt of the WS-Acknowledgement Request MessageWS-Acknowledgement Request Message. No guarantee is made that the WS-Acknowledgement Request MessageWS-Acknowledgement Request Message has been or will ever be processed. If the WS-Acknowledgement sender does not receive an acknowledgement within the pre-arranged retry interval then the WS-Acknowledgement sender will repeat the WS-Acknowledgement Request Message. The WS-Acknowledgement sender will continue to repeat the WS-Acknowledgement Request Message until the WS-Acknowledgement sender has retried the pre-arranged maximum number of times or until it receives an acknowledgement message. As part of the configuration of a reliable messaging exchange between two parties it is possible to ask for duplicate elimination. In that case the WS-Acknowledgement receiver is required to keep a persistent record of what Message IDs have been received for a pre-arranged period of time. If the WS-Acknowledgement receiver should receive a message whose Message ID matches that of one already in the persistent store then the WS-Acknowledgement receiver will repeat the previous transmitted Acknowledgement message. It will then discard the repeated message. The exact behavior of a reliable message exchange is decided by a set of configuration parameters defined in section 8. The WS-Acknowledgement sender and receiver, using an out of band mechanism, must agree on these parameters before reliable messaging can be initiated. WS-Acknowledgement is designed to operate at the SOAP message level and its behavior is therefore independent of any transport to which the SOAP messages may be bound. Table of Contents Web Service Acknowledgement Protocol(WS-Acknowledgement) 0.91 Introduction Table of Contents 1. Document Conventions 1.1 Notational Conventions 1.2 Compliance 2. The WS-Acknowledgement Model 2.1 Terminology 2.2 Reliable Delivery Policies 2.2.1 Exactly-Once 2.2.2 At-Least-Once 2.3 WS-Acknowledgement Sender Protocol 2.4 WS-Acknowledgement Receiver Protocol 3. WSDL 1.1 Message Exchange Pattern 4. AckRequested Header 5.1 TimeStamp Header 5.2 AckRequested Example 5.3 Recommended WSDL Behavior 5.4 Faults 5.4.1UnsupportedExpires 5.4.2 ExpiresNotIncluded 5.4.3 AckRequestedRequired 5.4.4 AckRequestedNotSupported 6. Acknowledgement Message 6.1 Acknowledgement Example 7. Configuration Parameters 7.1 ReliableMessages 7.2 Retries 7.3 RetryInterval 7.4 DuplicateElimination 7.5 PersistDuration 7.6 AckQuality 7.7 ImplicitAcknowledgement 8. Security Considerations 9. Appendix 9.1 Schema (Normative) 9.2 Message Flow Examples (Normative) 9.2.1 Reliable Request, No Response 9.2.2 Reliable Request, Unreliable Response 9.2.3 UnReliable Request, Reliable Response 9.2.4 Reliable Request, Reliable Response 9.3 Example (Non-Normative) 9.3.1 Protocol Trace 9.3.2 Yael's WSDL 9.3.3 Sven's WSDL 9.4 Use of URIs (Normative) 9.5 Processing WS-Acknowledgement (Normative) 9.6 Extending WS-Acknowledgement (Normative) 9.7 Acknowledgements (Non-Normative) 9.8 Variations from ebXML MS 2.0 (Non-Normative) 9.8.1 XML Ignore Rule 9.8.2 Application Interfaces 9.8.3 Version Attribute 9.8.4 MessageHeader 9.8.5 Fault Module 9.8.6 Reliable Faults 9.8.7 Hop-by-hop Acknowledgements 9.8.8 Acknowledgement Piggybacking 9.8.9 Persistent Storage 9.8.10 Signed Attribute 9.8.11 TimeStamp & TimeToLive 9.8.12 Reference 9.8.13 PersistDuration 9.9 Future Work Items (Non-Normative) 9.10 References (Normative) 1 Document Conventions 1.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 [2]. The XML examples are formatted for readability that means in some cases white space has been added in areas where it is not actually allowed. 1.2 Compliance An implementation is WS-Acknowledgement compliant if it satisfies all of the MUST or REQUIRED level requirements defined in this specification. 2 The WS-Acknowledgement Model 2.1 Terminology The specification depends on the terminology introduced in WS-CallBack. Header- A "header block" as defined by SOAP 1.2 [12]. WS-Acknowledgement Request Message A WS-CallBack request that contains an AckRequested header as well as secondary headers mandated by this specification. Note that it is possible for a SOAP Fault to be sent reliably which makes it a WS-Acknowledgement Request Message. WS-Acknowledgement Sender A WS-CallBack sender that initiates a WS-Acknowledgement interaction using WS-Acknowledgement Request Messages. WS-Acknowledgement Receiver A WS-CallBack receiver that receives WS-Acknowledgement Request Messages. Acknowledgement Message A SOAP message containing the Acknowledgement header as well as secondary headers mandated by this specification that is sent from a WS-Acknowledgement Receiver to a WS-Acknowledgement Sender confirming the receipt of a WS-Acknowledgement Request Message. WS-Acknowledgement Intermediary A SOAP intermediary that is aware of the syntax and semantics of WS-Acknowledgement Request Messages and Acknowledgement messages that may process such messages along a message path.
Example 1 - WS-Acknowledgement Request Message Taxonomy 2.2 Reliable Delivery Policies WS-Acknowledgement supports the following types of reliability policies. 2.2.1 Exactly-Once The WS-Acknowledgement Request Message is delivered exactly once. Duplicates will be detected and ignored. 2.2.2 At-Least-Once The WS-Acknowledgement Request Message is delivered at least once. Duplicates are allowed. 2.3 WS-Acknowledgement Sender Protocol The WS-Acknowledgement sender protocol is: 1. A WS-Acknowledgement sender sends a WS-Acknowledgement Request Message that MUST contain an ackRequested header, a CallBack header[19], a MessageData header [18] and a TimeStamp header [20]. 2. If an Acknowledgement has not been received within RetryInterval from the time of sending then the WS-Acknowledgement sender MAY retry by resending the exact same request. The WS-Acknowledgement sender MUST wait RetryInterval between each retry and continue retrying until it either receives the acknowledgement or has tried Retries times. If an acknowledgement is not received by the time PersistDuration has passed from the initial time of sending then the attempt to deliver the message is said to have failed. 3. All Acknowledgements received for the same WS-Acknowledgement Request Message, as defined by the Message ID, are to be treated as equivalent and all Acknowledgement messages after the first one may be ignored. 2.4 WS-Acknowledgement Receiver Protocol The WS-Acknowledgement Receiver protocol is: 1. A WS-Acknowledgement receiver receives a WS-Acknowledgement Request Message with ackRequested, CallBack MessageData and TimeStamp headers. If duplicate elimination is being used then the Message ID of the WS-Acknowledgement Request Message MUST be stored for PersistDuration. 2. If the message has not expired then the WS-Acknowledgement receiver responds with an Acknowledgement message that contains a RefToMessageId containing the Message ID of the WS-Acknowledgement Request Message. 3. If a WS-Acknowledgement Request Message is received with a Message ID that has been previously acknowledged and PersistDuration hasn't passed since the original message was received then the previously transmitted acknowledgement message MUST be re-transmitted. If duplicate elimination is activated then the received message is discarded. If duplicate elimination is not activated then the behavior is implementation specific. 3 WSDL 1.1 Message Exchange Pattern This specification focuses exclusively on WSDL 1.1 related message exchange patterns (MEPs) as implemented by widely deployed WSDL 1.1 systems. Unfortunately the available MEPs are not able to describe the full range of message flows enabled by WS-Acknowledgement. As such WS-Acknowledgement assumes that at the WSDL level WS-Acknowledgement requests and Acknowledgement messages will be modeled as one-way operations. This brings up exactly the same issues as discussed in section 3 of WS-CallBack and calls for similar solutions. In the simplest possible case where a WS-Acknowledgement Request Message is just a simple one-way message with no response other than an Acknowledgement the WS-Acknowledgement sender's WSDL will look like Figure 1.
Figure 1 - Simple WS-Acknowledgement sender's WSDL pattern Note that regardless of how many WS-Acknowledgement Request Messages the WS-Acknowledgement sender is sending there only needs to be a single operation on a single portType to handle all the Acknowledgement messages. The RefToMessage ID in the Acknowledgement will uniquely identify what message is being acknowledged. Similarly the complimentary WS-Acknowledgement receiver's WSDL will look like Figure 2.
Figure 2 - Simple WS-Acknowledgement receiver's WSDL pattern In the slightly more interesting case where there are reliable requests and unreliable responses only the WS-Acknowledgement sender's WSDL changes. The new WSDL is illustrated in Figure 3.
Figure 3 - WS-Acknowledgement sender's WSDL pattern with unreliable response Figure 3 reinforces the notion that one needs only one Acknowledgement operation per portType. Finally, in the case where both requests and responses are being sent reliably the side initiating the application requests will have a WSDL that matches Figure 3. However the side that receives the application requests will have a WSDL that looks like Figure 4.
Figure 4 - WSDL of the responding Web Service when both requests and responses are sent reliably 4 AckRequested Header The AckRequested header is placed on a message that the WS-Acknowledgement receiver is expected to send an Acknowledgement message in response to. The AckRequested header MUST include the SOAP mustUnderstand attribute with the value set to 1. All messages containing an AckRequested header MUST include the MessageData header from the WS-MessageData specification. The MessageData header MUST contain the MessageId element. If the WS-CallBack protocol is used with a message that contains an AckRequested header then the Acknowledgement message MUST be sent to the location specified by the CallBack header. WS-Senders compliant with this specification MUST NOT place more than one AckRequested header in a WS-Acknowledgement Request Message and either must not use the SOAP role attribute or, if assigning a role, the role MUST be that of the final destination. Future versions of this specification may define how to specify multiple AckRequested headers with different roles. Any SOAP message MAY have an AckRequested header on it except where specifically prohibited by this specification. 5.1 TimeStamp Header All messages containing the AckRequested header MUST include the TimeStamp header defined in section 10 of the Web Services Security Core Specification [20]. The TimeStamp header MUST be addressed to the final destination either by not specifying a SOAP role or specifying a SOAP role that targets the final destination. The TimeStamp header targeted at the final destination MUST include an Expires element whose value MUST be given using a XML schema dateTime [15] value in UTC. If the WS-Acknowledgement sender originally sent the message at time Ts then the value of Expires MUST be less than Ts+PersistDuration (as defined in section 8.5). If the WS-Acknowledgement receiver receives a WS-Acknowledgement Request Message with a TimeStamp header whose expires has passed then the receiver MUST NOT process the message. If no other fault has already caused the message to be rejected then the receiver MAY send a MessageExpired fault as defined in section 10.3 of WS-Security Core. Note however that the receiver is free to just drop the expired message and send no response. Unless an explicit agreement to the contrary has been reached through an unspecified mechanism the receiver MUST NOT modify the expires value in any way, including attempting to adjust for possible clock skew. 5.2 AckRequested Example
Example 2 - An AckRequested Example 5.3 Recommended WSDL Behavior The WS-Acknowledgement header is intended to be used only when necessary. This means that two messages sent by the same operation of the same service may not necessarily both include the AckRequested header. Unfortunately WSDL 1.1 does not include the concept of an optional header. If a header is specified in a message's definition then that header must always be included. As such if a message is intended to always be sent reliably then it is reasonable to include the AckRequested header otherwise the header should not be specified so as to leave the possibility of only including the header when needed. This specification does not propose a WSDL based solution to this problem because a number of groups such as the W3C WSDL 1.2 working group are already addressing the issue and are likely to come out with a comprehensive solution. 5.4 Faults WS-Acknowledgement faults are expressed as XML elements in the detail element of a SOAP fault element. All listed faults are part of the http://www.openuri.org/2003/02/soap/acknowledgement/ namespace. WS-Acknowledgement inherits all faults provided by its normative dependencies such as WS-CallBack and WS-MessageData. So, for example, if the CallBack header included in the message is malformed then one would use the <wscb:callbackHeaderMalformed xmlns:wscb="http://www.openuri.org/2003/02/soap/callback/"/> error. While any arbitrary SOAP fault may be sent reliably it is not always useful to do so. SOAP faults can only be sent if the message exchange pattern agreed to by the two parties allows for it. Unlike Acknowledgement messages that must be supported in order to use WS-Acknowledgement there is no equivalent requirement for SOAP faults. For example, if a one-way message is to be sent reliably and there is no matching one-way response then while an Acknowledgement can be sent back a fault could not. For example, notice that Figure 1, which identifies the WSDL for a one-way reliable message with no response, has the ability to receive an Acknowledgement message but not a SOAP fault.
Example 3 - An example of a SOAP UnsupportedExpires fault 5.4.1UnsupportedExpires The value in the expires element of the Timestamp header specifies a value that exceeds PersistDuration. At 12:59 PM the WS-Acknowledgement sender sends a WS-Acknowledgement Request Message to the WS-Acknowledgement receiver with an expires of 5:00 PM on the same day. The message arrives at the WS-Acknowledgement sender at 1:00 PM. As soon as the message arrives the WS-Acknowledgement receiver will start the PersistDuration clock. In this case the two parties agreed that PersistDuration will last for two hours. This means that the WS-Acknowledgement receiver's PersistDuration timer will expire at 1:00 PM + 2 hours = 3:00 PM. The problem is that the WS-Acknowledgement Request Message has an expires that lasts until 5:00 PM. If a duplicate of the WS-Acknowledgement Request Message should be held up in the network and make its way to the WS-Acknowledgement receiver after 3:00 PM then the receiver, having forgotten about the Message ID due to the expiration of PersistDuration, will think the repeated message is a brand new message. This is why the specification mandates that the expires time must be at least equal to the time the message was sent plus PersistDuration. This is also why the UnsupportedExpires error is provided. It allows the WS-Acknowledgement receiver to reject the WS-Acknowledgement Request Message. This will at least warn the WS-Acknowledgement sender that something is wrong. In theory no damage is done if repeats of the message are already in the network. They will all be rejected until one appears at 3:00 PM. This fault SHOULD be marked as a SOAP client fault. 5.4.2 ExpiresNotIncluded The WS-Acknowledgement Request Message either didn't include a Timestamp header or included a Timestamp header but didn't include the expires element. As such the message must be rejected. This fault SHOULD be marked as a SOAP client fault. 5.4.3 AckRequestedRequired The receiver has rejected the message because it was not a WS-Acknowledgement Request Message. This fault SHOULD be marked as a SOAP client fault. 5.4.4 AckRequestedNotSupported This message is used to reject a particular sender's request to use WS-Acknowledgement on a particular operation as part of a particular service. Generally this fault is used for cases where, for example, the sender's contract level with the receiver is not high enough to provide for WS-Acknowledgement support. This fault is not intended to indicate a transient failure. The sender SHOULD NOT send another WS-Acknowledgement request to the same operation on the same service without first having used an out-of-band mechanism to resolve the problem. The sender cannot conclude from this fault that WS-Acknowledgement requests to different operations on the same service may fail with the same fault. Furthermore the sender cannot conclude anything from this fault about how a different sender's WS-Acknowledgement request may be treated. 6 Acknowledgement Message The Acknowledgement message is sent by the WS-Acknowledgement receiver to the WS-Acknowledgement sender to acknowledge the message has been received by the targeted application. An acknowledgement does not guarantee, however, that the message has been or will be successfully processed. There MUST NOT be any responses of any form, including SOAP faults, to an Acknowledgement message. The Acknowledgment message MUST include an Acknowledgement header and a MessageData header. Other headers MAY be included. Implementations compliant with this specification MUST ignore the body of an Acknowledgement message. The Acknowledgement message MUST NOT contain an AckRequested header. The Acknowledgement header MUST include a SOAP mustUnderstand attribute on it with a value set to 1. The MessageData header included in an Acknowledgement message MUST include the RefToMessageId element whose value MUST equal the Message ID of the message being acknowledged. Note that Acknowledgement messages may also include a MessageId element inside of the MessageData header. WS-Acknowledgement receivers compliant with this specification MUST either not use the SOAP role attribute or must set the value of the SOAP role attribute to the WS-Acknowledgement sender. Future versions of this specification may define how to specify SOAP role attributes with values other than the final message destination endpoint. It is worth noting that even though a single instance of a WS-Acknowledgement Request Message may have been sent out multiple duplicates of the related Acknowledgement message may be received in turn. Although Acknowledgement messages cannot be sent reliably it is important to differentiate between retries at the transport versus at the SOAP level. While an Acknowledgement message at the SOAP level can only be repeated if an additional instance of the associated WS-Acknowledgement Request Message is received this in no way prevents, for example, retrying a HTTP connection if the first attempt to form the connection failed. WS-Acknowledgement has nothing to say regarding what, if any, retry behavior is to be attempted at the transport level. 6.1 Acknowledgement Example
Figure 5 - Example of Acknowledgement Message 7 Configuration Parameters The WS-Acknowledgement sender and receiver, using an out-of-band mechanism, must agree upon the following parameters. 7.1 ReliableMessages There does not yet exist a standard for how to annotate WSDLs with information such as the requirement that one MAY/SHOULD/MUST use WS-Acknowledgement on a particular message. However a number of proposals in the area have been made and there does not appear to be much utility in having WS-Acknowledgement make yet another one. As such it must suffice to point out that it would generally be useful for partners in a communication to agree before hand which messages in a particular service will support or even mandate the use of WS-Acknowledgement. Strictly speaking however such an agreement does not have to be made. After all senders are always free to put in an AckRequested header and take their chances. In practice however this is unlikely to be the predominate mode of interoperability so some sort of agreement is called for. In cases where the message exchange pattern allows for SOAP faults the agreement mechanism should also be able to specify if all/some/no faults are to be sent reliably. The agreement mechanism also needs to provide for the ability to specify what security mechanisms, if any, are to be used on WS-Acknowledgement and Acknowledgement messages. 7.2 Retries The Retries parameter specifies the number of times a WS-Acknowledgement sender SHOULD resend an unacknowledged message before giving up and deciding the message cannot be delivered. WS-Acknowledgement senders MUST NOT resend messages more than Retries times. WS-Acknowledgement only addresses retry behavior at the SOAP level. No comment is made by this specification on retry behavior at the transport level. For example, if a SOAP message is sent over FTP and the TCP/IP connection cannot be formed due to a router problem it would seem reasonable for the transport to automatically retry. This retry is not considered in terms of counting WS-Acknowledgement retries. 7.3 RetryInterval The RetryInterval specifies the time a WS-Acknowledgement sender MUST wait between retries. The WS-Acknowledgement sender is expected to wait RetryInterval after sending a request before retrying the request and to then wait RetryInterval between all subsequent retries. If an acknowledgement is received then the WS-Acknowledgement sender MUST NOT subsequently repeat the request. 7.4 DuplicateElimination The DuplicateElimination parameter determines whether the receiver is required to persistently store received messages or at least their Message IDs for PersistDuration in order to be able to detect duplicates. If a duplicate message arrives and duplicate elimination is activated then the receiver MUST repeat the original acknowledgement. DuplicateElimination SHOULD be used any time a non-idempotent WS-Acknowledgement Request Message is sent. If DuplicateElimination is not being used then the two parties must agree on the semantics of a duplicate WS-Acknowledgement Request Message. 7.5 PersistDuration PersistDuration is the period of time from when a WS-Acknowledgement Request Message with a particular Message ID is sent until that message MUST NOT be repeated by the WS-Acknowledgement sender. If DuplicateElimination is being used then WS-Acknowledgement receivers MUST store WS-Acknowledgement Request Messages, or minimally their Message IDs, for at least PersistDuration in order to detect duplicates. PersistDuration MUST be greater than RetryInterval*(Retries + 1). 7.6 AckQuality An acknowledgement only indicates that the message was received. No additional information is implied. In most cases however the sender and receiver will want to agree on some level of quality regarding how the message is stored before it is processed. E.g. they may want to agree that a message will at least be held in a persistent storage that is durable across system crashes. This specification makes no statement regarding what quality of storage, if any, is provided. The number of possible variations on such quality are endless. Examples include: in-memory storage, in-memory but replicated storage, persisted to disk, persisted to RAID disk, persisted to a distributed disk array, etc. In addition each one can be further qualified by information on how long it will take to recover from a crash. At this point it seems premature to try and provide standardized parameters to describe these various qualities of service. Only with implementation experience will it be clear which parameters will be most useful in a web services context. 7.7 ImplicitAcknowledgement Section 10.2.2 addresses the question of if an application response is received to a WS-Acknowledgement Request Message but an Acknowledgement message has not arrived can the WS-Acknowledgement sender treat the application response as a substitute for the Acknowledgement message? Strictly speaking this issue is out of scope for WS-Acknowledgement. If a WS-Acknowledgement sender, for any reasons, decides to lose interest in receiving an Acknowledgement that is generally a matter for the sender to worry about. However, a WS-Acknowledgement receiver may support various extensions to the Acknowledgement message and harbor some expectations that the WS-Acknowledgement sender will receive the Acknowledgement and act on those extensions. As such it is useful if the two parties communicate their mutual expectations about how to treat the situation described in the first paragraph of this section. 8 Security Considerations TBD 9 Appendix 9.1 Schema (Normative)
9.2 Message Flow Examples (Normative) In the following examples the WS-Acknowledgement Intermediary is meant to be a "stand in" for an arbitrary number of intermediaries as well as any number of possible networking and other connection problems. When an arrow stops at the intermediary but doesn't continue on to the end this means that the message is lost. 9.2.1 Reliable Request, No Response Since WS-Acknowledgement Request Messages are always one-way one can view them in isolation. Imagine an application that sends in a purchase order (PO).
Example 4 - One Way Asynchronous WS-Acknowledgement Request Message with repeat In Example 4 the PO request is sent and an acknowledgement is returned but lost by the WS-Acknowledgement intermediary so that the PO request is sent again and this time the Acknowledgement arrives. 9.2.2 Reliable Request, Unreliable Response In reality the actual message pattern is likely to be significantly more complex involving one or more responses. The presence of expected responses can, however, alter WS-Acknowledgement's behavior.
Example 5 - One Way Asynchronous WS-Acknowledgement Request Message with response but no Acknowledgement In Example 5 the PO request has successfully arrived and both an Acknowledgement message and a PO response message are sent out. The PO response successfully arrives but the Acknowledgement does not. Should the WS-Acknowledgement Sender resend the PO Request in order to receive an Acknowledgement message? As discussed in section 8.7 to a certain degree, the PO response can be said to serve in the role of an Acknowledgement. Therefore, in theory, the WS-Acknowledgement sender could choose not to repeat the PO request since the Acknowledgement would now be superfluous. However, the WS-Acknowledgement receiver in Example 5 may have good reasons for repeating the PO request in order to get an Acknowledgement message even though a PO response has already been received. The first reason is that the WS-Acknowledgement stack may have no knowledge of the relationship between PO request and PO response. This is not something that can currently be expressed in WSDL 1.1 so unless the information was provided to the WS-Acknowledgement stack through some other means then all the WS-Acknowledgement stack will see is the picture in Example 4. That is, it will only know about the PO request and the need for an Acknowledgement message. Not having received the PO request it will then automatically repeat the PO request until it receives the Acknowledgement. The second reason is that the Acknowledgement message may be digital signed and may be needed as part of the legal audit trail by the WS-Acknowledgement sender. In that case, even with a signed PO response in hand, the WS-Acknowledgement sender may still repeat the PO request in order to also get the signed Acknowledgement message. The third reason is that extensions may be used with the Acknowledgement message that the WS-Acknowledgement receiver will want to make sure the WS-Acknowledgement sender receives. Under the general theory of the fewer surprises the better it is best if both sides negotiate the WS-Acknowledgement sender's behavior as part of deciding on the out-of-band parameter ImplicitAcknowledgement. 9.2.3 UnReliable Request, Reliable Response It is theoretically possible for the PO request to be sent unreliably but the PO response to be sent reliably. Please note that Example 6 reverses the request/response order so that the unreliable request is coming from the WS-Acknowledgement receiver and the reliable response is coming from the WS-Acknowledgement sender.
In Example 6 the PO request is sent unreliably but the response, a SOAP fault, is sent reliably. The WS-Acknowledgement intermediary lost the first SOAP Fault so it never arrived at the WS-Acknowledgement receiver. After the time out the WS-Acknowledgement sender repeated the SOAP Fault and this message did arrive and so stimulate the transmission of an Acknowledgement message. A variation of Example 6 is the case where there are multiple possible responses, some of which could be sent reliably and some not. 9.2.4 Reliable Request, Reliable Response In this example both the PO request and the PO response are sent reliably. The result is that both sides of the communication are, at various points, both WS-Acknowledgement senders and receivers. To help sort things out the two parties are given names, Sven and Yael. Yael will send a reliable PO request to Sven and Sven will respond with a reliable PO response.
In Example 7 Sven's data center was struck by lightening after sending the Acknowledgement message but before sending the PO response. From a WS-Acknowledgement perspective there is nothing particular interesting here. Yael sent a message, Sven received it and an Acknowledgement message was sent in response. As far as WS-Acknowledgement is concerned its job is done, the message was delivered and acknowledged. Obviously Yael may beg to differ, an Acknowledgement message is all very well and good but what she really wants is the PO response. Should Yael repeat the PO request in hopes of stimulating a PO response? After all, Yael doesn't know that Sven's data center has been struck by lightening. For all Yael knows this is just a problem with a WS-Acknowledgement intermediary failing to deliver the PO response. WS-Acknowledgement has nothing to say about how Yael should behave. WS-Acknowledgement's job is to reliably send a single message which, in Example 7, it did. However, WS-CallBack defines the WaitTime parameter that specifies how long Yael should wait before giving up on receiving a response from Sven. Yael can, if she wants, choose to repeat the PO request so long as PersistDuration hasn't expired yet. But generally PersistDuration is less than WaitTime so the ability to repeat the PO request is of limited utility. Generally speaking the best Yael can do is to wait until either a response is received or WaitTime expires. The situation can be improved if Yael and Sven agree out-of-band that all PO responses will be sent reliably. In that case Yael knows that if Sven sends a PO response and it is lost for any reason then Sven will automatically repeat the PO response. The reason for the repetition is that if the PO response is lost then Yael won't send an Acknowledgement that will automatically cause Sven to resend.
In Example 8 the WS-Acknowledgement Intermediary is particularly unreliable and keeps on losing messages. Since both PO request and PO response are being sent reliably this results in a lot of repeats. The only reason to include such a long example is to have at least one full bi-directional examples with losses so as to illustrate the full retry behavior. 9.3 Example (Non-Normative) Yael and Sven wish to implement a Web Service using WS-Acknowledgement and WSDL 1.1 over HTTP. The Web Services consists of two separate request/response pairs, PORequest/POResponse and ConfirmingOrderDelivery/ConfirmingOrderDeliveryResponse. Both request/response pairs are materialized as one-way WSDL 1.1 operations. PORequest/POResponse uses WS-Acknowledgement for both messages. ConfirmingOrderDelivery is sent using WS-Acknowledgement but ConfirmingOrderDeliveryResponse is not. The ConfirmingOrderDelivery pair is included to show how this type of pattern affects the WSDL. An actual example of their use won't be provided. 9.3.1 Protocol Trace
Example 9 - Successful WS-Acknowledgement PO exchange
Example 10 - Connection 1 from Yael to Sven
9.3.2 Yael's WSDL
9.3.3 Sven's WSDL
9.4 Use of URIs (Normative) WS-Acknowledgement uses URIs for all identifiers. To WS-Acknowledgement, a URI is simply a formatted string that identifies-via name, location, or any other characteristic-a resource on the Web. This section defines the rules and conventions governing the URIs as values. The use of IP addresses in URIs SHOULD be avoided whenever possible (see RFC 1900 [1]). However, when used, the literal format for IPv6 addresses in URI's as described by RFC 2732 [6] MUST be supported. All URIs used in WS-Acknowledgement MAY be either absolute or relative. WS-Acknowledgement does not define a base URI but relies on the mechanisms defined in XML Base[13] and RFC 2396[3] for establishing a base URI against which relative URIs can be made absolute. SOAP 1.1 does not explicitly support XML Base. Therefore, the BASE URI infoset item may not be explicitly set by a SOAP 1.1 processor. A WS-Acknowledgement processor MAY be required to determine the Base URI as per the rules for resolving URIs in XML Base. An example of this is examining the xml:base attribute in the SOAP 1.1 envelope. SOAP 1.2 [10] explicitly supports XML Base. A WS-Acknowledgement node MUST use the Base URI as set by a SOAP 1.2 processor WS-Acknowledgement does not define equivalence rules for URIs as these are defined by the individual URI schemes and by RFC 2396 [3] (also see the W3C TAG's [16] work on the use of URIs for comparison [17]). It is recommended that WS-Acknowledgement Senders do not rely upon the WS-Acknowledgement Receiver to determine equivalence rules in addition to URI schemes and RFC 2396. WS-Acknowledgement does not place an a priori limit on the length of a URI but all WS-Acknowledgement compliant receivers MUST support URI values of at least 2048 bytes in length. 9.5 Processing WS-Acknowledgement (Normative) WS-Acknowledgement is designed to be extended such that new elements and attributes in the WS-Acknowledgement headers (e.g. AckRequested and Acknowledgement) can be added without requiring central registration. However this means that a WS-Acknowledgement sender/receivers could add in values to the WS-Acknowledgement headers that the WS-Acknowledgement receiver/sender may not understand. To deal with this possibility, upon receiving a WS-Acknowledgement header the WS-Acknowledgement sender/receiver MUST ignore any unrecognized elements/attributes for purposes of WS-Acknowledgement header processing. Ignoring an element means acting as if the element and its progeny had not been sent in the message. Ignoring an attribute means acting as if the attribute had not been sent in the message. Note that this does not require that the elements be physically removed, only ignored for WS-Acknowledgement header processing purposes. If a message is received with unrecognized elements in a WS-Acknowledgement header it is reasonable to expect that if the message is logged the serialized version would include the unrecognized elements. For example, imagine that a WS-Acknowledgement receiver that is only compliant with this specification (e.g. it has not been enhanced to support extended elements) received the following WS-Acknowledgement request:
The message in the previous example should 'look' to the WS-Acknowledgement receiver as if it were identical to the message in Example 2. The various highlighted entries would be ignored. The ncs:foo attribute would be ignored because it is unrecognized. The WS-Acknowledgement receiver never even has to look at the ncs:lk3 element because it would automatically be removed as a consequence of its parent, ncs:conf, not being recognized. The quality element is interesting because it comes from the WS-Acknowledgement namespace. But there is no quality element defined in this specification and as previously stated the WS-Acknowledgement receiver is only compliant with this specification. The WS-Acknowledgement receiver is to ignore elements not because of their namespace but because they are not defined in this specification. So even though the quality element comes from the WS-Acknowledgement namespace, it wasn't defined in this specification and therefore would be ignored. In a sense the maxpersist element, much like the ncs:lk3 element, would never be 'seen' because its parent, quality, was pruned. 9.6 Extending WS-Acknowledgement (Normative) A new child element to be added to a WS-Acknowledgement header can be defined by a specification that makes a normative reference to this specification and then defines the new element. However implementers MUST NOT define extension elements that come from XML namespaces [9] they do not own. The only requirement on an extension is that its syntax and semantics MUST be backwards compatible with the syntax and semantics defined in this specification. The term 'backwards compatible' in this context means that the extended version of a WS-Acknowledgement header (e.g. AckRequested and Acknowledgement) would be encoded such that an implementation based exclusively on this specification would be able to successfully process the incoming WS-Acknowledgement header in the manner defined by this specification. 9.7 Acknowledgements (Non-Normative) The authors would like to acknowledge the invaluable contributions of the OASIS ebXML Messaging Services TC from whose work this specification is heavily based. Specifically sections 6 of MSS 2.0 [7]. In addition, the following individuals deserve thanks: Daniel Weinreb, BEA Systems 9.8 Variations from ebXML MS 2.0 (Non-Normative) 9.8.1 XML Ignore Rule ebXML provides extensive mechanisms for extending XML using foreign namespaces, e.g. any namespace but the one specified in ebXML. However a consequence of this decision is that there is no way to add new elements in their current namespace since doing so would confuse existing implementations who expect to recognize all elements from the ebXML namespace. Also, extensions can only be added in areas where they have been specifically allowed. WS-Acknowledgement has chosen to use a more flexible extension mechanism that enables new elements to be added to existing namespaces in a backwards compatible manner and allows extensions to be specified everywhere. See sections 9.5 and 9.6 for details. 9.8.2 Application Interfaces ebXML specifies specific errors and warnings that the reliability sub-system must deliver to the application interfaces. WS-Acknowledgement avoids specifying the exact details of how the reliability sub-system and application interfaces should communicate. WS-Acknowledgement focuses on on-the-wire syntax and semantics. The line between defining semantics and requiring specific warnings/errors is a thin one and it is felt that ebXML's approach has many merits. But on balance WS-Acknowledgement choose to err on the side of leaving the most flexibility for implementers. 9.8.3 Version Attribute In ebXML both the AckRequested and Acknowledgement headers contain version attributes whose purpose is to let existing implementations properly detect and reject commands from newer non-backwards compatible versions of ebXML. WS-Acknowledgement chooses to rely on the XML namespace mechanism for its versioning capabilities. If a change is made to a header that is not 100% backwards compatible with this specification then a new element or namespace must be used. 9.8.4 MessageHeader ebXML has a generic MessageHeader header that contains information such as to, from, service, action, etc. Most of this functionality is not strictly required for WS-Acknowledgement and all of it needs to be defined in a generic web services framework that would exceed the areas WS-Acknowledgement addresses. As such WS-Acknowledgement does not provide equivalent functionality. 9.8.5 Fault Module ebXML provides a sophisticated error handling module that is too complicated for the simplicity that is desired for Web Services. Therefore WS-Acknowledgement errors are specified using a simple SOAP Fault based system. 9.8.6 Reliable Faults ebXML forbids error messages from being sent reliably. In practice this means that SOAP Fault are not be sent reliably. WS-Acknowledgement removes this restriction because many SOAP faults contain information as critical to the receiver as information in an application fault. So a blanket prohibition seemed inappropriate. WS-Acknowledgement instead requires that which SOAP faults may/should/must/must not be returned reliably be specified as part of the ReliableMessages parameter. 9.8.7 Hop-by-hop Acknowledgements ebXML provides for both end-to-end and hop-by-hop acknowledgements. WS-Acknowledgement does not support hop-by-hop acknowledgements (it restricts the use of SOAP role and multiple instances of the AckRequested header) in this version of WS-Acknowledgement but the spec has been designed such that this feature could be added later on in a backwards compatible way. 9.8.8 Acknowledgement Piggybacking ebXML allows Acknowledgements to be sent either as stand alone messages or to be piggybacked on other messages. This level of flexibility effectively requires allowing messages to be put inside of other messages, which causes all sorts of violence to the object model. For example, the TimeStamp, From and RefToMessageId values have to all be specially re-invented so they can be stuck inside of an Acknowledgement and eventually security headers would also have be re-invented. Given the general impression that the performance benefits of piggybacking are minimal (especially when transports such as HTTP support pipelining) it was felt better to just require that Acknowledgement messages must be sent as stand alone messages. A consequence of this decision is that WS-Acknowledgement does not support the syncReplyMode configuration parameter as all Acknowledgements must be sent asynchronously. 9.8.9 Persistent Storage ebXML requires that certain types of information be stored persistently, although it does leave it fairly open as to what that means. WS-Acknowledgement never mandates the mechanisms by which information is to be stored and has introduced an additional quality of service attribute, AckQuality that can explicitly define the exact expected persistence behavior. 9.8.10 Signed Attribute ebXML supports a signed attribute on the AckRequested header to specify if the Acknowledgement must be digitally signed. WS-Acknowledgement does not specify the use of this attribute in this version of the specification as WS-Security isn't quite ready to be normatively referenced. When WS-Security achieves standards status then a future version of this specification will reference it and specify how to use it. 9.8.11 TimeStamp & TimeToLive ebXML uses TimeStamp and TimeToLive elements inside of its MessageData element and TimeStamp inside of its Acknowledgement header. WS-Acknowledgement instead uses the TimeStamp header defined by WS-Security. WS-Security's TimeStamp header contains the creation and expiration elements that specify the same information as ebXML's TimeStamp and TimeToLive elements. WS-Acknowledgement also does not mandate the use of the TimeStamp header's creation sub-element where as ebXML does mandate similar information be placed in messages such as Acknowledgement. 9.8.12 Reference ebXML provides for the use of the Reference element to allow for XMLDSIG to sign acknowledgements. WS-Acknowledgement depends on WS-Security to provide the same functionality. 9.8.13 PersistDuration ebXML specifies that senders 'SHOULD' not repeat messages after PersistDuration. WS-Acknowledgement raises this requirement to a 'MUST' so as to provide the highest protection possible against senders sending messages after the receiver has forgotten about the MessageId (e.g. after PersistDuration expired) and so mistakenly thinking the repeated message is a new message. 9.9 Future Work Items (Non-Normative)
[1] B. Carpenter, Y. Rekhter, "Renumbering Needs Work", RFC 1900, IAB, February 1996 [2] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997 [3] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, MIT/LCS, U.C. Irvine, Xerox Corporation, August 1998. [4] Y. Goland, E. Whitehead, A. Faizi, S. Carter, D. Jensen, " HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, Microsoft, UC Irvine, Netscape, Novell, February 1999 [5] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, U.C. Irvine, DEC W3C/MIT, DEC, W3C/MIT, W3C/MIT, January 1997 [6] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6 Addresses in URL's", RFC 2732, Nokia, IBM, AT&T, December 1999 [7] OASIS ebXML Messaging Services Technical Committee, "Message Service Specification Version 2.0", April 2002, [8] W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000, http://www.w3.org/TR/2000/REC-xml-20001006 [9] W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999, http://www.w3.org/TR/1999/REC-xml-names-19990114/, [10] W3C Note "Simple Object Access Protocol (SOAP) 1.1" [11] W3C Note "Web Services Description Language (WSDL) 1.1" [12] W3C Working Draft "Simple Object Access Protocol (SOAP) 1.2 Part 1" [13] W3C Recommendation "XML Base", Jonathan Marsh, 27 June 2001, "http://www.w3.org/TR/2001/REC-xmlbase-20010627/ [14] W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001, " http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/" [15] W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001., "http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/" [16] W3C Technical Architecture Group, "http://www.w3.org/2001/tag/" [17] Architecture of the World-Wide Web, URI uses chapter, http://www.w3.org/TR/webarch/#uri-use [18] BEA Proposal "Web Services Message Data (WS-MessageData)", to be published. [19] BEA Proposal "Web Services CallBack (WS-CallBack)", to be published. [20] OASIS Web Service Security Technical Committee, "Web Services Security Core Specification - WSS-Core-08", December 2002 |