On 22nd January, EG member Chris Harrow logged the following issue
https://java.net/jira/browse/JMS_SPEC-167
(JMS 2.0: Session javadoc should mention consumer.close is allowed outside thread of control)
I think this is useful correction for the JMS 2.0 errata, so although we had a discussion on the JIRA issue itself I'd
like for formally discuss it here.
Chris's proposal is as follows:
------------------------------------------------------------------------
The class level javadoc for Session contains the following paragraph:
"Once a connection has been started, any session with one or more
registered message listeners is dedicated to the thread of control
that delivers messages to it. It is erroneous for client code to use
this session or any of its constituent objects from another thread
of control. The only exception to this rule is the use of the session
or connection close method."
The last sentence should be augmented to include message consumer close since from JMS 2.0 that method is now explicitly
allowed to be called from another thread (see JMS_SPEC-48 and MessageConsumer.close javadoc). Moreover, it should not
really mention connection close because that is irrelevant (the connection is not a constituent object of the Session).
Suggested rewording for the last sentence:
"The only exceptions to this rule are the use of the session and
message consumer close methods"
------------------------------------------------------------------------
I agree with this proposal, for the following two reasons:
* The existing Javadoc for MessageConsumer.close states that "This method is the only MessageConsumer method that can be
called concurrently. This is not particularly good wording but Session.close has the same wording, which means that the
method doesn't have to be call from the thread of control.
* Closing a Session implicits closing all MessageConsumers. If it's legal to call Session.close from outside the thread
of control then it's reasonable to expect to be able to call MessageConsumer.close from outside the thread of control.
* The javadoc for Connection states that "Connections support concurrent use." This applies to all methods, not just
Connection.close. So the reference specifically to Connection.close is incorrect. Moreover a Connection is not a
constituent object of a Session, so mentioning it at all is inappropriate.
Nigel