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 java.io.InputStream;
017    import java.io.OutputStream;
018    
019    import org.hornetq.api.core.HornetQException;
020    import 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     */
030    public 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    }