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 java.io.InputStream;
017import java.io.OutputStream;
018
019import org.hornetq.api.core.HornetQException;
020import org.hornetq.api.core.Message;
021
022/**
023 * 
024 * A ClientMessage represents a message sent and/or received by HornetQ.
025 * 
026 * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
027 * @author <a href="mailto:clebert.suconic@jboss.com">Clebert Suconic</a>
028 *
029 */
030public interface ClientMessage extends Message
031{
032   /**
033    * Returns the number of times this message was delivered.
034    */
035   int getDeliveryCount();
036
037   /**
038    * Set the delivery count for this message.
039    * 
040    * This method is not meant to be called by HornetQ clients.
041    * 
042    * @param deliveryCount message delivery count
043    */
044   void setDeliveryCount(int deliveryCount);
045
046   /**
047    * Acknowledge reception of this message.
048    * 
049    * If the session responsible to acknowledge this message has  {@code autoCommitAcks}
050    * set to {@code true}, the transaction will automatically commit the current transaction.
051    * Otherwise, this acknwoledgement will not be committed until the client commits the session transaction.
052    * 
053    * @throws HornetQException if an error occured while acknowledging the message.
054    * 
055    * @see ClientSession#isAutoCommitAcks()
056    */
057   void acknowledge() throws HornetQException;
058
059   /**
060    * Return the size (in bytes) of this message's body
061    */
062   int getBodySize();
063
064   /** 
065    * Sets the OutputStream that will receive the content of a message received in a non blocking way.
066    * <br> 
067    * This method is used when consuming large messages
068    * 
069    * @throws HornetQException
070    */
071   void setOutputStream(OutputStream out) throws HornetQException;
072
073   /** 
074    * Saves the content of the message to the OutputStream.
075    * It will block until the entire content is transfered to the OutputStream.
076    * <br> 
077    * 
078    * @throws HornetQException
079    */
080   void saveToOutputStream(OutputStream out) throws HornetQException;
081
082   /**
083    * Wait the outputStream completion of the message.
084    *
085    * This method is used when consuming large messages
086    * 
087    * @param timeMilliseconds - 0 means wait forever
088    * @return true if it reached the end
089    * @throws HornetQException
090    */
091   boolean waitOutputStreamCompletion(long timeMilliseconds) throws HornetQException;
092
093   /** 
094    * Sets the body's IntputStream. 
095    * <br> 
096    * This method is used when sending large messages
097    * 
098    * @throws HornetQException
099    */
100   void setBodyInputStream(InputStream bodyInputStream);
101
102}