jakarta.jms.MessageConsumer Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.jms;
/**
* A client uses a {@code MessageConsumer} object to receive messages from a destination. A {@code MessageConsumer}
* object is created by passing a {@code Destination} object to a message-consumer creation method supplied by a
* session.
*
*
* {@code MessageConsumer} is the parent interface for all message consumers.
*
*
* A {@code MessageConsumer} can be created with a message selector. A message selector allows the client to restrict
* the messages delivered to the message consumer to those that match the selector.
*
*
* A client may either synchronously receive a {@code MessageConsumer}'s messages or have the {@code MessageConsumer}
* asynchronously deliver them as they arrive.
*
*
* For synchronous receipt, a client can request the next message from a {@code MessageConsumer} 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 MessageConsumer}. As
* messages arrive at the {@code MessageConsumer}, it delivers them by calling the {@code MessageListener}'s
* {@code onMessage} method.
*
*
* It is a client programming error for a {@code MessageListener} to throw an exception.
*
* @see jakarta.jms.QueueReceiver
* @see jakarta.jms.TopicSubscriber
* @see jakarta.jms.Session
*
* @version Jakarta Messaging 2.0
* @since JMS 1.0
*/
public interface MessageConsumer extends AutoCloseable {
/**
* Gets this message consumer's message selector expression.
*
* @return this message consumer's message selector, or null if no message selector exists for the message consumer
* (that is, if the message selector was not set or was set to null or the empty string)
*
* @exception JMSException if the Jakarta Messaging provider fails to get the message selector due to some internal error.
*/
String getMessageSelector() throws JMSException;
/**
* Gets the {@code MessageConsumer}'s {@code MessageListener}.
*
*
* This method must not be used in a Jakarta EE web or EJB application. Doing so may cause a {@code JMSException} to be
* thrown though this is not guaranteed.
*
* @return the {@code MessageConsumer}'s {@code MessageListener}, or null if one was not set
*
* @exception JMSException if the Jakarta Messaging 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is
* thrown in this case)
*
*
* @see jakarta.jms.MessageConsumer#setMessageListener(jakarta.jms.MessageListener)
*/
MessageListener getMessageListener() throws JMSException;
/**
* Sets the {@code MessageConsumer}'s {@code MessageListener}.
*
*
* Setting the the {@code MessageListener} to null is the equivalent of unsetting the {@code MessageListener} for the
* {@code MessageConsumer}.
*
*
* The effect of calling this method while messages are being consumed by an existing listener or the
* {@code MessageConsumer} is being used to consume messages synchronously is undefined.
*
*
* This method must not be used in a Jakarta EE web or EJB application. Doing so may cause a {@code JMSException} to be
* thrown though this is not guaranteed.
*
* @param listener the listener to which the messages are to be delivered
*
* @exception JMSException if the Jakarta Messaging provider fails to set the {@code MessageConsumer}'s {@code MessageListener} for
* one of the following reasons:
*
* - an internal error has occurred or
*
- this method has been called in a Jakarta EE web or EJB application (though it is not guaranteed that an exception is
* thrown in this case)
*
*
* @see jakarta.jms.MessageConsumer#getMessageListener()
*/
void setMessageListener(MessageListener listener) throws JMSException;
/**
* Receives the next message produced for this message consumer.
*
*
* This call blocks indefinitely until a message is produced or until this message consumer is closed.
*
*
* If this {@code receive} is done within a transaction, the consumer retains the message until the transaction commits.
*
* @return the next message produced for this message consumer, or null if this message consumer is concurrently closed
*
* @exception JMSException if the Jakarta Messaging provider fails to receive the next message due to some internal error.
*
*/
Message receive() throws JMSException;
/**
* Receives the next message that arrives within the specified timeout interval.
*
*
* This call blocks until a message arrives, the timeout expires, or this message consumer is closed. A {@code timeout}
* of zero never expires, and the call blocks indefinitely.
*
* @param timeout the timeout value (in milliseconds)
*
* @return the next message produced for this message consumer, or null if the timeout expires or this message consumer
* is concurrently closed
*
* @exception JMSException if the Jakarta Messaging provider fails to receive the next message due to some internal error.
*/
Message receive(long timeout) throws JMSException;
/**
* Receives the next message if one is immediately available.
*
* @return the next message produced for this message consumer, or null if one is not available
*
* @exception JMSException if the Jakarta Messaging provider fails to receive the next message due to some internal error.
*/
Message receiveNoWait() throws JMSException;
/**
* Closes the message consumer.
*
*
* Since a provider may allocate some resources on behalf of a {@code MessageConsumer} 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 will block until a {@code receive} call in progress on this consumer has completed. A blocked
* {@code receive} call returns null when this message consumer is closed.
*
*
* 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 may be called from a message listener's {@code onMessage} method on its own consumer. After this method
* returns the {@code onMessage} method will be allowed to complete normally.
*
*
* This method is the only {@code MessageConsumer} method that can be called concurrently.
*
* @exception JMSException if the Jakarta Messaging provider fails to close the consumer due to some internal error.
*/
@Override
void close() throws JMSException;
}