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: */
017: package org.apache.commons.transaction.file;
018:
019: import java.io.InputStream;
020: import java.io.OutputStream;
021:
022: import javax.transaction.Status;
023:
024: /**
025: * Interface for resource managers.
026: *
027: * A resource manager is an entity
028: * that manages the processing and administration of resources.
029: *
030: * What is specified here are methods
031: * <ul>
032: * <li>for tasks related to starting and stopping of the resource manager
033: * <li>for transaction management, like
034: * starting, rolling back and committing of transactions
035: * <li>to set and get transaction timeouts
036: * <li>to set the isolation level of a transaction
037: * <li>for the general administration of resources
038: * <li>for reading and writing of resources
039: * </ul>
040: *
041: * @version $Id: ResourceManager.java 513490 2007-03-01 20:46:28Z ozeigermann $
042: */
043: public interface ResourceManager extends Status {
044:
045: /**
046: * Isolation level <b>read uncommitted</b>: data written by other transactions can be read even before they commit
047: */
048: public final static int ISOLATION_LEVEL_READ_UNCOMMITTED = 0;
049:
050: /**
051: * Isolation level <b>read committed</b>: data written by other transactions can be read after they commit
052: */
053: public final static int ISOLATION_LEVEL_READ_COMMITTED = 10;
054:
055: /**
056: * 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
057: */
058: public final static int ISOLATION_LEVEL_REPEATABLE_READ = 50;
059:
060: /**
061: * Isolation level <b>serializable</b>: result of other transactions will not influence the result of this transaction in any way
062: */
063: public final static int ISOLATION_LEVEL_SERIALIZABLE = 100;
064:
065: /**
066: * Shutdown mode: Wait for all transactions to complete
067: */
068: public final static int SHUTDOWN_MODE_NORMAL = 0;
069:
070: /**
071: * Shutdown mode: Try to roll back all active transactions
072: */
073: public final static int SHUTDOWN_MODE_ROLLBACK = 1;
074:
075: /**
076: * Shutdown mode: Try to stop active transaction <em>NOW</em>, do no rollbacks
077: */
078: public final static int SHUTDOWN_MODE_KILL = 2;
079:
080: /**
081: * Prepare result: resource manager guarantees a successful commit
082: */
083: public final static int PREPARE_SUCCESS = 1;
084:
085: /**
086: * Prepare result: resource manager guarantees a successful commit as there is nothing to commit
087: */
088: public final static int PREPARE_SUCCESS_READONLY = 2;
089:
090: /**
091: * Prepare result: transaction can not commit
092: */
093: public final static int PREPARE_FAILURE = -1;
094:
095: /**
096: * Starts this resource manager. A resource manager must be started before transactions
097: * can be started or any operations on transactions can be executed.
098: *
099: * @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)
112: throws ResourceManagerSystemException;
113:
114: /**
115: * Tries to stop this resource manager within a default timeout.
116: *
117: * @param mode one of predefined shutdown modes {@link #SHUTDOWN_MODE_NORMAL}, {@link #SHUTDOWN_MODE_ROLLBACK} or {@link #SHUTDOWN_MODE_KILL}
118: * or any other int representing a shutdown mode
119: * @return <code>true</code> if resource manager stopped within given timeout
120: * @throws ResourceManagerSystemException if anything fatal hapened during shutdown
121: */
122: public boolean stop(int mode) throws ResourceManagerSystemException;
123:
124: /**
125: * Tries to bring this resource manager back to a consistent state.
126: * Might be called after system failure. An administrator might be forced
127: * to fix system errors outside this resource manager to actually make
128: * recovery possible. E.g. there may be a need for more disk space or
129: * a network connection must be reestablished.
130: *
131: * @return <code>true</code> upon successful recovery of the resource manager
132: * @throws ResourceManagerSystemException if anything fatal hapened during recovery
133: */
134: public boolean recover() throws ResourceManagerSystemException;
135:
136: /**
137: * Gets the default isolation level as an integer.
138: * The higher the value the higher the isolation.
139: *
140: * @return one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED},
141: * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE}
142: * or any other int representing an isolation level
143: * @throws ResourceManagerException if an error occured
144: */
145: public int getDefaultIsolationLevel()
146: throws ResourceManagerException;
147:
148: /**
149: * Gets an array of all isolation levels supported by this resource manager.
150: * This array must not be <code>null</code> or empty as every resource manager has some sort of isolation level.
151: *
152: * @return array of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED},
153: * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE}
154: * or any other int representing an isolation level
155: * @throws ResourceManagerException if an error occured
156: * @see #getDefaultIsolationLevel
157: */
158: public int[] getSupportedIsolationLevels()
159: throws ResourceManagerException;
160:
161: /**
162: * Tests if the specified isolation level is supported by this resource manager.
163: *
164: * @param level isolation level whose support is to be tested
165: * @return <code>true</code> if the isolation level is supported
166: * @throws ResourceManagerException if an error occured
167: * @see #getDefaultIsolationLevel
168: */
169: public boolean isIsolationLevelSupported(int level)
170: throws ResourceManagerException;
171:
172: /**
173: * Gets the isolation level for the specified transaction.
174: *
175: * @param txId identifier for the concerned transaction
176: * @return one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED},
177: * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE}
178: * or any other int representing an isolation level
179: * @throws ResourceManagerException if an error occured
180: * @see #getDefaultIsolationLevel
181: */
182: public int getIsolationLevel(Object txId)
183: throws ResourceManagerException;
184:
185: /**
186: * Sets the isolation level for the specified transaction.
187: * <br>
188: * <em>Caution</em>: Implementations are likely to forbid changing the isolation level after any operations
189: * have been executed inside the specified transaction.
190: *
191: * @param txId identifier for the concerned transaction
192: * @param level one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED},
193: * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE}
194: * or any other int representing an isolation level
195: * @throws ResourceManagerException if an error occured
196: * @see #getDefaultIsolationLevel
197: */
198: public void setIsolationLevel(Object txId, int level)
199: throws ResourceManagerException;
200:
201: /**
202: * Gets the default transaction timeout in milliseconds.
203: * After this time expires and the concerned transaction has not finished
204: * - either rolled back or committed - the resource manager is allowed and
205: * also encouraged - but not required - to abort the transaction and to roll it back.
206: *
207: * @return default transaction timeout in milliseconds
208: * @throws ResourceManagerException if an error occured
209: */
210: public long getDefaultTransactionTimeout()
211: throws ResourceManagerException;
212:
213: /**
214: * Gets the transaction timeout of the specified transaction in milliseconds.
215: *
216: * @param txId identifier for the concerned transaction
217: * @return transaction timeout of the specified transaction in milliseconds
218: * @throws ResourceManagerException if an error occured
219: * @see #getDefaultTransactionTimeout
220: */
221: public long getTransactionTimeout(Object txId)
222: throws ResourceManagerException;
223:
224: /**
225: * Sets the transaction timeout of the specified transaction in milliseconds.
226: *
227: * @param txId identifier for the concerned transaction
228: * @param mSecs transaction timeout of the specified transaction in milliseconds
229: * @throws ResourceManagerException if an error occured
230: * @see #getDefaultTransactionTimeout
231: */
232: public void setTransactionTimeout(Object txId, long mSecs)
233: throws ResourceManagerException;
234:
235: /**
236: * Creates and starts a transaction using the specified transaction identifier.
237: * The identifier needs to be unique to this resource manager.
238: * As there is no transaction object returned all access to the transaction
239: * needs to be addressed to this resource manager.
240: *
241: * @param txId identifier for the transaction to be started
242: * @throws ResourceManagerException if an error occured
243: */
244: public void startTransaction(Object txId)
245: throws ResourceManagerException;
246:
247: /**
248: * Prepares the transaction specified by the given transaction identifier for commit.
249: * The preparation may either succeed ({@link #PREPARE_SUCCESS}),
250: * succeed as there is nothing to commit ({@link #PREPARE_SUCCESS_READONLY})
251: * or fail ({@link #PREPARE_FAILURE}). If the preparation fails, commit will
252: * fail as well and the transaction should be marked for rollback. However, if it
253: * succeeds the resource manager must guarantee that a following commit will succeed as well.
254: *
255: * <br><br>
256: * An alternative way to singal a <em>failed</em> status is to throw an exception.
257: *
258: * @param txId identifier for the transaction to be prepared
259: * @return result of the preparation effort, either {@link #PREPARE_SUCCESS}, {@link #PREPARE_SUCCESS_READONLY} or {@link #PREPARE_FAILURE}
260: * @throws ResourceManagerException alternative way to signal prepare failed
261: */
262: public int prepareTransaction(Object txId)
263: throws ResourceManagerException;
264:
265: /**
266: * Marks the transaction specified by the given transaction identifier for rollback.
267: * This means, even though the transaction is not actually finished, no other operation
268: * than <code>rollback</code> is permitted.
269: *
270: * @param txId identifier for the transaction to be marked for rollback
271: * @throws ResourceManagerException if an error occured
272: */
273: public void markTransactionForRollback(Object txId)
274: throws ResourceManagerException;
275:
276: /**
277: * Rolls back the transaction specified by the given transaction identifier.
278: * After roll back the resource manager is allowed to forget about
279: * the associated transaction.
280: *
281: * @param txId identifier for the transaction to be rolled back
282: * @throws ResourceManagerException if an error occured
283: */
284: public void rollbackTransaction(Object txId)
285: throws ResourceManagerException;
286:
287: /**
288: * Commis the transaction specified by the given transaction identifier.
289: * After commit the resource manager is allowed to forget about
290: * the associated transaction.
291: *
292: * @param txId identifier for the transaction to be committed
293: * @throws ResourceManagerException if an error occured
294: */
295: public void commitTransaction(Object txId)
296: throws ResourceManagerException;
297:
298: /**
299: * Gets the state of the transaction specified by the given transaction identifier.
300: * The state will be expressed by an <code>int</code> code as defined
301: * in the {@link javax.transaction.Status} interface.
302: *
303: * @param txId identifier for the transaction for which the state is returned
304: * @return state of the transaction as defined in {@link javax.transaction.Status}
305: * @throws ResourceManagerException if an error occured
306: */
307: public int getTransactionState(Object txId)
308: throws ResourceManagerException;
309:
310: /**
311: * Explicitly locks a resource. Although locking must be done implicitly by methods
312: * creating, reading or modifying resources, there may be cases when you want to do this
313: * explicitly.<br>
314: *
315: *<br>
316: * <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.
317: * This is done to make clear locking affects all transactions, not only the locking one.
318: * This should be clear anyhow, but seems to be worth noting.
319: *
320: * @param resourceId identifier for the resource to be locked
321: * @param txId identifier for the transaction that tries to acquire a lock
322: * @param shared <code>true</code> if this lock may be shared by other <em>shared</em> locks
323: * @param wait <code>true</code> if the method shall block when lock can not be acquired now
324: * @param timeoutMSecs timeout in milliseconds
325: * @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
326: * @return <code>true</code> when the lock has been acquired
327: * @throws ResourceManagerException if an error occured
328: */
329: public boolean lockResource(Object resourceId, Object txId,
330: boolean shared, boolean wait, long timeoutMSecs,
331: boolean reentrant) throws ResourceManagerException;
332:
333: /**
334: * Explicitly locks a resource in reentrant style. This method blocks until the lock
335: * actually can be acquired or the transaction times out.
336: *
337: * @param resourceId identifier for the resource to be locked
338: * @param txId identifier for the transaction that tries to acquire a lock
339: * @param shared <code>true</code> if this lock may be shared by other <em>shared</em> locks
340: * @throws ResourceManagerException if an error occured
341: * @see #lockResource(Object, Object, boolean, boolean, long, boolean)
342: */
343: public boolean lockResource(Object resourceId, Object txId,
344: boolean shared) throws ResourceManagerException;
345:
346: /**
347: * Explicitly locks a resource exclusively, i.e. for writing, in reentrant style. This method blocks until the lock
348: * actually can be acquired or the transaction times out.
349: *
350: * @param resourceId identifier for the resource to be locked
351: * @param txId identifier for the transaction that tries to acquire a lock
352: * @throws ResourceManagerException if an error occured
353: * @see #lockResource(Object, Object, boolean)
354: * @see #lockResource(Object, Object, boolean, boolean, long, boolean)
355: */
356: public boolean lockResource(Object resourceId, Object txId)
357: throws ResourceManagerException;
358:
359: /**
360: * Checks if a resource exists.
361: *
362: * @param txId identifier for the transaction in which the resource is to be checked for
363: * @param resourceId identifier for the resource to check for
364: * @return <code>true</code> if the resource exists
365: * @throws ResourceManagerException if an error occured
366: */
367: public boolean resourceExists(Object txId, Object resourceId)
368: throws ResourceManagerException;
369:
370: /**
371: * Checks if a resource exists wihtout being in a transaction. This means only take
372: * into account resources already globally commited.
373: *
374: * @param resourceId identifier for the resource to check for
375: * @return <code>true</code> if the resource exists
376: * @throws ResourceManagerException if an error occured
377: */
378: public boolean resourceExists(Object resourceId)
379: throws ResourceManagerException;
380:
381: /**
382: * Deletes a resource.
383: *
384: * @param txId identifier for the transaction in which the resource is to be deleted
385: * @param resourceId identifier for the resource to be deleted
386: * @throws ResourceManagerException if the resource does not exist or any other error occured
387: */
388: public void deleteResource(Object txId, Object resourceId)
389: throws ResourceManagerException;
390:
391: /**
392: * Deletes a resource.
393: *
394: * @param txId identifier for the transaction in which the resource is to be deleted
395: * @param resourceId identifier for the resource to be deleted
396: * @param assureOnly if set to <code>true</code> this method will not throw an exception when the resource does not exist
397: * @throws ResourceManagerException if the resource does not exist and <code>assureOnly</code> was not set to <code>true</code> or any other error occured
398: */
399: public void deleteResource(Object txId, Object resourceId,
400: boolean assureOnly) throws ResourceManagerException;
401:
402: /**
403: * Creates a resource.
404: *
405: * @param txId identifier for the transaction in which the resource is to be created
406: * @param resourceId identifier for the resource to be created
407: * @throws ResourceManagerException if the resource already exist or any other error occured
408: */
409: public void createResource(Object txId, Object resourceId)
410: throws ResourceManagerException;
411:
412: /**
413: * Creates a resource.
414: *
415: * @param txId identifier for the transaction in which the resource is to be created
416: * @param resourceId identifier for the resource to be created
417: * @param assureOnly if set to <code>true</code> this method will not throw an exception when the resource already exists
418: * @throws ResourceManagerException if the resource already exists and <code>assureOnly</code> was not set to <code>true</code> or any other error occured
419: */
420: public void createResource(Object txId, Object resourceId,
421: boolean assureOnly) throws ResourceManagerException;
422:
423: /**
424: * Opens a streamable resource for reading.
425: *
426: * <br><br>
427: * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.
428: *
429: * @param txId identifier for the transaction in which the streamable resource is to be openend
430: * @param resourceId identifier for the streamable resource to be opened
431: * @return stream to read from
432: * @throws ResourceManagerException if the resource does not exist or any other error occured
433: */
434: public InputStream readResource(Object txId, Object resourceId)
435: throws ResourceManagerException;
436:
437: /**
438: * Opens a streamable resource for a single reading request not inside the scope of a transaction.
439: *
440: * <br><br>
441: * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.
442: *
443: * @param resourceId identifier for the streamable resource to be opened
444: * @return stream to read from
445: * @throws ResourceManagerException if the resource does not exist or any other error occured
446: */
447: public InputStream readResource(Object resourceId)
448: throws ResourceManagerException;
449:
450: /**
451: * Opens a resource for writing.
452: *
453: * <br><br>
454: * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.
455: *
456: * @param txId identifier for the transaction in which the streamable resource is to be openend
457: * @param resourceId identifier for the streamable resource to be opened
458: * @return stream to write to
459: * @throws ResourceManagerException if the resource does not exist or any other error occured
460: */
461: public OutputStream writeResource(Object txId, Object resourceId)
462: throws ResourceManagerException;
463: }
|