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        * Acknowledge reception of a single message.
061        *
062        * If the session responsible to acknowledge this message has  {@code autoCommitAcks}
063        * set to {@code true}, the transaction will automatically commit the current transaction.
064        * Otherwise, this acknwoledgement will not be committed until the client commits the session transaction.
065        *
066        * @throws HornetQException if an error occured while acknowledging the message.
067        *
068        * @see ClientSession#isAutoCommitAcks()
069        */
070       void individualAcknowledge() throws HornetQException;
071    
072       /**
073        * Return the size (in bytes) of this message's body
074        */
075       int getBodySize();
076    
077       /**
078        * Sets the OutputStream that will receive the content of a message received in a non blocking way.
079        * <br>
080        * This method is used when consuming large messages
081        *
082        * @throws HornetQException
083        */
084       void setOutputStream(OutputStream out) throws HornetQException;
085    
086       /**
087        * Saves the content of the message to the OutputStream.
088        * It will block until the entire content is transfered to the OutputStream.
089        * <br>
090        *
091        * @throws HornetQException
092        */
093       void saveToOutputStream(OutputStream out) throws HornetQException;
094    
095       /**
096        * Wait the outputStream completion of the message.
097        *
098        * This method is used when consuming large messages
099        *
100        * @param timeMilliseconds - 0 means wait forever
101        * @return true if it reached the end
102        * @throws HornetQException
103        */
104       boolean waitOutputStreamCompletion(long timeMilliseconds) throws HornetQException;
105    
106       /**
107        * Sets the body's IntputStream.
108        * <br>
109        * This method is used when sending large messages
110        *
111        * @throws HornetQException
112        */
113       void setBodyInputStream(InputStream bodyInputStream);
114    
115    }