JavaEE API 8.0.1 · javax.jms

The Java Message Service (JMS) API provides a common way for Java programs to create, send, receive and read an enterprise messaging system's messages.

JMS Applications

A JMS application is composed of the following parts:

JMS provider - a messaging system that implements the JMS API in addition to the other administrative and control functionality required of a full-featured messaging product
JMS clients - the Java language programs that send and receive messages
Messages - objects that are used to communicate information between the clients of an application
Administered objects - provider-specific objects that clients look up and use to interact portably with a JMS provider
Non-JMS clients - clients that use a message system's native client API instead of the JMS API. If the application predated the availability of the JMS API, it is likely that it will include both JMS clients and non-JMS clients.

Administration

JMS providers differ significantly in their implementations of underlying messaging technology. There are also major differences in how a JMS provider's system is installed and administered.

For JMS clients to be portable, they must be isolated from these proprietary aspects of a provider. This is done by defining JMS administered objects that are created and customised by a provider's administrator and later used by clients. The client uses them through JMS interfaces that are portable. The administrator creates them using provider-specific facilities.

There are two types of JMS administered objects:

ConnectionFactory - the object a client uses to create a connection with a JMS provider
Destination - the object a client uses to specify the destination of messages it is sending and the source of messages it receives

Administered objects are placed by an administrator in a JNDI (Java Naming and Directory Interface) namespace. A JMS client typically notes in its documentation the JMS administered objects it requires and how the JNDI names of these objects should be provided to it.

Two Messaging Styles

JMS supports two styles of messaging:

point-to-point (PTP) messaging using queues
publish-and-subscribe (pub/sub)messaging using topics

These two styles represent two of the dominant approaches to messaging currently in use.

JMS APIs

For historical reasons JMS offers four alternative sets of interfaces for sending and receiving messages:

JMS 1.0 defined two domain-specific APIs, one for point-to-point messaging (queues) and one for pub/sub (topics). Although these remain part of JMS for reasons of backwards compatibility they should be considered to be completely superseded by the later APIs.
JMS 1.1 introduced a new unified API which offered a single set of interfaces that could be used for both point-to-point and pub/sub messaging. This is referred to here as the classic API.
JMS 2.0 introduces a simplified API which offers all the features of the classic API but which requires fewer interfaces and is simpler to use.

Each API offers a different set of interfaces for connecting to a JMS provider and for sending and receiving messages. However they all share a common set of interfaces for representing messages and message destinations and to provide various utility features.

All interfaces are in the javax.jms package.

Interfaces common to multiple APIs

The main interfaces common to multiple APIs are as follows:

Message, BytesMessage, MapMessage, ObjectMessage, StreamMessage and TextMessage - a message sent to or received from a JMS provider.
Queue - an administered object that encapsulates the identity of a message destination for point-to-point messaging
Topic - an administered object that encapsulates the identity of a message destination for pub/sub messaging.
Destination - the common supertype of Queue and Topic

Classic API interfaces

The main interfaces provided by the classic API are as follows:

ConnectionFactory - an administered object used by a client to create a Connection. This interface is also used by the simplified API.
Connection - an active connection to a JMS provider
Session - a single-threaded context for sending and receiving messages
MessageProducer - an object created by a Session that is used for sending messages to a queue or topic
MessageConsumer - an object created by a Session that is used for receiving messages sent to a queue or topic

Simplified API interfaces

The simplified API provides the same messaging functionality as the classic API but requires fewer interfaces and is simpler to use. The main interfaces provided by the simplified API are as follows:

ConnectionFactory - an administered object used by a client to create a JMSContext. This interface is also used by the classic API.
JMSContext - an active connection to a JMS provider and a single-threaded context for sending and receiving messages
JMSProducer - an object created by a JMSContext that is used for sending messages to a queue or topic
JMSConsumer - an object created by a JMSContext that is used for receiving messages sent to a queue or topic

Legacy domain-specific API interfaces

Although the domain-specific API remains part of JMS for reasons of backwards compatibility it should be considered to be completely superseded by the classic and simplified APIs.

The main interfaces provided by the domain-specific API for point-to-point messaging are as follows:

QueueConnectionFactory - an administered object used by a client to create a QueueConnection.
QueueConnection - an active connection to a JMS provider
QueueSession - a single-threaded context for sending and receiving messages
QueueSender - an object created by a QueueSession that is used for sending messages to a queue
QueueReceiver - an object created by a QueueSession that is used for receiving messages sent to a queue

The main interfaces provided by the domain-specific API for pub/sub messaging are as follows:

TopicConnectionFactory - an administered object used by a client to create a TopicConnection.
TopicConnection - an active connection to a JMS provider
TopicSession - a single-threaded context for sending and receiving messages
TopicPublisher - an object created by a TopicSession that is used for sending messages to a topic
TopicSubscriber - an object created by a TopicSession that is used for receiving messages sent to a topic

Terminology for sending and receiving messages

The term consume is used in this document to mean the receipt of a message by a JMS client; that is, a JMS provider has received a message and has given it to its client. Since JMS supports both synchronous and asynchronous receipt of messages, the term consume is used when there is no need to make a distinction between them.

The term produce is used as the most general term for sending a message. It means giving a message to a JMS provider for delivery to a destination.

Developing a JMS Application

Broadly speaking, a JMS application is one or more JMS clients that exchange messages. The application may also involve non-JMS clients; however, these clients use the JMS provider's native API in place of the JMS API.

A JMS application can be architected and deployed as a unit. In many cases, JMS clients are added incrementally to an existing application.

The message definitions used by an application may originate with JMS, or they may have been defined by the non-JMS part of the application.

Developing a JMS Client

A typical JMS client using the classic API executes the following JMS setup procedure:

Use JNDI to find a ConnectionFactory object
Use JNDI to find one or more Destination objects
Use the ConnectionFactory to create a JMS Connection object with message delivery inhibited
Use the Connection to create one or more JMS Session objects
Use a Session and the Destinations to create the MessageProducer and MessageConsumer objects needed
Tell the Connection to start delivery of messages

In contrast, a typical JMS client using the simplified API does the following:

Use JNDI to find a ConnectionFactory object
Use JNDI to find one or more Destination objects
Use the ConnectionFactory to create a JMSContext object
Use the JMSContext to create the JMSProducer and JMSConsumer objects needed.
Delivery of message is started automatically

At this point a client has the basic JMS setup needed to produce and consume messages.

Package Specification

Java Message Service 2.0 specification

Interface Summary

Modifier and Type	Interface and Description
public interface	BytesMessage A `BytesMessage` object is used to send a message containing a stream of uninterpreted bytes.
public interface	CompletionListener A `CompletionListener` is implemented by the application and may be specified when a message is sent asynchronously.
public interface	Connection A `Connection` object is a client's active connection to its JMS provider.
public interface	ConnectionConsumer For application servers, `Connection` objects provide a special facility for creating a `ConnectionConsumer` (optional).
public interface	ConnectionFactory A `ConnectionFactory` object encapsulates a set of connection configuration parameters that has been defined by an administrator.</font>
public interface	ConnectionMetaData A `ConnectionMetaData` object provides information describing the `Connection` object.
public interface	DeliveryMode The delivery modes supported by the JMS API are `PERSISTENT` and `NON_PERSISTENT`.
public interface	Destination A `Destination` object encapsulates a provider-specific address.</font>
public interface	ExceptionListener If a JMS provider detects a serious problem with a `Connection` object, it informs the `Connection` object's `ExceptionListener`, if one has been registered.
public interface	JMSConsumer A client using the simplified JMS API introduced for JMS 2.0 uses a `JMSConsumer` object to receive messages from a queue or topic.
public interface	JMSContext A `JMSContext` is the main interface in the simplified JMS API introduced for JMS 2.0.
public interface	JMSProducer A `JMSProducer` is a simple object used to send messages on behalf of a `JMSContext`.
public interface	MapMessage A `MapMessage` object is used to send a set of name-value pairs.
public interface	Message The `Message` interface is the root interface of all JMS messages.
public interface	MessageConsumer A client uses a `MessageConsumer` object to receive messages from a destination.
public interface	MessageListener A `MessageListener` object is used to receive asynchronously delivered messages.
public interface	MessageProducer A client uses a `MessageProducer` object to send messages to a destination.
public interface	ObjectMessage An `ObjectMessage` object is used to send a message that contains a serializable object in the Java programming language ("Java object").
public interface	Queue A `Queue` object encapsulates a provider-specific queue name.
public interface	QueueBrowser A client uses a `QueueBrowser` object to look at messages on a queue without removing them.
public interface	QueueConnection A `QueueConnection` object is an active connection to a point-to-point JMS provider.
public interface	QueueConnectionFactory A client uses a `QueueConnectionFactory` object to create `QueueConnection` objects with a point-to-point JMS provider.
public interface	QueueReceiver A client uses a `QueueReceiver` object to receive messages that have been delivered to a queue.
public interface	QueueSender A client uses a `QueueSender` object to send messages to a queue.
public interface	QueueSession A `QueueSession` object provides methods for creating `QueueReceiver`, `QueueSender`, `QueueBrowser`, and `TemporaryQueue` objects.
public interface	ServerSession A `ServerSession` object is an application server object that is used by a server to associate a thread with a JMS session (optional).
public interface	ServerSessionPool A `ServerSessionPool` object is an object implemented by an application server to provide a pool of `ServerSession` objects for processing the messages of a `ConnectionConsumer` (optional).
public interface	Session A `Session` object is a single-threaded context for producing and consuming messages.
public interface	StreamMessage A `StreamMessage` object is used to send a stream of primitive types in the Java programming language.
public interface	TemporaryQueue A `TemporaryQueue` object is a unique `Queue` object created for the duration of a `Connection`.
public interface	TemporaryTopic A `TemporaryTopic` object is a unique `Topic` object created for the duration of a `Connection`.
public interface	TextMessage A `TextMessage` object is used to send a message containing a `java.lang.String`.
public interface	Topic A `Topic` object encapsulates a provider-specific topic name.
public interface	TopicConnection A `TopicConnection` object is an active connection to a publish/subscribe JMS provider.
public interface	TopicConnectionFactory A client uses a `TopicConnectionFactory` object to create `TopicConnection` objects with a publish/subscribe JMS provider.
public interface	TopicPublisher A client uses a `TopicPublisher` object to publish messages on a topic.
public interface	TopicSession A `TopicSession` object provides methods for creating `TopicPublisher`, `TopicSubscriber`, and `TemporaryTopic` objects.
public interface	TopicSubscriber A client uses a `TopicSubscriber` object to receive messages that have been published to a topic.
public interface	XAConnection The `XAConnection` interface extends the capability of `Connection` by providing an `XASession` (optional).
public interface	XAConnectionFactory The `XAConnectionFactory` interface is a base interface for the `XAQueueConnectionFactory` and `XATopicConnectionFactory` interfaces.
public interface	XAJMSContext The `XAJMSContext` interface extends the capability of `JMSContext` by adding access to a JMS provider's support for the Java Transaction API (JTA) (optional).
public interface	XAQueueConnection An `XAQueueConnection` provides the same create options as `QueueConnection` (optional).
public interface	XAQueueConnectionFactory An `XAQueueConnectionFactory` provides the same create options as a `QueueConnectionFactory` (optional).
public interface	XAQueueSession An `XAQueueSession` provides a regular `QueueSession`, which can be used to create `QueueReceiver`, `QueueSender`, and `QueueBrowser` objects (optional).
public interface	XASession The `XASession` interface extends the capability of `Session` by adding access to a JMS provider's support for the Java Transaction API (JTA) (optional).
public interface	XATopicConnection An `XATopicConnection` provides the same create options as `TopicConnection` (optional).
public interface	XATopicConnectionFactory An `XATopicConnectionFactory` provides the same create options as a `TopicConnectionFactory` (optional).
public interface	XATopicSession An `XATopicSession` provides a regular `TopicSession`.

Annotation Summary

Modifier and Type	Annotation and Description
public @interface	JMSConnectionFactory This annotation may be used to specify the JNDI lookup name of a `javax.jms.ConnectionFactory` to be used when injecting a `javax.jms.JMSContext` object.
public @interface	JMSConnectionFactoryDefinition An application may use this annotation to specify a JMS `ConnectionFactory` resource that it requires in its operational environment.
public @interface	JMSConnectionFactoryDefinitions Specifies one or more `JMSConnectionFactoryDefinition` annotations.
public @interface	JMSDestinationDefinition An application may use this annotation to specify a JMS `Destination` resource that it requires in its operational environment.
public @interface	JMSDestinationDefinitions Specifies one or more `JMSDestinationDefinition` annotations.
public @interface	JMSPasswordCredential This annotation may be used to specify the userName and password to be used when injecting a `javax.jms.JMSContext` object.
public @interface	JMSSessionMode This annotation may be used to specify the session mode to be used when injecting a `javax.jms.JMSContext` object.

Class Summary

Modifier and Type	Class and Description
public class	IllegalStateException This exception is thrown when a method is invoked at an illegal or inappropriate time or if the provider is not in an appropriate state for the requested operation.
public class	IllegalStateRuntimeException This unchecked exception is thrown when a method is invoked at an illegal or inappropriate time or if the provider is not in an appropriate state for the requested operation, and the method signature does not permit a `IllegalStateRuntimeException` to be thrown.
public class	InvalidClientIDException This exception must be thrown when a client attempts to set a connection's client ID to a value that is rejected by a provider.
public class	InvalidClientIDRuntimeException This unchecked exception must be thrown when a client attempts to set a connection's client ID to a value that is rejected by a provider, and the method signature does not permit a `InvalidClientIDException` to be thrown.
public class	InvalidDestinationException This exception must be thrown when a destination either is not understood by a provider or is no longer valid.
public class	InvalidDestinationRuntimeException This unchecked exception must be thrown when a destination either is not understood by a provider or is no longer valid, and the method signature does not permit a `InvalidDestinationException` to be thrown.
public class	InvalidSelectorException This exception must be thrown when a JMS client attempts to give a provider a message selector with invalid syntax.
public class	InvalidSelectorRuntimeException This unchecked exception must be thrown when a JMS client attempts to give a provider a message selector with invalid syntax, and the method signature does not permit a `InvalidSelectorException` to be thrown.
public class	JMSException This is the root class of all checked exceptions in the JMS API.
public class	JMSRuntimeException This is the root class of all unchecked exceptions in the JMS API.
public class	JMSSecurityException This exception must be thrown when a provider rejects a user name/password submitted by a client.
public class	JMSSecurityRuntimeException This unchecked exception must be thrown when a provider rejects a user name/password submitted by a client, or for any case where a security restriction prevents a method from completing, and the method signature does not permit a `JMSSecurityException` to be thrown.
public class	MessageEOFException This exception must be thrown when an unexpected end of stream has been reached when a `StreamMessage` or `BytesMessage` is being read.
public class	MessageFormatException This exception must be thrown when a JMS client attempts to use a data type not supported by a message or attempts to read data in a message as the wrong type.
public class	MessageFormatRuntimeException This unchecked exception must be thrown when a JMS application attempts to use a data type not supported by a message or attempts to read data in a message as the wrong type, and the method signature does not permit a `MessageFormatException` to be thrown.
public class	MessageNotReadableException This exception must be thrown when a JMS client attempts to read a write-only message.
public class	MessageNotWriteableException This exception must be thrown when a JMS client attempts to write to a read-only message.
public class	MessageNotWriteableRuntimeException This unchecked exception must be thrown when a JMS client attempts to write to a read-only message.
public class	QueueRequestor The `QueueRequestor` helper class simplifies making service requests.
public class	ResourceAllocationException This exception is thrown when a provider is unable to allocate the resources required by a method.
public class	ResourceAllocationRuntimeException This unchecked exception is thrown when a provider is unable to allocate the resources required by a method.
public class	TopicRequestor The `TopicRequestor` helper class simplifies making service requests.
public class	TransactionInProgressException This exception is thrown when an operation is invalid because a transaction is in progress.
public class	TransactionInProgressRuntimeException This unchecked exception is thrown when an operation is invalid because a transaction is in progress.
public class	TransactionRolledBackException This exception must be thrown when a call to `Session.commit` results in a rollback of the current transaction.
public class	TransactionRolledBackRuntimeException This unchecked exception must be thrown when a call to `JMSContext.commit` results in a rollback of the current transaction.

Package javax.jms