    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    }