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