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.File;
020import java.io.IOException;
021import java.util.Set;
022
023import org.apache.activemq.Service;
024import org.apache.activemq.broker.ConnectionContext;
025import org.apache.activemq.broker.scheduler.JobSchedulerStore;
026import org.apache.activemq.command.ActiveMQDestination;
027import org.apache.activemq.command.ActiveMQQueue;
028import org.apache.activemq.command.ActiveMQTopic;
029import org.apache.activemq.command.ProducerId;
030import org.apache.activemq.usage.SystemUsage;
031
032/**
033 * Adapter to the actual persistence mechanism used with ActiveMQ
034 *
035 *
036 */
037public interface PersistenceAdapter extends Service {
038
039    /**
040     * Returns a set of all the
041     * {@link org.apache.activemq.command.ActiveMQDestination} objects that the
042     * persistence store is aware exist.
043     *
044     * @return active destinations
045     */
046    Set<ActiveMQDestination> getDestinations();
047
048    /**
049     * Factory method to create a new queue message store with the given
050     * destination name
051     *
052     * @param destination
053     * @return the message store
054     * @throws IOException
055     */
056    MessageStore createQueueMessageStore(ActiveMQQueue destination) throws IOException;
057
058    /**
059     * Factory method to create a new topic message store with the given
060     * destination name
061     *
062     * @param destination
063     * @return the topic message store
064     * @throws IOException
065     */
066    TopicMessageStore createTopicMessageStore(ActiveMQTopic destination) throws IOException;
067
068    /**
069     * Creates and returns a new Job Scheduler store instance.
070     *
071     * @return a new JobSchedulerStore instance if this Persistence adapter provides its own.
072     *
073     * @throws IOException If an error occurs while creating the new JobSchedulerStore.
074     * @throws UnsupportedOperationException If this adapter does not provide its own
075     *                                       scheduler store implementation.
076     */
077    JobSchedulerStore createJobSchedulerStore() throws IOException, UnsupportedOperationException;
078
079    /**
080     * Cleanup method to remove any state associated with the given destination.
081     * This method does not stop the message store (it might not be cached).
082     *
083     * @param destination
084     *            Destination to forget
085     */
086    void removeQueueMessageStore(ActiveMQQueue destination);
087
088    /**
089     * Cleanup method to remove any state associated with the given destination
090     * This method does not stop the message store (it might not be cached).
091     *
092     * @param destination
093     *            Destination to forget
094     */
095    void removeTopicMessageStore(ActiveMQTopic destination);
096
097    /**
098     * Factory method to create a new persistent prepared transaction store for
099     * XA recovery
100     *
101     * @return transaction store
102     * @throws IOException
103     */
104    TransactionStore createTransactionStore() throws IOException;
105
106    /**
107     * This method starts a transaction on the persistent storage - which is
108     * nothing to do with JMS or XA transactions - its purely a mechanism to
109     * perform multiple writes to a persistent store in 1 transaction as a
110     * performance optimization.
111     * <p/>
112     * Typically one transaction will require one disk synchronization point and
113     * so for real high performance its usually faster to perform many writes
114     * within the same transaction to minimize latency caused by disk
115     * synchronization. This is especially true when using tools like Berkeley
116     * Db or embedded JDBC servers.
117     *
118     * @param context
119     * @throws IOException
120     */
121    void beginTransaction(ConnectionContext context) throws IOException;
122
123    /**
124     * Commit a persistence transaction
125     *
126     * @param context
127     * @throws IOException
128     *
129     * @see PersistenceAdapter#beginTransaction(ConnectionContext context)
130     */
131    void commitTransaction(ConnectionContext context) throws IOException;
132
133    /**
134     * Rollback a persistence transaction
135     *
136     * @param context
137     * @throws IOException
138     *
139     * @see PersistenceAdapter#beginTransaction(ConnectionContext context)
140     */
141    void rollbackTransaction(ConnectionContext context) throws IOException;
142
143    /**
144     *
145     * @return last broker sequence
146     * @throws IOException
147     */
148    long getLastMessageBrokerSequenceId() throws IOException;
149
150    /**
151     * Delete's all the messages in the persistent store.
152     *
153     * @throws IOException
154     */
155    void deleteAllMessages() throws IOException;
156
157    /**
158     * @param usageManager
159     *            The UsageManager that is controlling the broker's memory
160     *            usage.
161     */
162    void setUsageManager(SystemUsage usageManager);
163
164    /**
165     * Set the name of the broker using the adapter
166     *
167     * @param brokerName
168     */
169    void setBrokerName(String brokerName);
170
171    /**
172     * Set the directory where any data files should be created
173     *
174     * @param dir
175     */
176    void setDirectory(File dir);
177
178    /**
179     * @return the directory used by the persistence adaptor
180     */
181    File getDirectory();
182
183    /**
184     * checkpoint any
185     *
186     * @param sync
187     * @throws IOException
188     *
189     */
190    void checkpoint(boolean sync) throws IOException;
191
192    /**
193     * A hint to return the size of the store on disk
194     *
195     * @return disk space used in bytes of 0 if not implemented
196     */
197    long size();
198
199    /**
200     * return the last stored producer sequenceId for this producer Id used to
201     * suppress duplicate sends on failover reconnect at the transport when a
202     * reconnect occurs
203     *
204     * @param id
205     *            the producerId to find a sequenceId for
206     * @return the last stored sequence id or -1 if no suppression needed
207     */
208    long getLastProducerSequenceId(ProducerId id) throws IOException;
209
210    void allowIOResumption();
211}