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    
014    package org.hornetq.api.core.client;
015    
016    import 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     */
034    public 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    }