[JMS_SPEC-64] Define simplified JMS API Created: 08/Dec/11  Updated: 20/Mar/13  Resolved: 21/Sep/12

Status: Resolved
Project: jms-spec
Component/s: None
Affects Version/s: 1.1
Fix Version/s: 2.0PD, 2.0

Type: Improvement Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Fixed Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
blocks MQ-176 Implement simplified API for JMS 2.0 Closed
blocks JMS_SPEC-33 Improving the JMS API with API simpli... Resolved
blocks JMS_SPEC-70 Define annotations for injecting Mess... Resolved
Tags: pd20-added


This is a request for a simplified JMS API. This would achieve the following goals:

  • To reduce the number of objects needed to send and receive messages, and in particular to combine the JMS 1.1 Connection, Session, MessageProducer and MessageConsumer objects as much as possible.
  • To take advantage of the fact that this is a new API to simplify method signatures and make other simplifications which cannot be made to the old API because it would break backwards compatibility.
  • To maintain a consistent style with the existing API where possible so that users of the old API feel it to be an evolution which that can learn quickly.
  • To support, and offer benefits to, both Java EE and Java SE applications.
  • To allow resource injection to be exploited in those environment which support it, whilst still offering significant improvements for those environments which do not.
  • To provide the option to send and receive message payloads to be sent and received directly without the need to use javax.jms.Message objects.
  • To remove as much as possible the need to catch JMSException on method calls
  • To be functionally complete. The old API will remain to provide backwards compatibility. However the new API is intended to be functionally as complete as the old JMS 1.1 API. Users should not need to switch back to the old API to perform an operation that is unavailable in the new API.

Comment by Nigel Deakin [ 08/Dec/11 ]

A proposed API is described in JMS20SimplifiedAPIv1.pdf with javadocs in jms-2.0-javadoc.jar

Comment by Nigel Deakin [ 03/Feb/12 ]

I've now updated the API, javadocs and the draft spec in accordance with the proposals made above.

The updated Javadocs are here:

See particularly the new interfaces javax.jms.MessagingContext, javax.jms.SyncMessageConsumer and the new factory methods on javax.jms.Connection.createMessagigingContext

The updated draft spec is here:

See particularly the new chapter 13 "Simplified JMS API" and the change log in section 11.5.16.

Note that these changes cover the simplified API only. They do not include any proposals for injection of JMS objects (which will be handled in a separate JIRA issue).

Comment by Nigel Deakin [ 17/Feb/12 ]

I've updated the API, javadocs and the draft spec in accordance with the following changes.

The updated API and Javadocs are here:

The updated draft spec is here:

Added new methods on MessagingContext to send the Map and byte[] payloads directly as MapMessage and BytesMessage.

Extended existing methods on SyncMessagingContext that receive message payloads directly to support MapMessage and BytesMessage

Added new method methods on MessagingContext: setAutoStart() and getAutoStart(). These allow the autostart behaviour (where the connection is automatically started when a consumer is created) to be disabled.

The spec has been clarified to define when MessagingContext.setClientID may be called and when it may not. The JMS 1.1 spec says that Connection.setClientID may only be called immediately after the conneciton is created and prior to doing anything else with the connection. Since the factory method to create a MessagingContext creates a connection and then uses it to create a session this means that calling MessagingContext.setClientID after this would never be valid. The spec has therefore been clarified to state that this is indeed valid.

Comment by Nigel Deakin [ 21/Mar/12 ]

Following discussions, I have changed the API for consuming messages asynchronously to require the use of a separate consumer. This means that applications cannot set a message listener directly on the MessagingContext. Instead they need to create a consumer object and set the message listener on that.

The new combined consumer object (for sync and async delivery) is called JMSConsumer
For reasons of consistency, MessagingContext has been renamed JMSContext

I've updated the API, javadocs and the draft spec with these changes

The updated API and Javadocs are here:

The updated draft spec is here:

API and Javadoc changes

Changes to SyncMessageConsumer

  • Renamed to JMSConsumer
  • New method getMessageListener added
  • New method setmessageListener added
  • New method getBatchMessageListener added
  • New method setBatchMessageListener added

Changes to MessagingContext

  • Renamed to JMSContext
  • Existing method createSyncConsumer (3 methods) renamed to createConsumer
  • Existing method createSyncDurableConsumer (2 methods) renamed to createDurableConsumer
  • Existing method setmessageListener (5 methods) deleted
  • Existing method setBatchMessageListener (5 methods) deleted
  • Existing method createMessagingContext renamed to createContext

Changes to ConnectionFactory

  • Existing method {{createMessagingContext (4 methods) renamed to createContext

Spec changes

Section 11.2.4 "Consuming messages asynchronously" has been completely deleted.

Section 11.2.5 "Consuming messages synchronously" has been renamed 11.2.4 "Consuming messages" and updated to cover async message delivery as well.

Following the deletion of the section mentioned above, sections 11.2.6, 11.2.7, 11.2.8 and 11.2.9 become 11.2.5, 11.2.6, 11.2.7 and 11.2.8.

In section A.2 "Unresolved issues in the JMS 2.0 Early Draft", subsection A.2.1 "Simplified JMS API: Support for multiple consumers on a session" has been deleted since this issue has now been resolved.

References to MessagingContext have been changed to JMSContext throughout
References to SyncMessageConsumer have been changed to JMSConsumer throughout

Section 11.4. "Examples using the simplified API" has been updated to reflect these API changes.

Note that the spec does not attempt to record the changes between the Early Draft and this version, since this would be too complicated.

Comment by Nigel Deakin [ 21/Sep/12 ]

The API for sending messages has been completely revised to introduce a new interface JMSProducer. For a full description see section 11.2.4 "Sending messages" in the JMS 2.0 public draft.

Generated at Sat Feb 06 17:00:52 UTC 2016 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.