1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.transaction.file;
18
19 import java.io.InputStream;
20 import java.io.OutputStream;
21
22 import javax.transaction.Status;
23
24 /**
25 * Interface for resource managers.
26 *
27 * A resource manager is an entity
28 * that manages the processing and administration of resources.
29 *
30 * What is specified here are methods
31 * <ul>
32 * <li>for tasks related to starting and stopping of the resource manager
33 * <li>for transaction management, like
34 * starting, rolling back and committing of transactions
35 * <li>to set and get transaction timeouts
36 * <li>to set the isolation level of a transaction
37 * <li>for the general administration of resources
38 * <li>for reading and writing of resources
39 * </ul>
40 *
41 * @version $Id: ResourceManager.java 513490 2007-03-01 20:46:28Z ozeigermann $
42 */
43 public interface ResourceManager extends Status {
44
45 /**
46 * Isolation level <b>read uncommitted</b>: data written by other transactions can be read even before they commit
47 */
48 public final static int ISOLATION_LEVEL_READ_UNCOMMITTED = 0;
49
50 /**
51 * Isolation level <b>read committed</b>: data written by other transactions can be read after they commit
52 */
53 public final static int ISOLATION_LEVEL_READ_COMMITTED = 10;
54
55 /**
56 * Isolation level <b>repeatable read</b>: data written by other transactions can be read after they commit if this transaction has not read this data before
57 */
58 public final static int ISOLATION_LEVEL_REPEATABLE_READ = 50;
59
60 /**
61 * Isolation level <b>serializable</b>: result of other transactions will not influence the result of this transaction in any way
62 */
63 public final static int ISOLATION_LEVEL_SERIALIZABLE = 100;
64
65 /**
66 * Shutdown mode: Wait for all transactions to complete
67 */
68 public final static int SHUTDOWN_MODE_NORMAL = 0;
69
70 /**
71 * Shutdown mode: Try to roll back all active transactions
72 */
73 public final static int SHUTDOWN_MODE_ROLLBACK = 1;
74
75 /**
76 * Shutdown mode: Try to stop active transaction <em>NOW</em>, do no rollbacks
77 */
78 public final static int SHUTDOWN_MODE_KILL = 2;
79
80 /**
81 * Prepare result: resource manager guarantees a successful commit
82 */
83 public final static int PREPARE_SUCCESS = 1;
84
85 /**
86 * Prepare result: resource manager guarantees a successful commit as there is nothing to commit
87 */
88 public final static int PREPARE_SUCCESS_READONLY = 2;
89
90 /**
91 * Prepare result: transaction can not commit
92 */
93 public final static int PREPARE_FAILURE = -1;
94
95 /**
96 * Starts this resource manager. A resource manager must be started before transactions
97 * can be started or any operations on transactions can be executed.
98 *
99 * @throws ResourceManagerSystemException if start failed due to internal problems
100 */
101 public void start() throws ResourceManagerSystemException;
102
103 /**
104 * Tries to stop this resource manager within the given timeout.
105 *
106 * @param mode one of {@link #SHUTDOWN_MODE_NORMAL}, {@link #SHUTDOWN_MODE_ROLLBACK} or {@link #SHUTDOWN_MODE_KILL}
107 * @param timeoutMSecs timeout for shutdown in milliseconds
108 * @return <code>true</code> if resource manager stopped within given timeout
109 * @throws ResourceManagerSystemException if something fatal hapened during shutdown
110 */
111 public boolean stop(int mode, long timeoutMSecs) throws ResourceManagerSystemException;
112
113 /**
114 * Tries to stop this resource manager within a default timeout.
115 *
116 * @param mode one of predefined shutdown modes {@link #SHUTDOWN_MODE_NORMAL}, {@link #SHUTDOWN_MODE_ROLLBACK} or {@link #SHUTDOWN_MODE_KILL}
117 * or any other int representing a shutdown mode
118 * @return <code>true</code> if resource manager stopped within given timeout
119 * @throws ResourceManagerSystemException if anything fatal hapened during shutdown
120 */
121 public boolean stop(int mode) throws ResourceManagerSystemException;
122
123 /**
124 * Tries to bring this resource manager back to a consistent state.
125 * Might be called after system failure. An administrator might be forced
126 * to fix system errors outside this resource manager to actually make
127 * recovery possible. E.g. there may be a need for more disk space or
128 * a network connection must be reestablished.
129 *
130 * @return <code>true</code> upon successful recovery of the resource manager
131 * @throws ResourceManagerSystemException if anything fatal hapened during recovery
132 */
133 public boolean recover() throws ResourceManagerSystemException;
134
135 /**
136 * Gets the default isolation level as an integer.
137 * The higher the value the higher the isolation.
138 *
139 * @return one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED},
140 * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE}
141 * or any other int representing an isolation level
142 * @throws ResourceManagerException if an error occured
143 */
144 public int getDefaultIsolationLevel() throws ResourceManagerException;
145
146 /**
147 * Gets an array of all isolation levels supported by this resource manager.
148 * This array must not be <code>null</code> or empty as every resource manager has some sort of isolation level.
149 *
150 * @return array of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED},
151 * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE}
152 * or any other int representing an isolation level
153 * @throws ResourceManagerException if an error occured
154 * @see #getDefaultIsolationLevel
155 */
156 public int[] getSupportedIsolationLevels() throws ResourceManagerException;
157
158 /**
159 * Tests if the specified isolation level is supported by this resource manager.
160 *
161 * @param level isolation level whose support is to be tested
162 * @return <code>true</code> if the isolation level is supported
163 * @throws ResourceManagerException if an error occured
164 * @see #getDefaultIsolationLevel
165 */
166 public boolean isIsolationLevelSupported(int level) throws ResourceManagerException;
167
168 /**
169 * Gets the isolation level for the specified transaction.
170 *
171 * @param txId identifier for the concerned transaction
172 * @return one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED},
173 * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE}
174 * or any other int representing an isolation level
175 * @throws ResourceManagerException if an error occured
176 * @see #getDefaultIsolationLevel
177 */
178 public int getIsolationLevel(Object txId) throws ResourceManagerException;
179
180 /**
181 * Sets the isolation level for the specified transaction.
182 * <br>
183 * <em>Caution</em>: Implementations are likely to forbid changing the isolation level after any operations
184 * have been executed inside the specified transaction.
185 *
186 * @param txId identifier for the concerned transaction
187 * @param level one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED},
188 * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE}
189 * or any other int representing an isolation level
190 * @throws ResourceManagerException if an error occured
191 * @see #getDefaultIsolationLevel
192 */
193 public void setIsolationLevel(Object txId, int level) throws ResourceManagerException;
194
195 /**
196 * Gets the default transaction timeout in milliseconds.
197 * After this time expires and the concerned transaction has not finished
198 * - either rolled back or committed - the resource manager is allowed and
199 * also encouraged - but not required - to abort the transaction and to roll it back.
200 *
201 * @return default transaction timeout in milliseconds
202 * @throws ResourceManagerException if an error occured
203 */
204 public long getDefaultTransactionTimeout() throws ResourceManagerException;
205
206 /**
207 * Gets the transaction timeout of the specified transaction in milliseconds.
208 *
209 * @param txId identifier for the concerned transaction
210 * @return transaction timeout of the specified transaction in milliseconds
211 * @throws ResourceManagerException if an error occured
212 * @see #getDefaultTransactionTimeout
213 */
214 public long getTransactionTimeout(Object txId) throws ResourceManagerException;
215
216 /**
217 * Sets the transaction timeout of the specified transaction in milliseconds.
218 *
219 * @param txId identifier for the concerned transaction
220 * @param mSecs transaction timeout of the specified transaction in milliseconds
221 * @throws ResourceManagerException if an error occured
222 * @see #getDefaultTransactionTimeout
223 */
224 public void setTransactionTimeout(Object txId, long mSecs) throws ResourceManagerException;
225
226 /**
227 * Creates and starts a transaction using the specified transaction identifier.
228 * The identifier needs to be unique to this resource manager.
229 * As there is no transaction object returned all access to the transaction
230 * needs to be addressed to this resource manager.
231 *
232 * @param txId identifier for the transaction to be started
233 * @throws ResourceManagerException if an error occured
234 */
235 public void startTransaction(Object txId) throws ResourceManagerException;
236
237 /**
238 * Prepares the transaction specified by the given transaction identifier for commit.
239 * The preparation may either succeed ({@link #PREPARE_SUCCESS}),
240 * succeed as there is nothing to commit ({@link #PREPARE_SUCCESS_READONLY})
241 * or fail ({@link #PREPARE_FAILURE}). If the preparation fails, commit will
242 * fail as well and the transaction should be marked for rollback. However, if it
243 * succeeds the resource manager must guarantee that a following commit will succeed as well.
244 *
245 * <br><br>
246 * An alternative way to singal a <em>failed</em> status is to throw an exception.
247 *
248 * @param txId identifier for the transaction to be prepared
249 * @return result of the preparation effort, either {@link #PREPARE_SUCCESS}, {@link #PREPARE_SUCCESS_READONLY} or {@link #PREPARE_FAILURE}
250 * @throws ResourceManagerException alternative way to signal prepare failed
251 */
252 public int prepareTransaction(Object txId) throws ResourceManagerException;
253
254 /**
255 * Marks the transaction specified by the given transaction identifier for rollback.
256 * This means, even though the transaction is not actually finished, no other operation
257 * than <code>rollback</code> is permitted.
258 *
259 * @param txId identifier for the transaction to be marked for rollback
260 * @throws ResourceManagerException if an error occured
261 */
262 public void markTransactionForRollback(Object txId) throws ResourceManagerException;
263
264 /**
265 * Rolls back the transaction specified by the given transaction identifier.
266 * After roll back the resource manager is allowed to forget about
267 * the associated transaction.
268 *
269 * @param txId identifier for the transaction to be rolled back
270 * @throws ResourceManagerException if an error occured
271 */
272 public void rollbackTransaction(Object txId) throws ResourceManagerException;
273
274 /**
275 * Commis the transaction specified by the given transaction identifier.
276 * After commit the resource manager is allowed to forget about
277 * the associated transaction.
278 *
279 * @param txId identifier for the transaction to be committed
280 * @throws ResourceManagerException if an error occured
281 */
282 public void commitTransaction(Object txId) throws ResourceManagerException;
283
284 /**
285 * Gets the state of the transaction specified by the given transaction identifier.
286 * The state will be expressed by an <code>int</code> code as defined
287 * in the {@link javax.transaction.Status} interface.
288 *
289 * @param txId identifier for the transaction for which the state is returned
290 * @return state of the transaction as defined in {@link javax.transaction.Status}
291 * @throws ResourceManagerException if an error occured
292 */
293 public int getTransactionState(Object txId) throws ResourceManagerException;
294
295 /**
296 * Explicitly locks a resource. Although locking must be done implicitly by methods
297 * creating, reading or modifying resources, there may be cases when you want to do this
298 * explicitly.<br>
299 *
300 *<br>
301 * <em>Note</em>: By intention the order of parameters (<code>txId</code> does not come first) is different than in other methods of this interface.
302 * This is done to make clear locking affects all transactions, not only the locking one.
303 * This should be clear anyhow, but seems to be worth noting.
304 *
305 * @param resourceId identifier for the resource to be locked
306 * @param txId identifier for the transaction that tries to acquire a lock
307 * @param shared <code>true</code> if this lock may be shared by other <em>shared</em> locks
308 * @param wait <code>true</code> if the method shall block when lock can not be acquired now
309 * @param timeoutMSecs timeout in milliseconds
310 * @param reentrant <code>true</code> if the lock should be acquired even when the <em>requesting transaction and no other</em> holds an incompatible lock
311 * @return <code>true</code> when the lock has been acquired
312 * @throws ResourceManagerException if an error occured
313 */
314 public boolean lockResource(
315 Object resourceId,
316 Object txId,
317 boolean shared,
318 boolean wait,
319 long timeoutMSecs,
320 boolean reentrant)
321 throws ResourceManagerException;
322
323 /**
324 * Explicitly locks a resource in reentrant style. This method blocks until the lock
325 * actually can be acquired or the transaction times out.
326 *
327 * @param resourceId identifier for the resource to be locked
328 * @param txId identifier for the transaction that tries to acquire a lock
329 * @param shared <code>true</code> if this lock may be shared by other <em>shared</em> locks
330 * @throws ResourceManagerException if an error occured
331 * @see #lockResource(Object, Object, boolean, boolean, long, boolean)
332 */
333 public boolean lockResource(Object resourceId, Object txId, boolean shared) throws ResourceManagerException;
334
335 /**
336 * Explicitly locks a resource exclusively, i.e. for writing, in reentrant style. This method blocks until the lock
337 * actually can be acquired or the transaction times out.
338 *
339 * @param resourceId identifier for the resource to be locked
340 * @param txId identifier for the transaction that tries to acquire a lock
341 * @throws ResourceManagerException if an error occured
342 * @see #lockResource(Object, Object, boolean)
343 * @see #lockResource(Object, Object, boolean, boolean, long, boolean)
344 */
345 public boolean lockResource(Object resourceId, Object txId) throws ResourceManagerException;
346
347 /**
348 * Checks if a resource exists.
349 *
350 * @param txId identifier for the transaction in which the resource is to be checked for
351 * @param resourceId identifier for the resource to check for
352 * @return <code>true</code> if the resource exists
353 * @throws ResourceManagerException if an error occured
354 */
355 public boolean resourceExists(Object txId, Object resourceId) throws ResourceManagerException;
356
357 /**
358 * Checks if a resource exists wihtout being in a transaction. This means only take
359 * into account resources already globally commited.
360 *
361 * @param resourceId identifier for the resource to check for
362 * @return <code>true</code> if the resource exists
363 * @throws ResourceManagerException if an error occured
364 */
365 public boolean resourceExists(Object resourceId) throws ResourceManagerException;
366
367 /**
368 * Deletes a resource.
369 *
370 * @param txId identifier for the transaction in which the resource is to be deleted
371 * @param resourceId identifier for the resource to be deleted
372 * @throws ResourceManagerException if the resource does not exist or any other error occured
373 */
374 public void deleteResource(Object txId, Object resourceId) throws ResourceManagerException;
375
376 /**
377 * Deletes a resource.
378 *
379 * @param txId identifier for the transaction in which the resource is to be deleted
380 * @param resourceId identifier for the resource to be deleted
381 * @param assureOnly if set to <code>true</code> this method will not throw an exception when the resource does not exist
382 * @throws ResourceManagerException if the resource does not exist and <code>assureOnly</code> was not set to <code>true</code> or any other error occured
383 */
384 public void deleteResource(Object txId, Object resourceId, boolean assureOnly) throws ResourceManagerException;
385
386 /**
387 * Creates a resource.
388 *
389 * @param txId identifier for the transaction in which the resource is to be created
390 * @param resourceId identifier for the resource to be created
391 * @throws ResourceManagerException if the resource already exist or any other error occured
392 */
393 public void createResource(Object txId, Object resourceId) throws ResourceManagerException;
394
395 /**
396 * Creates a resource.
397 *
398 * @param txId identifier for the transaction in which the resource is to be created
399 * @param resourceId identifier for the resource to be created
400 * @param assureOnly if set to <code>true</code> this method will not throw an exception when the resource already exists
401 * @throws ResourceManagerException if the resource already exists and <code>assureOnly</code> was not set to <code>true</code> or any other error occured
402 */
403 public void createResource(Object txId, Object resourceId, boolean assureOnly) throws ResourceManagerException;
404
405 /**
406 * Opens a streamable resource for reading.
407 *
408 * <br><br>
409 * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.
410 *
411 * @param txId identifier for the transaction in which the streamable resource is to be openend
412 * @param resourceId identifier for the streamable resource to be opened
413 * @return stream to read from
414 * @throws ResourceManagerException if the resource does not exist or any other error occured
415 */
416 public InputStream readResource(Object txId, Object resourceId) throws ResourceManagerException;
417
418 /**
419 * Opens a streamable resource for a single reading request not inside the scope of a transaction.
420 *
421 * <br><br>
422 * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.
423 *
424 * @param resourceId identifier for the streamable resource to be opened
425 * @return stream to read from
426 * @throws ResourceManagerException if the resource does not exist or any other error occured
427 */
428 public InputStream readResource(Object resourceId) throws ResourceManagerException;
429
430 /**
431 * Opens a resource for writing.
432 *
433 * <br><br>
434 * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.
435 *
436 * @param txId identifier for the transaction in which the streamable resource is to be openend
437 * @param resourceId identifier for the streamable resource to be opened
438 * @return stream to write to
439 * @throws ResourceManagerException if the resource does not exist or any other error occured
440 */
441 public OutputStream writeResource(Object txId, Object resourceId) throws ResourceManagerException;
442 }