I have another proposed correction for the JMS 2.0 errata. This is logged as
https://java.net/jira/browse/JMS_SPEC-133
(Update javadoc comments for QueueConnection#createQueueSession and TopicConnection#createTopicSession)
The issue here is that although the javadoc for Connection#createSession was substantially updated for JMS 2.0, these
two methods were overlooked and were not changed.
I am therefore proposing that we simply replace the existing javadoc for QueueConnection#createQueueSession and
TopicConnection#createTopicSession with a copy of the javadoc for Connection#createSession, with some small adjustments
(e.g. to the return type) which I'm listing at the end of this email.
I think this should be an uncontroversial correction to a minor oversight in JMS 2.0. (So the busy can stop reading now).
Note that JMS_SPEC-155 and JMS_SPEC-157 propose to modify the javadoc for Connection#createSession. The proposals below
incorporate those amendments.
As always, for a nicely-formatted version see
https://java.net/jira/browse/JMS_SPEC-133
javadoc for QueueConnection#createQueueSession
----------------------------------------------
Existing text:
QueueSession createQueueSession(
boolean transacted,int acknowledgeMode) throws JMSException
Creates a QueueSession object.
Parameters:
transacted - indicates whether the session is transacted
acknowledgeMode - indicates whether the consumer or the client will
acknowledge any messages it receives; ignored if the session is
transacted. Legal values are Session.AUTO_ACKNOWLEDGE,
Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.
Returns:
a newly created queue session
Throws:
JMSException - if the QueueConnection object fails to create a session
due to some internal error or lack of support for the specific transaction
and acknowledgement mode.
See Also:
Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE
Replacement text:
Session createQueueSession(
boolean transacted, int acknowledgeMode) throws JMSException
Creates a QueueSession object, specifying transacted and acknowledgeMode.
The effect of setting the transacted and acknowledgeMode arguments depends
on whether this method is called in a Java SE environment, in the Java EE
application client container, or in the Java EE web or EJB container. If
this method is called in the Java EE web or EJB container then the effect of
setting the transacted and acknowledgeMode arguments also depends on
whether or not there is an active JTA transaction in progress.
In a Java SE environment or in the Java EE application client container:
* If transacted is set to true then the session will use a local transaction
which may subsequently be committed or rolled back by calling the
session's commit or rollback methods. The argument acknowledgeMode is
ignored.
* If transacted is set to false then the session will be non-transacted.
In this case the argument acknowledgeMode is used to specify how messages
received by this session will be acknowledged. The permitted values are
Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these
acknowledgement modes see the links below.
In a Java EE web or EJB container, when there is an active JTA transaction in
progress:
* Both arguments transacted and acknowledgeMode are ignored. The session will
participate in the JTA transaction and will be committed or rolled back when
that transaction is committed or rolled back, not by calling the session's
commit or rollback methods. Since both arguments are ignored, developers are
recommended to use createSession(), which has no arguments, instead of this
method.
In the Java EE web or EJB container, when there is no active JTA transaction
in progress:
* If transacted is set to false and acknowledgeMode is set to
JMSContext.AUTO_ACKNOWLEDGE or JMSContext.DUPS_OK_ACKNOWLEDGE then the
session will be non-transacted and messages will be acknowledged according
to the value of sessionMode.
* If transacted is set to false and acknowledgeMode is set to
JMSContext.CLIENT_ACKNOWLEDGE then the JMS provider is recommended to
ignore the specified parameters and instead provide a non-transacted,
auto-acknowledged session. However the JMS provider may alternatively
provide a non-transacted session with client acknowledgement.
* If transacted is set to true, then the JMS provider is recommended to
ignore the specified parameters and instead provide a non-transacted,
auto-acknowledged session. However the JMS provider may alternatively
provide a local transacted session.
* Applications are recommended to set transacted to false and
acknowledgeMode to JMSContext.AUTO_ACKNOWLEDGE or
JMSContext.DUPS_OK_ACKNOWLEDGE since since applications which set
transacted to false and set acknowledgeMode to
JMSContext.CLIENT_ACKNOWLEDGE, or which set transacted to true, may not be
portable.
Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If
this method is called in a Java EE web or EJB container when an active Session
object already exists for this connection then a JMSException may be thrown.
Parameters:
transacted - indicates whether the session will use a local transaction,
except in the cases described above when this value is ignored.
acknowledgeMode - when transacted is false, indicates how messages received
by the session will be acknowledged, except in the cases described above
when this value is ignored.
Returns:
a newly created QueueSession
Throws:
JMSException - if the Connection object fails to create a QueueSession
due to
* some internal error,
* lack of support for the specific transaction and acknowledgement mode, or
* because this method is being called in a Java EE web or EJB application
and an active session already exists for this connection.
Since:
JMS 1.1
See Also:
Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE,
Session.DUPS_OK_ACKNOWLEDGE
javadoc for TopicConnection#createTopicSession
----------------------------------------------
Existing text:
TopicSession createTopicSession(
boolean transacted, int acknowledgeMode) throws JMSException
Creates a TopicSession object.
Parameters:
transacted - indicates whether the session is transacted
acknowledgeMode - indicates whether the consumer or the client will
acknowledge any messages it receives; ignored if the session is
transacted. Legal values are Session.AUTO_ACKNOWLEDGE,
Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.
Returns:
a newly created topic session
Throws:
JMSException - if the TopicConnection object fails to create a session
due to some internal error or lack of support for the specific transaction
and acknowledgement mode.
See Also:
Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE
Replacement text:
Session createTopicSession(
boolean transacted, int acknowledgeMode) throws JMSException
Creates a TopicSession object, specifying transacted and acknowledgeMode.
The effect of setting the transacted and acknowledgeMode arguments depends
on whether this method is called in a Java SE environment, in the Java EE
application client container, or in the Java EE web or EJB container. If
this method is called in the Java EE web or EJB container then the effect of
setting the transacted and acknowledgeMode arguments also depends on
whether or not there is an active JTA transaction in progress.
In a Java SE environment or in the Java EE application client container:
* If transacted is set to true then the session will use a local transaction
which may subsequently be committed or rolled back by calling the
session's commit or rollback methods. The argument acknowledgeMode is
ignored.
* If transacted is set to false then the session will be non-transacted.
In this case the argument acknowledgeMode is used to specify how messages
received by this session will be acknowledged. The permitted values are
Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these
acknowledgement modes see the links below.
In a Java EE web or EJB container, when there is an active JTA transaction in
progress:
* Both arguments transacted and acknowledgeMode are ignored. The session will
participate in the JTA transaction and will be committed or rolled back when
that transaction is committed or rolled back, not by calling the session's
commit or rollback methods. Since both arguments are ignored, developers are
recommended to use createSession(), which has no arguments, instead of this
method.
In the Java EE web or EJB container, when there is no active JTA transaction
in progress:
* If transacted is set to false and acknowledgeMode is set to
JMSContext.AUTO_ACKNOWLEDGE or JMSContext.DUPS_OK_ACKNOWLEDGE then the
session will be non-transacted and messages will be acknowledged according
to the value of sessionMode.
* If transacted is set to false and acknowledgeMode is set to
JMSContext.CLIENT_ACKNOWLEDGE then the JMS provider is recommended to
ignore the specified parameters and instead provide a non-transacted,
auto-acknowledged session. However the JMS provider may alternatively
provide a non-transacted session with client acknowledgement.
* If transacted is set to true, then the JMS provider is recommended to
ignore the specified parameters and instead provide a non-transacted,
auto-acknowledged session. However the JMS provider may alternatively
provide a local transacted session.
* Applications are recommended to set transacted to false and
acknowledgeMode to JMSContext.AUTO_ACKNOWLEDGE or
JMSContext.DUPS_OK_ACKNOWLEDGE since since applications which set
transacted to false and set acknowledgeMode to
JMSContext.CLIENT_ACKNOWLEDGE, or which set transacted to true, may not be
portable.
Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If
this method is called in a Java EE web or EJB container when an active Session
object already exists for this connection then a JMSException may be thrown.
Parameters:
transacted - indicates whether the session will use a local transaction,
except in the cases described above when this value is ignored.
acknowledgeMode - when transacted is false, indicates how messages received
by the session will be acknowledged, except in the cases described above
when this value is ignored.
Returns:
a newly created TopicSession
Throws:
JMSException - if the Connection object fails to create a TopicSession
due to
* some internal error,
* lack of support for the specific transaction and acknowledgement mode, or
* because this method is being called in a Java EE web or EJB application
and an active session already exists for this connection.
Since:
JMS 1.1
See Also:
Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE,
Session.DUPS_OK_ACKNOWLEDGE
Notes
-----
How does this replacement text compare with the text for Connection#createSession?
* replaced "Session" with "QueueSession" or "TopicSession" as appropriate.
* references to "session" not changed unless explicitly referring to the return type, in which case QueueSession or
TopicSession used instead.
* omitted the paragraph starting "This method has been superseded by the method createSession(int sessionMode)..." since
there is no corresponding createQueueSession/createTopicSession method
* omitted the sentence starting with "Since both arguments are ignored, developers are recommended to use
createSession()...", for the same reason.
* omitted the "see also" to createSession(int), createSession() for the same reason.