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