Here is an updated proposal which would update the specification and javadocs for the classic API (createSession
methods) but make no changes to the simplified API (createContext methods) on the grounds that these new methods do not
break backward compatibility and so don't need to be changed.
You can see a nicely-formatted version of this proposal at
https://java.net/jira/browse/JMS_SPEC-155?focusedCommentId=382430
The following javadoc changes already proposed would still be needed:
* Proposed changes for Connection.html#createSession(boolean, int):
* Proposed changes for Connection.html#createSession(int):
The following javadoc changes previously proposed would be dropped:
* Proposed changes for ConnectionFactory.html.createContext(String, String, int):
* Proposed changes for ConnectionFactory.html.createContext(int):
The changes originally proposed to the JMS specification section 12.3 "Behaviour of JMS sessions in the Java EE web or
EJB container" would be replaced by the following:
Existing text
-------------
12.3 "Behaviour of JMS sessions in the Java EE web or EJB container"
The behaviour of a JMS session in respect of transactions and message
acknowledgement is different for applications which run in a Java EE
web or EJB container than it is for applications which run in a normal
Java SE environment or in the Java EE application client container.
These differences also apply to JMSContext objects, since these
incorporate a JMS session.
When an application creates a Session or JMSContext in a Java EE web
or EJB container, and there is an active JTA transaction in progress,
then the session that is created will participate in the JTA
transaction and will be committed or rolled back when the JTA
transaction is committed or rolled back. Any session parameters that
are specified when creating the Session or JMSContext are ignored. The
use of local transactions or client acknowledgement is not permitted.
This applies irrespective of whether the JTA transaction is demarcated
automatically by the container or programmatically using methods on
javax.transaction.UserTransaction.
The term “session parameters” here refers to the arguments that may be
passed into a call to the createSession or createContext methods to
specify whether the session should use a local transaction and, if the
session is non-transacted, what the acknowledgement mode should be.
When an application creates a Session or JMSContext in a Java EE web
or EJB container, and there is no active JTA transaction in progress,
then the session that is created will be non-transacted and will be
automatically-acknowledged. The use of local transactions or client
acknowledgement is still not permitted. Parameters may be specified
when creating the Session or JMSContext to specify whether the
acknowledgement mode should be AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE. If any other session parameter values are
specified they will be ignored and an acknowledgement mode of
AUTO_ACKNOWLEDGE used.
The use of local transactions or client acknowledgement is not
permitted in a Java EE web or EJB container even if there is no active
JTA transaction because this would require applications to be written
differently depending on whether there was a JTA transaction or not.
The JMS API provides the following methods to create a session which
allow the session to be defined using either the two parameters
transacted and acknowledgeMode or by the single parameter sessionMode.
If these methods are called in a Java EE web or EJB container then
these parameters will be overridden as described above.
(4 methods)
It is recommended that applications that run in the Java EE web or EJB
container create a session using the following method which does not
specify a parameter:
(1 method)
The JMS API provides the following methods to create a JMSContext
which allow the session to be defined using the single parameter
sessionMode. If these methods are called in a Java EE web or EJB
container then this parameter will be overridden as described above.
(2 methods)
The following method to create a JMSContext from an existing
JMSContext is not permitted in a Java EE web or EJB container because
it would create a second session on an existing connection, which is
not permitted in a java EE web or EJB container.]
(1 method)
It is recommended that applications that run in the Java EE web or EJB
container creates a JMSContext using one of the following methods
which do not specify a sessionMode:
(2 methods)
Proposed text:
--------------
12.3 "Behaviour of JMS sessions in the Java EE web or EJB container"
The behaviour of JMS Session and JMSContext objects in respect of
transactions and message acknowledgement is different for applications
which run in a Java EE web or EJB container than it is for applications
which run in a normal Java SE environment or in the Java EE application
client container.
When an application creates a Session or JMSContext in a Java EE web
or EJB container, and there is an active JTA transaction in progress,
then the session that is created will participate in the JTA
transaction and will be committed or rolled back when the JTA
transaction is committed or rolled back. Any session parameters that
are specified when creating the Session or JMSContext are ignored. The
use of local transactions or client acknowledgement is not permitted.
This applies irrespective of whether the JTA transaction is demarcated
automatically by the container or programmatically using methods on
javax.transaction.UserTransaction.
The term “session parameters” here refers to the arguments that may be
passed into a call to the createSession or createContext methods to
specify whether the session should use a local transaction and, if the
session is non-transacted, what the acknowledgement mode should be.
When an application uses one of the createSession methods to create
a Session, and there is no active JTA transaction in progress,
then:
* If the session parameters specify that the session should be
non-transacted with an acknowledgement mode of AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages
will be acknowledged according to the specified acknowledgement mode.
* If the session parameters specify that the session should be
non-transacted with an acknowledgement mode of 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 the session parameters specify that the session should be transacted,
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 running in a Java EE web or EJB container are recommended to
specify no session parameters or to specify that the session be
non-transacted with an acknowledgement mode of AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE.
* It is not recommended that applications specify client acknowledgement
or a local transaction since applications may not be portable. Furthermore
if the JMS provider does support the use of client acknowledgement
and local transactions when there is no JTA transaction, the application
would need to be written differently dependent on whether there was a JTA
transaction or not.
When an application uses one of the createContext methods to create
a JMSContext, and there is no active JTA transaction in progress,
then:
* If the specified session mode is AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages
will be acknowledged according to the specified acknowledgement mode.
* If the specified session mode is CLIENT_ACKNOWLEDGE or SESSION_TRANSACTED
then it will be ignored and a session mode of AUTO_ACKNOWLEDGE used.
* Applications running in a Java EE web or EJB container are recommended to
specify no session parameters or to specify that the session be
non-transacted with an acknowledgement mode of AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE.
* The use of local transactions or client acknowledgement is not
permitted in a Java EE web or EJB container even if there is no active
JTA transaction because this would require applications to be written
differently depending on whether there was a JTA transaction or not.