Back in July I created this JIRA issue,
http://java.net/jira/browse/JMS_SPEC-27
This was how I described the issue:
> 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.
Recently I have spent some time trying to collect in a single place the restrictions on the use of the JMS API which
currently exists only in the EJB or Java EE specs. I have now done this and written a new section for the JMS spec. I
have added this to the draft spec and also added to JIRA.
If you want to see where these restrictions are currently defined, look in
Java EE 6 platform specification, section EE.6.7 "Java™ Message Service (JMS) 1.1 Requirements"
EJB 3.1 specification, section 21.3.5 "JMS 1.1 Requirements"
You can read the new section in JIRA here:
http://java.net/jira/browse/JMS_SPEC-27?focusedCommentId=330024&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_330024
Or you can read it in the draft spec here (it's section 12.2)
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf
This new section essentially explains:
* that several JMS methods are not allowed in a Java EE web or EJB container.
* that you aren't allowed to create two active sessions from the same connections in a Java EE web or EJB container.
I'd like to make it clear that in doing this I have tried not to change what is already specified. It has not been my
intention to add new restrictions or remove existing restrictions, but merely to bring into the EJB spec what is already
defined elsewhere.
I have also therefore amended the javadocs for all these methods to explain that their use is restricted or prohibited
in a Java EE web or EJB container.
I've written a summary of the javadoc changes in JIRA here:
http://java.net/jira/browse/JMS_SPEC-27?focusedCommentId=330026&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_330026
Or you can download the javadocs themselves here:
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar
I have been in discussions with the Java EE and EJB spec leads about tidying this up. We'll probably remove the
duplication from the EJB spec but may continue it with the Java EE spec.
Now, when I started writing this email I looked back to see what we had previously discussed about this particular JIRA
issue, and I was surprised to see that we don't appear to have had a discussion. So I seem to have made these changes to
the draft spec and javadocs without having discussed them with you all beforehand. This was an oversight for which I
apologise.
That said, I hope the changes I have made are not controversial since I am simply attempting to document better what is
already defined in other specs. Nevertheless if you have any comments or objections to this, please make them. In
particular, if you think I have misunderstood the requirements of the existing EJB and Java EE specs please say so and
we can have a discussion.
Nigel