[JMS_SPEC-27] Clarify the relationship between the JMS and other Java EE specifications Created: 06/Jul/11 Updated: 20/Mar/13 Resolved: 20/Mar/13
|Fix Version/s:||2.0ED, 2.0|
|Reporter:||Nigel Deakin||Assignee:||Nigel Deakin|
|Remaining Estimate:||Not Specified|
|Time Spent:||Not Specified|
|Original Estimate:||Not Specified|
We need to clarify the relationship between the JMS and other Java EE specifications. This is mainly a documentation exercise, especially for those methods which are forbidden or modified in a EJB or Web container, but there are some ambiguities, especially when the transaction context is undefined.
If you want use the JMS API in a Java EE application such as a EJB or servlet you soon discover that much of the JMS spec (including the JMS javadocs) does not apply, at least in the EJB and web containers. For example, you aren't allowed to create message listeners, you need to defined MDBs instead. You aren't allowed to create local transactions, you need to use CMT or BMT transactions instead. You aren't allowed to set clientID on a connection. You aren't allowed to perform client acknowledgement. Essentially, in a Java EE container, the JMS API is simply different. However this is not explained in the JMS spec but is described in other specs, notably the EJB and Java EE platform specs.
Some of this information of necessity in other specs, but the absence of any mention of it in the JMS spec or javadocs is confusing to users.
I would like the JMS expert group to review what it says about JMS in other specs and consider whether this material should be moved to the JMS spec, duplicated in the JMS spec, or cross-referenced from the JMS spec. In addition the javadocs need to be clarified to mention that some API is not allowed, or has a different effect, in a Java EE web or EJB container.
I see this mainly as a documentation exercise. However this analysis will inevitably identify that some areas of behaviour are not well defined. For example, the EJB spec states explicitly that in an "undefined transactional context" it is not defined how the JMS provider should handle transactions. This means that vendors may behave differently which reduces the portability of application. If possible this should be resolved.
|Comment by Nigel Deakin [ 26/Jan/12 ]|
I've now updated the API, javadocs and the draft spec.
I've written a completely new section to add to the new chapter 12 "Use of JMS API in Java EE applications" which was added for
12.2. Restrictions on the use of JMS API in the Java EE web or EJB container
JMS applications which run in the Java EE web or EJB container are subject to a number of restrictions in the way the JMS API may be used. These restrictions are necessary for the following reasons:
The restrictions described in this section do not apply to the Java EE application client container.
The following methods are intended for use by the application server and their use by applications running in the Java EE web or EJB container may interfere with the container's ability to properly manage the threads used in the runtime environment. They must therefore not be called by applications running in the Java EE web or EJB container:
The following methods may interfere with the container's ability to properly manage the threads used in the runtime environment and must not be used by applications running in the Java EE web or EJB container:
This restriction means that applications running in the Java EE web or EJB container which need to receive messages asynchronously may only do so using message-driven beans.
The following methods may interfere with the container's management of connections and must not be used by applications running in the Java EE web or EJB container:
Applications which need to use a specific client identifier must set it on the connection factory, as described in section 4.3.2 "Client Identifier"
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.
|Comment by Nigel Deakin [ 26/Jan/12 ]|
The updated Javadocs are here:
The javadocs for all the methods listed above which are not permitted in a Java EE web or Java EE container now include the following statement:
In addition, the list of exceptions for these methods now states that they may throw a JMSException (or JMSRuntimeException if called in a Java EE web or EJB container, together with the caveat that "it is not guaranteed that an exception is thrown in this case"
The three Connection methods createSession now include the statement:
The list of exceptions for these methods states that they will (must) throw a JMSException if "this method is being called in a Java EE web or EJB application and an active session already exists for this connection."
The MessageConsumer method createMessagingContext now includes the statement:
The list of exceptions for this method now states that it will (must) throw an exception if "this method is being called in a Java EE web or EJB application"
|Comment by Nigel Deakin [ 20/Mar/13 ]|
This issue is resolved in the JMS 2.0 final release. Marking issue as resolved with a "fix version" of 2.0