org.apache.commons.transaction.file
Interface ResourceManager

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

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

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 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


Copyright © 2004-2011 Apache Software Foundation. All Rights Reserved.