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 java.util.concurrent.Future;
021    import org.apache.activemq.Service;
022    import org.apache.activemq.broker.ConnectionContext;
023    import org.apache.activemq.command.ActiveMQDestination;
024    import org.apache.activemq.command.Message;
025    import org.apache.activemq.command.MessageAck;
026    import org.apache.activemq.command.MessageId;
027    import org.apache.activemq.usage.MemoryUsage;
028    
029    /**
030     * Represents a message store which is used by the persistent implementations
031     * 
032     * 
033     */
034    public interface MessageStore extends Service {
035    
036        /**
037         * Adds a message to the message store
038         * 
039         * @param context context
040         * @param message
041         * @throws IOException
042         */
043        void addMessage(ConnectionContext context, Message message) throws IOException;
044        
045        /**
046         * Adds a message to the message store
047         * 
048         * @param context context
049         * @param message
050         * @return a Future to track when this is complete
051         * @throws IOException 
052         * @throws IOException
053         */
054        Future<Object> asyncAddQueueMessage(ConnectionContext context, Message message) throws IOException;
055        
056        /**
057         * Adds a message to the message store
058         * 
059         * @param context context
060         * @param message
061         * @return a Future to track when this is complete
062         * @throws IOException 
063         * @throws IOException
064         */
065        Future<Object> asyncAddTopicMessage(ConnectionContext context, Message message) throws IOException;
066    
067        /**
068         * Looks up a message using either the String messageID or the
069         * messageNumber. Implementations are encouraged to fill in the missing key
070         * if its easy to do so.
071         * 
072         * @param identity which contains either the messageID or the messageNumber
073         * @return the message or null if it does not exist
074         * @throws IOException
075         */
076        Message getMessage(MessageId identity) throws IOException;
077    
078        /**
079         * Removes a message from the message store.
080         * 
081         * @param context
082         * @param ack the ack request that cause the message to be removed. It
083         *                conatins the identity which contains the messageID of the
084         *                message that needs to be removed.
085         * @throws IOException
086         */
087        void removeMessage(ConnectionContext context, MessageAck ack) throws IOException;
088        
089        void removeAsyncMessage(ConnectionContext context, MessageAck ack) throws IOException;
090    
091        /**
092         * Removes all the messages from the message store.
093         * 
094         * @param context
095         * @throws IOException
096         */
097        void removeAllMessages(ConnectionContext context) throws IOException;
098    
099        /**
100         * Recover any messages to be delivered.
101         * 
102         * @param container
103         * @throws Exception
104         */
105        void recover(MessageRecoveryListener container) throws Exception;
106    
107        /**
108         * The destination that the message store is holding messages for.
109         * 
110         * @return the destination
111         */
112        ActiveMQDestination getDestination();
113    
114        /**
115         * @param memoeyUSage The SystemUsage that is controlling the
116         *                destination's memory usage.
117         */
118        void setMemoryUsage(MemoryUsage memoeyUSage);
119    
120        /**
121         * @return the number of messages ready to deliver
122         * @throws IOException
123         * 
124         */
125        int getMessageCount() throws IOException;
126    
127        /**
128         * A hint to the Store to reset any batching state for the Destination
129         * 
130         */
131        void resetBatching();
132    
133        void recoverNextMessages(int maxReturned, MessageRecoveryListener listener) throws Exception;
134    
135        void dispose(ConnectionContext context);
136    
137        /**
138         * allow caching cursors to set the current batch offset when cache is exhausted
139         * @param messageId
140         * @throws Exception 
141         */
142        void setBatch(MessageId messageId) throws Exception;
143        
144        /**
145         * flag to indicate if the store is empty
146         * @return true if the message count is 0
147         * @throws Exception 
148         */
149        boolean isEmpty() throws Exception;
150        
151        /**
152         * A hint to the store to try recover messages according to priority
153         * @param prioritizedMessages
154         */
155        public void setPrioritizedMessages(boolean prioritizedMessages);
156        
157        /**
158         * 
159         * @return true if store is trying to recover messages according to priority
160         */
161        public boolean isPrioritizedMessages();
162        
163    }