001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.activemq.store;
018    
019    import java.io.IOException;
020    import org.apache.activemq.Service;
021    import org.apache.activemq.broker.ConnectionContext;
022    import org.apache.activemq.command.ActiveMQDestination;
023    import org.apache.activemq.command.Message;
024    import org.apache.activemq.command.MessageAck;
025    import org.apache.activemq.command.MessageId;
026    import org.apache.activemq.usage.MemoryUsage;
027    
028    /**
029     * Represents a message store which is used by the persistent implementations
030     * 
031     * @version $Revision: 1.5 $
032     */
033    public interface MessageStore extends Service {
034    
035        /**
036         * Adds a message to the message store
037         * 
038         * @param context context
039         * @param message
040         * @throws IOException
041         */
042        void addMessage(ConnectionContext context, Message message) throws IOException;
043    
044        /**
045         * Looks up a message using either the String messageID or the
046         * messageNumber. Implementations are encouraged to fill in the missing key
047         * if its easy to do so.
048         * 
049         * @param identity which contains either the messageID or the messageNumber
050         * @return the message or null if it does not exist
051         * @throws IOException
052         */
053        Message getMessage(MessageId identity) throws IOException;
054    
055        /**
056         * Removes a message from the message store.
057         * 
058         * @param context
059         * @param ack the ack request that cause the message to be removed. It
060         *                conatins the identity which contains the messageID of the
061         *                message that needs to be removed.
062         * @throws IOException
063         */
064        void removeMessage(ConnectionContext context, MessageAck ack) throws IOException;
065    
066        /**
067         * Removes all the messages from the message store.
068         * 
069         * @param context
070         * @throws IOException
071         */
072        void removeAllMessages(ConnectionContext context) throws IOException;
073    
074        /**
075         * Recover any messages to be delivered.
076         * 
077         * @param container
078         * @throws Exception
079         */
080        void recover(MessageRecoveryListener container) throws Exception;
081    
082        /**
083         * The destination that the message store is holding messages for.
084         * 
085         * @return the destination
086         */
087        ActiveMQDestination getDestination();
088    
089        /**
090         * @param memoeyUSage The SystemUsage that is controlling the
091         *                destination's memory usage.
092         */
093        void setMemoryUsage(MemoryUsage memoeyUSage);
094    
095        /**
096         * @return the number of messages ready to deliver
097         * @throws IOException
098         * 
099         */
100        int getMessageCount() throws IOException;
101    
102        /**
103         * A hint to the Store to reset any batching state for the Destination
104         * 
105         */
106        void resetBatching();
107    
108        void recoverNextMessages(int maxReturned, MessageRecoveryListener listener) throws Exception;
109    
110        void dispose(ConnectionContext context);
111    
112        /**
113         * allow caching cursors to set the current batch offset when cache is exhausted
114         * @param messageId
115         * @throws Exception 
116         */
117        void setBatch(MessageId messageId) throws Exception;
118        
119        /**
120         * flag to indicate if the store is empty
121         * @return true if the message count is 0
122         * @throws Exception 
123         */
124        boolean isEmpty() throws Exception;
125        
126    }