Book Home Java Enterprise in a Nutshell Search this book

Chapter 21. The javax.jms Package

The javax.jms package implements the Java Message Service (JMS), which provides an API for message-based communication between separate Java processes. Message-based communication is asynchronous; a message addressed to a recipient or group is sent, and the recipient receives and acts on the message at some later time. This is different from other network-based communication between clients, like RMI, where the sender of a message waits for a response before continuing.

In the JMS model, clients of a message service send and receive messages through a provider that is responsible for delivering messages. JMS 1.0 provides two models for messaging among clients: point-to-point and publish/subscribe. In point-to-point messaging, a message is created by one client and addressed for a single remote recipient. The provider is handed the message and delivers it to the one recipient targeted by the message. This model revolves around message queues: a message sender queues outgoing messages for delivery and a message recipient queues incoming messages for handling. The interfaces provided in the javax.jms package for point-to-point messaging have "Queue" as their prefix (QueueConnection, QueueSession, etc.). In publish/subscribe messaging, a hierarchical content tree is established. Clients publish messages to specific nodes or topics in the tree, and these messages are delivered to any clients that have subscribed to these nodes. Interfaces related to publish/subscribe messaging have "Topic" as their prefix (TopicConnection, TopicSession, etc.). Point-to-point messaging is analogous to typical email messaging; publish/subscribe messaging works like Internet newsgroups.

In a typical scenario, a JMS client gets a reference to a ConnectionFactory from the JMS provider (usually through a JNDI lookup). The ConnectionFactory creates a Connection to the provider. With the Connection, a client can create Session objects to send and receive messages. Within a single Session, messages are sent and received in a serial order. Once the client has a Session, it can send and receive Message objects composed of a header, optional properties, and a body. Different types of Message objects can hold different contents in their body (e.g., text, binary data, name/value pairs).

Figure 21-1 shows the interfaces in the javax.jms package, while Figure 21-2 shows the classes and exceptions.

figure

Figure 21-1. The interfaces of the javax.jms package

figure

Figure 21-2. The classes and exceptions of the javax.jms package

BytesMessageJMS 1.0
javax.jms

A BytesMessage is a Message that contains an uninterpreted stream of bytes as its body. This is typically used to wrap an existing (non-JMS) message format so that it can be delivered over JMS. Data is written to the message's binary body using its writeXXX() methods and read using its readXXX() methods. Once a BytesMessage has been created (using a series of write calls), the reset() method can put the message into read-only mode. Until this is done, the message is in write-only mode, and the contents cannot be read.

public interface BytesMessage extends Message {
// Public Instance Methods
public abstract boolean readBoolean () throws JMSException;
public abstract byte readByte () throws JMSException;
public abstract int readBytes (byte[ ] value) throws JMSException;
public abstract int readBytes (byte[ ] value, int length) throws JMSException;
public abstract char readChar () throws JMSException;
public abstract double readDouble () throws JMSException;
public abstract float readFloat () throws JMSException;
public abstract int readInt () throws JMSException;
public abstract long readLong () throws JMSException;
public abstract short readShort () throws JMSException;
public abstract int readUnsignedByte () throws JMSException;
public abstract int readUnsignedShort () throws JMSException;
public abstract String readUTF () throws JMSException;
public abstract void reset () throws JMSException;
public abstract void writeBoolean (boolean value) throws JMSException;
public abstract void writeByte (byte value) throws JMSException;
public abstract void writeBytes (byte[ ] value) throws JMSException;
public abstract void writeBytes (byte[ ] value, int offset, int length) throws JMSException;
public abstract void writeChar (char value) throws JMSException;
public abstract void writeDouble (double value) throws JMSException;
public abstract void writeFloat (float value) throws JMSException;
public abstract void writeInt (int value) throws JMSException;
public abstract void writeLong (long value) throws JMSException;
public abstract void writeObject (Object value) throws JMSException;
public abstract void writeShort (short value) throws JMSException;
public abstract void writeUTF (String value) throws JMSException;
}

Hierarchy: (BytesMessage(Message))

Returned By: Session.createBytesMessage()

ConnectionJMS 1.0
javax.jms

A JMS client needs to have a Connection to the JMS provider in order to send or receive messages. The javax.jms.Connection interface for messaging is roughly analogous to the java.sql.Connection interface in JDBC--one connects a client to a messaging service, while the other connects a client to a persistent data service. JMS Connection objects are generally expensive to create, because setup requires network communication with the provider. Thus, a client normally has only one, or very few, Connection objects to its JMS provider.

A Connection can either be in running mode (messages are being sent and received through the connection), or it can be stopped. When a Connection is in stopped mode, it can send messages, but not receive them. A newly created Connection is in stopped mode so that you can finish setting up your client (e.g., creating Session objects; creating MessageConsumer and/or MessageProducer objects). A Connection can be started and stopped using stop() and start() multiple times, if necessary. When you're done with a Connection, you should free up its resources by calling its close() method.

A Connection object creates sessions for message exchanges. The methods for creating sessions are defined by extensions of the Connection interface (QueueConnection and TopicConnection).

public interface Connection {
// Public Instance Methods
public abstract void close () throws JMSException;
public abstract String getClientID () throws JMSException;
public abstract ConnectionMetaData getMetaData () throws JMSException;
public abstract void setClientID (String clientID) throws JMSException;
public abstract void setExceptionListener (ExceptionListener listener) throws JMSException;
public abstract void start () throws JMSException;
public abstract void stop () throws JMSException;
}

Implementations: QueueConnection, TopicConnection

ConnectionConsumerJMS 1.0
javax.jms

A ConnectionConsumer is used in situations where messages need to be read concurrently by multiple agents within the same process (e.g., within an application server running multiple message-based applications). The ConnectionConsumer delivers messages to one or more Session objects that are associated with MessageListener objects for individual clients. It contains a reference to a ServerSessionPool that accesses the Session objects concurrently reading messages. ConnectionConsumer is typically used by an application server to provide a message-handling service for client applications; applications normally don't need to use the interface directly.

public interface ConnectionConsumer {
// Public Instance Methods
public abstract void close () throws JMSException;
public abstract ServerSessionPool getServerSessionPool () throws JMSException;
}

Returned By: QueueConnection.createConnectionConsumer(), TopicConnection.{createConnectionConsumer(), createDurableConnectionConsumer()}

ConnectionFactoryJMS 1.0
javax.jms

A messaging client uses a ConnectionFactory to get a Connection object to a message provider. A ConnectionFactory is usually acquired through a JNDI lookup. The ConnectionFactory interface doesn't define methods for creating Connection objects; these methods are provided by extensions to this interface (e.g., QueueConnectionFactory, TopicConnectionFactory).

public interface ConnectionFactory {
}

Implementations: QueueConnectionFactory, TopicConnectionFactory

ConnectionMetaDataJMS 1.0
javax.jms

The Connection.getMetaData() method returns a ConnectionMetaData object that holds information about the JMS connection, including the version of JMS being used by the provider and version information about the provider itself.

public interface ConnectionMetaData {
// Public Instance Methods
public abstract int getJMSMajorVersion () throws JMSException;
public abstract int getJMSMinorVersion () throws JMSException;
public abstract String getJMSProviderName () throws JMSException;
public abstract String getJMSVersion () throws JMSException;
public abstract int getProviderMajorVersion () throws JMSException;
public abstract int getProviderMinorVersion () throws JMSException;
public abstract String getProviderVersion () throws JMSException;
}

Returned By: javax.jms.Connection.getMetaData()

DeliveryModeJMS 1.0
javax.jms

This interface defines constants that represent delivery modes a JMS provider can support. NON_PERSISTENT delivery implies that a significant failure by the provider before a message can be delivered causes the message to be lost. PERSISTENT delivery mode implies that the provider stores messages to persistent storage, so that the messages survive a crash by the provider. A message sender specifies the delivery mode for a Message in its header, using the Message.setJMSDeliveryMode() method, and the provider is responsible for honoring the delivery mode.

public interface DeliveryMode {
// Public Constants
public static final int NON_PERSISTENT ; =1
public static final int PERSISTENT ; =2
}
DestinationJMS 1.0
javax.jms

A Destination represents a delivery address for a message. This interface is simply a marker interface, without any methods or members, since JMS does not attempt to define an addressing syntax. An implementor of a JMS provider needs to provide implementations of this interface that define its message-addressing syntax. Destination objects might be published by a JMS provider using JNDI. In this case, a JMS client needs to assemble the name of the queue in the syntax expected by the provider and then do a JNDI lookup to get a reference to the Destination.

public interface Destination {
}

Implementations: Queue, Topic

Passed To: Message.{setJMSDestination(), setJMSReplyTo()}

Returned By: Message.{getJMSDestination(), getJMSReplyTo()}

ExceptionListenerJMS 1.0
javax.jms

An ExceptionListener gets asynchronous notification of errors that occur with a Connection to a JMS provider. If a client registers an ExceptionListener with a Connection using the Connection.setExceptionListener() method, the provider calls the onException() method on the ExceptionListener when any error occurs, passing it the exception that describes the error.

public interface ExceptionListener {
// Public Instance Methods
public abstract void onException (JMSException exception);
}

Passed To: javax.jms.Connection.setExceptionListener()

IllegalStateExceptionJMS 1.0
javax.jmsserializable checked

Thrown if a request is made of a provider at a time when the request cannot be satisfied.

public class IllegalStateException extends JMSException {
// Public Constructors
public IllegalStateException (String reason);
public IllegalStateException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->IllegalStateException

InvalidClientIDExceptionJMS 1.0
javax.jmsserializable checked

Thrown by the Connection.setClientID() method when an invalid client ID is given.

public class InvalidClientIDException extends JMSException {
// Public Constructors
public InvalidClientIDException (String reason);
public InvalidClientIDException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->InvalidClientIDException

InvalidDestinationExceptionJMS 1.0
javax.jmsserializable checked

Thrown when the provider encounters a destination it cannot understand or is no longer accessible by the provider (e.g., a topic has been removed from a publish/subscribe context, or a queue associated with a user account has been removed because the account has been closed).

public class InvalidDestinationException extends JMSException {
// Public Constructors
public InvalidDestinationException (String reason);
public InvalidDestinationException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->InvalidDestinationException

InvalidSelectorExceptionJMS 1.0
javax.jmsserializable checked

Thrown when a malformed selector is given to a provider (e.g., as part of a MessageSelector).

public class InvalidSelectorException extends JMSException {
// Public Constructors
public InvalidSelectorException (String reason);
public InvalidSelectorException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->InvalidSelectorException

JMSExceptionJMS 1.0
javax.jmsserializable checked

This is the base class for all JMS-related exceptions. It provides a provider-specific error code and a nested exception that is the source of the error.

public class JMSException extends Exception {
// Public Constructors
public JMSException (String reason);
public JMSException (String reason, String errorCode);
// Public Instance Methods
public String getErrorCode ();
public Exception getLinkedException ();
public void setLinkedException (Exception ex); synchronized
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException

Subclasses: javax.jms.IllegalStateException, InvalidClientIDException, InvalidDestinationException, InvalidSelectorException, JMSSecurityException, MessageEOFException, MessageFormatException, MessageNotReadableException, MessageNotWriteableException, ResourceAllocationException, TransactionInProgressException, TransactionRolledBackException

Passed To: ExceptionListener.onException()

Thrown By: Too many methods to list.

JMSSecurityExceptionJMS 1.0
javax.jmsserializable checked

Thrown by a provider when a request cannot be satisfied for security reasons (e.g., a client-provided name/password fails authentication).

public class JMSSecurityException extends JMSException {
// Public Constructors
public JMSSecurityException (String reason);
public JMSSecurityException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->JMSSecurityException

MapMessageJMS 1.0
javax.jms

A MapMessage has a set of name/value pairs as its message body. The name of a property is a String, and the value is a Java primitive type. There are getXXX() and setXXX() methods for each primitive type, plus getObject() and setObject() methods for situations where the type of the value is not known until runtime. If a property is set to a value of a certain type, it has to be read back using a get method appropriate for that type, according to this table:

If written as:

Can be read as:

boolean

byte

char

short

int

long

float

double

String

byte[]

boolean

X

X

byte

X

X

X

X

X

char

X

X

short

X

X

X

X

int

X

X

X

long

X

X

float

X

X

X

double

X

X

String

X

X

X

X

X

X

X

X

X

byte[]

X

If a value is read using an inappropriate get method, a MessageFormatException is thrown. The getMapNames() methods returns an Enumeration of names for the values in the MapMessage. A client that receives a MapMessage can read only the contents of the message until it calls clearBody() on the message. If a client tries to write values to the message before this, a MessageNotWriteableException is thrown.

public interface MapMessage extends Message {
// Public Instance Methods
public abstract boolean getBoolean (String name) throws JMSException;
public abstract byte getByte (String name) throws JMSException;
public abstract byte[ ] getBytes (String name) throws JMSException;
public abstract char getChar (String name) throws JMSException;
public abstract double getDouble (String name) throws JMSException;
public abstract float getFloat (String name) throws JMSException;
public abstract int getInt (String name) throws JMSException;
public abstract long getLong (String name) throws JMSException;
public abstract java.util.Enumeration getMapNames () throws JMSException;
public abstract Object getObject (String name) throws JMSException;
public abstract short getShort (String name) throws JMSException;
public abstract String getString (String name) throws JMSException;
public abstract boolean itemExists (String name) throws JMSException;
public abstract void setBoolean (String name, boolean value) throws JMSException;
public abstract void setByte (String name, byte value) throws JMSException;
public abstract void setBytes (String name, byte[ ] value) throws JMSException;
public abstract void setBytes (String name, byte[ ] value, int offset, int length) throws JMSException;
public abstract void setChar (String name, char value) throws JMSException;
public abstract void setDouble (String name, double value) throws JMSException;
public abstract void setFloat (String name, float value) throws JMSException;
public abstract void setInt (String name, int value) throws JMSException;
public abstract void setLong (String name, long value) throws JMSException;
public abstract void setObject (String name, Object value) throws JMSException;
public abstract void setShort (String name, short value) throws JMSException;
public abstract void setString (String name, String value) throws JMSException;
}

Hierarchy: (MapMessage(Message))

Returned By: Session.createMapMessage()

MessageJMS 1.0
javax.jms

The Message interface is the base interface for all messages in JMS. A Message is composed of a set of predefined header fields, an optional set of application-specific properties, and a body that contains the content of the message. A set and get method are provided for each header field supported by a JMS message. The possible header fields include:

JMSCorrelationID

A String that identifies another message (e.g., original message for a response) with which this message is related. The ID value is dictated by either the JMS provider or the application.

JMSDeliveryMode

One of the static values of the DeliveryMode interface.

JMSDestination

The target of this message, as a Destination object.

JMSExpiration

The time (in milliseconds since the epoch) when the message will expire. Each client specifies a time-to-live for the messages they send, so this header field is automatically set at send time to the current time plus the client's time-to-live.

JMSMessageID

A unique String identifier for this message. The provider sets this field automatically when a message is sent.

JMSPriority

A value from 0 to 9 (9 is highest) that indicates the urgency of the message. JMS providers are supposed to attempt to deliver messages with a priority from 5 to 9 before attempting to deliver lower-priority messages.

JMSRedelivered

An indicator that the message was delivered to the client earlier but no acknowledgment was received.

JMSReplyTo

A Destination where the receiver can send a reply to the message.

JMSTimestamp

The time (in milliseconds since the epoch) at which a message was given to a JMS provider for sending.

JMSType

A String that indicates the type of the message. There are no standard values for a message's type; they can be provider- or application-specific.

Properties with names prefixed by "JMSX" are reserved for use by the JMS standard.

Properties can be added to a message using the setXXXProperty() methods and read using the getXXXProperty() methods. If a property is written with a value of a given type, it needs to be read from the message according to the following table:

If written as:

Can be read as:

boolean

byte

short

int

long

float

double

String

boolean

X

X

byte

X

X

X

X

X

short

X

X

X

X

int

X

X

X

long

X

X

float

X

X

X

double

X

X

String

X

X

X

X

X

X

X

X

If in invalid get method is used for a property, a MessageFormatException is thrown.

public interface Message {
// Public Constants
public static final int DEFAULT_DELIVERY_MODE ; =-1
public static final int DEFAULT_PRIORITY ; =-1
public static final int DEFAULT_TIME_TO_LIVE ; =-1
// Public Instance Methods
public abstract void acknowledge () throws JMSException;
public abstract void clearBody () throws JMSException;
public abstract void clearProperties () throws JMSException;
public abstract boolean getBooleanProperty (String name) throws JMSException;
public abstract byte getByteProperty (String name) throws JMSException;
public abstract double getDoubleProperty (String name) throws JMSException;
public abstract float getFloatProperty (String name) throws JMSException;
public abstract int getIntProperty (String name) throws JMSException;
public abstract String getJMSCorrelationID () throws JMSException;
public abstract byte[ ] getJMSCorrelationIDAsBytes () throws JMSException;
public abstract int getJMSDeliveryMode () throws JMSException;
public abstract Destination getJMSDestination () throws JMSException;
public abstract long getJMSExpiration () throws JMSException;
public abstract String getJMSMessageID () throws JMSException;
public abstract int getJMSPriority () throws JMSException;
public abstract boolean getJMSRedelivered () throws JMSException;
public abstract Destination getJMSReplyTo () throws JMSException;
public abstract long getJMSTimestamp () throws JMSException;
public abstract String getJMSType () throws JMSException;
public abstract long getLongProperty (String name) throws JMSException;
public abstract Object getObjectProperty (String name) throws JMSException;
public abstract java.util.Enumeration getPropertyNames () throws JMSException;
public abstract short getShortProperty (String name) throws JMSException;
public abstract String getStringProperty (String name) throws JMSException;
public abstract boolean propertyExists (String name) throws JMSException;
public abstract void setBooleanProperty (String name, boolean value) throws JMSException;
public abstract void setByteProperty (String name, byte value) throws JMSException;
public abstract void setDoubleProperty (String name, double value) throws JMSException;
public abstract void setFloatProperty (String name, float value) throws JMSException;
public abstract void setIntProperty (String name, int value) throws JMSException;
public abstract void setJMSCorrelationID (String correlationID) throws JMSException;
public abstract void setJMSCorrelationIDAsBytes (byte[ ] correlationID) throws JMSException;
public abstract void setJMSDeliveryMode (int deliveryMode) throws JMSException;
public abstract void setJMSDestination (Destination destination) throws JMSException;
public abstract void setJMSExpiration (long expiration) throws JMSException;
public abstract void setJMSMessageID (String id) throws JMSException;
public abstract void setJMSPriority (int priority) throws JMSException;
public abstract void setJMSRedelivered (boolean redelivered) throws JMSException;
public abstract void setJMSReplyTo (Destination replyTo) throws JMSException;
public abstract void setJMSTimestamp (long timestamp) throws JMSException;
public abstract void setJMSType (String type) throws JMSException;
public abstract void setLongProperty (String name, long value) throws JMSException;
public abstract void setObjectProperty (String name, Object value) throws JMSException;
public abstract void setShortProperty (String name, short value) throws JMSException;
public abstract void setStringProperty (String name, String value) throws JMSException;
}

Implementations: BytesMessage, MapMessage, ObjectMessage, StreamMessage, TextMessage

Passed To: MessageListener.onMessage(), QueueRequestor.request(), QueueSender.send(), TopicPublisher.publish(), TopicRequestor.request()

Returned By: MessageConsumer.{receive(), receiveNoWait()}, QueueRequestor.request(), Session.createMessage(), TopicRequestor.request()

MessageConsumerJMS 1.0
javax.jms

A JMS client uses a MessageConsumer to receive messages. A client creates a message consumer by specifying a Destination from which to receive messages and an optional message selector that filters messages according to their header fields and property values. The methods for creating MessageConsumer objects are defined in subinterfaces of the Connection interface.

A message selector is a filter string whose syntax is based on the SQL92 conditional expression syntax. See the JMS specification for more details on the syntax of message selectors.

A client can use a MessageConsumer synchronously by polling it with its receive methods or asynchronously by registering a MessageListener with the consumer. When a message arrives that matches the sending Destination and the message selector, the onMessage() method on the registered listener is called.

A MessageConsumer should be freed by calling its close() method, to free up any resources allocated for it by the provider.

public interface MessageConsumer {
// Public Instance Methods
public abstract void close () throws JMSException;
public abstract MessageListener getMessageListener () throws JMSException;
public abstract String getMessageSelector () throws JMSException;
public abstract Message receive () throws JMSException;
public abstract Message receive (long timeOut) throws JMSException;
public abstract Message receiveNoWait () throws JMSException;
public abstract void setMessageListener (MessageListener listener) throws JMSException;
}

Implementations: QueueReceiver, TopicSubscriber

MessageEOFExceptionJMS 1.0
javax.jmsserializable checked

Thrown if the end of a StreamMessage or BytesMessage is reached before it is expected.

public class MessageEOFException extends JMSException {
// Public Constructors
public MessageEOFException (String reason);
public MessageEOFException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->MessageEOFException

MessageFormatExceptionJMS 1.0
javax.jmsserializable checked

Thrown when an attempt is made to read data from a message as the wrong data type or to write data to a message in a type it does not support.

public class MessageFormatException extends JMSException {
// Public Constructors
public MessageFormatException (String reason);
public MessageFormatException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->MessageFormatException

MessageListenerJMS 1.0
javax.jms

A MessageListener is registered by a client with a MessageConsumer, to allow the client to asynchronously receive messages. When the consumer receives a message, the listener's onMessage() method is invoked. The consumer waits until the onMessage() method is complete before delivering the next message.

public interface MessageListener {
// Public Instance Methods
public abstract void onMessage (Message message);
}

Passed To: MessageConsumer.setMessageListener(), Session.setMessageListener()

Returned By: MessageConsumer.getMessageListener(), Session.getMessageListener()

MessageNotReadableExceptionJMS 1.0
javax.jmsserializable checked

Thrown if a client attempts to read data from a write-only message (e.g., a StreamMessage whose contents have not yet been reset).

public class MessageNotReadableException extends JMSException {
// Public Constructors
public MessageNotReadableException (String reason);
public MessageNotReadableException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->MessageNotReadableException

MessageNotWriteableExceptionJMS 1.0
javax.jmsserializable checked

Thrown when an attempt is made to write data to a read-only message (e.g., a received MapMessage that has not yet had its clearBody() method called).

public class MessageNotWriteableException extends JMSException {
// Public Constructors
public MessageNotWriteableException (String reason);
public MessageNotWriteableException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->MessageNotWriteableException

MessageProducerJMS 1.0
javax.jms

A client uses a MessageProducer to send messages. A MessageProducer can be tied to a specific Destination, and any messages sent through the producer are addressed to the Destination specified when it was created. If a Destination is not specified when a MessageProducer is created, a Destination has to provide for each message sent. Methods to create MessageProducer objects are provided by subinterfaces of the Session interface (e.g., TopicSession, QueueSession).

A MessageProducer has a default delivery mode, priority, and time-to-live for messages it sends. There are get and set methods for these default properties. If these properties are specified on a message, they override the defaults of the MessageProducer.

public interface MessageProducer {
// Public Instance Methods
public abstract void close () throws JMSException;
public abstract int getDeliveryMode () throws JMSException;
public abstract boolean getDisableMessageID () throws JMSException;
public abstract boolean getDisableMessageTimestamp () throws JMSException;
public abstract int getPriority () throws JMSException;
public abstract int getTimeToLive () throws JMSException;
public abstract void setDeliveryMode (int deliveryMode) throws JMSException;
public abstract void setDisableMessageID (boolean value) throws JMSException;
public abstract void setDisableMessageTimestamp (boolean value) throws JMSException;
public abstract void setPriority (int deliveryMode) throws JMSException;
public abstract void setTimeToLive (int timeToLive) throws JMSException;
}

Implementations: QueueSender, TopicPublisher

ObjectMessageJMS 1.0
javax.jms

This is a message that contains a single serialized Java object as its body. Only a Serializable object can be used as the body of an ObjectMessage. When an ObjectMessage is received, it is read-only until the clearBody() method is called on it.

public interface ObjectMessage extends Message {
// Public Instance Methods
public abstract Serializable getObject () throws JMSException;
public abstract void setObject (Serializable object) throws JMSException;
}

Hierarchy: (ObjectMessage(Message))

Returned By: Session.createObjectMessage()

QueueJMS 1.0
javax.jms

A Queue is a Destination specific to point-to-point messaging. The Queue has a String name whose syntax is dictated by the provider. Queue objects are created using the createQueue() method on a QueueSession.

public interface Queue extends Destination {
// Public Instance Methods
public abstract String getQueueName () throws JMSException;
public abstract String toString ();
}

Hierarchy: (Queue(Destination))

Implementations: TemporaryQueue

Passed To: QueueConnection.createConnectionConsumer(), QueueRequestor.QueueRequestor(), QueueSender.send(), QueueSession.{createBrowser(), createReceiver(), createSender()}

Returned By: QueueBrowser.getQueue(), QueueReceiver.getQueue(), QueueSender.getQueue(), QueueSession.createQueue()

QueueBrowserJMS 1.0
javax.jms

A QueueBrowser peeks at the contents of a message queue without actually removing messages. A QueueBrowser has an optional message selector that can filter the messages checked for on the queue. QueueBrowser objects are created using the createBrowser() methods on QueueSession.

public interface QueueBrowser {
// Public Instance Methods
public abstract void close () throws JMSException;
public abstract java.util.Enumeration getEnumeration () throws JMSException;
public abstract String getMessageSelector () throws JMSException;
public abstract Queue getQueue () throws JMSException;
}

Returned By: QueueSession.createBrowser()

QueueConnectionJMS 1.0
javax.jms

A QueueConnection is a Connection specific to a point-to-point messaging provider. The QueueConnection allows clients to create QueueSession objects using the createQueueSession() method.

public interface QueueConnection extends javax.jms.Connection {
// Public Instance Methods
public abstract ConnectionConsumer createConnectionConsumer (Queue queue, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException;
public abstract QueueSession createQueueSession (boolean transacted, int acknowledgeMode) throws JMSException;
}

Hierarchy: (QueueConnection(javax.jms.Connection))

Implementations: XAQueueConnection

Returned By: QueueConnectionFactory.createQueueConnection()

QueueConnectionFactoryJMS 1.0
javax.jms

A QueueConnectionFactory is exported by point-to-point providers to allow clients to create QueueConnection objects to the provider. The default createQueueConnection() method creates a connection under the default user identity of the client JVM, while the other constructor accepts a name and password that authenticates the connection request.

public interface QueueConnectionFactory extends ConnectionFactory {
// Public Instance Methods
public abstract QueueConnection createQueueConnection () throws JMSException;
public abstract QueueConnection createQueueConnection (String userName, String password) throws JMSException;
}

Hierarchy: (QueueConnectionFactory(ConnectionFactory))

Implementations: XAQueueConnectionFactory

QueueReceiverJMS 1.0
javax.jms

A QueueReceiver is a MessageConsumer specific to point-to-point messaging. The getQueue() method returns the Queue associated with the receiver. QueueReceiver objects are created using the createReceiver() methods on QueueSession.

public interface QueueReceiver extends MessageConsumer {
// Public Instance Methods
public abstract Queue getQueue () throws JMSException;
}

Hierarchy: (QueueReceiver(MessageConsumer))

Returned By: QueueSession.createReceiver()

QueueRequestorJMS 1.0
javax.jms

QueueRequestor is a utility class provided for situations in which a client wants to send a message to a specific destination and wait for a response. A QueueRequestor is constructed with a QueueSession and a destination Queue, and then its request() method is called with the Message to be sent. The QueueRequestor sets the reply-to destination on the message to a temporary Queue that it creates. It sends the message and waits for a response. The response Message is the return value of the request() method.

public class QueueRequestor {
// Public Constructors
public QueueRequestor (QueueSession session, Queue queue) throws JMSException;
// Public Instance Methods
public void close () throws JMSException;
public Message request (Message message) throws JMSException;
}
QueueSenderJMS 1.0
javax.jms

A QueueSender is a MessageProducer that sends messages in a point-to-point context. QueueSender objects are created using the createQueue() method on QueueSession, specifying a default Queue as the target of messages. A client can override the default message target by using one of the send() methods on the QueueSender that accepts a target Queue. If a send() method is called without a target Queue, and the QueueSender does not have a default target Queue defined (e.g., it was created with a null target Queue), an InvalidDestinationException is thrown.

public interface QueueSender extends MessageProducer {
// Public Instance Methods
public abstract Queue getQueue () throws JMSException;
public abstract void send (Message message) throws JMSException;
public abstract void send (Queue queue, Message message) throws JMSException;
public abstract void send (Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
public abstract void send (Queue queue, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
}

Hierarchy: (QueueSender(MessageProducer))

Returned By: QueueSession.createSender()

QueueSessionJMS 1.0
javax.jmsrunnable

The QueueSession is a Session specific to a point-to-point messaging context. It provides methods for creating point-to-point message consumers (QueueReceiver), producers (QueueSender), and destinations (Queue), as well as utilities objects such as QueueBrowser and TemporaryQueue.

public interface QueueSession extends Session {
// Public Instance Methods
public abstract QueueBrowser createBrowser (Queue queue) throws JMSException;
public abstract QueueBrowser createBrowser (Queue queue, String messageSelector) throws JMSException;
public abstract Queue createQueue (String queueName) throws JMSException;
public abstract QueueReceiver createReceiver (Queue queue) throws JMSException;
public abstract QueueReceiver createReceiver (Queue queue, String messageSelector) throws JMSException;
public abstract QueueSender createSender (Queue queue) throws JMSException;
public abstract TemporaryQueue createTemporaryQueue () throws JMSException;
}

Hierarchy: (QueueSession(Session(Runnable)))

Passed To: QueueRequestor.QueueRequestor()

Returned By: QueueConnection.createQueueSession(), XAQueueSession.getQueueSession()

ResourceAllocationExceptionJMS 1.0
javax.jmsserializable checked

Thrown when a request is made of a provider, and it cannot be completed due to resource issues.

public class ResourceAllocationException extends JMSException {
// Public Constructors
public ResourceAllocationException (String reason);
public ResourceAllocationException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->ResourceAllocationException

ServerSessionJMS 1.0
javax.jms

A ServerSession is used by an application server when it needs to separate Session objects to individual threads, for concurrent access to and handling of flows of messages. The ServerSession represents a JMS Session tied to a thread. A ConnectionConsumer keeps a pool of ServerSession objects, which it handles messages as they arrive. The ConnectionConsumer assigns one or more messages to the Session contained in the ServerSession, and then calls the ServerSession's start() method. The ServerSession calls start() on the Thread for the Session, which eventually calls the run() method of the Session (Session implements the java.lang.Runnable interface).

public interface ServerSession {
// Public Instance Methods
public abstract Session getSession () throws JMSException;
public abstract void start () throws JMSException;
}

Returned By: ServerSessionPool.getServerSession()

ServerSessionPoolJMS 1.0
javax.jms

A ConnectionConsumer uses a ServerSessionPool to manage a pool of ServerSession objects. The ServerSessionPool can manage the pool any way it likes and can block if the pool is exhausted.

public interface ServerSessionPool {
// Public Instance Methods
public abstract ServerSession getServerSession () throws JMSException;
}

Passed To: QueueConnection.createConnectionConsumer(), TopicConnection.{createConnectionConsumer(), createDurableConnectionConsumer()}

Returned By: ConnectionConsumer.getServerSessionPool()

SessionJMS 1.0
javax.jmsrunnable

A Session provides a client with the means for creating messages, message producers, and message consumers. Extensions of Session create type-specific versions of these objects (e.g., QueueSender and TopicPublisher).

Within a Session, messages are sent and received in a serial order. The Session interface also provides facilities for JMS providers that chose to provide transactional support in their Session implementations. A transaction is started when the Session is created. In a messaging context, a transaction consists of a series of message transmissions and receipts. Committing a messaging transaction (by calling commit() on the corresponding Session) causes all pending transmissions to be sent and all pending receipts to be finalized and acknowledged. If a transaction is aborted (by calling the rollback() method on the Session), the outgoing messages are destroyed, and incoming messages are cancelled. A new transaction is started as soon as the current one is committed or rolled back.

public interface Session extends Runnable {
// Public Constants
public static final int AUTO_ACKNOWLEDGE ; =1
public static final int CLIENT_ACKNOWLEDGE ; =2
public static final int DUPS_OK_ACKNOWLEDGE ; =3
// Public Instance Methods
public abstract void close () throws JMSException;
public abstract void commit () throws JMSException;
public abstract BytesMessage createBytesMessage () throws JMSException;
public abstract MapMessage createMapMessage () throws JMSException;
public abstract Message createMessage () throws JMSException;
public abstract ObjectMessage createObjectMessage () throws JMSException;
public abstract ObjectMessage createObjectMessage (Serializable object) throws JMSException;
public abstract StreamMessage createStreamMessage () throws JMSException;
public abstract TextMessage createTextMessage () throws JMSException;
public abstract TextMessage createTextMessage (StringBuffer stringBuffer) throws JMSException;
public abstract MessageListener getMessageListener () throws JMSException;
public abstract boolean getTransacted () throws JMSException;
public abstract void recover () throws JMSException;
public abstract void rollback () throws JMSException;
public abstract void setMessageListener (MessageListener listener) throws JMSException;
}

Hierarchy: (Session(Runnable))

Implementations: QueueSession, TopicSession, XASession

Returned By: ServerSession.getSession()

StreamMessageJMS 1.0
javax.jms

A StreamMessage is a Message whose body consists of a stream of serialized Java primitive data items. It is similar in many ways to a BytesMessage, except that the contents of a StreamMessage are read in the same order they are written by the sender. Otherwise, StreamMessage has a similar set of read/write methods and similar rules about how certain data types are read from the message as BytesMessage.

public interface StreamMessage extends Message {
// Public Instance Methods
public abstract boolean readBoolean () throws JMSException;
public abstract byte readByte () throws JMSException;
public abstract int readBytes (byte[ ] value) throws JMSException;
public abstract char readChar () throws JMSException;
public abstract double readDouble () throws JMSException;
public abstract float readFloat () throws JMSException;
public abstract int readInt () throws JMSException;
public abstract long readLong () throws JMSException;
public abstract Object readObject () throws JMSException;
public abstract short readShort () throws JMSException;
public abstract String readString () throws JMSException;
public abstract void reset () throws JMSException;
public abstract void writeBoolean (boolean value) throws JMSException;
public abstract void writeByte (byte value) throws JMSException;
public abstract void writeBytes (byte[ ] value) throws JMSException;
public abstract void writeBytes (byte[ ] value, int offset, int length) throws JMSException;
public abstract void writeChar (char value) throws JMSException;
public abstract void writeDouble (double value) throws JMSException;
public abstract void writeFloat (float value) throws JMSException;
public abstract void writeInt (int value) throws JMSException;
public abstract void writeLong (long value) throws JMSException;
public abstract void writeObject (Object value) throws JMSException;
public abstract void writeShort (short value) throws JMSException;
public abstract void writeString (String value) throws JMSException;
}

Hierarchy: (StreamMessage(Message))

Returned By: Session.createStreamMessage()

TemporaryQueueJMS 1.0
javax.jms

A TemporaryQueue is a Queue used internally by a QueueConnection.

public interface TemporaryQueue extends Queue {
// Public Instance Methods
public abstract void delete () throws JMSException;
}

Hierarchy: (TemporaryQueue(Queue(Destination)))

Returned By: QueueSession.createTemporaryQueue()

TemporaryTopicJMS 1.0
javax.jms

A TemporaryTopic is a Topic used internally by a TopicConnection.

public interface TemporaryTopic extends Topic {
// Public Instance Methods
public abstract void delete () throws JMSException;
}

Hierarchy: (TemporaryTopic(Topic(Destination)))

Returned By: TopicSession.createTemporaryTopic()

TextMessageJMS 1.0
javax.jms

A TextMessage is a Message whose body is a String. The contents of the message can be retrieved using the getText() method. The text of the message might be simple ASCII, or it could be structured according to a syntax like HTML or XML.

public interface TextMessage extends Message {
// Public Instance Methods
public abstract String getText () throws JMSException;
public abstract void setText (String string) throws JMSException;
}

Hierarchy: (TextMessage(Message))

Returned By: Session.createTextMessage()

TopicJMS 1.0
javax.jms

A Topic is an address for a message in a publish/subscribe context. The Topic interface simply defines a String name for the topic. Providers define how topics are defined and grouped into a hierarchy.

public interface Topic extends Destination {
// Public Instance Methods
public abstract String getTopicName () throws JMSException;
public abstract String toString ();
}

Hierarchy: (Topic(Destination))

Implementations: TemporaryTopic

Passed To: TopicConnection.{createConnectionConsumer(), createDurableConnectionConsumer()}, TopicPublisher.publish(), TopicRequestor.TopicRequestor(), TopicSession.{createDurableSubscriber(), createPublisher(), createSubscriber()}

Returned By: TopicPublisher.getTopic(), TopicSession.createTopic(), TopicSubscriber.getTopic()

TopicConnectionJMS 1.0
javax.jms

A TopicConnection is a Connection to a publish/subscribe-based JMS provider. It provides methods for creating TopicSession objects, as well as ConnectionConsumer objects.

public interface TopicConnection extends javax.jms.Connection {
// Public Instance Methods
public abstract ConnectionConsumer createConnectionConsumer (Topic topic, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException;
public abstract ConnectionConsumer createDurableConnectionConsumer (Topic topic, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException;
public abstract TopicSession createTopicSession (boolean transacted, int acknowledgeMode) throws JMSException;
}

Hierarchy: (TopicConnection(javax.jms.Connection))

Implementations: XATopicConnection

Returned By: TopicConnectionFactory.createTopicConnection()

TopicConnectionFactoryJMS 1.0
javax.jms

A TopicConnectionFactory is exported by publish/subscribe providers to allow clients to create TopicConnection objects to the provider. The default createTopicConnection() method creates a connection under the default user identity of the client JVM, while the other constructor accepts a name and password that authenticates the connection request.

public interface TopicConnectionFactory extends ConnectionFactory {
// Public Instance Methods
public abstract TopicConnection createTopicConnection () throws JMSException;
public abstract TopicConnection createTopicConnection (String userName, String password) throws JMSException;
}

Hierarchy: (TopicConnectionFactory(ConnectionFactory))

Implementations: XATopicConnectionFactory

TopicPublisherJMS 1.0
javax.jms

A TopicPublisher is a MessageProducer specific to a publish/subscribe context. TopicPublisher objects are created using the createPublisher() method on a TopicSession. A TopicPublisher is created with a Topic under which it publishes messages. A client can override the default Topic using one of the publish() methods that accepts a Topic as an argument along with the Message to be sent. Sending a Message without a Topic (i.e., the TopicPublisher was created with a nullTopic, and the Message was sent without specifying a Topic) causes an InvalidDestinationException to be thrown.

public interface TopicPublisher extends MessageProducer {
// Public Instance Methods
public abstract Topic getTopic () throws JMSException;
public abstract void publish (Message message) throws JMSException;
public abstract void publish (Topic topic, Message message) throws JMSException;
public abstract void publish (Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
public abstract void publish (Topic topic, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
}

Hierarchy: (TopicPublisher(MessageProducer))

Returned By: TopicSession.createPublisher()

TopicRequestorJMS 1.0
javax.jms

TopicRequestor is a utility class provided for situations where a client wants to send a message to a specific Topic and wait for a response. The TopicRequestor is constructed with a TopicSession and a destination Topic, and then its request() method is called with the Message to be sent. The TopicRequestor sets the reply-to destination on the message to a temporary Topic it creates. It sends the message and waits for a response. The response Message is the return value of the request() method.

public class TopicRequestor {
// Public Constructors
public TopicRequestor (TopicSession session, Topic topic) throws JMSException;
// Public Instance Methods
public void close () throws JMSException;
public Message request (Message message) throws JMSException;
}
TopicSessionJMS 1.0
javax.jmsrunnable

A TopicSession is a Session specific to a publish/subscribe context. It provides methods for creating publish/subscribe message consumers (TopicSubscriber), message producers (TopicPublisher), and message destinations (Topic). It also has methods for creating utilities objects such as TemporaryTopic.

public interface TopicSession extends Session {
// Public Instance Methods
public abstract TopicSubscriber createDurableSubscriber (Topic topic, String name) throws JMSException;
public abstract TopicSubscriber createDurableSubscriber (Topic topic, String name, String messageSelector, boolean noLocal) throws JMSException;
public abstract TopicPublisher createPublisher (Topic topic) throws JMSException;
public abstract TopicSubscriber createSubscriber (Topic topic) throws JMSException;
public abstract TopicSubscriber createSubscriber (Topic topic, String messageSelector, boolean noLocal) throws JMSException;
public abstract TemporaryTopic createTemporaryTopic () throws JMSException;
public abstract Topic createTopic (String topicName) throws JMSException;
public abstract void unsubscribe (String name) throws JMSException;
}

Hierarchy: (TopicSession(Session(Runnable)))

Passed To: TopicRequestor.TopicRequestor()

Returned By: TopicConnection.createTopicSession(), XATopicSession.getTopicSession()

TopicSubscriberJMS 1.0
javax.jms

A TopicSubscriber is a MessageConsumer specific to a publish/subscribe context. TopicSubscriber objects are created using the createSubscriber() and createDurableSubscriber() methods on the TopicSession. A TopicSubscriber is created with a Topic to subscribe to and can optionally be created with a message selector that filters the messages received by the subscriber. If a client is both publishing and subscribing to the same Topic, the no-local attribute on the TopicSubscriber specifies whether to filter out messages published by the same connection.

If a TopicSubscriber is created as durable (using createDurableSubscriber() on the TopicSession), the provider collects messages for this subscriber even when the subscriber is inactive. The provider keeps these messages until the subscriber receives them, or until they expire according to the sender's time-to-live header attribute. In order for the client to retrieve the messages collected under a durable TopicSubscriber after it has reactivated itself, it has to create a new TopicSubscriber under the same Topic with the same client ID.

public interface TopicSubscriber extends MessageConsumer {
// Public Instance Methods
public abstract boolean getNoLocal () throws JMSException;
public abstract Topic getTopic () throws JMSException;
}

Hierarchy: (TopicSubscriber(MessageConsumer))

Returned By: TopicSession.{createDurableSubscriber(), createSubscriber()}

TransactionInProgressExceptionJMS 1.0
javax.jmsserializable checked

Thrown if an invalid request is made during a transactional session (e.g., attempting to commit() a session while a message is still being sent).

public class TransactionInProgressException extends JMSException {
// Public Constructors
public TransactionInProgressException (String reason);
public TransactionInProgressException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->TransactionInProgressException

TransactionRolledBackExceptionJMS 1.0
javax.jmsserializable checked

Thrown by the Session.commit() method if the transaction needs to be rolled back because of some internal error.

public class TransactionRolledBackException extends JMSException {
// Public Constructors
public TransactionRolledBackException (String reason);
public TransactionRolledBackException (String reason, String errorCode);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->JMSException-->TransactionRolledBackException

XAConnectionJMS 1.0
javax.jms

This interface represents a Connection to a provider that supports transactional messaging, according to the X/Open XA protocol for transactional processing. Subinterfaces of XAConnection generate transactional sessions in the form of XASession objects.

public interface XAConnection {
}

Implementations: XAQueueConnection, XATopicConnection

XAConnectionFactoryJMS 1.0
javax.jms

A transactional JMS provider exports an XAConnectionFactory for clients to use to create XAConnection objects. Clients typically find a provider's XAConnectionFactory using a JNDI lookup.

public interface XAConnectionFactory {
}

Implementations: XAQueueConnectionFactory, XATopicConnectionFactory

XAQueueConnectionJMS 1.0
javax.jms

An XAQueueConnection is a Connection to a transactional provider of point-to-point messaging. It extends the QueueConnection interface with a createXAQueueSession() method, which creates a transactional XAQueueSession.

public interface XAQueueConnection extends javax.jms.XAConnection, QueueConnection {
// Public Instance Methods
public abstract XAQueueSession createXAQueueSession () throws JMSException;
}

Hierarchy: (XAQueueConnection(javax.jms.XAConnection,QueueConnection(javax.jms.Connection)))

Returned By: XAQueueConnectionFactory.createXAQueueConnection()

XAQueueConnectionFactoryJMS 1.0
javax.jms

An XAQueueConnectionFactory is a QueueConnectionFactory that creates XAQueueConnection objects to a transactional point-to-point JMS provider.

public interface XAQueueConnectionFactory extends XAConnectionFactory, QueueConnectionFactory {
// Public Instance Methods
public abstract XAQueueConnection createXAQueueConnection () throws JMSException;
public abstract XAQueueConnection createXAQueueConnection (String userName, String password) throws JMSException;
}

Hierarchy: (XAQueueConnectionFactory(XAConnectionFactory,QueueConnectionFactory(ConnectionFactory)))

XAQueueSessionJMS 1.0
javax.jmsrunnable

An XAQueueSession is a wrapper around a QueueSession. It represents a transactional session with a JMS point-to-point provider.

public interface XAQueueSession extends XASession {
// Public Instance Methods
public abstract QueueSession getQueueSession () throws JMSException;
}

Hierarchy: (XAQueueSession(XASession(Session(Runnable))))

Returned By: XAQueueConnection.createXAQueueSession()

XASessionJMS 1.0
javax.jmsrunnable

An XASession is a Session with a provider that supports transactional messaging according to the X/Open XA protocol for transactional processing. The XASession contains a javax.transaction.xa.XAResource object that represents the association of the Session with a transaction context.

public interface XASession extends Session {
// Public Instance Methods
public abstract javax.transaction.xa.XAResource getXAResource ();
}

Hierarchy: (XASession(Session(Runnable)))

Implementations: XAQueueSession, XATopicSession

XATopicConnectionJMS 1.0
javax.jms

An XATopicConnection represents a Connection to a transactional provider of publish/subscribe messaging. It extends the TopicConnection interface with a createXATopicSession() method, which creates a transactional XATopicSession.

public interface XATopicConnection extends javax.jms.XAConnection, TopicConnection {
// Public Instance Methods
public abstract XATopicSession createXATopicSession () throws JMSException;
}

Hierarchy: (XATopicConnection(javax.jms.XAConnection,TopicConnection(javax.jms.Connection)))

Returned By: XATopicConnectionFactory.createXATopicConnection()

XATopicConnectionFactoryJMS 1.0
javax.jms

An XATopicConnectionFactory is a TopicConnectionFactory that creates XATopicConnection objects to a transactional publish/subscribe JMS provider.

public interface XATopicConnectionFactory extends XAConnectionFactory, TopicConnectionFactory {
// Public Instance Methods
public abstract XATopicConnection createXATopicConnection () throws JMSException;
public abstract XATopicConnection createXATopicConnection (String userName, String password) throws JMSException;
}

Hierarchy: (XATopicConnectionFactory(XAConnectionFactory,TopicConnectionFactory(ConnectionFactory)))

XATopicSessionJMS 1.0
javax.jmsrunnable

An XATopicSession is a wrapper around a TopicSession. It represents a transactional session with a JMS publish/subscribe provider.

public interface XATopicSession extends XASession {
// Public Instance Methods
public abstract TopicSession getTopicSession () throws JMSException;
}

Hierarchy: (XATopicSession(XASession(Session(Runnable))))

Returned By: XATopicConnection.createXATopicSession()



Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.

This HTML Help has been published using the chm2web software.