Java 2 Platform EE v1.3: Package javax.jms - Java Platform, Enterprise Edition v1.3.1 API Specifications

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV PACKAGE NEXT PACKAGE

FRAMES NO FRAMES

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.

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.

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

TemporaryTopic A TemporaryTopic object is a unique Topic object created for the duration of a TopicConnection.

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.

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.

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.

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.

InvalidDestinationException This exception must be thrown when a destination either is not understood by a provider or is no longer valid.

InvalidSelectorException This exception must be thrown when a JMS client attempts to give a provider a message selector with invalid syntax.

JMSException This is the root class of all JMS API exceptions.

JMSSecurityException This exception must be thrown when a provider rejects a user name/password submitted by a client.

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.

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.

ResourceAllocationException This 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.

TransactionRolledBackException This exception must be thrown when a call to Session.commit results in a rollback of the current transaction.

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:

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

It is expected that JMS providers will differ significantly in their underlying messaging technology. It is also expected there will be major differences in how a provider's system is installed and administered.

If JMS clients are 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 customized 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 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 in a Java Naming and Directory Interface^TM (JNDI) namespace by an administrator. 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

A JMS application uses either the point-to-point (PTP) or the publish-and-subscribe (Pub/Sub) style of messaging. Nothing prevents these styles from being combined in a single application; however, the JMS API focuses on applications that use one or the other.

The JMS API defines these two styles because they represent the two dominant approaches to messaging currently in use. Since many messaging systems only support one of these styles, the JMS API provides a separate domain for each and defines compliance for each domain.

JMS Interfaces

The JMS API is based on a set of common messaging concepts. Each JMS messaging domain - PTP and Pub/Sub - defines a customized set of interfaces for these concepts.

**Relationship of PTP and Pub/Sub interfaces**
JMS Parent	PTP Domain	Pub/Sub Domain
ConnectionFactory	QueueConnectionFactory	TopicConnectionFactory
Connection	QueueConnection	TopicConnection
Destination	Queue	Topic
Session	QueueSession	TopicSession
MessageProducer	QueueSender	TopicPublisher
MessageConsumer	QueueReceiver, QueueBrowser	TopicSubscriber

The following provides a brief definition of these JMS concepts. See the PTP and Pub/Sub chapters for more information.

ConnectionFactory - an administered object used by a client to create a Connection
Connection - an active connection to a JMS provider
Destination - an administered object that encapsulates the identity of a message destination
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 destination
MessageConsumer - an object created by a Session that is used for receiving messages sent to a destination

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 the JMS API 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 executes the following 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 with message delivery inhibited
Use the Connection to create one or more JMS Sessions
Use a Session and the Destinations to create the MessageProducers and MessageConsumers needed
Enable the Connection to start delivering messages to MessageConsumers

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

Package Specification

Java Message Service Specification - Version 1.0.2

Interface Summary
*BytesMessage*	A `BytesMessage` object is used to send a message containing a stream of uninterpreted bytes.
*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.
*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 `QueueConnection`.
*TemporaryTopic*	A `TemporaryTopic` object is a unique `Topic` object created for the duration of a `TopicConnection`.
*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.
*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`.

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.
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.
InvalidDestinationException	This exception must be thrown when a destination either is not understood by a provider or is no longer valid.
InvalidSelectorException	This exception must be thrown when a JMS client attempts to give a provider a message selector with invalid syntax.
JMSException	This is the root class of all JMS API exceptions.
JMSSecurityException	This exception must be thrown when a provider rejects a user name/password submitted by a client.
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.
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.
ResourceAllocationException	This 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.
TransactionRolledBackException	This exception must be thrown when a call to `Session.commit` results in a rollback of the current transaction.