Here's another old JIRA issue that I'm trying to make progress with:
http://java.net/jira/browse/JMS_SPEC-47
You may remember we discussed this back in September 2011. This relates to the domain-specific interfaces
QueueConnectionFactory, QueueConnection, QueueSession, QueueSender and QueueReceiver, TopicConnectionFactory,
TopicConnection, TopicSession, TopicPublisher and TopicSubscriber (and the optional XAQueueConnectionFactory,
XATopicConnectionFactory, XAQueueConnection, XATopicConnection, XAQueueSession and XATopicSession).
We agreed (with support from Reza, Ruediger and Clebert) with my proposal that:
* These interfaces would be formally marked as deprecated, by use of the @java.lang.Deprecated annotation. This would
cause compilers to issue a warning when a deprecated method was used.
* These interfaces would be formally marked in the specification as being "proposed for removal", with the expectation
that they would be made optional in the next release.
However you may also remember that some time after that I checked with the Java EE spec leads and other colleagues and
was told that doing this would break the compatibility requirements for Java EE specifications. I asked questions to
determine what these were, wrote them down, and the Java EE spec leads have published them here:
http://java.net/projects/javaee-spec/pages/CompatibilityRequirements
In short, these requirements mean that we cannot mark any existing interfaces as @java.lang.Deprecated, and we cannot
propose the removal of individual interfaces for removal in the future. Essentially, we're stuck with these interfaces
indefinitely. Although there might be scope to deprecate or interfaces which are unsafe in some way, or propose
interfaces for removal that we know very few people actually use, neither applies here.
This means that we cannot implement my original proposal.
However we are still free to write whatever we like in the spec and javadocs to discourage users from using these
interfaces and encouraging them to use the unified API instead.
I propose we describe these interfaces as "obsolete" and modify the spec and javadocs to make it clear that the
domain-specific interfaces are a legacy from JMS 1.0 which is kept only to preserve compatibility, and to encourage
applications to use the domain-independent interfaces instead.
Here are some of the places that need to be changed:
1. Modify the package description
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/package-summary.html#package_description
and change the section "JMS Interfaces" to give clear precedence to the domain-independent interfaces and to state
clearly that the domain-specific interfaces are a legacy from JMS 1.0 which is kept only to preserve compatibility.
2. Reword section 1.2.3.3 "JMS domains", 2.4 "Two messaging styles", 2.5 "JMS interfaces", 5.1. "Overview" (of PTP), 6.1
"Overview" (of pub/sub), 8.6 "JMS application server interfaces" to give clear precedence to the domain-independent
interfaces and to state clearly that the domain-specific interfaces are a legacy from JMS 1.0 which is kept only to
preserve compatibility.
3. Insert additional text into the class comment for QueueConnectionFactory, QueueConnection, QueueSession, QueueSender
and QueueReceiver, TopicConnectionFactory, TopicConnection, TopicSession, TopicPublisher and TopicSubscriber,
XAQueueConnectionFactory, XATopicConnectionFactory, XAQueueConnection, XATopicConnection, XAQueueSession and
XATopicSession along the lines of
"This interface is part of the JMS domain-specific API and is now obsolete. Applications are encouraged to use the JMS
domain-independent API instead. The domain-independent equivalent to this interface is foo. For more information see bar.
4. Insert a similar comment into the method comment for the two createDurableSubscriber methods on Session.
I will make the changes that I think are needed and offer them to this group for review.
I know this isn't what we wanted, but this is the best I think we can do...
Nigel