Deprecate domain-specific APIs and propose for removal

[glassfishrobot]

Summary

In version 1.0b of the JMS specification, applications had to use a completely separate set of interfaces when working with queues as they did when working with topics.

Specifically, applications working with queues had to use the interfaces QueueConnectionFactory, QueueConnection, QueueSession, QueueSender and QueueReceiver, whilst applications working with topics had to use the interfaces TopicConnectionFactory, TopicConnection, TopicSession, TopicPublisher and TopicSubscriber.

Although these two sets of interfaces shared common supertype interfaces ConnectionFactory, Connection, Session, MessageProducer and MessageConsumer, these were effectively abstract classes, and applications were forced to use the interfaces specific for the messaging domain (queue or topic) that they were using.

In version 1.1, new API methods were added to the common superclass, domain-independent, interfaces to allow them to be used directly by client applications. This offered a simpler programming model, and for first time allowed queues and topics to participate in the same local transaction, now that they could be accessed using the same session.

In JMS 1.1 all of the domain-specific interfaces were retained to provide backwards compatibility, but it was stated in Section 1.5 that "in the future, some of the domain-specific APIs may be deprecated".

For 2.0 it is time to take this to the next stage, and to formally announce that these interfaces are now deprecated and that they will be removed from a future version of the specification.

This would remove 15 interfaces from JMS and reduce the total number of interfaces by 34%, from 44 to 28.

Detail

This change would affect the following interfaces:

XAQueueConnection XAQueueConnectionFactory XAQueueSession XATopicConnection XATopicConnectionFactory XATopicSession QueueConnection QueueConnectionFactory QueueReceiver QueueSender QueueSession TopicConnection TopicConnectionFactory TopicPublisher TopicSession TopicSubscriber

There would be two changes:

• 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.

There do not appear to be any binding policies on how to deprecate or remove classes from a Java EE API, which means that the final decision is up to the expert group. However the Java EE Specification, section EE.6.1.3 "6.1.3Pruned Java Technologies" (which discusses a different issue, that of removing entire technologies from Java EE), links to a Java SE policy described at http://mreinhold.org/blog/removing-features, which appears to be a suitable policy to offer.

That policy states that a particular version of a spec may state that a feature is "proposed for removal". This means that the following version can remove it.

However that policy also states that "removal" of a feature does not mean actually deleting it. Instead the feature will remain in the specification but will become optional. This means that implementers are not required to implement it. Its tests will remain in the TCK to allow those who decide to implement it to verify that it has been implemented correctly.

Other issues

Before making this change we should confirm that the "domain-independent" interfaces are a complete replacement for the "domain-specific" interfaces.

It has been noticed that Session.createDurableSubscriber() returns a TopicSubscriber, not a MessageConsumer. This looks to me like a mistake which would need to be fixed before we could remove TopicSubscriber. The solution would be for this method to return a MessageConsumer. Since this is a supertype of TopicSubscriber it should not break existing applications. (Edit: This has now been raised separately as #51 )

[glassfishrobot]

• Issue Imported From: https://github.com/javaee/jms-spec/issues/47
• Original Issue Raised By:@glassfishrobot
• Original Issue Assigned To: Unassigned

[glassfishrobot]

@glassfishrobot Commented Reported by @nigeldeakin

[glassfishrobot]

@glassfishrobot Commented This issue was imported from java.net JIRA JMS_SPEC-47