Application Notes for Web Services Reliable Messaging specification

Working Draft 0.5, 18 March, 2006

Editors:

Kazunori Iwasa, Fujitsu Limited

Tom Rutt, Fujitsu Software Cooperation

Abstract:

This document describes complementary notes for the Web Services Reliable Messaging specification, useful for implementers of the specification or for the deployment of an implementation. In a first part some material about the binding options of WS-Reliable Messaging messages to underlying transports is presented, in particular HTTP. The document attempts to identify how these binding options may affect interoperability.

Table of Contents

1 Introduction 3

1.1 Terminology 3

1.2 Normative References 3

1.3 Non-Normative References 3

2 Message Sequence Patterns 4

2.1 Binding Options for Sequence Management 4

2.1.1 Synchronous Sequence Management 5

2.1.2 Asynchronous Sequence Management (Case 1) 6

2.1.3 Asynchronous Sequence Management (Case 2) 7

2.2 Binding Options for the Acknowledgement Patterns 7

3 Error Handling 9

A. Combination of AcksTo and WSDL MEP 10

B. Acknowledgements 15

C. Non-Normative Text 16

D. Revision History 17

9 December 2005

Copyright © Fujitsu Limited 2005-2006. All Rights Reserved. Page 17 of 17

1  Introduction

The first section of this document is focused on typical message sequence patterns for Web Services Reliable Messaging, and related http binding options.

1.1 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

1.2 Normative References

[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.

Reference] ion]

1.3 Non-Normative References

Reference] ion]

2  Message Sequence Patterns

Two message sequence patterns in the WSRM specification present several binding options to underlying protocols, on which it may be necessary for an RMS and RMD to agree.

(1) The Sequence management pattern takes place when one of the following elements: CreateSequence, CloseSequence, TerminateSequence, is sent from RMS to RMD, and when the related response is sent back.

(2) The acknowledgement pattern may be of two kinds: (a) the “requested” pattern takes place when a message requesting an Acknowledgement is sent (AckRequested), and the related Acknowledgement message is sent back. The “unrequested” pattern concerns the periodic sending of SequenceAcknowledgement messages on the initiative of the RMD (e.g. based on a time interval).

These patterns are illustrated in the following figure.

2.1 Binding Options for Sequence Management

Two HTTP binding options are presented here for the sequence management pattern, not exclusive from others (e.g. PAOS binding) that will be investigated in a future version of this draft. In particular, the case where an RMD is unable to receive incoming HTTP requests - e.g. due to security or addressing restrictions - and therefore must initiate all message transfers (application messages as well as management messages) is not investigated here,

[Note]

2.1.1 Synchronous Sequence Management

In this case, the first message (either to create, close or terminate a sequence) is sent over HTTP POST. The response message (either one of: CreateSequenceResponse, CloseSequenceResponse or TerminateSequenceResponse ) is sent back over the HTTP response. Some RMS implementations may require this binding option to be used at the exclusion of others as they may be unable to accept incoming HTTP requests. The following figure illustrates this binding option.

The use of this binding option may be agreed upon “out of band”. It is however preferable that it is indicated in the protocol, within the request message, because an RMD implementation may not always be able to resolve the pattern to be used when solely based on an out-of-band contract with the sender of the request. This may be the case when receiving many CreateSequence messages from various RMS instances.

A way to indicate the synchronous binding option in the protocol is as follows:

When the AcksTo element in a CreateSequence message carried on HTTP Request contains the element "<wsa:address>http://www.w3c.org/2005/08/addressing/anonymous</wsa:address>", the response message - that is the CreateSequenceResponse message – MUST be returned on the HTTP Response. The same pattern will also apply to CloseSequence and TerminateSequence.

1) An example of CreateSequence message

<wsrm:CreateSequence>

<wsrm:AcksTo>

wsa:Address>http://www.w3c.org/2005/08/addressing/anonymous</wsa:Address>

</wsrm:AcksTo>

<wsrm:Expires>P3M</wsrm:Expires>

<wsrm:Offer>

<wsrm:Identifier>http://example.com/serviceX/1225</wsrm:Identifier>

<wsrm:Expires>P3M</wsrm:Expires>

</wsrm:Offer>

</wsrm:CreateSequence>

2) An example of CreateSequenceResponse message

<wsrm:CreateSequenceResponse>

<wsrm:Identifier>http://example.com/serviceX/1225</wsrm:Identifier>

<wsrm:Expires>P3M</wsrm:Expires>

<wsrm:Accept>

<wsrm:AcksTo>

<wsa:Address>http://www.w3c.org/2005/08/addressing/anonymous</wsa:Address>

/wsrm:AcksTo>

</wsrm:Accept>

</wsrm:CreateSequenceResponse>

The main reason for controlling the binding option for this pattern based on the content of AcksTo, is the need to align with the binding option used for the Acknowledgement patterns (see 2.2), as the same addressing and/or security restrictions may apply. However, the above method introduces a dependency between addressing indication and HTTP binding option. Another way to indicate the use of this pattern, is to profile extensibility points in CreateSequence.

2.1.2 Asynchronous Sequence Management (Case 1)

In this case, the first message (either to create, close or terminate a sequence) is sent over HTTP POST. The response message (either one of: CreateSequenceResponse, CloseSequenceResponse or TerminateSequenceResponse ) is also sent back over an HTTP request (POST).

The following figure illustrates this binding option.

The use of this pattern may be agreed upon “out of band”. It is however preferable that it is indicated in the protocol, within the request message,

A way to indicate this asynchronous pattern in the protocol is as follows:

When the AcksTo element in a CreateSequence message carried on an HTTP Request does not contain the element "<wsa:address>http://www.w3c.org/2005/08/addressing/anonymous</wsa:address>", the response message - that is the CreateSequenceResponse message - MUST NOT be returned on HTTP Response of the message. It MUST be sent on an HTTP Request from the RMD to RMS.

1) An example of CreateSequence message

<wsrm:CreateSequence>

<wsrm:AcksTo>

wsa:Address>http://example.com/serviceX/AckReceiver</wsa:Address>

</wsrm:AcksTo>

<wsrm:Expires>P3M</wsrm:Expires>

<wsrm:Offer>

<wsrm:Identifier>http://example.com/serviceX/1001</wsrm:Identifier>

<wsrm:Expires>P3M</wsrm:Expires>

</wsrm:Offer>

</wsrm:CreateSequence>

2) An example of CreateSequenceResponse message

<wsrm:CreateSequenceResponse>

<wsrm:Identifier>http://example.com/serviceX/1001</wsrm:Identifier>

<wsrm:Expires>P3M</wsrm:Expires>

<wsrm:Accept>

<wsrm:AcksTo>

wsa:Address>http://example.com/serviceX/AckReceiver</wsa:Address>

</wsrm:AcksTo>

</wsrm:Accept>

</wsrm:CreateSequenceResponse>

However, the above method introduces a dependency between addressing indication and HTTP binding pattern. Another way to indicate the use of this binding option, is to profile extensibility points in CreateSequence.

2.1.3 Asynchronous Sequence Management (Case 2)

In this case, the RMD – or the associated endpoint - is initiating all exchanges over HTTP. The first message (either to create, close or terminate a sequence) is sent over an HTTP response received by the RMD. The response message (either one of: CreateSequenceResponse, CloseSequenceResponse or TerminateSequenceResponse ) is sent back by the RMD over an HTTP request (POST). This binding option is aligned with the PAOS binding.

2.2 Binding Options for the Acknowledgement Patterns

The “requested Acknowledgement” pattern is also a request-response pattern similar to the sequence management pattern. It is recommended that the same binding option(s) be used between an RMS and an RMD, for these two patterns. In particular, in case the synchronous sequence management binding is used exclusively - due to restrictions previously mentioned - the requested Acknowledgement pattern MUST also use the synchronous binding option.

The binding option may be indicated as previously described:

If the AcksTo element of CreateSequence message contains: wsa:Address>http://www.w3c.org/2005/08/addressing/anonymous</wsa:Address> the SequenceAcknowledgement MUST be send back in the HTTP Response message.

The “un-requested Acknowledgement” pattern MUST also use a binding option consistent with the one used by the requested Acknowledgement pattern. If a synchronous binding option is exclusively used for the requested Acknowledgement pattern, then un-requested Acknowledgement messages MUST be sent as HTTP responses, e.g. over responses to application messages sent reliably.

3  Error Handling

(TBD)

Note: This section may specify how to deal with fatal error, e.g., how to specify the status of the messages sent, how to recover the status when it was re-started, and so on. Some of these are implementation decisions, and some of them may be specified in a document.

A.  Combination of AcksTo and WSDL MEP

<This section needs to be updated after we resolve the issue brought up by the implementation SC on use of anonymous AcksTo with reliability on the response.>

This Appendix presents UML sequence diagrams which show the sequence of message transfers, including representations for the underlying transport connections. These figures can be clarified even further in a set of application notes, which explicitly describe the behaviour when the underlying transport is HTTP/POST over TCP/IP.

[Note]

<additional HTTP bindings, like in WS-Reliability, need to be prepared to correspond with each of these example Sequence Diagrams>

A) Asynchronous AckTo: When the value is URI

A1) One-way WSDL operation: Asynch AckTo (no business reply shown)

  1. SA invokes send(message:string) primitive on RMS
  2. RMS assigns RequestNumber and buffers message for possible retransmission
  3. RMS invokes receiveSoapRqst on RMD (with SequenceHdr and message body)
  4. RMD invokes deliver(message:string) primitive on RA
  5. RMD returns empty receiveSoapResp to sending RMS
  6. RMD invokes receiveSoapRqst on AckTo RMS (with AckHdr)

7.  AckTo RMS returns empty receiveSoapResp to RMD

8.  AckTo RMS frees message buffer for acknowledged RequestNumber(s)

Steps 3, 5 6 and 7 are shown (with representations for underlying transport connections) in a sequence diagram in Figure A1

A2) Request/Response WSDL operation: Synchronous Business Reply, Asynch AckTo

  1. SA invokes sendRqst(message:string) primitive on RMS
  2. RMS assigns RequestNumber and buffers message for possible retransmission
  3. RMS invokes receiveSoapRqst on RMD (with SequenceHdr and message body)
  4. RMD invokes deliverRqst(message:string) primitive on RA
  5. RA invokes sendResp(message:string) primitive on RMD
  6. RMD returns receiveSoapResp to sending RMS (with message body)
  7. RMD invokes receiveSoapRqst on ActTo RMS (with AckHdr)

8.  AckTo RMS returns receiveSoapResp to RMD (empty)

9.  AckTo RMS frees message buffer for acknowledged RequestNumber(s)

Steps 3, 6, 7, 8, correspond to Steps 3, 5, 6, and 7 in scenario A1. Figure A1, at its level of detail, does not distinguish between scenarios A1, and A2, since it does not constrain the contents of the Soap Body for the SOAP Return message. A more detailed set of application note features should show the differences between A1 and A2 scenarios with respect the contents of the SOAP Body.

Figure A1:Asynchronous AckTo using Callback

B) Synchronous AckTo: When the AckTo value is "anonymous"

B1) Request/Response WSDL operation: Synchronous Business Reply

  1. SA invokes sendRqst(message:string) primitive on RMS
  2. RMS assigns RequestNumber and buffers message for possible retransmission
  3. RMS invokes receiveSoapRqst on RMD (with SequenceHdr and message body)
  4. RMD invokes deliverRqst(message:string) primitive on RA
  5. RA invokes sendResp(message:string) primitive on RMD
  6. RMD returns receiveSoapResp (with AckHdr and message body) to RMS

7.  RMS invokes deliverResp(message:string) primitive on SA

8.  RMS frees message buffer for acknowledged RequestNumber(s)

Steps 3, 6 are shown in Figure B1, including representations for underlying transport connections.

B2) One-way WSDL operation for Request: Separate one-way callback(using wsa:ReplyTo) for Business Reply (not listed but shown in Figure B2)

Note- this scenario is not WS-I BP 1.x compliant, but is one that people want to be able to realize with ws-reliableMessaging..

  1. SA invokes send(message:string) primitive on RMS
  2. RMS assigns RequestNumber and buffers message for possible retransmission
  3. RMS invokes receiveSoapRqst on RMD (with SequenceHdr and message body)
  4. RMD invokes deliver(message:string) primitive on RA

5.  RMD returns receiveSoapResp to RMS (with AckHdr and empty body)

6.  RMS frees message buffer for acknowledged RequestNumber(s)

Steps 3, 5 of Scenario B2 correspond to steps 3 and 6 of scenario B1. Figure B2 also shows the


Figure B1:Async AckTo (Callback)

[Note]

The middle Transport Connections model what is below soap. tci are just an instance names on the figure for a new instance of a transport connection.
The sending soap "processor" sends a soap request on a transport connection, and the receiving soap processor receives a soap request.
So you could consider it at the api level, but it could be considered as modeling the sending and receiving of a message. If there is a transport failure, the receive will never be issued. There is other sequence
diagrams showing a failure (see attached).
These figures can be the basis for creating the kind of http binding figures in ws-reliability. However at the level of abstraction that it is a transport, not specific to HTTP.
I also attach another example, which is base on the sequence diagram in the current WS-Reliable Messaging spec. This figure adds the transport connection to the sequence diagram in the spec, so the "x" to show not delivered message is replaced withmessage going into the transport, and never being delivered by the transport.

B.  Acknowledgements

The following individuals have contributed to the creation of this specification:

Masanori Yokoyama, Fujitsu Limited

Masahiko Narita, Fujitsu Limited

Masayoshi Shimamura, Fujitsu Limited

Jacques Durand, Fujitsu Software

C.  Non-Normative Text

D.  Revision History

Revision / Date / Editor / Changes Made
er] / te] / fied By] / hanges]

9 December 2005

Copyright © Fujitsu Limited 2005-2006. All Rights Reserved. Page 17 of 17