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 config) throws 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 messageId) throws 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 messageId) throws 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 context) throws 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 context) throws 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 context) throws 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 lastContentBody) throws 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 messageMetaData) throws 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 messageId) throws 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 index) throws 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 }
|