javax.jms.MessageConsumer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ow2-jms-2.0-spec Show documentation
The Java Message Service (JMS) API, version 2.0
The newest version!
/**
 * 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: MessageConsumer.java 6347 2013-03-13 08:52:02Z tachker $
 *  ---------------------------------------------------------------------
 */

package javax.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.
 * 
 * @see javax.jms.QueueReceiver
 * @see javax.jms.TopicSubscriber
 * @see javax.jms.Session
 * 
 * @version JMS 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 JMS provider fails to get the message selector due to
   *              some internal error.
   */

  String getMessageSelector() throws JMSException;

  /**
   * Gets the {@code MessageConsumer}'s {@code MessageListener}.
   * 
   * @return the {@code MessageConsumer}'s {@code MessageListener}, or null if
   *         one was not set
   * 
   * @exception JMSException
   *              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.MessageConsumer#setMessageListener(javax.jms.MessageListener)
   */
  MessageListener getMessageListener() throws JMSException;

  /**
   * Sets the {@code MessageConsumer}'s {@code MessageListener}.
   * 
   * @param listener
   *          the listener to which the messages are to be delivered
   * 
   * @exception JMSException
   *              if the JMS 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 Java EE web or EJB
   *              application (though it is not guaranteed that an exception is
   *              thrown in this case)
   *              
   * 
   * @see javax.jms.MessageConsumer#getMessageListener()
   */
  void setMessageListener(MessageListener listener) throws JMSException;

  /**
   * Receives the next message produced for this message consumer.
   * 
   * @return the next message produced for this message consumer, or null if
   *         this message consumer is concurrently closed
   * 
   * @exception JMSException
   *              if the JMS 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. *
   * 
   * @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 JMS 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 JMS provider fails to receive the next message due to
   *              some internal error.
   */

  Message receiveNoWait() throws JMSException;

  /**
   * Closes the message consumer.
   * 
   * @exception JMSException
   *              if the JMS provider fails to close the consumer due to some
   *              internal error.
   */

  void close() throws JMSException;
}