TransactionLog.java
001 /*
002  *
003  * Licensed to the Apache Software Foundation (ASF) under one
004  * or more contributor license agreements.  See the NOTICE file
005  * distributed with this work for additional information
006  * regarding copyright ownership.  The ASF licenses this file
007  * to you under the Apache License, Version 2.0 (the
008  * "License"); you may not use this file except in compliance
009  * with the License.  You may obtain a copy of the License at
010  *
011  *   http://www.apache.org/licenses/LICENSE-2.0
012  *
013  * Unless required by applicable law or agreed to in writing,
014  * software distributed under the License is distributed on an
015  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016  * KIND, either express or implied.  See the License for the
017  * specific language governing permissions and limitations
018  * under the License.
019  *
020  */
021 package org.apache.qpid.server.transactionlog;
022 
023 import org.apache.commons.configuration.Configuration;
024 
025 import org.apache.qpid.AMQException;
026 import org.apache.qpid.framing.AMQShortString;
027 import org.apache.qpid.framing.FieldTable;
028 import org.apache.qpid.framing.abstraction.ContentChunk;
029 import org.apache.qpid.server.configuration.VirtualHostConfiguration;
030 import org.apache.qpid.server.exchange.Exchange;
031 import org.apache.qpid.server.queue.MessageMetaData;
032 import org.apache.qpid.server.queue.AMQQueue;
033 import org.apache.qpid.server.virtualhost.VirtualHost;
034 import org.apache.qpid.server.store.StoreContext;
035 
036 /**
037  * TransactionLog defines the interface for performing transactions.
038  * This is used to preserve the state of messages, queues
039  * and exchanges in a transactional manner.
040  *
041  <p/>All message store, remove, enqueue and dequeue operations are carried out against a {@link StoreContext} which
042  * encapsulates the transactional context they are performed in. Many such operations can be carried out in a single
043  * transaction.
044  *
045  <p/>The storage and removal of queues and exchanges, are not carried out in a transactional context.
046  *
047  <p/><table id="crc"><caption>CRC Card</caption>
048  <tr><th> Responsibilities
049  <tr><td> Accept transaction boundary demarcations: Begin, Commit, Abort.
050  <tr><td> Store and remove queues.
051  <tr><td> Store and remove exchanges.
052  <tr><td> Store and remove messages.
053  <tr><td> Bind and unbind queues to exchanges.
054  <tr><td> Enqueue and dequeue messages to queues.
055  <tr><td> Generate message identifiers.
056  </table>
057  */
058 public interface TransactionLog
059 {
060     /**
061      * Called after instantiation in order to configure the message store. A particular implementation can define
062      * whatever parameters it wants.
063      *
064      @param virtualHost The virtual host using by this store
065      @param base        The base element identifier from which all configuration items are relative. For example, if
066      *                    the base element is "store", the all elements used by concrete classes will be "store.foo" etc.
067      @param config      The apache commons configuration object.
068      *
069      @throws Exception If any error occurs that means the store is unable to configure itself.
070      */
071     void configure(VirtualHost virtualHost, String base, VirtualHostConfiguration configthrows Exception;
072 
073     /**
074      * Called to close and cleanup any resources used by the message store.
075      *
076      @throws Exception If the close fails.
077      */
078     void close() throws Exception;
079 
080     /**
081      * Places a message onto a specified queue, in a given transactional context.
082      *
083      @param context   The transactional context for the operation.
084      @param queue     The queue to place the message on.
085      @param messageId The message to enqueue.
086      @throws AMQException If the operation fails for any reason.
087      */
088     void enqueueMessage(StoreContext context, final AMQQueue queue, Long messageIdthrows AMQException;
089 
090     /**
091      * Extracts a message from a specified queue, in a given transactional context.
092      *
093      @param context   The transactional context for the operation.
094      @param queue     The queue to place the message on.
095      @param messageId The message to dequeue.
096      @throws AMQException If the operation fails for any reason, or if the specified message does not exist.
097      */
098     void dequeueMessage(StoreContext context, final AMQQueue queue, Long messageIdthrows AMQException;
099 
100     /**
101      * Begins a transactional context.
102      *
103      @param context The transactional context to begin.
104      *
105      @throws AMQException If the operation fails for any reason.
106      */
107     void beginTran(StoreContext contextthrows AMQException;
108 
109     /**
110      * Commits all operations performed within a given transactional context.
111      *
112      @param context The transactional context to commit all operations for.
113      *
114      @throws AMQException If the operation fails for any reason.
115      */
116     void commitTran(StoreContext contextthrows AMQException;
117 
118     /**
119      * Abandons all operations performed within a given transactional context.
120      *
121      @param context The transactional context to abandon.
122      *
123      @throws AMQException If the operation fails for any reason.
124      */
125     void abortTran(StoreContext contextthrows AMQException;
126 
127     /**
128      * Tests a transactional context to see if it has been begun but not yet committed or aborted.
129      *
130      @param context The transactional context to test.
131      *
132      @return <tt>true</tt> if the transactional context is live, <tt>false</tt> otherwise.
133      */
134     boolean inTran(StoreContext context);
135 
136 
137     /**
138      * Stores a chunk of message data.
139      *
140      @param context         The transactional context for the operation.
141      @param messageId       The message to store the data for.
142      @param index           The index of the data chunk.
143      @param contentBody     The content of the data chunk.
144      @param lastContentBody Flag to indicate that this is the last such chunk for the message.
145      *
146      @throws AMQException If the operation fails for any reason, or if the specified message does not exist.
147      */
148     void storeContentBodyChunk(StoreContext context, Long messageId, int index, ContentChunk contentBody,
149         boolean lastContentBodythrows AMQException;
150 
151     /**
152      * Stores message meta-data.
153      *
154      @param context         The transactional context for the operation.
155      @param messageId       The message to store the data for.
156      @param messageMetaData The message meta data to store.
157      *
158      @throws AMQException If the operation fails for any reason, or if the specified message does not exist.
159      */
160     void storeMessageMetaData(StoreContext context, Long messageId, MessageMetaData messageMetaDatathrows AMQException;
161 
162     /**
163      * Retrieves message meta-data.
164      *
165      @param context   The transactional context for the operation.
166      @param messageId The message to get the meta-data for.
167      *
168      @return The message meta data.
169      *
170      @throws AMQException If the operation fails for any reason, or if the specified message does not exist.
171      */
172     MessageMetaData getMessageMetaData(StoreContext context, Long messageIdthrows AMQException;
173 
174     /**
175      * Retrieves a chunk of message data.
176      *
177      @param context   The transactional context for the operation.
178      @param messageId The message to get the data chunk for.
179      @param index     The offset index of the data chunk within the message.
180      *
181      @return A chunk of message data.
182      *
183      @throws AMQException If the operation fails for any reason, or if the specified message does not exist.
184      */
185     ContentChunk getContentBodyChunk(StoreContext context, Long messageId, int indexthrows AMQException;
186 
187     /**
188      * Is this store capable of persisting the data
189      *
190      @return true if this store is capable of persisting data
191      */
192     boolean isPersistent();
193 
194 }