See: Description
Interface | Description |
---|---|
BytesMessage |
A
BytesMessage object is used to send a message containing a stream of uninterpreted bytes. |
CompletionListener |
A
CompletionListener is implemented by the application and may be specified when a message is sent
asynchronously. |
Connection |
A
Connection object is a client's active connection to its Jakarta Messaging provider. |
ConnectionConsumer |
For application servers,
Connection objects provide a special facility for creating a
ConnectionConsumer (optional). |
ConnectionFactory |
A
ConnectionFactory object encapsulates a set of connection configuration parameters that has been defined by
an administrator. |
ConnectionMetaData |
A
ConnectionMetaData object provides information describing the Connection object. |
DeliveryMode |
The delivery modes supported by the Jakarta Messaging API are
PERSISTENT and NON_PERSISTENT . |
Destination |
A
Destination object encapsulates a provider-specific address. |
ExceptionListener |
If a Jakarta Messaging provider detects a serious problem with a
Connection object, it informs the Connection
object's ExceptionListener , if one has been registered. |
JMSConsumer |
A client using the simplified Jakarta Messaging API introduced for Jakarta Messaging 2.0 uses a
JMSConsumer object to receive messages
from a queue or topic. |
JMSContext |
A
JMSContext is the main interface in the simplified Jakarta Messaging API introduced for Jakarta Messaging 2.0. |
JMSProducer |
A
JMSProducer is a simple object used to send messages on behalf of a JMSContext . |
MapMessage |
A
MapMessage object is used to send a set of name-value pairs. |
Message |
The
Message interface is the root interface of all Jakarta Messaging messages. |
MessageConsumer |
A client uses a
MessageConsumer object to receive messages from a destination. |
MessageListener |
A
MessageListener object is used to receive asynchronously delivered messages. |
MessageProducer |
A client uses a
MessageProducer object to send messages to a destination. |
ObjectMessage |
An
ObjectMessage object is used to send a message that contains a serializable object in the Java programming
language ("Java object"). |
Queue |
A
Queue object encapsulates a provider-specific queue name. |
QueueBrowser |
A client uses a
QueueBrowser object to look at messages on a queue without removing them. |
QueueConnection |
A
QueueConnection object is an active connection to a point-to-point Jakarta Messaging provider. |
QueueConnectionFactory |
A client uses a
QueueConnectionFactory object to create QueueConnection objects with a point-to-point
Jakarta Messaging provider. |
QueueReceiver |
A client uses a
QueueReceiver object to receive messages that have been delivered to a queue. |
QueueSender |
A client uses a
QueueSender object to send messages to a queue. |
QueueSession |
A
QueueSession object provides methods for creating QueueReceiver , QueueSender ,
QueueBrowser , and TemporaryQueue objects. |
ServerSession |
A
ServerSession object is an application server object that is used by a server to associate a thread with a
Jakarta Messaging session (optional). |
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). |
Session |
A
Session object is a single-threaded context for producing and consuming messages. |
StreamMessage |
A
StreamMessage object is used to send a stream of primitive types in the Java programming language. |
TemporaryQueue |
A
TemporaryQueue object is a unique Queue object created for the duration of a Connection . |
TemporaryTopic |
A
TemporaryTopic object is a unique Topic object created for the duration of a Connection . |
TextMessage |
A
TextMessage object is used to send a message containing a java.lang.String . |
Topic |
A
Topic object encapsulates a provider-specific topic name. |
TopicConnection |
A
TopicConnection object is an active connection to a publish/subscribe Jakarta Messaging provider. |
TopicConnectionFactory |
A client uses a
TopicConnectionFactory object to create TopicConnection objects with a
publish/subscribe Jakarta Messaging provider. |
TopicPublisher |
A client uses a
TopicPublisher object to publish messages on a topic. |
TopicSession |
A
TopicSession object provides methods for creating TopicPublisher , TopicSubscriber , and
TemporaryTopic objects. |
TopicSubscriber |
A client uses a
TopicSubscriber object to receive messages that have been published to a topic. |
XAConnection |
The
XAConnection interface extends the capability of Connection by providing an XASession
(optional). |
XAConnectionFactory |
The
XAConnectionFactory interface is a base interface for the XAQueueConnectionFactory and
XATopicConnectionFactory interfaces. |
XAJMSContext |
The
XAJMSContext interface extends the capability of JMSContext by adding access to a Jakarta Messaging provider's
support for the Java Transaction API (JTA) (optional). |
XAQueueConnection |
An
XAQueueConnection provides the same create options as QueueConnection (optional). |
XAQueueConnectionFactory |
An
XAQueueConnectionFactory provides the same create options as a QueueConnectionFactory (optional). |
XAQueueSession |
An
XAQueueSession provides a regular QueueSession , which can be used to create QueueReceiver ,
QueueSender , and QueueBrowser objects (optional). |
XASession |
The
XASession interface extends the capability of Session by adding access to a Jakarta Messaging provider's
support for the Java Transaction API (JTA) (optional). |
XATopicConnection |
An
XATopicConnection provides the same create options as TopicConnection (optional). |
XATopicConnectionFactory |
An
XATopicConnectionFactory provides the same create options as a TopicConnectionFactory (optional). |
XATopicSession |
An
XATopicSession provides a regular TopicSession . |
Class | Description |
---|---|
QueueRequestor |
The
QueueRequestor helper class simplifies making service requests. |
TopicRequestor |
The
TopicRequestor helper class simplifies making service requests. |
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 a
IllegalStateRuntimeException 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 a
InvalidClientIDException 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 a
InvalidDestinationException 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 a
InvalidSelectorException 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 a
JMSSecurityException to be thrown. |
MessageEOFException |
This exception must be thrown when an unexpected end of stream has been reached when a
StreamMessage or
BytesMessage 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 a
MessageFormatException 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 to
Session.commit results in a rollback of the current transaction. |
TransactionRolledBackRuntimeException |
This unchecked exception must be thrown when a call to
JMSContext.commit results in a rollback of the current
transaction. |
Annotation Type | Description |
---|---|
JMSConnectionFactory |
This annotation may be used on a field to specify the JNDI lookup name of a
javax.jms.ConnectionFactory to be
used when injecting a javax.jms.JMSContext object. |
JMSConnectionFactoryDefinition |
An application may use this annotation to specify a Jakarta Messaging
ConnectionFactory resource that it requires in its operational environment. |
JMSConnectionFactoryDefinitions |
Specifies one or more
JMSConnectionFactoryDefinition annotations. |
JMSDestinationDefinition |
An application may use this annotation to specify a Jakarta Messaging
Destination resource that it requires in its operational environment. |
JMSDestinationDefinitions |
Specifies one or more
JMSDestinationDefinition annotations. |
JMSPasswordCredential |
This annotation may be used to specify the userName and password to be used when injecting a
javax.jms.JMSContext object. |
JMSSessionMode |
This annotation may be used to specify the session mode to be used when injecting a
javax.jms.JMSContext
object. |
The Jakarta Messaging API provides a common way for Java programs to create, send, receive and read an enterprise messaging system's messages.
A Jakarta Messaging application is composed of the following parts:
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 receivesAdministered 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.
Jakarta Messaging supports two styles of messaging:
These two styles represent two of the dominant approaches to messaging currently in use.
For historical reasons Jakarta Messaging offers four alternative sets of interfaces for sending and receiving messages:
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 javax.jms
package.
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 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 of Queue
and Topic
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 Jakarta Messaging 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
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 Jakarta Messaging 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
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 a QueueConnection
.
QueueConnection
- an active connection to a Jakarta Messaging 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
TopicConnectionFactory
- an administered object used by a client to create a TopicConnection
.
TopicConnection
- an active connection to a Jakarta Messaging 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
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.
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.
A typical Jakarta Messaging client using the classic API executes the following Jakarta Messaging setup procedure:
ConnectionFactory
objectDestination
objectsConnection
object with message delivery inhibitedSession
objectsMessageProducer
and MessageConsumer
objects neededConnection
to start delivery of messagesIn contrast, a typical Jakarta Messaging client using the simplified API does the following:
ConnectionFactory
objectDestination
objectsConnectionFactory
to create a JMSContext
objectJMSContext
to create the JMSProducer
and JMSConsumer
objects needed.At this point a client has the basic Jakarta Messaging setup needed to produce and consume messages.
Jakarta Messaging 2.0 specification
Jakarta Enterprise Edition Technical Documentation
Copyright © 2019 JBoss by Red Hat. All rights reserved.