ResourceManager


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