The JMS and Jakarta Messaging model

The JMS and Jakarta Messaging model defines a set of interfaces that Java applications can use to perform messaging operations. IBM® MQ classes for JMS and IBM MQ classes for Jakarta Messaging are both messaging providers. They define how JMS and Jakarta Messaging objects are related to IBM MQ concepts. The JMS and Jakarta Messaging specifications expect certain JMS and Jakarta Messaging objects to be administered objects.

[JMS 2.0] IBM MQ 8.0 added support for the JMS 2.0 version of the JMS standard, which introduced a simplified API, while also retaining the classic API, from JMS 1.1.

From IBM MQ 9.3.0, Jakarta Messaging 3.0 is supported for developing new applications. IBM MQ 9.3.0 continues to support JMS 2.0 for existing applications. It is not supported to use both the JMS 2.0 API and the Jakarta Messaging 3.0 API in the same application.

Note: For Jakarta Messaging 3.0, control of the JMS specification moves from Oracle to the Java Community Process. However, Oracle retains control of the "javax" name, which is used in other Java technologies that have not moved to the Java Community Process. So, while Jakarta Messaging 3.0 is functionally equivalent to JMS 2.0 there are some differences in naming:

The official name for version 3.0 is Jakarta Messaging rather than Java Message Service.
The package and constant names are prefixed with jakarta rather than javax. For example, in JMS 2.0 the initial connection to a messaging provider is a javax.jms.Connection object, and in Jakarta Messaging 3.0 it is a jakarta.jms.Connection object.

[JMS 2.0] The javax.jms packages define the JMS interfaces, and a JMS provider implements these interfaces for a specific messaging product. IBM MQ classes for JMS is a JMS provider that implements the JMS interfaces for IBM MQ.

[Jakarta Messaging 3.0] The jakarta.jms packages define the Jakarta Messaging interfaces, and a Jakarta Messaging provider implements these interfaces for a specific messaging product. IBM MQ classes for Jakarta Messaging is a Jakarta Messaging provider that implements the Jakarta Messaging interfaces for IBM MQ.

Because JMS and Jakarta Messaging share much in common, further references to JMS in this topic can be taken as referring to both. Any differences are highlighted as necessary.

Simplified API

JMS 2.0 introduced the simplified API, while also retaining the domain specific and domain independent interfaces from JMS 1.1. The simplified API reduces the number of objects that are needed to send and receive messages and consists of the following interfaces:

ConnectionFactory: A ConnectionFactory is an administered object that is used by a JMS client to create a Connection. This interface is also used in the classic API.
JMSContext: This object combines the Connection and Session objects of the classic API. JMSContext objects can be created from other JMSContext objects, with the underlying connection being duplicated.
JMSProducer: A JMSProducer is created by a JMSContext and is used to send messages to a queue or topic. The JMSProducer object causes the creation of objects that are required to send the message.
JMSConsumer: A JMSConsumer is created by a JMSContext and is used to receive messages from a topic or a queue.

The simplified API has a number of effects:

The JMSContext object always automatically starts the underlying connection.
JMSProducers and JMSConsumers can now work directly with message bodies, without having to get the whole message object, by using the Message's getBody method.
Message properties can be set on the JMSProducer object, using method chaining, before sending a 'body', a messages content. The JMSProducer will handle the creation of all objects that are needed to send the message. Using JMS 2.0, properties can be set, and a message sent as follows:
```
context.createProducer().
setProperty("foo", "bar").
setTimeToLive(10000).
setDeliveryMode(NON_PERSISTENT).
setDisableMessageTimestamp(true).
send(dataQueue, body);
```

JMS 2.0 also introduced shared subscriptions where messages can be shared between multiple consumers. All JMS 1.1 subscriptions are treated as unshared subscriptions.

Classic API

The following list summarizes the main JMS interfaces of the classic API:

Destination: A destination is where an application sends messages, or it is a source from which an application receives messages, or both.
ConnectionFactory: A ConnectionFactory object encapsulates a set of configuration properties for a connection. An application uses a connection factory to create a connection.
Connection: A Connection object encapsulates an application's active connection to a messaging server. An application uses a connection to create sessions.
Session: A session is a single threaded context for sending and receiving messages. An application uses a session to create messages, message producers, and message consumers. A session is either transacted or not transacted.
Message: A Message object encapsulates a message that an application sends or receives.
MessageProducer: An application uses a message producer to send messages to a destination.
MessageConsumer: An application uses a message consumer to receive messages sent to a destination.

Figure 1 shows these objects and their relationships.

The diagram shows the main JMS interfaces: ConnectionFactory, Connection, Session, MessageProducer, MessageConsumer, Message, and Destination. An application uses a connection factory to create a connection, and uses a connection to create sessions. The application can then use a session to create messages, message producers, and message consumers. The application uses a message producer to send messages to a destination, and uses a message consumer to receive messages sent to a destination. — Figure 1. JMS objects and their relationships

A Destination, ConnectionFactory, or Connection object can be used concurrently by different threads of a multithreaded application, but a Session, MessageProducer, or MessageConsumer object cannot be used concurrently by different threads. The simplest way of ensuring that a Session, MessageProducer, or MessageConsumer object is not used concurrently is to create a separate Session object for each thread.

Messaging domains

JMS supports two styles of messaging:

Point-to-point messaging
Publish/subscribe messaging

These styles of messaging are also referred to as messaging domains, and you can combine both styles of messaging in an application. In the point-to-point domain, a destination is a queue and, in the publish/subscribe domain, a destination is a topic.

With versions of JMS before JMS 1.1, programming for the point-to-point domain uses one set of interfaces and methods, and programming for the publish/subscribe domain uses another set. The two sets are similar, but separate. From JMS 1.1, you can use a common set of interfaces and methods that support both messaging domains. The common interfaces provide a domain independent view of each messaging domain. Table 1 lists the JMS domain independent interfaces and their corresponding domain specific interfaces.

Table 1. The JMS domain independent and domain specific interfaces
Domain independent interfaces	Domain specific interfaces for the point-to-point domain	Domain specific interfaces for the publish/subscribe domain
ConnectionFactory	QueueConnectionFactory	TopicConnectionFactory
Connection	QueueConnection	TopicConnection
Destination	Queue	Topic
Session	QueueSession	TopicSession
MessageProducer	QueueSender	TopicPublisher
MessageConsumer	QueueReceiver QueueBrowser	TopicSubscriber

[JMS 2.0] IBM MQ classes for JMS 2.0 supports both the earlier JMS 1.1 domain specific interfaces and the simplified API of JMS 2.0. IBM MQ classes for JMS 2.0 can therefore be used for maintaining existing applications, including developing new function in existing applications.

[Jakarta Messaging 3.0] IBM MQ classes for Jakarta Messaging 3.0 supports the Jakarta Messaging versions of the same interfaces, and is recommended for new application development.

In IBM MQ classes for JMS and IBM MQ classes for Jakarta Messaging, JMS objects are related to IBM MQ concepts in the following ways:

A Connection object has properties that are derived from the properties of the connection factory that was used to create the connection. These properties control how an application connects to a queue manager. Examples of these properties are the name of the queue manager and, for an application that connects to the queue manager in client mode, the host name or IP address of the system on which the queue manager is running.
A Session object encapsulates an IBM MQ connection handle, which therefore defines the transactional scope of the session.
A MessageProducer object and a MessageConsumer object each encapsulates an IBM MQ object handle.

When using IBM MQ classes for JMS or IBM MQ classes for Jakarta Messaging, all the normal rules of IBM MQ apply. Note, in particular, that an application can send a message to a remote queue but it can receive a message only from a queue that is owned by the queue manager to which the application is connected.

The JMS specification expects ConnectionFactory and Destination objects to be administered objects. An administrator creates and maintains administered objects in a central repository, and a JMS application retrieves these objects using the Java Naming and Directory Interface (JNDI).

In IBM MQ classes for JMS and IBM MQ classes for Jakarta Messaging, the implementation of the Destination interface is an abstract superclass of Queue and Topic, and so an instance of Destination is either a Queue object or a Topic object. The domain independent interfaces treat a queue or a topic as a destination. The messaging domain for a MessageProducer or MessageConsumer object is determined by whether the destination is a queue or a topic.

In IBM MQ classes for JMS and IBM MQ classes for Jakarta Messaging therefore, objects of the following types can be administered objects:

ConnectionFactory
QueueConnectionFactory
TopicConnectionFactory
Queue
Topic
XAConnectionFactory
XAQueueConnectionFactory
XATopicConnectionFactory