public interface JMSConsumer extends AutoCloseable
JMSConsumer object to receive messages from a queue or topic. A
JMSConsumer object may be created either created by passing a
Queue or Topic object to one of the createConsumer
methods on a JMSContext. or by passing a Topic object to one
of the createSharedConsumer or createDurableConsumer methods
on a JMSContext.
A JMSConsumer can be created with a message selector. A message
selector allows the client to restrict the messages delivered to the
JMSConsumer to those that match the selector.
A client may either synchronously receive a JMSConsumer's messages or
have the JMSConsumer asynchronously deliver them as they arrive.
For synchronous receipt, a client can request the next message from a
JMSConsumer using one of its receive methods. There are
several variations of receive that allow a client to poll or wait for
the next message.
For asynchronous delivery, a client can register a MessageListener
object with a JMSConsumer. As messages arrive at the
JMSConsumer, it delivers them by calling the MessageListener
's onMessage method.
It is a client programming error for a MessageListener to throw an
exception.
JMSContext| Modifier and Type | Method and Description |
|---|---|
void |
close()
Closes the
JMSConsumer. |
MessageListener |
getMessageListener()
Gets the
JMSConsumer's MessageListener. |
String |
getMessageSelector()
Gets this
JMSConsumer's message selector expression. |
Message |
receive()
Receives the next message produced for this
JMSConsumer. |
Message |
receive(long timeout)
Receives the next message that arrives within the specified
timeout interval.
|
Message |
receiveNoWait()
Receives the next message if one is immediately available.
|
<T> T |
receivePayload(Class<T> c)
Receives the next message produced for this
JMSConsumer and
returns its payload, which must be of the specified type |
<T> T |
receivePayload(Class<T> c,
long timeout)
Receives the next message produced for this
JMSConsumer that
arrives within the specified timeout period, and returns its payload,
which must be of the specified type |
<T> T |
receivePayloadNoWait(Class<T> c)
Receives the next message produced for this
JMSConsumer if one is immediately available
and returns its payload, which must be of the specified type. |
void |
setMessageListener(MessageListener listener)
Sets the
JMSConsumer's MessageListener. |
String getMessageSelector()
JMSConsumer's message selector expression.JMSConsumer's message selector, or null if no
message selector exists for the JMSConsumer (that is, if
the message selector was not set or was set to null or the
empty string)JMSRuntimeException - if the JMS provider fails to get the message
selector due to some internal error.MessageListener getMessageListener() throws JMSRuntimeException
JMSConsumer's MessageListener.
This method must not be used in a Java EE web or EJB application.
Doing so may cause a JMSRuntimeException to be thrown though this is not guaranteed.
JMSConsumer's MessageListener, or null if one was not setJMSRuntimeException - if the JMS provider fails to get the MessageListener
for one of the following reasons:
setMessageListener(javax.jms.MessageListener)void setMessageListener(MessageListener listener) throws JMSRuntimeException
JMSConsumer's MessageListener.
Setting the MessageListener to null is the equivalent of
unsetting the MessageListener for the JMSConsumer.
The effect of calling this method
while messages are being consumed by an existing listener
or the JMSConsumer is being used to consume messages synchronously
is undefined.
This method must not be used in a Java EE web or EJB application.
Doing so may cause a JMSRuntimeException to be thrown though this is not guaranteed.
listener - the listener to which the messages are to be
deliveredJMSRuntimeException - if the JMS provider fails to set the JMSConsumer's MessageListener
for one of the following reasons:
getMessageListener()Message receive()
JMSConsumer.
This call blocks indefinitely until a message is produced
or until this JMSConsumer is closed.
If this receive is done within a transaction, the
JMSConsumer retains the message until the transaction commits.
JMSConsumer, or
null if this JMSConsumer is concurrently closedJMSRuntimeException - if the JMS provider fails to receive the next
message due to some internal error.Message receive(long timeout)
This call blocks until a message arrives, the
timeout expires, or this JMSConsumer is closed.
A timeout of zero never expires, and the call blocks
indefinitely.
timeout - the timeout value (in milliseconds)JMSConsumer, or
null if the timeout expires or this JMSConsumer is concurrently
closedJMSRuntimeException - if the JMS provider fails to receive the next
message due to some internal error.Message receiveNoWait()
JMSConsumer, or
null if one is not availableJMSRuntimeException - if the JMS provider fails to receive the next
message due to some internal error.void close()
JMSConsumer.
Since a provider may allocate some resources on behalf of a
JMSConsumer outside the Java virtual machine,
clients should close them when they are not needed. Relying on garbage
collection to eventually reclaim these resources may not be timely
enough.
This call blocks until a receive in progress has completed.
A blocked message consumer receive call returns null when
this JMSConsumer is closed.
close in interface AutoCloseableJMSRuntimeException - if the JMS provider fails to close the JMSConsumer
due to some internal error.<T> T receivePayload(Class<T> c)
JMSConsumer and
returns its payload, which must be of the specified type
This call blocks indefinitely until a message is produced or until this
JMSConsumer is closed.
If receivePayload is called within a transaction, the
JMSConsumer retains the message until the transaction commits.
c - The class of the payload of the next message.TextMessage then
this should be set to String.class.ObjectMessage then
this should be set to java.io.Serializable.class. MapMessage then this
should be set to java.util.Map.class.BytesMessage then this
should be set to byte[].class.ClassCastException will be thrown
and the message will not be delivered.JMSConsumer, or null if this JMSConsumer is
concurrently closedJMSRuntimeException - if the JMS provider fails to receive the next message due
to some internal errorClassCastException - if the next message is not of the expected type<T> T receivePayload(Class<T> c, long timeout)
JMSConsumer that
arrives within the specified timeout period, and returns its payload,
which must be of the specified type
This call blocks until a message arrives, the timeout expires, or this
JMSConsumer is closed. A timeout of zero never expires, and the
call blocks indefinitely.
If receivePayload is called within a transaction, the
JMSConsumer retains the message until the transaction commits.
c - The class of the payload of the next message.TextMessage then
this should be set to String.class.ObjectMessage then
this should be set to java.io.Serializable.class. MapMessage then this
should be set to java.util.Map.class.BytesMessage then this
should be set to byte[].class.ClassCastException will be thrown
and the message will not be delivered.JMSConsumer, or null if the timeout expires or this JMSConsumer is
concurrently closedJMSRuntimeException - if the JMS provider fails to receive the next message due
to some internal errorClassCastException - if the next message is not of the expected type<T> T receivePayloadNoWait(Class<T> c)
JMSConsumer if one is immediately available
and returns its payload, which must be of the specified type.
If a message is not immediately available null is returned.
If receivePayloadNoWait is called within a transaction, the
JMSConsumer retains the message until the transaction commits.
c - The class of the payload of the next message.TextMessage then
this should be set to String.class.ObjectMessage then
this should be set to java.io.Serializable.class. MapMessage then this
should be set to java.util.Map.class.BytesMessage then this
should be set to byte[].class.ClassCastException will be thrown
and the message will not be delivered.JMSConsumer, or null if one is not immediately available
or this JMSConsumer is concurrently closedJMSRuntimeException - if the JMS provider fails to receive the next message due
to some internal errorClassCastException - if the next message is not of the expected typeCopyright © 2012. All Rights Reserved.