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

Guys,

I think these are excellent write ups. 

Here's my 10 cents.

Several outstanding actions within our working group are playing in the
same ballpark: e.g. TextMessage versus BytesMessage, how to express a
Queue versus a Topic destination, how to specify properties that get
used for client JNDI environment setup, how to communicate arbitrary JMS
properties from the client to the SOAP/JMS Web Service.

Leading to the obvious questions....

What should go in JMS IRI ?

What should go in WSDL extensions ?

Should we have additional WSDL SOAP binding transport attributes for JMS
with TextMessage versus BytesMessage ?

What should be fixed by our specifications e.g. like BytesMessage is
currently ?

What if anything is "subject" to standard JMS transport-like
communication(analogy to HTTP transfer-encoding), and therefore
documented in our specification as this ? 

Along with Eric, of the three use cases for TextMessage, the possibility
to interoperate with an existing SOAP/JMS stack seemed to me the most
compelling. As Eric points there's much more to this that BytesMessage
versus TextMessage, Of note , JMS properties were mentioned. 

Here's my thoughts on this:

1. The JMS IRI is in danger of becoming very cumbersome, we should not
consider any further changes EXCEPT perhaps a "domain" attribute that
would be useful to ease programming to the "context" variant (e.g.
domain=QUEUE says I should be doing a Queue programming setup etc)

2. I think that defining a new JMS transport URI solves the Bytes versus
Text problem but that's all it does.

3. That leaves WSDL extensions as the approach which is what I am
suggesting. 

So by example:

<wsdl11:port="...">

<soapjms:messageType>TEXT</soapjms:messageType>
<soapjms:jndiProperty name="com.xyz.naming.traceOn" value="true"
type="string"/>
<soapjms:jndiProperty name="com.xyz.naming.traceFile"
value="traceTrades.trc" type="string"/>
<soapjms:jmsProperty name="XYZ_SOAPJMSAction" value="Sell"/>

<wsdl11soap11:address location="jms:context:SampleQ1?domain=QUEUE"/>
</wsdl11:port>


Peter



________________________________

From: public-soap-jms-request@w3.org
[mailto:public-soap-jms-request@w3.org] On Behalf Of Eric Johnson
Sent: Friday, September 19, 2008 1:03 PM
To: Phil Adams
Cc: public-soap-jms@w3.org
Subject: Re: ACTION-34: write up specific proposal on how to support
TextMessage


Hi Phil,

In general, it looks like a good thorough write up.

I'm still slightly puzzled by the use-case, and I think this helps
clarify it - which is certainly the point!

For a request/reply exchange, it seems like you've clearly identified a
messageType property that does this:

Client -->  (via TextMessage)  --> (received by) server ... which
generates a reply
Client <-- (via ????Message) <-- server sends reply

This is referenced in your update to section 2.6.2.3.

Here's what makes this particularly interesting - if I understand your
use case  - in practice, neither the client or the server particularly
cares whether the message sent is "TextMessage" - presumably, if they're
conforming to our (properly complete) specification, they can generate
and consume both TextMessage and BytesMessage.  The point is that
something in the middle between the two endpoints cares.  Does that
something in the middle care per input/output/fault message, per
operation, per portType/port, or the entire set of services provided by
a server?

Further, we've written off the notion of using attachments with
TextMessage, but it is clearly possible - although I cannot figure any
obvious alternative to simply doing a Base64 encoding of the attachment
- which implies a 33% increase in the size of the message.  However, if
it is fundamentally a "MUST" that the message be carried as a
TextMessage, why are we making an exception with respect to attachments?
Might customers want the choice of bigger payload versus the convenience
of auditing?

Some other comments below.

Phil Adams wrote: 


	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: 

	1.	The user's application needs to interface with a legacy
system or another Web services toolkit which might only support
TextMessage. 
	2.	The user needs to perform audit logging of SOAP request
and response messages.   A TextMessage would make this easier. 
	3.	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. 

I actually don't buy this last justification for a single moment.  The
payload is *XML*.  Surely customers are not doing routing by scanning a
text string and hoping to get that right without being aware of
surrounding XML context (CDATA sections, comments, etc.)?  Which means
that, if the customer is doing this correctly (and I don't think we
should be supporting them doing it incorrectly!), they still have to
send the data to an XML parser.  Once you're doing that, at least in
Java, the difference between sending a bytes payload and a text payload
is at most one line of additional code - maybe five if you count the
required if statement and lines with "else" and braces.

As to justification #2, this is somewhat suspect in my view.  What will
make auditing easier is a single standard for doing this, not the
introduction of TextMessage for the cases where attachments don't apply.
Having never looked at the auditing tools for messages, I don't know
whether my analysis is simplistic in practice.  Not knowing the details,
I'm certainly willing to go along with this one.

The first use-case is certainly quite compelling in principle.  In
practice, though, does it work?  If you're using the newly defined
standard SOAP/JMS binding for sending SOAP messages over JMS, how is
ever going to be compatible with an existing SOAP/JMS binding that
expects a specific set of headers in a specific place.  For us to enable
that would require defining some means to map the properties we've
defined to JMS Message Properties, so that they could be carried in the
appropriate headers for the pre-existing binding.  In short, just
throwing a "TextMessage" into the mix maybe solves 10% of the
compatibility question.  Isn't it, rather, for us the vendors to support
those old bindings?


	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
<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&d
eliveryMode=PERSISTENT&messageType=TEXT
		

My suggestion is that we make no changes to the URI scheme internet
draft.  We can instead follow the pattern of what we did for the
"service" parameter that is exposed by the SOAP/JMS binding, but is not
defined by the URI scheme.  That is, we leave the URI scheme to continue
to capture the details of getting a Destination.


	2.  The SOAP/JMS spec (located at:
http://www.w3.org/TR/2008/WD-soapjms-20080723/
<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.
		

This highlights the key question for me.  It seems to me like once you
want a TextMessage, you always want a text message - for all messages in
all operations for an entire portType.  Which means we might just as
well define an alternate "@transport" value specifically for carrying
TextMessage.

This differs from the other characteristics (priority, timeToLive,
deliveryMode), in that those properties may affect how the message is
routed, and quality of service, whereas using TextMessage shouldn't
fundamentally affect anything about the service - at least you've not
indicated that it should.


	*	
	*	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
<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.
		

Do we need/want this level of per-operation granularity? It appears here
that you're setting it on an operation - but the use cases above all
suggest that it matters really only at the level of an entire
portType/port.


	*	
		
	*	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... 
	

I may come across as being contrarian with regards to this proposal.  I
do see the value of supporting TextMessage, I'm just not clear on the
best way to support it.

-Eric.



	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