I've now updated the API docs at
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/XAQueueConnection.html#createQueueSession%28boolean,%20int%29
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/XATopicConnection.html#createTopicSession%28boolean,%20int%29
Clebert: can you quickly proofread this?
Thanks,
Nigel
On 14/02/2013 14:21, Nigel Deakin wrote:
> Clebert,
>
> On 12/02/2013 21:54, Clebert Suconic wrote:
>> Hey I have a quick question.. this seems an inconsistency:
>> on XAConnection, a createSession is supposed to return a Connection
>>
>> http://docs.oracle.com/javaee/6/api/javax/jms/XAConnection.html#createSession(boolean,%20int)
>>
>> While on a QueueConnection a createSession is supposed to return a XAConnection
>> http://docs.oracle.com/javaee/1.3/api/javax/jms/XAQueueConnection.html#createQueueSession(boolean,%20int)
>>
>> Is that a typo on the spec? from what I have seen around users are expecting the super class to be respected an not have
>> the semantic changing by just getting an XAConnection or XQueueConnection.
>>
>> We are doing a new release of HornetQ and I was reviewing our implementation when I bumped into this. that seems a
>> typo to me.
>
> Good question. The problem methods are on XAQueueConnection
>
> /** Creates an {_at_code XAQueueSession} object.
> *
> * @param transacted usage undefined
> * @param acknowledgeMode usage undefined
> *
> * @return a newly created {_at_code XAQueueSession}
> *
> * @exception JMSException if the {_at_code XAQueueConnection} object
> * fails to create an XA queue session due to some
> * internal error.
> */
> QueueSession
> createQueueSession(boolean transacted,
> int acknowledgeMode) throws JMSException;
>
> and on XATopicConnection
>
> /** Creates an {_at_code XATopicSession} object.
> *
> * @param transacted usage undefined
> * @param acknowledgeMode usage undefined
> *
> * @return a newly created XA topic session
> *
> * @exception JMSException if the {_at_code XATopicConnection} object
> * fails to create an XA topic session due to some
> * internal error.
> */
>
> TopicSession
> createTopicSession(boolean transacted,
> int acknowledgeMode) throws JMSException;
>
>
> I agree that this looks like a typo, especially since they are inconsistent with the API docs for XAConnection . If the
> method signature returns a QueueSession (or TopicSession) that it makes no sense at all for the javadoc comment to say
> that it creates a XAQueueSession (or XATopicSession), especially when there are alternative methods to return a
> XAQueueSession (or XATopicSession).
>
> I've logged this as
> http://java.net/jira/browse/JMS_SPEC-114
>
> I think we can correct this for JMS 2.0
>
> That said, the spec doesn't explain why two separate methods are provided here.
>
> Neither method is intended for direct application use: the javadoc comment for XAConnection states that it is "for use
> by JMS providers to support transactional environments. Client programs are strongly encouraged to use the transactional
> support available in their environment, rather than use these XA interfaces directly."
>
> We still have http://java.net/jira/browse/JMS_SPEC-26 open to discuss the future of these interfaces (and perhaps
> clarify how they are supposed to be used), which we will revisit for JMS 2.1.
>
> Any other views?
>
> Nigel