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
This call blocks indefinitely until a message is produced or until this
JMSConsumer is closed. |
<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
This call blocks until a message arrives, the timeout expires, or this
JMSConsumer is closed. |
<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 AutoCloseable
JMSRuntimeException
- 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 (c) 2012, Oracle and/or its affiliates. All rights reserved.