|
Oracle GlassFish(tm) Server Message Queue 5.0 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface JMSConsumer
A client using the simplified JMS API introduced for JMS 2.0 uses a JMSConsumer
object to receive messages from a destination. A JMSConsumer
object is created by passing a Destination
object to one of the
createConsumer
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
Method Summary | ||
---|---|---|
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. |
|
|
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. |
|
|
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. |
|
|
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 . |
Method Detail |
---|
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 set
JMSRuntimeException
- 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
delivered
JMSRuntimeException
- 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 closed
JMSRuntimeException
- 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
closed
JMSRuntimeException
- if the JMS provider fails to receive the next
message due to some internal error.Message receiveNoWait()
JMSConsumer
, or
null if one is not available
JMSRuntimeException
- 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.
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 closed
JMSRuntimeException
- if the JMS provider fails to receive the next message due
to some internal error
ClassCastException
- 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 closed
JMSRuntimeException
- if the JMS provider fails to receive the next message due
to some internal error
ClassCastException
- 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 closed
JMSRuntimeException
- if the JMS provider fails to receive the next message due
to some internal error
ClassCastException
- if the next message is not of the expected type
|
Oracle GlassFish(tm) Server Message Queue 5.0 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |