This Message type carries an array of primitive bytes as its payload. It's useful for exchanging data in an application's native format, which may not be compatible with other existing Message types. It is also useful where JMS is used purely as a transport between two systems, and the message payload is opaque to the JMS client:

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

The Connection is the base interface for the TopicConnection and the QueueConnection. It defines several general-purpose methods used by clients of the messaging system in managing a JMS connection. Among these methods are the getMetaData( ), start( ), stop( ), and close( ) methods:

public interface Connection {
    public void close(  ) throws JMSException;
    public String getClientID(  ) throws JMSException;
    public ExceptionListener getExceptionListener(  ) throws JMSException; 
    public ConnectionMetaData getMetaData(  ) throws JMSException; 
    public void setClientID(java.lang.String clientID) 
       throws JMSException; 
    public void setExceptionListener(ExceptionListener listener) 
       throws JMSException; 
    public void start(  ) throws JMSException; 
    public void stop(  ) throws JMSException;
}

A Connection object represents a physical connection to a JMS provider for either point-to-point (QueueConnection) or publish-and-subscribe (TopicConnection) messaging. A JMS client might choose to create multiple connections from the same connection factory, but this is rare as connections are relatively expensive (each connection requires a network socket, I/O streams, memory, etc.). Creating multiple Session objects from the same Connection object is considered more efficient, because sessions share access to the same connection.

The ConnectionFactory is the base type for the TopicConnectionFactory and the QueueConnectionFactory, which are used in the publish-and-subscribe and point-to-point messaging models, respectively.

The ConnectionFactory is implemented differently by each vendor, so configuration options available vary from product to product. A connection factory might, for example, be configured to manufacture connections that use a particular protocol, security scheme, clustering strategy, etc.:

public interface ConnectionFactory {
}

This type of object is obtained from a Connection object (TopicConnection or QueueConnection). It provides information describing the JMS connection and the JMS provider. Information available includes the identity of the JMS provider, the JMS version supported by the provider, JMS provider version numbers, and the JMS properties supported:

public interface ConnectionMetaData {
    public int getJMSMajorVersion(  ) throws JMSException;
    public int getJMSMinorVersion(  ) throws JMSException;
    public String getJMSProviderName(  ) throws JMSException; 
    public String getJMSVersion(  ) throws JMSException; 
    public Enumeration getJMSXPropertyNames(  ) throws JMSException; 
    public int getProviderMajorVersion(  ) throws JMSException; 
    public int getProviderMinorVersion(  ) throws JMSException; 
    public String getProviderVersion(  ) throws JMSException;
}

This class contains two final static variables, PERSISTENT and NON_PERSISTENT. These variables are used when establishing the delivery mode of a MessageProducer (TopicPublisher or QueueSender).

There are two types of delivery modes in JMS: persistent and nonpersistent. A persistent message should be delivered once-and-only-once, which means that a message is not lost if the JMS provider fails; it will be delivered after the server recovers. A nonpersistent message is delivered at-most-once, which means that it can be lost and never delivered if the JMS provider fails:

public interface DeliveryMode {
   public static final int NON_PERSISTENT = 1;
   public static final int PERSISTENT = 2;
}

This interface is the base interface for the Topic and Queue interfaces, which represent destinations in the pub/sub and p2p domains respectively.

In all modern enterprise messaging systems, applications exchange messages through virtual channels called destinations. When sending a message, the message is addressed to a destination, not a specific application. Any application that subscribes or registers an interest in that destination may receive that message. In this way, the applications that receive messages and those that send messages are decoupled. Senders and receivers are not bound to each other in any way and may send and receive messages as they see fit:

public interface Destination {
}

JMS provides an ExceptionListener interface for trapping a lost connection and notifying the client of this condition. The ExceptionListener is bound to the connection. The ExceptionListener is very useful to JMS clients that wait passively for messages to be delivered and otherwise have no way of knowing that a connection has been lost.

It is the responsibility of the JMS provider to call the onException( ) method of all registered ExceptionListeners after making reasonable attempts to reestablish the connection automatically. The JMS client can implement the ExceptionListener so that it can be alerted to a lost connection, and possibly attempt to reestablish the connection manually:

public interface ExceptionListener {
   public void onException(JMSException exception);
}

The JMSException is the base exception type for all exceptions thrown by the JMS API. It may provide an error message describing the cause of the exception, a provider-specific error code, and possibly a reference to the exception that caused the JMS exception:

public class JMSException extends java.lang.Exception {    
    public JMSException(java.lang.String reason) { .. }
    public JMSException(java.lang.String reason, 
                        java.lang.String errorCode) { .. } 
    public String getErrorCode(  ) { .. } 
    public Exception getLinkedException(  ) { .. } 
    public void setLinkedException(java.lang.Exception ex) { .. }
}

While the JMSException is usually declared as the exception type thrown from methods in the JMS API, the actual exception thrown may be one of a dozen subtypes, which are enumerated below. The descriptions of these exception types are derived from Sun Microsystems' JMS API documentation and they implement the methods defined by the JMSException super type:

This Message type carries a set of name-value pairs as its payload. The payload is similar to a java.util.Properties object, except the values must be Java primitives or their wrappers. The MapMessage is useful for delivering keyed data:

public interface MapMessage extends Message { 

    public boolean getBoolean(String name) throws JMSException;
    public void setBoolean(String name, boolean value) 
        throws JMSException;
    public byte getByte(String name) throws JMSException;
    public void setByte(String name, byte value) throws JMSException;
    public byte[] getBytes(String name) throws JMSException;
    public void setBytes(String name, byte[] value) 
        throws JMSException;
    public void setBytes(String name, byte[] value, 
                         int offset, int length)    
        throws  JMSException;
    public short getShort(String name) throws JMSException;
    public void setShort(String name, short value) throws JMSException;
    public char getChar(String name) throws JMSException;
    public void setChar(String name, char value) throws JMSException;
    public int getInt(String name) throws JMSException;
    public void setInt(String name, int value)throws JMSException;
    public long getLong(String name) throws JMSException;
    public void setLong(String name, long value) throws JMSException;
    public float getFloat(String name) throws JMSException;
    public void setFloat(String name, float value)
        throws JMSException;
    public double getDouble(String name) throws JMSException;
    public void setDouble(String name, double value)
        throws JMSException;
    public String getString(String name) throws JMSException;
    public void setString(String name, String value)
        throws JMSException;
    public Object getObject(String name) throws JMSException;
    public void setObject(String name, Object value)
        throws JMSException;
    public Enumeration getMapNames(  ) throws JMSException;
    public boolean itemExists(String name) throws JMSException;
}

The Message interface is the super interface for all message types. There are six messages types including: Message, TextMessage, ObjectMessage, StreamMessage, BytesMessage, and MapMessage. The Message type has no payload. It is useful for simple event notification.

A message basically has two parts: a header and payload . The header is comprised of special fields that are used to identify the message, declare attributes of the message, and provide information for routing. The difference between message types is determined largely by their payload, which determines the type of application data the message contains:

public interface Message {
    public void acknowledge(  ) throws JMSException;
    public void clearBody(  ) throws JMSException;

    public Destination getJMSDestination(  ) throws JMSException; 
    public void setJMSDestination(Destination destination) 
        throws JMSException; 
    public int getJMSDeliveryMode(  ) throws JMSException; 
    public void setJMSDeliveryMode(int deliveryMode) 
        throws JMSException; 
    public String getJMSMessageID(  ) throws JMSException; 
    public void setJMSMessageID(String id) throws JMSException; 
    public long getJMSTimestamp(  ) throws JMSException; 
    public void setJMSTimestamp(long timestamp) throws JMSException
    public long getJMSExpiration(  ) throws JMSException; 
    public void setJMSExpiration(long expiration) throws JMSException; 
    public boolean getJMSRedelivered(  ) throws JMSException; 
    public void setJMSRedelivered(boolean redelivered) 
        throws JMSException; 
    public int getJMSPriority(  ) throws JMSException; 
    public void setJMSPriority(int priority) throws JMSException; 
    public Destination getJMSReplyTo(  ) throws JMSException; 
    public void setJMSReplyTo(Destination replyTo) throws JMSException; 
    public String getJMSCorrelationID(  ) throws JMSException; 
    public void setJMSCorrelationID(String correlationID) 
        throws JMSException; 
    public byte[] getJMSCorrelationIDAsBytes(  ) throws JMSException; 
    public void setJMSCorrelationIDAsBytes(byte[] correlationID) 
        throws JMSException; 
    public String getJMSType(  ) throws JMSException; 
    public void setJMSType(String type) throws JMSException; 

    public String getStringProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setStringProperty(String name, String value) 
        throws JMSException, MessageNotWriteableException; 
    public int getIntProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setIntProperty(String name, int value) 
        throws JMSException, MessageNotWriteableException; 
    public boolean getBooleanProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setBooleanProperty(String name, boolean value) 
        throws JMSException, MessageNotWriteableException; 
    public double getDoubleProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setDoubleProperty(String name, double value)
        throws JMSException, MessageNotWriteableException; 
    public float getFloatProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setFloatProperty(String name, float value) 
        throws JMSException, MessageNotWriteableException; 
    public byte getByteProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setByteProperty(String name, byte value) 
        throws JMSException, MessageNotWriteableException; 
    public long getLongProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setLongPreperty(String name, long value)
        throws JMSException, MessageNotWriteableException; 
    public short getShortProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setShortProperty(String name, short value) 
        throws JMSException, MessageNotWriteableException; 
    public Object getObjectProperty(String name) 
        throws JMSException, MessageFormatException; 
    public void setObjectProperty(String name, Object value) 
        throws JMSException, MessageNotWriteableException; 
    public void clearProperties(  )
        throws JMSException;
    public Enumeration getPropertyNames(  ) 
        throws JMSException;
    public boolean propertyExists(String name)
        throws JMSException;
}

The MessageConsumer is the base interface for the TopicSubscriber and the QueueReceiver. It defines several general-purpose methods used by clients when using a consumer. Among these methods are the setMessageListener( )and close( ) methods, and three types of receive( ) methods.

MessageConsumer can consume messages asynchronously or synchronously. To consume messages asynchronously, the JMS client must provide the MessageConsumer with a MessageListener object, which will then receive the messages as they arrive. To consume messages synchronously, the JMS client may call one of three receive methods: receive( ), receive(long timeout), and receiveNoWait( ):

public interface MessageConsumer {
    public void close(  ) throws JMSException;
    public MessageListener getMessageListener(  ) throws JMSException; 
    public String getMessageSelector(  ) throws JMSException; 
    public Message receive(  ) throws JMSException; 
    public Message receive(long timeout) throws JMSException; 
    public Message receiveNoWait(  ) throws JMSException; 
    public void setMessageListener(MessageListener listener) 
        throws JMSException;
}

The MessageListener is implemented by the JMS client. It receives messages asynchronously from one or more Consumers (TopicSubscriber or QueueReceiver).

The Session (TopicSession or QueueSession) must ensure that messages are passed to the MessageListener serially, so that the messages can be processed separately. A MessageListener object may be registered with many consumers, but serial delivery is only guaranteed if all of its consumers were created by the same session:

public interface MessageListener {
    public void onMessage(Message message);
}

The MessageProducer is the base interface for the TopicPublisher and the QueueSender. It defines several general-purpose methods used by clients. Among these methods are setDeliveryMode( ) , close( ) , setPriority( ) , and setTimeToLive(long timeToLive).

MessageProducer sends messages to a specified destination (Topic or Queue). The default destination can be determined when the MessageProducer is created by its session, or the destination can be set each time a message is sent—in this case there is no default destination:

public interface MessageProducer {
    public void setDisableMessageID(boolean value) throws JMSException; 
    public boolean getDisableMessageID(  ) throws JMSException; 
    public void setDisableMessageTimestamp(boolean value) 
        throws JMSException; 
    public boolean getDisableMessageTimestamp(  ) throws JMSException; 
    public void setDeliveryMode(int deliveryMode) throws JMSException; 
    public void setPriority(int defaultPriority) int getDeliveryMode(  )     
        throws JMSException;
    public int getPriority(  ) throws JMSException; 
    public void setTimeToLive(long timeToLive) throws JMSException; 
    public long getTimeToLive(  ) throws JMSException; 
    public void close(  ) throws JMSException;
}

This Message type carries a serializable Java object as its payload. It is useful for exchanging Java objects:

public interface ObjectMessage extends Message {
    public java.io.Serializable getObject(  ) 
        throws JMSException;
    public void setObject(java.io.Serializable payload) 
        throws JMSException, MessageNotWriteableException;
}

The Session is the base interface for the TopicSession and the QueueSession. It defines several general-purpose methods used by JMS clients for managing a JMS Session. Among these methods are the six createMessage( ) methods (one for each type of Message object), setMessageListener( ), close( ), and transaction methods.

A Session is a single-threaded context for producing and consuming messages. It creates message consumers, producers, and messages for a specific JMS provider. The Session manages the scope of transactions across send and receive operations, tracks message acknowledgment for consumers, and serializes delivery of messages to MessageListener objects:

public interface Session extends java.lang.Runnable {
    public static final int AUTO_ACKNOWLEDGE = 1;
    public static final int CLIENT_ACKNOWLEDGE = 2;
    public static final int DUPS_OK_ACKNOWLEDGE = 3;
    
    public BytesMessage createBytesMessage(  ) throws JMSException; 
    public MapMessage createMapMessage(  ) throws JMSException; 
    public Message createMessage(  ) throws JMSException; 
    public ObjectMessage createObjectMessage(  ) throws JMSException; 
    public ObjectMessage createObjectMessage(Serializable object) 
        throws JMSException; 
    public StreamMessage createStreamMessage(  ) throws JMSException; 
    public TextMessage createTextMessage(  ) throws JMSException;
    public TextMessage createTextMessage(java.lang.String text) 
        throws JMSException; 
    public boolean getTransacted(  ) throws JMSException; 
    public void commit(  ) throws JMSException; 
    public void rollback(  ) throws JMSException; 
    public void close(  ) throws JMSException; 
    public void recover(  ) throws JMSException; 
    public MessageListener getMessageListener(  ) throws JMSException; 
    public void setMessageListener(MessageListener listener) 
        throws JMSException; 
    public void run(  );
}

This Message type carries a stream of primitive Java types (int, double, char, etc.) as its payload. It provides a set of convenience methods for mapping a formatted stream of bytes to Java primitives. It provides an easy programming model for exchanging primitive application data in a fixed order:

public interface StreamMessage extends Message {

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

This Message type carries a java.lang.String as its payload. It is useful for exchanging simple text messages and for more complex character data, such as XML documents:

public interface TextMessage extends Message {
    public String getText(  ) 
        throws JMSException;
    public void setText(String payload) 
        throws JMSException, MessageNotWriteableException;
}