javax.jms.JMSConsumer Maven / Gradle / Ivy
Show all versions of ow2-jms-2.0-spec Show documentation
/**
* Copyright 2013 ScalAgent Distributed Technologies
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* ---------------------------------------------------------------------
* $Id: JMSConsumer.java 6347 2013-03-13 08:52:02Z tachker $
* ---------------------------------------------------------------------
*/
package javax.jms;
/**
* A client using the simplified JMS API introduced for JMS 2.0 uses a
* {@code JMSConsumer} object to receive messages from a queue or topic. A
* {@code JMSConsumer} object may be created either created by passing a
* {@code Queue} or {@code Topic} object to one of the {@code createConsumer}
* methods on a {@code JMSContext}. or by passing a {@code Topic} object to one
* of the {@code createSharedConsumer} or {@code createDurableConsumer} methods
* on a {@code JMSContext}. A client may either synchronously receive a
* {@code JMSConsumer}'s messages or have the {@code JMSConsumer} asynchronously
* deliver them as they arrive.
*
* For synchronous receipt, a client can request the next message from a
* {@code JMSConsumer} using one of its {@code receive} methods. There are
* several variations of {@code receive} that allow a client to poll or wait for
* the next message.
*
* For asynchronous delivery, a client can register a {@code MessageListener}
* object with a {@code JMSConsumer}. As messages arrive at the
* {@code JMSConsumer}, it delivers them by calling the {@code MessageListener}
* 's {@code onMessage} method.
*
* It is a client programming mistake for a {@code MessageListener} to throw an
* exception.
*
* @see javax.jms.JMSContext
*
* @version JMS 2.0
* @since JMS 2.0
*
*/
public interface JMSConsumer extends AutoCloseable {
/**
* Gets this {@code JMSConsumer}'s message selector expression.
*
* @return this {@code JMSConsumer}'s message selector, or null if no message
* selector exists for the {@code JMSConsumer}
*
* @exception JMSRuntimeException
* if the JMS provider fails to get the message selector due to
* some internal error.
*/
String getMessageSelector();
/**
* Gets the {@code JMSConsumer}'s {@code MessageListener}.
*
* @return the {@code JMSConsumer}'s {@code MessageListener}, or null if one
* was not set
*
* @exception JMSRuntimeException
* if the JMS provider fails to get the {@code MessageListener}
* for one of the following reasons:
*
* - an internal error has occurred or
*
- this method has been called in a Java EE web or EJB
* application (though it is not guaranteed that an exception is
* thrown in this case)
*
*
* @see javax.jms.JMSConsumer#setMessageListener(javax.jms.MessageListener)
*/
MessageListener getMessageListener() throws JMSRuntimeException;
/**
* Specifies the {@code JMSConsumer}'s {@code MessageListener}.
*
* Setting the {@code MessageListener} to null is the equivalent of unsetting
* the {@code MessageListener} for the {@code JMSConsumer}.
*
* The effect of calling this method while messages are being consumed by an
* existing listener or the {@code JMSConsumer} is being used to consume
* messages synchronously is undefined.
*
* @param listener
* the listener to which the messages are to be delivered
*
* @exception JMSRuntimeException
* if the JMS provider fails to set the {@code JMSConsumer}'s
* {@code MessageListener} for one of the following reasons:
*
* - an internal error has occurred or
- this method has been
* called in a Java EE web or EJB application (though it is not
* guaranteed that an exception is thrown in this case)
*
*
* @see javax.jms.JMSConsumer#getMessageListener()
*/
void setMessageListener(MessageListener listener) throws JMSRuntimeException;
/**
* Receives the next message produced for this {@code JMSConsumer}.
*
*
* This call blocks indefinitely until a message is produced or until this
* {@code JMSConsumer} is closed.
*
* @return the next message produced for this {@code JMSConsumer}, or null if
* this {@code JMSConsumer} is concurrently closed
*
* @exception JMSRuntimeException
* if the JMS provider fails to receive the next message due to
* some internal error.
*
*/
Message receive();
/**
* Gets the next message that arrives within the specified timeout interval.
*
* @param timeout
* the timeout value (in milliseconds)
*
* @return the next message produced for this {@code JMSConsumer}, or null if
* the timeout expires or this {@code JMSConsumer} is concurrently
* closed
*
* @exception JMSRuntimeException
* if the JMS provider fails to receive the next message due to
* some internal error.
*/
Message receive(long timeout);
/**
* Gets the next message if one is immediately available.
*
* @return the next message produced for this {@code JMSConsumer}, or null if
* one is not available
*
* @exception JMSRuntimeException
* if the JMS provider fails to receive the next message due to
* some internal error.
*/
Message receiveNoWait();
/**
* Closes the {@code JMSConsumer}. If this method is called whilst a message
* listener is in progress in another thread then it will block until the
* message listener has completed. This method is the only {@code JMSConsumer}
* method that can be called concurrently.
*
* @exception JMSRuntimeException
* if the JMS provider fails to close the consumer due to some
* internal error.
*/
void close();
/**
* Receives the next message produced for this {@code JMSConsumer} and returns
* its body as an object of the specified type. This method may be used to
* receive any type of message except for {@code StreamMessage} and
* {@code Message}, so long as the message has a body which is capable of
* being assigned to the specified type. This means that the specified class
* or interface must either be the same as, or a superclass or superinterface
* of, the class of the message body. If the message is not one of the
* supported types, or its body cannot be assigned to the specified type, or
* it has no body, then a {@code MessageFormatRuntimeException} is thrown.
*
* This method does not give access to the message headers or properties (such
* as the {@code JMSRedelivered} message header field or the
* {@code JMSXDeliveryCount} message property) and should only be used if the
* application has no need to access them.
*
* This call blocks indefinitely until a message is produced or until this
* {@code JMSConsumer} is closed.
*
* If this method is called within a transaction, the {@code JMSConsumer}
* retains the message until the transaction commits.
*
* The result of this method throwing a {@code MessageFormatRuntimeException}
* depends on the session mode.
*
* @param c
* The type to which the body of the next message should be assigned.
* If the next message is expected to be a {@code TextMessage} then
* this should be set to {@code String.class} or another class to
* which a {@code String} is assignable.
* If the next message is expected to be a {@code ObjectMessage} then
* this should be set to {@code java.io.Serializable.class} or
* another class to which the body is assignable.
* If the next message is expected to be a {@code MapMessage} then
* this should be set to {@code java.util.Map.class} (or
* {@code java.lang.Object.class}).
* If the next message is expected to be a {@code BytesMessage} then
* this should be set to {@code byte[].class} (or
* {@code java.lang.Object.class}).
*
* @return the body of the next message produced for this {@code JMSConsumer},
* or null if this {@code JMSConsumer} is concurrently closed
*
* @throws MessageFormatRuntimeException
*
* - if the message is not one of the supported types listed above
*
- if the message body cannot be assigned to the specified type
*
- if the message has no body
- if the message is an
* {@code ObjectMessage} and object deserialization fails.
*
* @throws JMSRuntimeException
* if the JMS provider fails to receive the next message due to some
* internal error
*/
T receiveBody(Class c);
/**
* Receives the next message produced for this {@code JMSConsumer} that
* arrives within the specified timeout period and returns its body as an
* object of the specified type.
*
* This method does not give access to the message headers or properties (such
* as the {@code JMSRedelivered} message header field or the
* {@code JMSXDeliveryCount} message property) and should only be used if the
* application has no need to access them.
*
* This call blocks indefinitely until a message is produced or until this
* {@code JMSConsumer} is closed.
*
* If this method is called within a transaction, the {@code JMSConsumer}
* retains the message until the transaction commits.
*
* @param c
* The type to which the body of the next message should be assigned.
* If the next message is expected to be a {@code TextMessage} then
* this should be set to {@code String.class} or another class to
* which a {@code String} is assignable.
* If the next message is expected to be a {@code ObjectMessage} then
* this should be set to {@code java.io.Serializable.class} or
* another class to which the body is assignable.
* If the next message is expected to be a {@code MapMessage} then
* this should be set to {@code java.util.Map.class} (or
* {@code java.lang.Object.class}).
* If the next message is expected to be a {@code BytesMessage} then
* this should be set to {@code byte[].class} (or
* {@code java.lang.Object.class}).
*
* @return the body of the next message produced for this {@code JMSConsumer},
* or null if the timeout expires or this {@code JMSConsumer} is
* concurrently closed
*
* @throws MessageFormatRuntimeException
*
* - if the message is not one of the supported types listed above
*
- if the message body cannot be assigned to the specified type
*
- if the message has no body
- if the message is an
* {@code ObjectMessage} and object deserialization fails.
*
* @throws JMSRuntimeException
* if the JMS provider fails to receive the next message due to some
* internal error
*/
T receiveBody(Class c, long timeout);
/**
* Receives the next message produced for this {@code JMSConsumer} if one is
* immediately available and returns its body as an object of the specified
* type.
*
* This method does not give access to the message headers or properties (such
* as the {@code JMSRedelivered} message header field or the
* {@code JMSXDeliveryCount} message property) and should only be used if the
* application has no need to access them.
*
* This call blocks indefinitely until a message is produced or until this
* {@code JMSConsumer} is closed.
*
* If this method is called within a transaction, the {@code JMSConsumer}
* retains the message until the transaction commits.
*
* @param c
* The type to which the body of the next message should be assigned.
* If the next message is expected to be a {@code TextMessage} then
* this should be set to {@code String.class} or another class to
* which a {@code String} is assignable.
* If the next message is expected to be a {@code ObjectMessage} then
* this should be set to {@code java.io.Serializable.class} or
* another class to which the body is assignable.
* If the next message is expected to be a {@code MapMessage} then
* this should be set to {@code java.util.Map.class} (or
* {@code java.lang.Object.class}).
* If the next message is expected to be a {@code BytesMessage} then
* this should be set to {@code byte[].class} (or
* {@code java.lang.Object.class}).
*
* @return the body of the next message produced for this {@code JMSConsumer},
* or null if one is not immediately available or this
* {@code JMSConsumer} is concurrently closed
*
* @throws MessageFormatRuntimeException
*
* - if the message is not one of the supported types listed above
*
- if the message body cannot be assigned to the specified type
*
- if the message has no body
- if the message is an
* {@code ObjectMessage} and object deserialization fails.
*
*
* @throws JMSRuntimeException
* if the JMS provider fails to receive the next message due to some
* internal error
*/
T receiveBodyNoWait(Class c);
}