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;
020import java.util.concurrent.Future;
021
022import org.apache.activemq.Service;
023import org.apache.activemq.broker.ConnectionContext;
024import org.apache.activemq.command.ActiveMQDestination;
025import org.apache.activemq.command.Message;
026import org.apache.activemq.command.MessageAck;
027import org.apache.activemq.command.MessageId;
028import org.apache.activemq.usage.MemoryUsage;
029
030/**
031 * Represents a message store which is used by the persistent implementations
032 *
033 *
034 */
035public 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}