I refer to
http://java.net/jira/browse/JMS_SPEC-45
I've now updated the API, javadocs and the draft spec in accordance with the proposals made in the above JIRA issue.
The updated Javadocs are here:
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar
* New methods Connection.createSession(int sessionMode) and Connection.createSession() which create a Session.
* New javadoc comment for the existing method Connection.createSession(boolean transacted, int acknowledgeMode) which
creates a Session. This is not deprecated but a comment encourages users to use the other two methods instead.
* New javadoc comments for the various methods on ConnectionFactory and MessagingContext which create a MessagingContext
The updated draft spec is here:
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf
* Updated section 1.4.7 "Java Platform, Enterprise Edition (Java EE)"
* Deleted section 1.4.8 "Integration of JMS with the EJB Components"
* New chapter 12 "Use of JMS API in Java EE applications"
* New section 12.2 "Use of JMS API in Java EE applications"
* New sections 11.5.14 & 11.5.15 which are the change log for these changes
To give you a quick idea of what I have written, I've pasted below the updated javadoc for the existing createSession
method on Connection. (The javadoc for the new methods Connection.createSession(int sessionMode) and
Connection.createSession() ate similar to this). Remember the full javadocs can be downloaded using the link above.
Note that I'm still hoping that existing JMS vendors can review this to confirm that this is consistent with their
existing interpretation of the spec. I have attempted to ensure that everything below is justified by the existing EJB spec.
*
Session <cid:part1.00060901.08060400_at_oracle.com> createSession(boolean transacted,
int acknowledgeMode)
throwsJMSException <cid:part2.05020604.07080007_at_oracle.com>
Creates a |Session| object, specifying |transacted| and |acknowledgeMode|.
This method has been superseded by the method |createSession(int sessionMode)| which specifies the same information
using a single argument, and by the method |createSession()| which is for use in a Java EE JTA transaction.
Applications should consider using those methods instead of this one.
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*:
o 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.
o 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*:
o 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*:
o 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.
o 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.
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.
o 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|.
o 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.
o 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.
Returns:
a newly created session
Throws:
|JMSException <cid:part2.05020604.07080007_at_oracle.com>| - if the |Connection| object fails to create a session
due to some internal error or lack of support for the specific transaction and acknowledgement mode.
Since:
1.1
See Also:
|Session.AUTO_ACKNOWLEDGE| <cid:part4.08020604.01030506_at_oracle.com>, |Session.CLIENT_ACKNOWLEDGE|
<cid:part5.09080606.08070102_at_oracle.com>, |Session.DUPS_OK_ACKNOWLEDGE|
<cid:part6.07070702.04030608_at_oracle.com>, |createSession(int)| <cid:part7.02060708.01040001_at_oracle.com>,
|createSession()| <cid:part8.06090700.04050201_at_oracle.com>
Nigel