On 04/12/2014 12:30, Nigel Deakin wrote:
> Here's the next proposed correction for the JMS 2.0 errata release.
> https://java.net/jira/browse/JMS_SPEC-155
> (JMS 2.0 introduced an incompatible restriction on creating two sessions per connection in Java EE)
>
> This is quite a significant correction, so I'll explain the issue in some detail and then give a high-level summary of
> how I propose to correct its. You can read a more nicely-formatted version in the JIRA issue.
>
> I'll follow this up with a second email containing a line-by-line list of spec and javadoc changes.
Here's that line-by-line list of proposed spec and javadoc changes. Again, you can read a more nicely-formatted version
in the JIRA issue.
JMS specification section 12.3 "Behaviour of JMS sessions in the Java EE web or EJB container"
----------------------------------------------------------------------------------------------
Existing text:
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]
Replacement text:
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:
* 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.
Javadocs for Connection.html#createSession(boolean, int):
---------------------------------------------------------
Existing text:
In the Java EE web or EJB container, when there is no active JTA
transaction in progress:
* The argument transacted is ignored. The session will always be
non-transacted, using one of the two acknowledgement modes
AUTO_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE.
* The argument acknowledgeMode is used to specify how messages
received by this session will be acknowledged. The only permitted
values in this case are Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE. The value Session.CLIENT_ACKNOWLEDGE
may not be used. For a definition of the meaning of these
acknowledgement modes see the links below.
Replacement text:
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.
Existing text:
Parameters:
transacted - indicates whether the session will use a local transaction.
If this method is called in the Java EE web or EJB container then this
argument is ignored.
acknowledgeMode - indicates how messages received by the session will be
acknowledged.
* If this method is called in a Java SE environment or in the Java EE
application client container, the permitted values are
Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and
Session.DUPS_OK_ACKNOWLEDGE.
* If this method is called in the Java EE web or EJB container when
there is an active JTA transaction in progress then this argument is
ignored.
* If this method is called in the Java EE web or EJB container when
there is no active JTA transaction in progress, the permitted values
are Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. In this
case Session.CLIENT_ACKNOWLEDGE is not permitted.
Replacement text:
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.
Javadocs for Connection.html#createSession(int):
------------------------------------------------
Existing text:
In the Java EE web or EJB container, when there is no active JTA
transaction in progress:
* The argument acknowledgeMode must be set to either of
Session.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE. The session will
be non-transacted and messages received by this session will be
acknowledged automatically according to the value of acknowledgeMode. For
a definition of the meaning of these acknowledgement modes see the links
below. The values Session.SESSION_TRANSACTED and Session.CLIENT_ACKNOWLEDGE
may not be used.
Replacement text:
In the Java EE web or EJB container, when there is no active JTA
transaction in progress:
* If sessionMode 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 sessionMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS
provider is recommended to ignore the specified parameter and instead
provide a non-transacted, auto-acknowledged session. However the JMS
provider may alternatively provide a non-transacted session with
client acknowledgement.
* If sessionMode is set to JMSContext.SESSION_TRANSACTED, then the JMS
provider is recommended to ignore the specified parameter and instead
provide a non-transacted, auto-acknowledged session. However the JMS
provider may alternatively provide a local transacted session.
* Applications are recommended to use only the values
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE
since applications which use JMSContext.CLIENT_ACKNOWLEDGE or
JMSContext.SESSION_TRANSACTED may not be portable.
Existing text:
Parameters:
sessionMode - indicates which of four possible session modes will be used.
* If this method is called in a Java SE environment or in the Java EE
application client container, the permitted values are
Session.SESSION_TRANSACTED, Session.CLIENT_ACKNOWLEDGE,
Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE.
* If this method is called in the Java EE web or EJB container when there
is an active JTA transaction in progress then this argument is ignored.
* If this method is called in the Java EE web or EJB container when there
is no active JTA transaction in progress, the permitted values are
Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. In this case
the values Session.TRANSACTED and Session.CLIENT_ACKNOWLEDGE are not permitted.
Replacement text:
sessionMode - specifies the session mode that will be used, except in the
cases described above when this value is ignored. Legal values are
JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.
Javadocs for ConnectionFactory.html.createContext(int):
-------------------------------------------------------
Existing text:
In the Java EE web or EJB container, when there is no active JTA
transaction in progress:
* The argument acknowledgeMode must be set to either of
JMSContext.AUTO_ACKNOWLEDGE or JMSContext.DUPS_OK_ACKNOWLEDGE. The
session will be non-transacted and messages received by this session
will be acknowledged automatically according to the value of
acknowledgeMode. For a definition of the meaning of these
acknowledgement modes see the links below. The values
JMSContext.SESSION_TRANSACTED and JMSContext.CLIENT_ACKNOWLEDGE may
not be used.
Replacement text:
In the Java EE web or EJB container, when there is no active JTA
transaction in progress:
* If sessionMode 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 sessionMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS
provider is recommended to ignore the specified parameter and instead
provide a non-transacted, auto-acknowledged session. However the JMS
provider may alternatively provide a non-transacted session with
client acknowledgement.
* If sessionMode is set to JMSContext.SESSION_TRANSACTED, then the JMS
provider is recommended to ignore the specified parameter and instead
provide a non-transacted, auto-acknowledged session. However the JMS
provider may alternatively provide a local transacted session.
* Applications are recommended to use only the values
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE
since applications which use JMSContext.CLIENT_ACKNOWLEDGE or
JMSContext.SESSION_TRANSACTED may not be portable.
Existing text:
Parameters:
sessionMode - indicates which of four possible session modes will be used.
* If this method is called in a Java SE environment or in the Java EE
application client container, the permitted values are
JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.
* If this method is called in the Java EE web or EJB container when there
is an active JTA transaction in progress then this argument is ignored.
* If this method is called in the Java EE web or EJB container when there
is no active JTA transaction in progress, the permitted values are
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE. In this case
the values JMSContext.TRANSACTED and JMSContext.CLIENT_ACKNOWLEDGE are not
permitted.
Replacement text:
Parameters:
sessionMode - specifies the session mode that will be used, except in the
cases described above when this value is ignored. Legal values are
JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.
Javadocs for ConnectionFactory.html.createContext(String, String, int):
-----------------------------------------------------------------------
Existing text:
In the Java EE web or EJB container, when there is no active JTA
transaction in progress:
* The argument acknowledgeMode must be set to either of
JMSContext.AUTO_ACKNOWLEDGE or JMSContext.DUPS_OK_ACKNOWLEDGE. The session
will be non-transacted and messages received by this session will be
acknowledged automatically according to the value of acknowledgeMode.
For a definition of the meaning of these acknowledgement modes see the
links below. The values JMSContext.SESSION_TRANSACTED and
JMSContext.CLIENT_ACKNOWLEDGE may not be used.
Replacement text:
In the Java EE web or EJB container, when there is no active JTA
transaction in progress:
* If sessionMode 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 sessionMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS
provider is recommended to ignore the specified parameter and instead
provide a non-transacted, auto-acknowledged session. However the JMS
provider may alternatively provide a non-transacted session with
client acknowledgement.
* If sessionMode is set to JMSContext.SESSION_TRANSACTED, then the JMS
provider is recommended to ignore the specified parameter and instead
provide a non-transacted, auto-acknowledged session. However the JMS
provider may alternatively provide a local transacted session.
* Applications are recommended to use only the values
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE
since applications which use JMSContext.CLIENT_ACKNOWLEDGE or
JMSContext.SESSION_TRANSACTED may not be portable.
Existing text:
Parameters:
userName - the caller's user name
password - the caller's password
sessionMode - indicates which of four possible session modes will be used.
* If this method is called in a Java SE environment or in the Java EE
application client container, the permitted values are
JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.
* If this method is called in the Java EE web or EJB container when there
is an active JTA transaction in progress then this argument is ignored.
* If this method is called in the Java EE web or EJB container when there
is no active JTA transaction in progress, the permitted values are
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE. In this
case the values JMSContext.TRANSACTED and JMSContext.CLIENT_ACKNOWLEDGE
are not permitted.
Replacement text:
Parameters:
userName - the caller's user name
password - the caller's password
sessionMode - specifies the session mode that will be used, except in the
cases described above when this value is ignored. Legal values are
JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.
Nigel