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}