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.

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

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 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 JMS 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

The JMS specification defines two styles of messaging: the point-to-point (PTP) or the publish-and-subscribe (Pub/Sub). These styles can be combined in a single application, or a given application can use just one of these styles.

The JMS API defines these two styles because they represent two of the dominant approaches to messaging currently in use. While the domains have many similarities, they also have some differences. JMS provides a unified programming interface to allow the client programmer to easily send and receive message using either domain, but the client programmer must also be aware of the differences between the domains. The key differences relate to how message persistence is handled, and the meaning of certain message attributes.

JMS Interfaces

In earlier versions of JMS, there were separate class hierarchies for the pub/sub and point-to-point programming models that had to be used. These class hierarchies are retained to support backward compatibility with earlier versions of the JMS API, but client developers are encouraged to use the common interfaces.

Relationship of PTP and Pub/Sub interfaces

JMS Common	PTP Domain	Pub/Sub Domain
ConnectionFactory	QueueConnectionFactory	TopicConnectionFactory
Connection	QueueConnection	TopicConnection
Destination	Queue	Topic
Session	QueueSession	TopicSession
MessageProducer	QueueSender	TopicPublisher
MessageConsumer	QueueReceiver	TopicSubscriber

The following provides a brief definition of these JMS concepts. See the PTP and Pub/Sub chapters of the JMS specification 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. At this point, message delivery is inhibited
• Use the Connection to create one or more JMS Sessions
• Use a Session and the Destinations to create the MessageProducers and MessageConsumers needed
• Start message delivery for the Connection. Messages will be delivered 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.1

Related Documentation

Java Message Service Tutorial

A client marks a message as persistent if it feels that the application will have problems if the message is lost in transit. A client marks a message as non-persistent if an occasional lost message is tolerable.

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.

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.

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

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

This is the root class of all JMS API exceptions.

It provides the following information:

• A provider-specific string describing the error.

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

This exception must be thrown when an unexpected end of stream has been reached when a StreamMessage or BytesMessage is being read.

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.

Each session must insure that it passes messages serially to the listener.

This exception must be thrown when a JMS client attempts to read a write-only message.

This exception must be thrown when a JMS client attempts to write to a read-only message.

The getEnumeration method returns a java.util.Enumeration that is used to scan the queue's messages.

QueueConnectionFactory can be used to create a QueueConnection, from which specialized queue-related objects can be created.

Although it is possible to have multiple QueueReceivers for the same queue, the JMS API does not define how messages are distributed between the QueueReceivers.

If a QueueReceiver specifies a message selector, the messages that are not selected remain on the queue.

The QueueRequestor constructor is given a non-transacted QueueSession and a destination Queue.

Normally, the Queue is specified when a QueueSender is created.

If there are messages that have been received but not acknowledged when a QueueSession terminates, these messages will be retained and redelivered when a consumer next accesses the queue.

A QueueSession is used for creating Point-to-Point specific objects.

This exception is thrown when a provider is unable to allocate the resources required by a method.

A ServerSession implements two methods:

• getSession - returns the ServerSession's JMS session.
• start - starts the execution of the ServerSession thread and results in the execution of the JMS session's run method.

A ConnectionConsumer implemented by a JMS provider uses a ServerSession to process one or more messages that have arrived.

Its only method is getServerSession.

A Session object is a single-threaded context for producing and consuming messages.

This message type can be used to transport text-based messages, including those with XML content.

When a client receives a TextMessage, it is in read-only mode.

A TopicConnectionFactory can be used to create a TopicConnection, from which specialized topic-related objects can be created.

The TopicRequestor constructor is given a non-transacted TopicSession and a destination Topic.

This exception is thrown when an operation is invalid because a transaction is in progress.

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

The XAConnection interface is optional.

Some application servers provide support for grouping JTS capable resource use into a distributed transaction (optional).

The XATopicConnectionFactory interface is optional.

The XAQueueSession interface is optional.

The XATopicConnectionFactory interface is optional.

The XATopicSession interface is optional.