jakarta.jms.package.html Maven / Gradle / Ivy
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:
- {@code ConnectionFactory} - the object a client uses to create a
connection with a Jakarta Messaging provider
- {@code 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 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 {@code jakarta.jms} package.
Interfaces common to multiple APIs
The main interfaces common to multiple APIs are as follows:
- {@code Message}, {@code BytesMessage}, {@code MapMessage}, {@code ObjectMessage}, {@code StreamMessage} and {@code TextMessage} -
a message sent to or received from a Jakarta Messaging provider.
- {@code Queue} - an administered object that encapsulates the identity of a message destination for point-to-point messaging
- {@code Topic} - an administered object that encapsulates the identity of a message destination for pub/sub messaging.
- {@code Destination} - the common supertype of {@code Queue} and {@code Topic}
Classic API interfaces
The main interfaces provided by the classic API are as follows:
- {@code ConnectionFactory} - an administered object used by a client to create a {@code Connection}. This interface is also used by the simplified API.
- {@code Connection} - an active connection to a Jakarta Messaging provider
- {@code Session} - a single-threaded context for sending and receiving messages
- {@code MessageProducer} - an object created by a Session that is used for sending messages to a queue or topic
- {@code 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:
- {@code ConnectionFactory} - an administered object used by a client to create a {@code JMSContext}. This interface is also used by the classic API.
- {@code JMSContext} - an active connection to a Jakarta Messaging provider and a single-threaded context for sending and receiving messages
- {@code JMSProducer} - an object created by a {@code JMSContext} that is used for sending messages to a queue or topic
- {@code JMSConsumer} - an object created by a {@code 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 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:
- {@code QueueConnectionFactory} - an administered object used by a client to create a {@code QueueConnection}.
- {@code QueueConnection} - an active connection to a Jakarta Messaging provider
- {@code QueueSession} - a single-threaded context for sending and receiving messages
- {@code QueueSender} - an object created by a {@code QueueSession} that is used for sending messages to a queue
- {@code QueueReceiver} - an object created by a {@code 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:
- {@code TopicConnectionFactory} - an administered object used by a client to create a {@code TopicConnection}.
- {@code TopicConnection} - an active connection to a Jakarta Messaging provider
- {@code TopicSession} - a single-threaded context for sending and receiving messages
- {@code TopicPublisher} - an object created by a {@code TopicSession} that is used for sending messages to a topic
- {@code TopicSubscriber} - an object created by a {@code 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 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 {@code ConnectionFactory} object
- Use JNDI to find one or more {@code Destination} objects
- Use the ConnectionFactory to create a Jakarta Messaging {@code Connection} object with message delivery inhibited
- Use the Connection to create one or more Jakarta Messaging {@code Session} objects
- Use a Session and the Destinations to create the {@code MessageProducer} and {@code MessageConsumer} objects needed
- Tell the {@code 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 {@code ConnectionFactory} object
- Use JNDI to find one or more {@code Destination} objects
- Use the {@code ConnectionFactory} to create a {@code JMSContext} object
- Use the {@code JMSContext} to create the {@code JMSProducer} and {@code JMSConsumer} 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