Oracle GlassFish(tm) Server Message Queue
5.0

Package 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.

See:
          Description

Interface Summary
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 JMS 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 JMS API are PERSISTENT and NON_PERSISTENT.
Destination A Destination object encapsulates a provider-specific address.
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.
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.
JMSContext A JMSContext is the main interface in the simplified JMS API introduced for JMS 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 JMS 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 JMS provider.
QueueConnectionFactory A client uses a QueueConnectionFactory object to create QueueConnection objects with a point-to-point JMS 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 JMS 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 JMS provider.
TopicConnectionFactory A client uses a TopicConnectionFactory object to create TopicConnection objects with a publish/subscribe JMS 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 JMS 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 JMS 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. which can be used to create TopicSubscriber and TopicPublisher objects (optional).
 

Class Summary
QueueRequestor The QueueRequestor helper class simplifies making service requests.
TopicRequestor The TopicRequestor helper class simplifies making service requests.
 

Exception Summary
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 JMS client attempts to give a provider a message selector with invalid syntax.
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.
JMSException This is the root class of all checked exceptions in the JMS API.
JMSRuntimeException This is the root class of all unchecked exceptions in the JMS 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 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.
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.
MessageNotReadableException This exception must be thrown when a JMS client attempts to read a write-only message.
MessageNotWriteableException This exception must be thrown when a JMS client attempts to write to a read-only message.
MessageNotWriteableRuntimeException This unchecked exception must be thrown when a JMS 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 Types Summary
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.
JMSConnectionFactoryDefinition An application may use this annotation to specify a JMS 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 JMS 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.
 

Package javax.jms Description

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:

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:

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:

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:

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:

Classic API interfaces

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

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:

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:

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

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:

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

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

Package Specification

Java Message Service 2.0 specification

Related Documentation

Java Platform, Enterprise Edition (Java EE) Technical Documentation


Oracle GlassFish(tm) Server Message Queue
5.0

Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.