(This is a minor spec/API update which clarifies the restriction on the use of async send in a Java EE web or EJB container)
In the draft JMS 2.0 specification, section 7.3.5 "Restrictions on usage in Java EE" states that
"An asynchronous send is not permitted in a Java EE EJB or web container. If the application component violates this
restriction the send method may throw a JMSException or JMSRuntimeException (depending on the method signature)."
The same text can be found in the API docs for
MessageProducer.send(message, completionListener)
MessageProducer.send(message, deliveryMode, priority, timeToLive, completionListener)
MessageProducer.send(destination, message, completionListener)
MessageProducer.send(destination, message, deliveryMode, priority, timeToLive, completionListener)
and for
JMSProducer.setAsync(completionListener)
If you've forgotten why we're imposing this restriction, I've summarised it on this wiki page
http://java.net/projects/jms-spec/pages/JMS20ReasonsFAQ#Why_is_asynchronous_send_not_permitted_in_a_Java_EE_web_or_EJB_container?
(This text isn't in the spec, but we could add it if people think it would be helpful)
There are two things I would like to clarify:
1. Is there a restriction on calling JMSProducer.setAsync in a Java EE EJB or web container? The wording above implies
that this is perfectly valid so long as the application doesn't subsequently call send(). This needs to be clarified in
both the spec and API docs.
2. The list of prohibited methods in section 12.2 "Restrictions on the use of JMS API in the Java EE web or EJB
container" needs to be updated to include the methods related to async send.
Let us consider (1). I think allowing JMSProducer.setAsync, but prohibiting a subsequent call to JMSProducer.send, is
simply confusing. When I drafted the existing text I was certain that an async send should not be permitted in a Java EE
web or EJB container (for the reasons linked to above) but I had not thought deeply about exactly what this meant in
terms of banned methods. So the existing wording is not deliberate.
I propose we clarify this and state that JMSProducer.setAsync must not be called in a Java EE web or EJB container. If
an application violates this restriction then this method may throw a JMSRuntimeException.
(Although this method is definitely prohibited, I propose keeping it optional whether the JMS provider enforces this
with an exception, since that is consistent with all the other methods which are prohibited in the Java EE web or EJB
container. This also has the benefit of not requiring any last-minute changes to the RI or compatibility tests.
----------------------------------------------------------------------------------------------------------------------
PROPOSAL: 7.3.5. Restrictions on usage in Java EE (this is part of section 7.3 "Asynchronous send")
Proposed new text:
An asynchronous send is not permitted in a Java EE EJB or web container.
The following methods must therefore not be used in a Java EE web or EJB container:
* javax.jms.Session method send(Message message, CompletionListener completionListener)
* javax.jms.Session method send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener
completionListener)
* javax.jms.Session method send(Destination destination, Message message, CompletionListener completionListener)
* javax.jms.Session method send(Destination destination, Message message, int deliveryMode, int priority, long
timeToLive, CompletionListener completionListener)
* javax.jms.JMSProducer method setAsync(CompletionListener completionListener)
All the methods listed in this section may throw a javax.jms.JMSException (if allowed by the method) or a
javax.jms.JMSRuntimeException (if not) when called by an application running in the Java EE web or EJB container. This
is recommended but not required.
----------------------------------------------------------------------------------------------------------------------
PROPOSAL: 12.2. Restrictions on the use of JMS API in the Java EE web or EJB container (a summary list for the whole API)
Insert new text:
An asynchronous send is not permitted in a Java EE EJB or web container. The following methods must therefore not be
used in a Java EE web or EJB container:
* javax.jms.Session method send(Message message, CompletionListener completionListener)
* javax.jms.Session method send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener
completionListener)
* javax.jms.Session method send(Destination destination, Message message, CompletionListener completionListener)
* javax.jms.Session method send(Destination destination, Message message, int deliveryMode, int priority, long
timeToLive, CompletionListener completionListener)
* javax.jms.JMSProducer method setAsync(CompletionListener completionListener)
----------------------------------------------------------------------------------------------------------------------
PROPOSAL: Amend the API docs for all five methods above by deleting the sentence:
Restrictions on usage in Java EE - An asynchronous send is not permitted in a Java EE EJB or web container. If the
application component violates this restriction this method may throw a JMSRuntimeException.
and replacing with the more explicit (and consistent with other methods):
Restrictions on usage in Java EE - This method must not be used in a Java EE EJB or web container. Doing so may cause a
JMS(Runtime)Exception to be thrown though this is not guaranteed.
To make this change easier to review I've updated the draft spec and API docs, which you can review in the usual place:
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/index.html
However comments and corrections are invited and I am happy to make further changes in the light of comments.
Nigel