Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.transaction.file
Interface ResourceManager

All Superinterfaces:
  Status

All Known Implementing Classes:
  FileResourceManager

public interface ResourceManager
extends Status

Interface for resource managers. A resource manager is an entity that manages the processing and administration of resources. What is specified here are methods

- for tasks related to starting and stopping of the resource manager
- for transaction management, like starting, rolling back and committing of transactions
- to set and get transaction timeouts
- to set the isolation level of a transaction
- for the general administration of resources
- for reading and writing of resources

Version:
  $Revision$

Field Summary
`static int` | `ISOLATION_LEVEL_READ_COMMITTED` Isolation level read committed: data written by other transactions can be read after they commit
`static int` | `ISOLATION_LEVEL_READ_UNCOMMITTED` Isolation level read uncommitted: data written by other transactions can be read even before they commit
`static int` | `ISOLATION_LEVEL_REPEATABLE_READ` Isolation level repeatable read: data written by other transactions can be read after they commit if this transaction has not read this data before
`static int` | `ISOLATION_LEVEL_SERIALIZABLE` Isolation level serializable: result of other transactions will not influence the result of this transaction in any way
`static int` | `PREPARE_FAILURE` Prepare result: transaction can not commit
`static int` | `PREPARE_SUCCESS` Prepare result: resource manager guarantees a successful commit
`static int` | `PREPARE_SUCCESS_READONLY` Prepare result: resource manager guarantees a successful commit as there is nothing to commit
`static int` | `SHUTDOWN_MODE_KILL` Shutdown mode: Try to stop active transaction NOW, do no rollbacks
`static int` | `SHUTDOWN_MODE_NORMAL` Shutdown mode: Wait for all transactions to complete
`static int` | `SHUTDOWN_MODE_ROLLBACK` Shutdown mode: Try to roll back all active transactions

Fields inherited from interface javax.transaction.Status
`STATUS_ACTIVE, STATUS_COMMITTED, STATUS_COMMITTING, STATUS_MARKED_ROLLBACK, STATUS_NO_TRANSACTION, STATUS_PREPARED, STATUS_PREPARING, STATUS_ROLLEDBACK, STATUS_ROLLING_BACK, STATUS_UNKNOWN`

Method Summary
`void` | `commitTransaction(Object txId)` Commis the transaction specified by the given transaction identifier.
`void` | `createResource(Object txId, Object resourceId)` Creates a resource.
`void` | `createResource(Object txId, Object resourceId, boolean assureOnly)` Creates a resource.
`void` | `deleteResource(Object txId, Object resourceId)` Deletes a resource.
`void` | `deleteResource(Object txId, Object resourceId, boolean assureOnly)` Deletes a resource.
`int` | `getDefaultIsolationLevel()` Gets the default isolation level as an integer.
`long` | `getDefaultTransactionTimeout()` Gets the default transaction timeout.
`int` | `getIsolationLevel(Object txId)` Gets the isolation level for the specified transaction.
`int[]` | `getSupportedIsolationLevels()` Gets an array of all isolation levels supported by this resource manager.
`int` | `getTransactionState(Object txId)` Gets the state of the transaction specified by the given transaction identifier.
`long` | `getTransactionTimeout(Object txId)` Gets the transaction timeout of the specified transaction.
`boolean` | `isIsolationLevelSupported(int level)` Tests if the specified isolation level is supported by this resource manager.
`boolean` | `lockResource(Object resourceId, Object txId)` Explicitly locks a resource exclusively, i.e. for writing, in reentrant style.
`boolean` | `lockResource(Object resourceId, Object txId, boolean shared)` Explicitly locks a resource in reentrant style.
`boolean` | `lockResource(Object resourceId, Object txId, boolean shared, boolean wait, long timeoutMSecs, boolean reentrant)` Explicitly locks a resource.
`void` | `markTransactionForRollback(Object txId)` Marks the transaction specified by the given transaction identifier for rollback.
`int` | `prepareTransaction(Object txId)` Prepares the transaction specified by the given transaction identifier for commit.
`InputStream` | `readResource(Object resourceId)` Opens a streamable resource for a single reading request not inside the scope of a transaction.
`InputStream` | `readResource(Object txId, Object resourceId)` Opens a streamable resource for reading.
`boolean` | `recover()` Tries to bring this resource manager back to a consistent state.
`boolean` | `resourceExists(Object resourceId)` Checks if a resource exists wihtout being in a transaction.
`boolean` | `resourceExists(Object txId, Object resourceId)` Checks if a resource exists.
`void` | `rollbackTransaction(Object txId)` Rolls back the transaction specified by the given transaction identifier.
`void` | `setIsolationLevel(Object txId, int level)` Sets the isolation level for the specified transaction.
`void` | `setTransactionTimeout(Object txId, long mSecs)` Sets the transaction timeout of the specified transaction.
`void` | `start()` Starts this resource manager.
`void` | `startTransaction(Object txId)` Creates and starts a transaction using the specified transaction identifier.
`boolean` | `stop(int mode)` Tries to stop this resource manager within a default timeout.
`boolean` | `stop(int mode, long timeoutMSecs)` Tries to stop this resource manager within the given timeout.
`OutputStream` | `writeResource(Object txId, Object resourceId)` Opens a resource for writing.

Field Detail

### ISOLATION_LEVEL_READ_UNCOMMITTED

    public static final int ISOLATION_LEVEL_READ_UNCOMMITTED

  Isolation level read uncommitted: data written by other transactions can be read even before they commit

  See Also:
    Constant Field Values

### ISOLATION_LEVEL_READ_COMMITTED

    public static final int ISOLATION_LEVEL_READ_COMMITTED

  Isolation level read committed: data written by other transactions can be read after they commit

  See Also:
    Constant Field Values

### ISOLATION_LEVEL_REPEATABLE_READ

    public static final int ISOLATION_LEVEL_REPEATABLE_READ

  Isolation level repeatable read: data written by other transactions can be read after they commit if this transaction has not read this data before

  See Also:
    Constant Field Values

### ISOLATION_LEVEL_SERIALIZABLE

    public static final int ISOLATION_LEVEL_SERIALIZABLE

  Isolation level serializable: result of other transactions will not influence the result of this transaction in any way

  See Also:
    Constant Field Values

### SHUTDOWN_MODE_NORMAL

    public static final int SHUTDOWN_MODE_NORMAL

  Shutdown mode: Wait for all transactions to complete

  See Also:
    Constant Field Values

### SHUTDOWN_MODE_ROLLBACK

    public static final int SHUTDOWN_MODE_ROLLBACK

  Shutdown mode: Try to roll back all active transactions

  See Also:
    Constant Field Values

### SHUTDOWN_MODE_KILL

    public static final int SHUTDOWN_MODE_KILL

  Shutdown mode: Try to stop active transaction NOW, do no rollbacks

  See Also:
    Constant Field Values

### PREPARE_SUCCESS

    public static final int PREPARE_SUCCESS

  Prepare result: resource manager guarantees a successful commit

  See Also:
    Constant Field Values

### PREPARE_SUCCESS_READONLY

    public static final int PREPARE_SUCCESS_READONLY

  Prepare result: resource manager guarantees a successful commit as there is nothing to commit

  See Also:
    Constant Field Values

### PREPARE_FAILURE

    public static final int PREPARE_FAILURE

  Prepare result: transaction can not commit

  See Also:
    Constant Field Values

Method Detail

### start

    public void start()
               throws ResourceManagerSystemException

  Starts this resource manager. A resource manager must be started before transactions can be started or any operations on transactions can be executed.

  Throws:
    `ResourceManagerSystemException` - if start failed due to internal problems

### stop

    public boolean stop(int mode,
                        long timeoutMSecs)
                 throws ResourceManagerSystemException

  Tries to stop this resource manager within the given timeout.

  Parameters:
    `mode` - one of `SHUTDOWN_MODE_NORMAL`, `SHUTDOWN_MODE_ROLLBACK` or `SHUTDOWN_MODE_KILL`
    `timeoutMSecs` - timeout for shutdown in milliseconds
  Returns:
    `true` if resource manager stopped within given timeout
  Throws:
    `ResourceManagerSystemException` - if something fatal hapened during shutdown

### stop

    public boolean stop(int mode)
                 throws ResourceManagerSystemException

  Tries to stop this resource manager within a default timeout.

  Parameters:
    `mode` - one of predefined shutdown modes `SHUTDOWN_MODE_NORMAL`, `SHUTDOWN_MODE_ROLLBACK` or `SHUTDOWN_MODE_KILL` or any other int representing a shutdown mode
  Returns:
    `true` if resource manager stopped within given timeout
  Throws:
    `ResourceManagerSystemException` - if anything fatal hapened during shutdown

### recover

    public boolean recover()
                    throws ResourceManagerSystemException

  Tries to bring this resource manager back to a consistent state. Might be called after system failure. An administrator might be forced to fix system errors outside this resource manager to actually make recovery possible. E.g. there may be a need for more disk space or a network connection must be reestablished.

  Returns:
    `true` upon successful recovery of the resource manager
  Throws:
    `ResourceManagerSystemException` - if anything fatal hapened during shutdown

### getDefaultIsolationLevel

    public int getDefaultIsolationLevel()
                                 throws ResourceManagerException

  Gets the default isolation level as an integer. The higher the value the higher the isolation.

  Returns:
    one of the predefined isolation levels `ISOLATION_LEVEL_READ_UNCOMMITTED`, `ISOLATION_LEVEL_READ_COMMITTED`, `ISOLATION_LEVEL_REPEATABLE_READ` or `ISOLATION_LEVEL_SERIALIZABLE` or any other int representing an isolation level
  Throws:
    `ResourceManagerException` - if an error occured

### getSupportedIsolationLevels

    public int[] getSupportedIsolationLevels()
                                      throws ResourceManagerException

  Gets an array of all isolation levels supported by this resource manager. This array must not be `null` or empty as every resource manager has some sort of isolation level.

  Returns:
    array of the predefined isolation levels `ISOLATION_LEVEL_READ_UNCOMMITTED`, `ISOLATION_LEVEL_READ_COMMITTED`, `ISOLATION_LEVEL_REPEATABLE_READ` or `ISOLATION_LEVEL_SERIALIZABLE` or any other int representing an isolation level
  Throws:
    `ResourceManagerException` - if an error occured
  See Also:
    `getDefaultIsolationLevel()`

### isIsolationLevelSupported

    public boolean isIsolationLevelSupported(int level)
                                      throws ResourceManagerException

  Tests if the specified isolation level is supported by this resource manager.

  Parameters:
    `level` - isolation level whose support is to be tested
  Returns:
    `true` if the isolation level is supported
  Throws:
    `ResourceManagerException` - if an error occured
  See Also:
    `getDefaultIsolationLevel()`

### getIsolationLevel

    public int getIsolationLevel(Object txId)
                          throws ResourceManagerException

  Gets the isolation level for the specified transaction.

  Parameters:
    `txId` - identifier for the concerned transaction
  Returns:
    one of the predefined isolation levels `ISOLATION_LEVEL_READ_UNCOMMITTED`, `ISOLATION_LEVEL_READ_COMMITTED`, `ISOLATION_LEVEL_REPEATABLE_READ` or `ISOLATION_LEVEL_SERIALIZABLE` or any other int representing an isolation level
  Throws:
    `ResourceManagerException` - if an error occured
  See Also:
    `getDefaultIsolationLevel()`

### setIsolationLevel

    public void setIsolationLevel(Object txId,
                                  int level)
                           throws ResourceManagerException

  Sets the isolation level for the specified transaction.
  Caution: Implementations are likely to forbid changing the isolation level after any operations have been executed inside the specified transaction.

  Parameters:
    `txId` - identifier for the concerned transaction
    `level` - one of the predefined isolation levels `ISOLATION_LEVEL_READ_UNCOMMITTED`, `ISOLATION_LEVEL_READ_COMMITTED`, `ISOLATION_LEVEL_REPEATABLE_READ` or `ISOLATION_LEVEL_SERIALIZABLE` or any other int representing an isolation level
  Throws:
    `ResourceManagerException` - if an error occured
  See Also:
    `getDefaultIsolationLevel()`

### getDefaultTransactionTimeout

    public long getDefaultTransactionTimeout()
                                      throws ResourceManagerException

  Gets the default transaction timeout. After this time expires and the concerned transaction has not finished - either rolled back or committed - the resource manager is allowed and also encouraged - but not required - to abort the transaction and to roll it back.

  Returns:
    default transaction timeout
  Throws:
    `ResourceManagerException` - if an error occured

### getTransactionTimeout

    public long getTransactionTimeout(Object txId)
                               throws ResourceManagerException

  Gets the transaction timeout of the specified transaction.

  Parameters:
    `txId` - identifier for the concerned transaction
  Returns:
    transaction timeout of the specified transaction in milliseconds
  Throws:
    `ResourceManagerException` - if an error occured
  See Also:
    `getDefaultTransactionTimeout()`

### setTransactionTimeout

    public void setTransactionTimeout(Object txId,
                                      long mSecs)
                               throws ResourceManagerException

  Sets the transaction timeout of the specified transaction.

  Parameters:
    `txId` - identifier for the concerned transaction
    `mSecs` - transaction timeout of the specified transaction in milliseconds
  Throws:
    `ResourceManagerException` - if an error occured
  See Also:
    `getDefaultTransactionTimeout()`

### startTransaction

    public void startTransaction(Object txId)
                          throws ResourceManagerException

  Creates and starts a transaction using the specified transaction identifier. The identifier needs to be unique to this resource manager. As there is no transaction object returned all access to the transaction needs to be addressed to this resource manager.

  Parameters:
    `txId` - identifier for the transaction to be started
  Throws:
    `ResourceManagerException` - if an error occured

### prepareTransaction

    public int prepareTransaction(Object txId)
                           throws ResourceManagerException

  Prepares the transaction specified by the given transaction identifier for commit. The preparation may either succeed (`PREPARE_SUCCESS`), succeed as there is nothing to commit (`PREPARE_SUCCESS_READONLY`) or fail (`PREPARE_FAILURE`). If the preparation fails, commit will fail as well and the transaction should be marked for rollback. However, if it succeeds the resource manager must guarantee that a following commit will succeed as well.
  An alternative way to singal a failed status is to throw an exception.

  Parameters:
    `txId` - identifier for the transaction to be prepared
  Returns:
    result of the preparation effort, either `PREPARE_SUCCESS`, `PREPARE_SUCCESS_READONLY` or `PREPARE_FAILURE`
  Throws:
    `ResourceManagerException` - alternative way to signal prepare failed

### markTransactionForRollback

    public void markTransactionForRollback(Object txId)
                                    throws ResourceManagerException

  Marks the transaction specified by the given transaction identifier for rollback. This means, even though the transaction is not actually finished, no other operation than `rollback` is permitted.

  Parameters:
    `txId` - identifier for the transaction to be marked for rollback
  Throws:
    `ResourceManagerException` - if an error occured

### rollbackTransaction

    public void rollbackTransaction(Object txId)
                             throws ResourceManagerException

  Rolls back the transaction specified by the given transaction identifier. After roll back the resource manager is allowed to forget about the associated transaction.

  Parameters:
    `txId` - identifier for the transaction to be rolled back
  Throws:
    `ResourceManagerException` - if an error occured

### commitTransaction

    public void commitTransaction(Object txId)
                           throws ResourceManagerException

  Commis the transaction specified by the given transaction identifier. After commit the resource manager is allowed to forget about the associated transaction.

  Parameters:
    `txId` - identifier for the transaction to be committed
  Throws:
    `ResourceManagerException` - if an error occured

### getTransactionState

    public int getTransactionState(Object txId)
                            throws ResourceManagerException

  Gets the state of the transaction specified by the given transaction identifier. The state will be expressed by an `int` code as defined in the `Status` interface.

  Parameters:
    `txId` - identifier for the transaction for which the state is returned
  Returns:
    state of the transaction as defined in `Status`
  Throws:
    `ResourceManagerException` - if an error occured

### lockResource

    public boolean lockResource(Object resourceId,
                                Object txId,
                                boolean shared,
                                boolean wait,
                                long timeoutMSecs,
                                boolean reentrant)
                         throws ResourceManagerException

  Explicitly locks a resource. Although locking must be done implicitly by methods creating, reading or modifying resources, there may be cases when you want to do this explicitly.
  Note: By intention the order of parameters (`txId` does not come first) is different than in other methods of this interface. This is done to make clear locking affects all transactions, not only the locking one. This should be clear anyhow, but seems to be worth noting.

  Parameters:
    `resourceId` - identifier for the resource to be locked
    `txId` - identifier for the transaction that tries to acquire a lock
    `shared` - `true` if this lock may be shared by other shared locks
    `wait` - `true` if the method shall block when lock can not be acquired now
    `timeoutMSecs` - timeout in milliseconds
    `reentrant` - `true` if the lock should be acquired even when the requesting transaction and no other holds an incompatible lock
  Returns:
    `true` when the lock has been acquired
  Throws:
    `ResourceManagerException` - if an error occured

### lockResource

    public boolean lockResource(Object resourceId,
                                Object txId,
                                boolean shared)
                         throws ResourceManagerException

  Explicitly locks a resource in reentrant style. This method blocks until the lock actually can be acquired or the transaction times out.

  Parameters:
    `resourceId` - identifier for the resource to be locked
    `txId` - identifier for the transaction that tries to acquire a lock
    `shared` - `true` if this lock may be shared by other shared locks
  Throws:
    `ResourceManagerException` - if an error occured
  See Also:
    `lockResource(Object, Object, boolean, boolean, long, boolean)`

### lockResource

    public boolean lockResource(Object resourceId,
                                Object txId)
                         throws ResourceManagerException

  Explicitly locks a resource exclusively, i.e. for writing, in reentrant style. This method blocks until the lock actually can be acquired or the transaction times out.

  Parameters:
    `resourceId` - identifier for the resource to be locked
    `txId` - identifier for the transaction that tries to acquire a lock
  Throws:
    `ResourceManagerException` - if an error occured
  See Also:
    `lockResource(Object, Object, boolean)`, `lockResource(Object, Object, boolean, boolean, long, boolean)`

### resourceExists

    public boolean resourceExists(Object txId,
                                  Object resourceId)
                           throws ResourceManagerException

  Checks if a resource exists.

  Parameters:
    `txId` - identifier for the transaction in which the resource is to be checked for
    `resourceId` - identifier for the resource to check for
  Returns:
    `true` if the resource exists
  Throws:
    `ResourceManagerException` - if an error occured

### resourceExists

    public boolean resourceExists(Object resourceId)
                           throws ResourceManagerException

  Checks if a resource exists wihtout being in a transaction. This means only take into account resources already globally commited.

  Parameters:
    `resourceId` - identifier for the resource to check for
  Returns:
    `true` if the resource exists
  Throws:
    `ResourceManagerException` - if an error occured

### deleteResource

    public void deleteResource(Object txId,
                               Object resourceId)
                        throws ResourceManagerException

  Deletes a resource.

  Parameters:
    `txId` - identifier for the transaction in which the resource is to be deleted
    `resourceId` - identifier for the resource to be deleted
  Throws:
    `ResourceManagerException` - if the resource does not exist or any other error occured

### deleteResource

    public void deleteResource(Object txId,
                               Object resourceId,
                               boolean assureOnly)
                        throws ResourceManagerException

  Deletes a resource.

  Parameters:
    `txId` - identifier for the transaction in which the resource is to be deleted
    `resourceId` - identifier for the resource to be deleted
    `assureOnly` - if set to `true` this method will not throw an exception when the resource does not exist
  Throws:
    `ResourceManagerException` - if the resource does not exist and `assureOnly` was not set to `true` or any other error occured

### createResource

    public void createResource(Object txId,
                               Object resourceId)
                        throws ResourceManagerException

  Creates a resource.

  Parameters:
    `txId` - identifier for the transaction in which the resource is to be created
    `resourceId` - identifier for the resource to be created
  Throws:
    `ResourceManagerException` - if the resource already exist or any other error occured

### createResource

    public void createResource(Object txId,
                               Object resourceId,
                               boolean assureOnly)
                        throws ResourceManagerException

  Creates a resource.

  Parameters:
    `txId` - identifier for the transaction in which the resource is to be created
    `resourceId` - identifier for the resource to be created
    `assureOnly` - if set to `true` this method will not throw an exception when the resource already exists
  Throws:
    `ResourceManagerException` - if the resource already exists and `assureOnly` was not set to `true` or any other error occured

### readResource

    public InputStream readResource(Object txId,
                                    Object resourceId)
                             throws ResourceManagerException

  Opens a streamable resource for reading.
  Important: By contract, the application is responsible for closing the stream after its work is finished.

  Parameters:
    `txId` - identifier for the transaction in which the streamable resource is to be openend
    `resourceId` - identifier for the streamable resource to be opened
  Returns:
    stream to read from
  Throws:
    `ResourceManagerException` - if the resource does not exist or any other error occured

### readResource

    public InputStream readResource(Object resourceId)
                             throws ResourceManagerException

  Opens a streamable resource for a single reading request not inside the scope of a transaction.
  Important: By contract, the application is responsible for closing the stream after its work is finished.

  Parameters:
    `resourceId` - identifier for the streamable resource to be opened
  Returns:
    stream to read from
  Throws:
    `ResourceManagerException` - if the resource does not exist or any other error occured

### writeResource

    public OutputStream writeResource(Object txId,
                                      Object resourceId)
                               throws ResourceManagerException

  Opens a resource for writing.
  Important: By contract, the application is responsible for closing the stream after its work is finished.

  Parameters:
    `txId` - identifier for the transaction in which the streamable resource is to be openend
    `resourceId` - identifier for the streamable resource to be opened
  Returns:
    stream to write to
  Throws:
    `ResourceManagerException` - if the resource does not exist or any other error occured

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 The Apache Software Foundation. All Rights Reserved.