Package jakarta.jms
The Jakarta Messaging API provides a common way for Java programs to create, send, receive and read an enterprise messaging system's messages.
Jakarta Messaging Applications
A Jakarta Messaging application is composed of the following parts:
- Jakarta Messaging provider - a messaging system that implements the Jakarta Messaging API in addition to the other administrative and control functionality required of a full-featured messaging product
- Jakarta Messaging 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 Jakarta Messaging provider
- Non-Jakarta Messaging clients - clients that use a message system's native client API instead of the Jakarta Messaging API. If the application predated the availability of the Jakarta Messaging API, it is likely that it will include both Jakarta Messaging clients and non-Jakarta Messaging clients.
Administration
Jakarta Messaging providers differ significantly in their implementations of underlying messaging technology. There are also major differences in how a Jakarta Messaging provider's system is installed and administered.
For Jakarta Messaging clients to be portable, they must be isolated from these proprietary aspects of a provider. This is done by defining Jakarta Messaging administered objects that are created and customised by a provider's administrator and later used by clients. The client uses them through Jakarta Messaging interfaces that are portable. The administrator creates them using provider-specific facilities.
There are two types of Jakarta Messaging administered objects:
ConnectionFactory
- the object a client uses to create a connection with a Jakarta Messaging providerDestination
- 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 Jakarta Messaging client typically notes in its documentation the Jakarta Messaging administered objects it requires and how the JNDI names of these objects should be provided to it.
Two Messaging Styles
Jakarta Messaging 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.
Jakarta Messaging APIs
For historical reasons Jakarta Messaging offers four alternative sets of interfaces for sending and receiving messages:
- Java Message Service 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 Jakarta Messaging for reasons of backwards compatibility they should be considered to be completely superseded by the later APIs.
- Java Message Service 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.
- Jakarta Messaging 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 Jakarta Messaging 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 jakarta.jms
package.
Interfaces common to multiple APIs
The main interfaces common to multiple APIs are as follows:
Message
,BytesMessage
,MapMessage
,ObjectMessage
,StreamMessage
andTextMessage
- a message sent to or received from a Jakarta Messaging provider.Queue
- an administered object that encapsulates the identity of a message destination for point-to-point messagingTopic
- an administered object that encapsulates the identity of a message destination for pub/sub messaging.Destination
- the common supertype ofQueue
andTopic
Classic API interfaces
The main interfaces provided by the classic API are as follows:ConnectionFactory
- an administered object used by a client to create aConnection
. This interface is also used by the simplified API.Connection
- an active connection to a Jakarta Messaging providerSession
- a single-threaded context for sending and receiving messagesMessageProducer
- an object created by a Session that is used for sending messages to a queue or topicMessageConsumer
- 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 aJMSContext
. This interface is also used by the classic API.JMSContext
- an active connection to a Jakarta Messaging provider and a single-threaded context for sending and receiving messagesJMSProducer
- an object created by aJMSContext
that is used for sending messages to a queue or topicJMSConsumer
- an object created by aJMSContext
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 Jakarta Messaging 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 aQueueConnection
.QueueConnection
- an active connection to a Jakarta Messaging providerQueueSession
- a single-threaded context for sending and receiving messagesQueueSender
- an object created by aQueueSession
that is used for sending messages to a queueQueueReceiver
- an object created by aQueueSession
that is used for receiving messages sent to a queue
TopicConnectionFactory
- an administered object used by a client to create aTopicConnection
.TopicConnection
- an active connection to a Jakarta Messaging providerTopicSession
- a single-threaded context for sending and receiving messagesTopicPublisher
- an object created by aTopicSession
that is used for sending messages to a topicTopicSubscriber
- an object created by aTopicSession
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 Jakarta Messaging client; that is, a Jakarta Messaging provider has received a message and has given it to its client. Since Jakarta Messaging 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 Jakarta Messaging provider for delivery to a destination.
Developing a Jakarta Messaging Application
Broadly speaking, a Jakarta Messaging application is one or more Jakarta Messaging clients that exchange messages. The application may also involve non-Jakarta Messaging clients; however, these clients use the Jakarta Messaging provider's native API in place of the Jakarta Messaging API.
A Jakarta Messaging application can be architected and deployed as a unit. In many cases, Jakarta Messaging 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-Jakarta Messaging part of the application.
Developing a Jakarta Messaging Client
A typical Jakarta Messaging client using the classic API executes the following Jakarta Messaging setup procedure:
- Use JNDI to find a
ConnectionFactory
object - Use JNDI to find one or more
Destination
objects - Use the ConnectionFactory to create a Jakarta Messaging
Connection
object with message delivery inhibited - Use the Connection to create one or more Jakarta Messaging
Session
objects - Use a Session and the Destinations to create the
MessageProducer
andMessageConsumer
objects needed - Tell the
Connection
to start delivery of messages
In contrast, a typical Jakarta Messaging 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 aJMSContext
object - Use the
JMSContext
to create theJMSProducer
andJMSConsumer
objects needed. - Delivery of message is started automatically
At this point a client has the basic Jakarta Messaging setup needed to produce and consume messages.
Package Specification
Jakarta Messaging 3.1 specification
Related Documentation
Jakarta Enterprise Edition Technical Documentation
-
Interface Summary Interface Description BytesMessage ABytesMessage
object is used to send a message containing a stream of uninterpreted bytes.CompletionListener ACompletionListener
is implemented by the application and may be specified when a message is sent asynchronously.Connection AConnection
object is a client's active connection to its Jakarta Messaging provider.ConnectionConsumer For application servers,Connection
objects provide a special facility for creating aConnectionConsumer
(optional).ConnectionFactory AConnectionFactory
object encapsulates a set of connection configuration parameters that has been defined by an administrator.ConnectionMetaData AConnectionMetaData
object provides information describing theConnection
object.DeliveryMode The delivery modes supported by the Jakarta Messaging API arePERSISTENT
andNON_PERSISTENT
.Destination ADestination
object encapsulates a provider-specific address.ExceptionListener If a Jakarta Messaging provider detects a serious problem with aConnection
object, it informs theConnection
object'sExceptionListener
, if one has been registered.JMSConsumer A client using the simplified Jakarta Messaging API introduced for Jakarta Messaging 2.0 uses aJMSConsumer
object to receive messages from a queue or topic.JMSContext AJMSContext
is the main interface in the simplified Jakarta Messaging API introduced for Jakarta Messaging 2.0.JMSProducer AJMSProducer
is a simple object used to send messages on behalf of aJMSContext
.MapMessage AMapMessage
object is used to send a set of name-value pairs.Message TheMessage
interface is the root interface of all Jakarta Messaging messages.MessageConsumer A client uses aMessageConsumer
object to receive messages from a destination.MessageListener AMessageListener
object is used to receive asynchronously delivered messages.MessageProducer A client uses aMessageProducer
object to send messages to a destination.ObjectMessage AnObjectMessage
object is used to send a message that contains a serializable object in the Java programming language ("Java object").Queue AQueue
object encapsulates a provider-specific queue name.QueueBrowser A client uses aQueueBrowser
object to look at messages on a queue without removing them.QueueConnection AQueueConnection
object is an active connection to a point-to-point Jakarta Messaging provider.QueueConnectionFactory A client uses aQueueConnectionFactory
object to createQueueConnection
objects with a point-to-point Jakarta Messaging provider.QueueReceiver A client uses aQueueReceiver
object to receive messages that have been delivered to a queue.QueueSender A client uses aQueueSender
object to send messages to a queue.QueueSession AQueueSession
object provides methods for creatingQueueReceiver
,QueueSender
,QueueBrowser
, andTemporaryQueue
objects.ServerSession AServerSession
object is an application server object that is used by a server to associate a thread with a Jakarta Messaging session (optional).ServerSessionPool AServerSessionPool
object is an object implemented by an application server to provide a pool ofServerSession
objects for processing the messages of aConnectionConsumer
(optional).Session ASession
object is a single-threaded context for producing and consuming messages.StreamMessage AStreamMessage
object is used to send a stream of primitive types in the Java programming language.TemporaryQueue ATemporaryQueue
object is a uniqueQueue
object created for the duration of aConnection
.TemporaryTopic ATemporaryTopic
object is a uniqueTopic
object created for the duration of aConnection
.TextMessage ATextMessage
object is used to send a message containing ajava.lang.String
.Topic ATopic
object encapsulates a provider-specific topic name.TopicConnection ATopicConnection
object is an active connection to a publish/subscribe Jakarta Messaging provider.TopicConnectionFactory A client uses aTopicConnectionFactory
object to createTopicConnection
objects with a publish/subscribe Jakarta Messaging provider.TopicPublisher A client uses aTopicPublisher
object to publish messages on a topic.TopicSession ATopicSession
object provides methods for creatingTopicPublisher
,TopicSubscriber
, andTemporaryTopic
objects.TopicSubscriber A client uses aTopicSubscriber
object to receive messages that have been published to a topic.XAConnection TheXAConnection
interface extends the capability ofConnection
by providing anXASession
(optional).XAConnectionFactory TheXAConnectionFactory
interface is a base interface for theXAQueueConnectionFactory
andXATopicConnectionFactory
interfaces.XAJMSContext TheXAJMSContext
interface extends the capability ofJMSContext
by adding access to a Jakarta Messaging provider's support for the Java Transaction API (JTA) (optional).XAQueueConnection AnXAQueueConnection
provides the same create options asQueueConnection
(optional).XAQueueConnectionFactory AnXAQueueConnectionFactory
provides the same create options as aQueueConnectionFactory
(optional).XAQueueSession AnXAQueueSession
provides a regularQueueSession
, which can be used to createQueueReceiver
,QueueSender
, andQueueBrowser
objects (optional).XASession TheXASession
interface extends the capability ofSession
by adding access to a Jakarta Messaging provider's support for the Java Transaction API (JTA) (optional).XATopicConnection AnXATopicConnection
provides the same create options asTopicConnection
(optional).XATopicConnectionFactory AnXATopicConnectionFactory
provides the same create options as aTopicConnectionFactory
(optional).XATopicSession AnXATopicSession
provides a regularTopicSession
. -
Class Summary Class Description QueueRequestor TheQueueRequestor
helper class simplifies making service requests.TopicRequestor TheTopicRequestor
helper class simplifies making service requests. -
Exception Summary Exception Description 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.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 aIllegalStateRuntimeException
to be thrown.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.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 aInvalidClientIDException
to be thrown.InvalidDestinationException This exception must be thrown when a destination either is not understood by a provider or is no longer valid.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 aInvalidDestinationException
to be thrown.InvalidSelectorException This exception must be thrown when a Jakarta Messaging client attempts to give a provider a message selector with invalid syntax.InvalidSelectorRuntimeException This unchecked exception must be thrown when a Jakarta Messaging client attempts to give a provider a message selector with invalid syntax, and the method signature does not permit aInvalidSelectorException
to be thrown.JMSException This is the root class of all checked exceptions in the Jakarta Messaging API.JMSRuntimeException This is the root class of all unchecked exceptions in the Jakarta Messaging API.JMSSecurityException This exception must be thrown when a provider rejects a user name/password submitted by a client.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 aJMSSecurityException
to be thrown.MessageEOFException This exception must be thrown when an unexpected end of stream has been reached when aStreamMessage
orBytesMessage
is being read.MessageFormatException This exception must be thrown when a Jakarta Messaging client attempts to use a data type not supported by a message or attempts to read data in a message as the wrong type.MessageFormatRuntimeException This unchecked exception must be thrown when a Jakarta Messaging 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 aMessageFormatException
to be thrown.MessageNotReadableException This exception must be thrown when a Jakarta Messaging client attempts to read a write-only message.MessageNotWriteableException This exception must be thrown when a Jakarta Messaging client attempts to write to a read-only message.MessageNotWriteableRuntimeException This unchecked exception must be thrown when a Jakarta Messaging client attempts to write to a read-only message.ResourceAllocationException This exception is thrown when a provider is unable to allocate the resources required by a method.ResourceAllocationRuntimeException This unchecked exception is thrown when a provider is unable to allocate the resources required by a method.TransactionInProgressException This exception is thrown when an operation is invalid because a transaction is in progress.TransactionInProgressRuntimeException This unchecked exception is thrown when an operation is invalid because a transaction is in progress.TransactionRolledBackException This exception must be thrown when a call toSession.commit
results in a rollback of the current transaction.TransactionRolledBackRuntimeException This unchecked exception must be thrown when a call toJMSContext.commit
results in a rollback of the current transaction. -
Annotation Types Summary Annotation Type Description JMSConnectionFactory This annotation may be used on a field to specify the JNDI lookup name of ajakarta.jms.ConnectionFactory
to be used when injecting ajakarta.jms.JMSContext
object.JMSConnectionFactoryDefinition An application may use this annotation to specify a Jakarta MessagingConnectionFactory
resource that it requires in its operational environment.JMSConnectionFactoryDefinitions Specifies one or moreJMSConnectionFactoryDefinition
annotations.JMSDestinationDefinition An application may use this annotation to specify a Jakarta MessagingDestination
resource that it requires in its operational environment.JMSDestinationDefinitions Specifies one or moreJMSDestinationDefinition
annotations.JMSPasswordCredential This annotation may be used to specify the userName and password to be used when injecting ajakarta.jms.JMSContext
object.JMSSessionMode This annotation may be used to specify the session mode to be used when injecting ajakarta.jms.JMSContext
object.