ISSUE 18 - Clarify the rules on which queues and topics are used forresponses and callbacks

[Simon Holdsworth <simon_holdsworth@uk.ibm.com>]

Folks,

Updated proposal for resolution to issue
18:

Replace section 7 "Callback and
Conversation Protocol" with the following text.

I've included the section on conversations
as it needed to be rewritten for the conformance statements, and is also
affected by the updates to the preceeding sections.

I'd appreciate any comments on this
in advance of the call on Thursday.

----------------------------------------------------------------

7 Message Exchange Patterns

This section describes the message exchange
patterns that are possible when using the JMS binding, including one-way,
request/response, callbacks and conversations.  JMS has a looser concept
of message exchange patterns than WSDL, so this section explains how JMS
messages that are sent and received by the SCA runtime relate to the WSDL
input/output messages.  Each operation in a WSDL interface is either
one-way or request/response.  Callback interfaces may include both
one-way and request/response operations.

7.1 One-way message exchange (non-bidirectional)

A one-way message exchange is one where
a request message is sent that does not require or expect a corresponding
response message. These are represented in WSDL as an operation with an
input element and no output or fault elements. 

When a request message is sent by a
reference with a JMS binding for a one-way MEP, the SCA runtime SHOULD
NOT set the JMSReplyTo destination header in the JMS message that it creates,
regardless of whether the JMS binding has a response element with a destination
defined.

When a request message is received by
a reference with a JMS binding for a one-way MEP, the SCA runtime SHOULD
ignore the JMSReplyTo destination header in the JMS message.

The use of one-way exchanges when using
a bidirectional interface is described below.

7.2 Request/response message exchange
(non-bidirectional)

A request/response message exchange
is one where a request message is sent and a response message is expected,
possibly identified by its correlation identifier.  These are represented
in WSDL as an operation with an input element and an output and/or fault
element.  

When a request message is sent by a
reference with a JMS binding for a request/response MEP, the SCA runtime
MUST set a non-null value for the JMSReplyTo header in the JMS message
it creates for the request.  If the JMS binding has a response element
with a destination defined, then the SCA runtime MUST use that destination
for the JMSReplyTo value, otherwise the SCA runtime MUST provide an appropriate
destination on which to receive response messages. Response messages MAY
be received by
the SCA runtime on the basis of its correlation identifier as defined by
the correlationScheme attribute.

When a response message is sent by a
service with a JMS binding for a request/response MEP, the SCA runtime
MUST send the response message to the JMS destination identified by the
request message's JMSReplyTo destination if not null, otherwise the SCA
runtime MUST send the response message to the destination identified by
the JMS binding's response element if specified.  If there is no destination
defined by either means then an error SHOULD be recorded by the SCA runtime.
 The SCA runtime MUST set the correlation identifier in the JMS message
that it creates for the response as defined by the JMS binding's correlationScheme
attribute.

The use of request/response exchanges
when using a bidirectional interface is described below.

7.3 JMS User Properties  [as per
existing section 7.1]

7.4 Callbacks

A callback is the invocation of an operation
on a service's callback interface.  A callback operation can be one-way
or request/response.  Messages that correspond to one-way or request/response
operations on a bidirectional interface use either the scaCallbackQueue
user property or JMSReplyTo destination, or both, to identify the destination
to which messages are to be sent when operations are invoked on the callback
interface.  The use of JMSReplyTo for this purpose is to enable interaction
with non-SCA JMS applications, as described below.

7.4.1 Invocation of operations on a
bidirectional interface

When a request message is sent by a
reference with a JMS binding for a one-way MEP with a bidirectional interface,
the SCA runtime MUST set the destination to which callback messages are
to be sent as the value of the scaCallbackQueue user property in the message
it creates.  The SCA runtime MAY also set the JMSReplyTo destination
to this value.

When a request message is sent by a
reference with a JMS binding for a request/response MEP with a bidirectional
interface, the SCA runtime MUST set the destination to which callback messages
are to be sent as the value the scaCallbackQueue user property in the message
it creates. The SCA runtime MUST set the JMSReplyTo destination as for
a non-bidirectional interface as stated in section 7.2.

For both one-way and request/response
operations, if the reference has a callback service element with a JMS
binding with a request destination, then the SCA runtime MUST use that
destination as the one to which callback messages are to be sent, otherwise
the SCA runtime MUST provide an appropriate destination for this purpose.

7.4.2 Invocation of operations on a
callback interface

An SCA service with a callback interface
can invoke operations on that callback interface at any time after receiving
a message that contains a value for the scaCallbackQueue user property,
a one-way message with the JMSReplyTo destination set to a non-null value,
or at any time if the service's callback reference has a JMS binding with
a request destination element.

When a callback request message is sent
by a service with a JMS binding for either a one-way or request/response
MEP, the SCA runtime MUST send the callback request message to the JMS
destination identified as follows, in order of priority:

• The scaCallbackQueue identified by an earlier request, if not null
• The JMSReplyTo destination identified by an earlier one-way request, if not null,
• The request destination of the services' callback reference JMS binding, if specified.
  

If no destination is identified
then the SCA runtime SHOULD record an error, and MUST throw an exception
to the caller of the callback operation.

The SCA runtime MUST set the JMSReplyTo
destination and correlation identifier in the callback request message
as defined in sections 7.1 or 7.2 as appropriate for the operation invoked.

7.4.3 Use of JMSReplyTo for callbacks
for non-SCA JMS applications

When interacting with non-SCA JMS applications,
the assembler can choose to model a request/response message exchange using
a bidirectional interface.  In this case it is likely that the non-SCA
JMS application does not support the use of the scaCallbackQueue user property.
 

For a service with a JMS binding, the
SCA runtime MAY use the JMSReplyTo destination in messages that it receives
to identify the destination to be used to deliver callback messages in
the event that the scaCallbackQueue user property is not set.  

For a reference with a JMS binding,
the SCA runtime MAY set the JMSReplyTo destination in messages that it
creates to identify the destination to which callback messages are to be
sent.

7.5 Conversations

A conversation is a sequence of operations
between two parties that have a common context.  The conversation
may include a mixture of operations in either direction between the two
parties. Interfaces are marked as conversational in order to ensure that
the runtime manages the lifecycle of this context. Component implementation
specifications define the manner in which the context that is associated
with the conversation identifier is made available to component implementations.

7.5.1 Starting a conversation

A conversation is started when an operation
is invoked on a conversational interface and there is no active conversation
with the target of the invocation. When this happens the SCA runtime MUST
supply an identifier for the conversation, set the scaConversationStart
user property to this value in the JMS message that it sends for the request,
and associate a new runtime context with this conversation identifier.

When a message is received that contains
a value for the scaConversationStart user property, the SCA runtime MUST
associate a new runtime context with the given conversation identifier.

The SCA runtime MAY include in the message
that starts the conversation the scaConversationMaxIdleTime user property;
if this value is not present the SCA runtime MUST derive the the maximum
idle time for the conversation by subtracting the current time from the
value of the JMSExpiration property, unless the JMSExpiration property
value is zero, in which case the maximum idle time is unlimited.

[The following paragraph is not specific
to the JMS binding and may be removed or moved to the assembly specification
if not already stated there]

The SCA runtime MUST consider operations
invoked on other parties to be outside of a conversation with a given party,
and MUST use different conversation identifiers if those operations are
conversational.

7.5.2 Continuing a conversation

When creating messages for subsequent
operations between the sender and receiver that are part of this conversation,
the SCA runtime MUST include the scaConversationId user property in the
JMS message, set to the conversation identifier. The SCA runtime MAY may
also include an updated value of the scaConversationMaxIdleTime property.
 The value of the scaCallbackQueue destination MUST be ignored by
the SCA Runtime within a conversation in messages after the one that starts
the conversation.

The SCA runtime MUST consider messages
received containing a conversation identifier that does not correspond
to a started conversation, or containing an scaConversationStart property
with a conversation identifier that matches an active conversation as an
error, and MUST not deliver such messages.

7.5.3 Ending a conversation

When an operation is invoked by either
party that is marked as “endsConversation”, or the maximum idle time
is exceeded, then the SCA runtime MUST discard the conversation identifier
and associated context after the operation has been processed.  The
idle time is defined as the amount of time since the SCA runtime last completed
processing of an operation that is part of the conversation. There may
be times whenone party ends the conversation before the other does.  In
that case if one party does invoke an operation on the other, the SCA runtime
MUST NOT deliver the message and SHOULD report an error.

[The following paragraph is not specific
to the JMS binding and may be removed or moved to the assembly specification
if not already stated there]

The SCA runtime MAY reuse conversation
identifiers.  In particular, the SCA runtime does not have to guarantee
unique conversation identifiers and does not have to be able to identify
an ended conversation indefinitely, although it may do for some period
after the conversation ends. Due to the long-running nature of conversations,
the SCA runtime SHOULD ensure conversation context is available across
server restarts, although it MAY choose to treat a server restart as implicitly
ending the conversation.

----------------------------------------------------------------

Simon Holdsworth
STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair
MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
Internet - Simon_Holdsworth@uk.ibm.com

---

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU