looks fine... thanks a lot!
On Thu, Feb 14, 2013 at 8:47 AM, Nigel Deakin <nigel.deakin_at_oracle.com>wrote:
> 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/XAQueueConnection.html#createQueueSession%28boolean,%20int%29>
> http://jms-spec.java.net/2.0-**SNAPSHOT/apidocs/javax/jms/**
> XATopicConnection.html#**createTopicSession%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)<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)<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<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<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
>>
>
--
Clebert Suconic
http://community.jboss.org/people/clebert.suconic@jboss.com
http://clebertsuconic.blogspot.com