001/*
002 * Copyright 2009 Red Hat, Inc.
003 * Red Hat licenses this file to you under the Apache License, version
004 * 2.0 (the "License"); you may not use this file except in compliance
005 * with the License.  You may obtain a copy of the License at
006 *    http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
010 * implied.  See the License for the specific language governing
011 * permissions and limitations under the License.
012 */
013
014package org.hornetq.api.core.client;
015
016import org.hornetq.api.core.HornetQException;
017
018/**
019 * A ClientConsumer receives messages from HornetQ queues.
020 * <br>
021 * Messages can be consumed synchronously by using the <code>receive()</code> methods
022 * which will block until a message is received (or a timeout expires) or asynchronously
023 * by setting a {@link MessageHandler}.
024 * <br>
025 * These 2 types of consumption are exclusive: a ClientConsumer with a MessageHandler set will
026 * throw HornetQException if its <code>receive()</code> methods are called.
027 * 
028 * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
029 * @author <a href="mailto:clebert.suconic@jboss.org">Clebert Suconic</a>
030 * @author <a href="mailto:ataylor@redhat.com">Andy Taylor</a>
031 * 
032 * @see ClientSession#createConsumer(String)
033 */
034public interface ClientConsumer
035{
036   /**
037    * Receives a message from a queue.
038    * 
039    * This call will block indefinitely until a message is received.
040    * 
041    * Calling this method on a closed consumer will throw a HornetQException.
042    * 
043    * @return a ClientMessage
044    * 
045    * @throws HornetQException if an exception occurs while waiting to receive a message
046    */
047   ClientMessage receive() throws HornetQException;
048
049   /**
050    * Receives a message from a queue.
051    * 
052    * This call will block until a message is received or the given timeout expires
053    * 
054    * Calling this method on a closed consumer will throw a HornetQException.
055    * @param timeout time (in milliseconds) to wait to receive a message
056    * 
057    * @return a message or <code>null</code> if the time out expired
058    * 
059    * @throws HornetQException  if an exception occurs while waiting to receive a message
060    */
061   ClientMessage receive(long timeout) throws HornetQException;
062
063   /**
064    * Receives a message from a queue.
065    * 
066    * This call will force a network trip to HornetQ server to ensure that
067    * there are no messages in the queue which can be delivered to this consumer.
068    * This call will never wait indefinitely for a message, it will return <code>null</code>
069    * if no messages are available for this consumer.
070    * Note however that there is a performance cost as an additional network trip to the 
071    * server may required to check the queue status.
072    * 
073    * Calling this method on a closed consumer will throw a HornetQException.
074    * 
075    * @return a message or <code>null</code> if there are no messages in the queue for this consumer
076    * 
077    * @throws HornetQException  if an exception occurs while waiting to receive a message
078    */
079   ClientMessage receiveImmediate() throws HornetQException;
080
081   /**
082    * Returns the MessageHandler associated to this consumer.
083    * 
084    * Calling this method on a closed consumer will throw a HornetQException.
085    * 
086    * @return the MessageHandler associated to this consumer or <code>null</code>
087    * 
088    * @throws HornetQException  if an exception occurs while getting the MessageHandler
089    */
090   MessageHandler getMessageHandler() throws HornetQException;
091
092   /**
093    * Sets the MessageHandler for this consumer to consume messages asynchronously.
094    * 
095    * Calling this method on a closed consumer will throw a HornetQException.
096    * 
097    * @param handler a MessageHandler
098    * @throws HornetQException  if an exception occurs while setting the MessageHandler
099    */
100   void setMessageHandler(MessageHandler handler) throws HornetQException;
101
102   /**
103    * Closes the consumer.
104    * 
105    * Once this consumer is closed, it can not receive messages, whether synchronously or asynchronously.
106    * 
107    * @throws HornetQException
108    */
109   void close() throws HornetQException;
110
111   /**
112    * Returns whether the consumer is closed or not.
113    * 
114    * @return <code>true</code> if this consumer is closed, <code>false</code> else
115    */
116   boolean isClosed();
117
118   /**
119    * Returns the last exception thrown by a call to this consumer's MessageHandler.
120    * 
121    * @return the last exception thrown by a call to this consumer's MessageHandler or <code>null</code>
122    */
123   Exception getLastException();
124}