ACTION-34: write up specific proposal on how to support TextMessage

Hi everyone,
During our 9/16 call, I took an action item to write up a specific 
proposal regarding TextMessages that we can hopefully make a decision on 
fairly soon.


Background:
Customer feedback that I've received has indicated that the use of a 
TextMessage as an alternative to a BytesMessage would be useful in 
situations where:
The user's application needs to interface with a legacy system or another 
Web services toolkit which might only support TextMessage.
The user needs to perform audit logging of SOAP request and response 
messages.   A TextMessage would make this easier.
Using a TextMessage would make it easier for an intermediary to process a 
message for routing or other purposes, where the processing needs to look 
at the message content.
These are the main justifications that I've heard from customers.   There 
might be other reasons that some of you know about.

Proposal:
My proposal for introducing TextMessage support to the SOAP/JMS spec would 
include the following:

1.  The JMS URI spec (located at: 
http://www.ietf.org/internet-drafts/draft-merrick-jms-uri-03.txt) would be 
updated as follows:

Introduce support for a new "shared parameter" called "messageType". 
Section 4.1.5 would be added to document this as follows:

4.1.5   messageType
This property specifies the JMS message type that should be used for the 
request message.   The valid values for this property are "TEXT" and 
"BYTES".  If this property is specified as "TEXT", then a JMS TextMessage 
MUST be used.   If a value of "BYTES" is specified, then a JMS 
BytesMessage MUST be used.    If this parameter is not specified, then a 
value of "BYTES" SHOULD be used.

"messageType" should be added to the list of parameters in section 8.2.1.  
 The "messageType" parameter should also be removed from the request URI 
that is set on the request message.

Here's an example of the messageType parameter within a JMS URI:
jms:jndi:jms/MyQueue&jndiConnectionFactoryName=jms/MyCF&timeToLive=300&deliveryMode=PERSISTENT&messageType=TEXT


2.  The SOAP/JMS spec (located at: 
http://www.w3.org/TR/2008/WD-soapjms-20080723/) would be updated as 
follows:
In section 2.2.2 (JMS Message Header properties) we would add a section 
which describes the "messageType" property:

[Definition: soapjms:messageType] (xsd:string)
  - indicates the JMS message type for the request.   The valid values are 
"TEXT" and "BYTES".  The default value is "BYTES".
  - optional in URI, optional in WSDL, optional in environment
  - if specified as "TEXT", then the message sending node MUST use a JMS 
TextMessage for the request if there 
    are no attachments.   If there are attachments, then a fault is 
generated. [Definition: use fault subcode invalidMessageType]
  - if specified as "BYTES" or not specified at all, then the message 
sending node MUST use a JMS BytesMessage for the request.

Issue: It's possible to argue that "messageType" is not exactly in the 
same category as the other "JMS Message Header properties" as it dictates 
the type of the JMS message, rather than the value of a JMS Message 
Header, so perhaps this property doesn't belong in section 2.2.2 but 
belongs in a new section of its own.    I think it's ok in section 2.2.2 
but I certainly can understand if others don't agree with that.

In section 2.2.4 (Binding of Properties to URI), the following row should 
be added to the table:

"messageType", "as messageType query parameter", "Should exclude"

In section 2.4 (The JMS Message Body), we should reword the first sentence 
to indicate that the message should be a TextMessage if messageType=TEXT 
is specified, and a BytesMessage otherwise.      Also, at the end of 
section 2.4, we should perhaps add an explanation that if the user 
requests a TextMessage and attachments exist, then the message sending 
node MUST generate a fault with subcode invalidMessageType.   This would 
be redundant with section 2.2.2 (above), so perhaps we can omit it here?

In section 2.6.1.1 (Init), we should change the second sentence so that it 
specifies that a TextMessage MUST be used if messageType=TEXT is 
specified, and a BytesMessage MUST be used if messageType=BYTES is 
specified.      In addition, a row should be added to the table to account 
for the fact that the messageType property specifies the JMS message type.

In section 2.6.2.3 (Receiving + Sending), we should re-word the third 
sentence as follows:

If the request message is a JMS TextMessage and no attachments exist in 
the response, then the response MUST be created as a JMS TextMessage, 
otherwise the response MUST be created as a JMS BytesMessage.

Issue: There might be some debate over the handling of this situation. My 
opinion is that the message receiving node should try to respond in kind 
if at all possible, but should use a BytesMessage if attachments exist.  
My thought is that we should not generate a fault in this case, but should 
do our best to get the response back to the requester, although I can see 
both sides of this issue.

In section 2.6.2.3 (Receiving + Sending), we should add a row to the table 
to account for the JMS message type and explain that it is derived from 
the request message type.

In section 2.7.1 (Behaviour of Sending SOAP Node), the first sentence of 
the second paragraph should be re-worded to account for TextMessage as 
well as BytesMessage, similar to section 2.6.1.1 above.     In addition, 
we should add a row to the table to account for the JMS message type.

In section 2.8 (Faults), we should add "invalidMessageType" to the list of 
fault subcodes.

In section 3.4.1 (Example), we might consider adding an example of the 
"messageType" property to the existing WSDL 1.1 example, perhaps like 
this:

24       <wsdl11:operation name="GetLastTradePrice">
25         <wsdl11soap11:operation soapAction="
http://example.com/GetLastTradePrice"/>
26         <wsdl11:input>
27             <wsdl11soap11:body use="literal"/>
28         </wsdl11:input>
29         <wsdl11:output>
30             <wsdl11soap11:body use="literal"/>
31         </wsdl11:output>
>>>>>>     <soapjms:messageType>TEXT</soapjms:messageType> 
32       </wsdl11:operation>

This would indicate that a TextMessage should be used when the client 
invokes the "GetLastTracePrice" operation.

In section 3.6 (Properties), we should add a row to the table:

"messageType", "service, port/endpoint, binding"

I identified a couple of issues above, but there's one more that was 
discussed on our calls and I'm not sure there was a resolution to it.  It 
has to do with the encoding of the JMS message vs the encoding of the SOAP 
envelope within the JMS message.    We will need to discuss and resolve 
this...

Regards,

Phil Adams 
WebSphere Development - Web Services
IBM Austin, TX
email: phil_adams@us.ibm.com
office: (512) 838-6702  (tie-line 678-6702)
mobile: (512) 750-6599