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