ResourceManager (Commons Transaction 1.3-SNAPSHOT API)

All Superinterfaces:

Status

All Known Implementing Classes:

FileResourceManager, VirtualAdminCommandsFileResourceManager
```
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:

$Id: ResourceManager.java 513490 2007-03-01 20:46:28Z ozeigermann $

Field Summary

Fields
Modifier and Type	Field and Description
`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

Methods
Modifier and Type	Method and Description
`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 in milliseconds.
`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 in milliseconds.
`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.
`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 in milliseconds.
`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
```
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
```
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
```
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
```
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
```
static final int SHUTDOWN_MODE_NORMAL
```
    Shutdown mode: Wait for all transactions to complete
    
    See Also:
    Constant Field Values
  - SHUTDOWN_MODE_ROLLBACK
```
static final int SHUTDOWN_MODE_ROLLBACK
```
    Shutdown mode: Try to roll back all active transactions
    
    See Also:
    Constant Field Values
  - SHUTDOWN_MODE_KILL
```
static final int SHUTDOWN_MODE_KILL
```
    Shutdown mode: Try to stop active transaction NOW, do no rollbacks
    
    See Also:
    Constant Field Values
  - PREPARE_SUCCESS
```
static final int PREPARE_SUCCESS
```
    Prepare result: resource manager guarantees a successful commit
    
    See Also:
    Constant Field Values
  - PREPARE_SUCCESS_READONLY
```
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
```
static final int PREPARE_FAILURE
```
    Prepare result: transaction can not commit
    
    See Also:
    Constant Field Values
- Method Detail
  - start
```
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
```
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
```
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
```
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 recovery
  - getDefaultIsolationLevel
```
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
```
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
```
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
```
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
```
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
```
long getDefaultTransactionTimeout()
                                  throws ResourceManagerException
```
    Gets the default transaction timeout in milliseconds. 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 in milliseconds
    
    Throws:
    
    ResourceManagerException - if an error occured
  - getTransactionTimeout
```
long getTransactionTimeout(Object txId)
                           throws ResourceManagerException
```
    Gets the transaction timeout of the specified transaction in milliseconds.
    
    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
```
void setTransactionTimeout(Object txId,
                         long mSecs)
                           throws ResourceManagerException
```
    Sets the transaction timeout of the specified transaction in milliseconds.
    
    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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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

Interface ResourceManager

Field Summary

Fields inherited from interface javax.transaction.Status

Method Summary

Field Detail

ISOLATION_LEVEL_READ_UNCOMMITTED

ISOLATION_LEVEL_READ_COMMITTED

ISOLATION_LEVEL_REPEATABLE_READ

ISOLATION_LEVEL_SERIALIZABLE

SHUTDOWN_MODE_NORMAL

SHUTDOWN_MODE_ROLLBACK

SHUTDOWN_MODE_KILL

PREPARE_SUCCESS

PREPARE_SUCCESS_READONLY

PREPARE_FAILURE

Method Detail

start

stop

stop

recover

getDefaultIsolationLevel

getSupportedIsolationLevels

isIsolationLevelSupported

getIsolationLevel

setIsolationLevel

getDefaultTransactionTimeout

getTransactionTimeout

setTransactionTimeout

startTransaction

prepareTransaction

markTransactionForRollback

rollbackTransaction

commitTransaction

getTransactionState

lockResource

lockResource

lockResource

resourceExists

resourceExists

deleteResource

deleteResource

createResource

createResource

readResource

readResource

writeResource