This section covers the queue-based API.
The
Queue
is an
administered object that acts as a handle or identifier for an actual
queue, called a physical
queue
, on the messaging server. A physical
queue is a channel through which many clients can receive and send
messages. The Queue
is a subtype of the
Destination
interface.
Multiple receivers may connect to a queue, but each message in the queue may only be consumed by one of the queue's receivers. Messages in the queue are ordered so that consumers receive messages in the order the message server placed them in the queue:
public interface Queue extends Destination { public String getQueueName( ) throws JMSException; public String toString( ); }
A
QueueBrowser
is a specialized object that allows
you to peek ahead at pending messages on a Queue
without actually consuming them. This feature is unique to
point-to-point messaging. Queue browsing can be useful for monitoring
the contents of a queue from an administration tool, or for browsing
through multiple messages to locate a message that is more important
than the one that is at the head of the queue:
public interface QueueBrowser { public Queue getQueue( ) throws JMSException; public String getMessageSelector( ) throws JMSException; public Enumeration getEnumeration( ) throws JMSException; public void close( ) throws JMSException; }
The
QueueConnection
is created by the
QueueConnectionFactory
. Each
QueueConnection
represents a unique connection to
the server.[1] The
QueueConnection
is a subtype of the
Connection
interface:
public interface QueueConnection extends Connection { public QueueSession createQueueSession(boolean transacted, int acknowledgeMode) throws JMSException; public ConnectionConsumer createConnectionConsumer (Queue queue, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException; }
The
QueueConnectionFactory
is an administered object that is used to manufacture
QueueConnectionFactory
objects. The
QueueConnection
is a subtype of the
ConnectionFactory
interface:
public interface QueueConnectionFactory extends ConnectionFactory { public QueueConnection createQueueConnection( ) throws JMSException; public QueueConnection createQueueConnection(String username, String password) throws JMSException; }
The
QueueReceiver
is created by a
QueueSession
for a specific queue. The JMS client
uses the QueueReceiver
to receive messages
delivered to its assigned queue. The QueueReceiver
is a subtype of the MessageConsumer
interface.
Each message in a queue is delivered to only one
QueueReceiver
. Multiple receivers may connect to a
queue, but each message in the queue may only be consumed by one of
the queue's receivers:
public interface QueueReceiver extends MessageConsumer { public Queue getQueue( ) throws JMSException; }
A QueueSender
is created by a
QueueSession
, usually for a specific
queue.
Messages sent by the
QueueSender
to a queue are delivered to a client
connected to that queue. The QueueSender
is a
subtype of the MessageProducer
interface:
public interface QueueSender extends MessageProducer { public Queue getQueue( ) throws JMSException; public void send(Message message) throws JMSException; public void send(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException; public void send(Queue queue, Message message) throws JMSException; public void send(Queue queue, Message message,int deliveryMode, int priority,long timeToLive) throws JMSException; }
The QueueSession
is created by the
QueueConnection
. A QueueSession
object is a factory for creating Message
,
QueueSender
, and QueueReceiver
objects. A client can create multiple QueueSession
objects to provide more granular control over senders, receivers, and
their associated transactions. The QueueSession
is
a subtype of the Session
interface:
public interface QueueSession extends Session { public Queue createQueue(java.lang.String queueName) throws JMSException; public QueueReceiver createReceiver(Queue queue) throws JMSException; public QueueReceiver createReceiver(Queue queue, String messageSelector) throws JMSException; public QueueSender createSender(Queue queue) throws JMSException; public QueueBrowser createBrowser(Queue queue) throws JMSException; public QueueBrowser createBrowser(Queue queue, String messageSelector) throws JMSException; public TemporaryQueue createTemporaryQueue( ) throws JMSException; }
A TemporaryQueue
is created by a
QueueSession
. A temporary queue is associated with
the connection that belongs to the QueueSession
that created it. It is only active for the duration of the
session's connection, and is guaranteed to be unique across all
connections. It lasts only as long as its associated client
connection is active. In all other respects, a temporary queue is
just like a "regular" queue. The
TemporaryQueue
is a subtype of the
Queue
interface.
Since a temporary queue is created by a JMS client, it is unavailable
to other JMS clients unless the queue identity is transferred using
the JMSReplyTo
header. While any client may send
messages on another client's temporary queue, only the sessions
that are associated with the JMS client connection that created the
temporary queue may receive messages from it. JMS clients can also,
of course, send messages to their own temporary queues:
public interface TemporaryQueue extends Queue { public void delete( ) throws JMSException; }
[1] The actual physical network connection may or may not be unique, depending on the vendor. However, the connection is considered to be logically unique so authentication and connection control can be managed separately from other connections.