org.apache.commons.transaction.file
Class FileResourceManager

java.lang.Object
  extended by org.apache.commons.transaction.file.FileResourceManager
All Implemented Interfaces:
Status, ResourceManager, ResourceManagerErrorCodes

public class FileResourceManager
extends Object
implements ResourceManager, ResourceManagerErrorCodes

A resource manager for streamable objects stored in a file system. It is intended for developper and "out of the box" use. It is not intended to be a real alternative for a full blown DMBS (of course it can not be compared to an RDBMS at all). Major features:

Compared to a "real" DBMS major limitations are (in order of assumed severity):
Important: If possible you should have the work and store directory located in the same file system. If not, you might get additional problems, as there are: General limitations include:
Caution:
The txId passed to many methods as an identifier for the transaction concerned will function as a key in a HashMap. Thus assure that equals and hashCode are both properly implemented and match each other. Caution: You will have to guarantee that no other process will access neither the store or the working dir concurrently to this FileResourceManager. Special Caution: Be very careful not to have two instances of FileResourceManager working in the same store and/or working dir.

Version:
$Revision$

Nested Class Summary
protected  class FileResourceManager.TransactionContext
          Inner class to hold the complete context, i.e.
 
Field Summary
protected  boolean cleanUp
           
protected static String CONTEXT_FILE
           
protected  boolean debug
           
protected static int DEFAULT_COMMIT_TIMEOUT_FACTOR
           
protected static int DEFAULT_ISOLATION_LEVEL
           
protected static String DEFAULT_PARAMETER_ENCODING
           
protected static int DEFAULT_TIMEOUT_MSECS
           
protected  long defaultTimeout
           
protected  boolean dirty
           
protected  List globalOpenResources
           
protected  Map globalTransactions
           
protected  ResourceIdToPathMapper idMapper
           
protected static int LOCK_ACCESS
           
protected static int LOCK_COMMIT
           
protected static int LOCK_EXCLUSIVE
           
protected static int LOCK_SHARED
           
protected  LockManager2 lockManager
           
protected  LoggerFacade logger
           
protected static int NATIVE_ISOLATION_LEVEL
           
protected static int NO_LOCK
           
protected static int OPERATION_MODE_RECOVERING
           
protected static int OPERATION_MODE_STARTED
           
protected static int OPERATION_MODE_STARTING
           
protected static int OPERATION_MODE_STOPPED
           
protected static int OPERATION_MODE_STOPPING
           
protected  int operationMode
           
protected  String storeDir
           
protected static String WORK_CHANGE_DIR
           
protected static String WORK_DELETE_DIR
           
protected  String workDir
           
 
Fields inherited from interface org.apache.commons.transaction.file.ResourceManager
ISOLATION_LEVEL_READ_COMMITTED, ISOLATION_LEVEL_READ_UNCOMMITTED, ISOLATION_LEVEL_REPEATABLE_READ, ISOLATION_LEVEL_SERIALIZABLE, PREPARE_FAILURE, PREPARE_SUCCESS, PREPARE_SUCCESS_READONLY, SHUTDOWN_MODE_KILL, SHUTDOWN_MODE_NORMAL, SHUTDOWN_MODE_ROLLBACK
 
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
 
Fields inherited from interface org.apache.commons.transaction.file.ResourceManagerErrorCodes
ERR_DEAD_LOCK, ERR_DUP_TX, ERR_ISOLATION_LEVEL_UNSUPPORTED, ERR_LOCK, ERR_MARKED_FOR_ROLLBACK, ERR_NO_LOCK, ERR_NO_SUCH_RESOURCE, ERR_NO_TX, ERR_RESOURCE_EXISTS, ERR_RESOURCEID_INVALID, ERR_SYSTEM, ERR_SYSTEM_INCONSISTENT, ERR_THREAD_INVALID, ERR_TX_INACTIVE, ERR_TX_INCONSISTENT, ERR_TXID_INVALID, ERR_UNKNOWN
 
Constructor Summary
FileResourceManager(String storeDir, String workDir, boolean urlEncodePath, LoggerFacade logger)
          Creates a new resouce manager operation on the specified directories.
FileResourceManager(String storeDir, String workDir, boolean urlEncodePath, LoggerFacade logger, boolean debug)
          Creates a new resouce manager operation on the specified directories.
FileResourceManager(String storeDir, String workDir, ResourceIdToPathMapper idMapper, LoggerFacade logger, boolean debug)
          Creates a new resouce manager operation on the specified directories.
 
Method Summary
protected static void applyDeletes(File removeDir, File targetDir, File rootDir)
           
protected  String assureLeadingSlash(Object pathObject)
           
protected  void assureNotMarkedForRollback(FileResourceManager.TransactionContext context)
           
protected  void assureRMReady()
           
protected  void assureStarted()
           
protected  void closeOpenResource(Object openResource)
           
 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.
protected  void fileInitialSaneCheck(Object txId, Object path)
           
 String generatedUniqueTxId()
          Generates a transaction identifier unique to this resource manager.
protected  String getChangePath(Object txId, Object path)
           
protected  FileResourceManager.TransactionContext getContext(Object txId)
           
 int getDefaultIsolationLevel()
          Gets the default isolation level as an integer.
 long getDefaultTransactionTimeout()
          Gets the default transaction timeout in milliseconds.
protected  String getDeletePath(Object txId, Object path)
           
 int getIsolationLevel(Object txId)
          Gets the isolation level for the specified transaction.
 LoggerFacade getLogger()
          Gets the logger used by this resource manager.
protected  String getMainPath(Object path)
           
protected  String getPathForRead(Object txId, Object resourceId)
           
protected  String getPathForWrite(Object txId, Object resourceId)
           
protected  int getSharedLockLevel(FileResourceManager.TransactionContext context)
           
 String getStoreDir()
          Gets the store directory.
 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.
 String getWorkDir()
          Gets the working directory.
 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.
protected  void recoverContexts()
           
protected  void registerOpenResource(Object openResource)
           
protected  void releaseGlobalOpenResources()
           
 void reset()
          Resets the store by deleting work and store directory.
 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.
protected  boolean rollBackOrForward()
           
 void rollbackTransaction(Object txId)
          Rolls back the transaction specified by the given transaction identifier.
 void setDefaultTransactionTimeout(long timeout)
          Sets the default transaction timeout.
protected  void setDirty(Object txId, Throwable t)
           
 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.
protected  boolean shutdown(int mode, long timeoutMSecs)
           
 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 timeOut)
          Tries to stop this resource manager within the given timeout.
 void sync()
          Synchronizes persistent data with caches.
protected  FileResourceManager.TransactionContext txInitialSaneCheck(Object txId)
           
protected  FileResourceManager.TransactionContext txInitialSaneCheckForWriting(Object txId)
           
protected  boolean undoScheduledChangeOrCreate(Object txId, Object resourceId)
           
protected  boolean undoScheduledDelete(Object txId, Object resourceId)
           
protected  boolean waitForAllTxToStop(long timeoutMSecs)
           
 OutputStream writeResource(Object txId, Object resourceId)
          Opens a resource for writing.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NATIVE_ISOLATION_LEVEL

protected static final int NATIVE_ISOLATION_LEVEL
See Also:
Constant Field Values

DEFAULT_ISOLATION_LEVEL

protected static final int DEFAULT_ISOLATION_LEVEL
See Also:
Constant Field Values

NO_LOCK

protected static final int NO_LOCK
See Also:
Constant Field Values

LOCK_ACCESS

protected static final int LOCK_ACCESS
See Also:
Constant Field Values

LOCK_SHARED

protected static final int LOCK_SHARED
See Also:
Constant Field Values

LOCK_EXCLUSIVE

protected static final int LOCK_EXCLUSIVE
See Also:
Constant Field Values

LOCK_COMMIT

protected static final int LOCK_COMMIT
See Also:
Constant Field Values

OPERATION_MODE_STOPPED

protected static final int OPERATION_MODE_STOPPED
See Also:
Constant Field Values

OPERATION_MODE_STOPPING

protected static final int OPERATION_MODE_STOPPING
See Also:
Constant Field Values

OPERATION_MODE_STARTED

protected static final int OPERATION_MODE_STARTED
See Also:
Constant Field Values

OPERATION_MODE_STARTING

protected static final int OPERATION_MODE_STARTING
See Also:
Constant Field Values

OPERATION_MODE_RECOVERING

protected static final int OPERATION_MODE_RECOVERING
See Also:
Constant Field Values

DEFAULT_PARAMETER_ENCODING

protected static final String DEFAULT_PARAMETER_ENCODING
See Also:
Constant Field Values

DEFAULT_TIMEOUT_MSECS

protected static final int DEFAULT_TIMEOUT_MSECS
See Also:
Constant Field Values

DEFAULT_COMMIT_TIMEOUT_FACTOR

protected static final int DEFAULT_COMMIT_TIMEOUT_FACTOR
See Also:
Constant Field Values

WORK_CHANGE_DIR

protected static final String WORK_CHANGE_DIR
See Also:
Constant Field Values

WORK_DELETE_DIR

protected static final String WORK_DELETE_DIR
See Also:
Constant Field Values

CONTEXT_FILE

protected static final String CONTEXT_FILE
See Also:
Constant Field Values

workDir

protected String workDir

storeDir

protected String storeDir

cleanUp

protected boolean cleanUp

dirty

protected boolean dirty

operationMode

protected int operationMode

defaultTimeout

protected long defaultTimeout

debug

protected boolean debug

logger

protected LoggerFacade logger

globalTransactions

protected Map globalTransactions

globalOpenResources

protected List globalOpenResources

lockManager

protected LockManager2 lockManager

idMapper

protected ResourceIdToPathMapper idMapper
Constructor Detail

FileResourceManager

public FileResourceManager(String storeDir,
                           String workDir,
                           boolean urlEncodePath,
                           LoggerFacade logger)
Creates a new resouce manager operation on the specified directories.

Parameters:
storeDir - directory where main data should go after commit
workDir - directory where transactions store temporary data
urlEncodePath - if set to true encodes all paths to allow for any kind of characters
logger - the logger to be used by this store

FileResourceManager

public FileResourceManager(String storeDir,
                           String workDir,
                           boolean urlEncodePath,
                           LoggerFacade logger,
                           boolean debug)
Creates a new resouce manager operation on the specified directories.

Parameters:
storeDir - directory where main data should go after commit
workDir - directory where transactions store temporary data
urlEncodePath - if set to true encodes all paths to allow for any kind of characters
logger - the logger to be used by this store
debug - if set to true logs all locking information to "transaction.log" for debugging inspection

FileResourceManager

public FileResourceManager(String storeDir,
                           String workDir,
                           ResourceIdToPathMapper idMapper,
                           LoggerFacade logger,
                           boolean debug)
Creates a new resouce manager operation on the specified directories.

Parameters:
storeDir - directory where main data should go after commit
workDir - directory where transactions store temporary data
idMapper - mapper for resourceId to path
logger - the logger to be used by this store
debug - if set to true logs all locking information to "transaction.log" for debugging inspection
Method Detail

applyDeletes

protected static void applyDeletes(File removeDir,
                                   File targetDir,
                                   File rootDir)
                            throws IOException
Throws:
IOException

getStoreDir

public String getStoreDir()
Gets the store directory.

Returns:
the store directory
See Also:
FileResourceManager(String, String, boolean, LoggerFacade), FileResourceManager(String, String, boolean, LoggerFacade, boolean)

getWorkDir

public String getWorkDir()
Gets the working directory.

Returns:
the work directory
See Also:
FileResourceManager(String, String, boolean, LoggerFacade), FileResourceManager(String, String, boolean, LoggerFacade, boolean)

getLogger

public LoggerFacade getLogger()
Gets the logger used by this resource manager.

Returns:
used logger

lockResource

public boolean lockResource(Object resourceId,
                            Object txId)
                     throws ResourceManagerException
Description copied from interface: ResourceManager
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.

Specified by:
lockResource in interface ResourceManager
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:
ResourceManager.lockResource(Object, Object, boolean), ResourceManager.lockResource(Object, Object, boolean, boolean, long, boolean)

lockResource

public boolean lockResource(Object resourceId,
                            Object txId,
                            boolean shared)
                     throws ResourceManagerException
Description copied from interface: ResourceManager
Explicitly locks a resource in reentrant style. This method blocks until the lock actually can be acquired or the transaction times out.

Specified by:
lockResource in interface ResourceManager
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:
ResourceManager.lockResource(Object, Object, boolean, boolean, long, boolean)

lockResource

public boolean lockResource(Object resourceId,
                            Object txId,
                            boolean shared,
                            boolean wait,
                            long timeoutMSecs,
                            boolean reentrant)
                     throws ResourceManagerException
Description copied from interface: ResourceManager
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.

Specified by:
lockResource in interface ResourceManager
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

getDefaultIsolationLevel

public int getDefaultIsolationLevel()
Description copied from interface: ResourceManager
Gets the default isolation level as an integer. The higher the value the higher the isolation.

Specified by:
getDefaultIsolationLevel in interface ResourceManager
Returns:
one of the predefined isolation levels ResourceManager.ISOLATION_LEVEL_READ_UNCOMMITTED, ResourceManager.ISOLATION_LEVEL_READ_COMMITTED, ResourceManager.ISOLATION_LEVEL_REPEATABLE_READ or ResourceManager.ISOLATION_LEVEL_SERIALIZABLE or any other int representing an isolation level

getSupportedIsolationLevels

public int[] getSupportedIsolationLevels()
                                  throws ResourceManagerException
Description copied from interface: ResourceManager
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.

Specified by:
getSupportedIsolationLevels in interface ResourceManager
Returns:
array of the predefined isolation levels ResourceManager.ISOLATION_LEVEL_READ_UNCOMMITTED, ResourceManager.ISOLATION_LEVEL_READ_COMMITTED, ResourceManager.ISOLATION_LEVEL_REPEATABLE_READ or ResourceManager.ISOLATION_LEVEL_SERIALIZABLE or any other int representing an isolation level
Throws:
ResourceManagerException - if an error occured
See Also:
ResourceManager.getDefaultIsolationLevel()

isIsolationLevelSupported

public boolean isIsolationLevelSupported(int level)
                                  throws ResourceManagerException
Description copied from interface: ResourceManager
Tests if the specified isolation level is supported by this resource manager.

Specified by:
isIsolationLevelSupported in interface ResourceManager
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:
ResourceManager.getDefaultIsolationLevel()

getDefaultTransactionTimeout

public long getDefaultTransactionTimeout()
Gets the default transaction timeout in milliseconds.

Specified by:
getDefaultTransactionTimeout in interface ResourceManager
Returns:
default transaction timeout

setDefaultTransactionTimeout

public void setDefaultTransactionTimeout(long timeout)
Sets the default transaction timeout.

Parameters:
timeout - timeout in milliseconds

getTransactionTimeout

public long getTransactionTimeout(Object txId)
                           throws ResourceManagerException
Description copied from interface: ResourceManager
Gets the transaction timeout of the specified transaction.

Specified by:
getTransactionTimeout in interface ResourceManager
Parameters:
txId - identifier for the concerned transaction
Returns:
transaction timeout of the specified transaction in milliseconds
Throws:
ResourceManagerException - if an error occured
See Also:
ResourceManager.getDefaultTransactionTimeout()

setTransactionTimeout

public void setTransactionTimeout(Object txId,
                                  long mSecs)
                           throws ResourceManagerException
Description copied from interface: ResourceManager
Sets the transaction timeout of the specified transaction.

Specified by:
setTransactionTimeout in interface ResourceManager
Parameters:
txId - identifier for the concerned transaction
mSecs - transaction timeout of the specified transaction in milliseconds
Throws:
ResourceManagerException - if an error occured
See Also:
ResourceManager.getDefaultTransactionTimeout()

getIsolationLevel

public int getIsolationLevel(Object txId)
                      throws ResourceManagerException
Description copied from interface: ResourceManager
Gets the isolation level for the specified transaction.

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

setIsolationLevel

public void setIsolationLevel(Object txId,
                              int level)
                       throws ResourceManagerException
Description copied from interface: ResourceManager
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.

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

start

public void start()
           throws ResourceManagerSystemException
Description copied from interface: ResourceManager
Starts this resource manager. A resource manager must be started before transactions can be started or any operations on transactions can be executed.

Specified by:
start in interface ResourceManager
Throws:
ResourceManagerSystemException - if start failed due to internal problems

stop

public boolean stop(int mode)
             throws ResourceManagerSystemException
Description copied from interface: ResourceManager
Tries to stop this resource manager within a default timeout.

Specified by:
stop in interface ResourceManager
Parameters:
mode - one of predefined shutdown modes ResourceManager.SHUTDOWN_MODE_NORMAL, ResourceManager.SHUTDOWN_MODE_ROLLBACK or ResourceManager.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

stop

public boolean stop(int mode,
                    long timeOut)
             throws ResourceManagerSystemException
Description copied from interface: ResourceManager
Tries to stop this resource manager within the given timeout.

Specified by:
stop in interface ResourceManager
Parameters:
mode - one of ResourceManager.SHUTDOWN_MODE_NORMAL, ResourceManager.SHUTDOWN_MODE_ROLLBACK or ResourceManager.SHUTDOWN_MODE_KILL
timeOut - timeout for shutdown in milliseconds
Returns:
true if resource manager stopped within given timeout
Throws:
ResourceManagerSystemException - if something fatal hapened during shutdown

recover

public boolean recover()
                throws ResourceManagerSystemException
Description copied from interface: ResourceManager
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.

Specified by:
recover in interface ResourceManager
Returns:
true upon successful recovery of the resource manager
Throws:
ResourceManagerSystemException - if anything fatal hapened during shutdown

getTransactionState

public int getTransactionState(Object txId)
                        throws ResourceManagerException
Description copied from interface: ResourceManager
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.

Specified by:
getTransactionState in interface ResourceManager
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

startTransaction

public void startTransaction(Object txId)
                      throws ResourceManagerException
Description copied from interface: ResourceManager
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.

Specified by:
startTransaction in interface ResourceManager
Parameters:
txId - identifier for the transaction to be started
Throws:
ResourceManagerException - if an error occured

markTransactionForRollback

public void markTransactionForRollback(Object txId)
                                throws ResourceManagerException
Description copied from interface: ResourceManager
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.

Specified by:
markTransactionForRollback in interface ResourceManager
Parameters:
txId - identifier for the transaction to be marked for rollback
Throws:
ResourceManagerException - if an error occured

prepareTransaction

public int prepareTransaction(Object txId)
                       throws ResourceManagerException
Description copied from interface: ResourceManager
Prepares the transaction specified by the given transaction identifier for commit. The preparation may either succeed (ResourceManager.PREPARE_SUCCESS), succeed as there is nothing to commit (ResourceManager.PREPARE_SUCCESS_READONLY) or fail (ResourceManager.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.

Specified by:
prepareTransaction in interface ResourceManager
Parameters:
txId - identifier for the transaction to be prepared
Returns:
result of the preparation effort, either ResourceManager.PREPARE_SUCCESS, ResourceManager.PREPARE_SUCCESS_READONLY or ResourceManager.PREPARE_FAILURE
Throws:
ResourceManagerException - alternative way to signal prepare failed

rollbackTransaction

public void rollbackTransaction(Object txId)
                         throws ResourceManagerException
Description copied from interface: ResourceManager
Rolls back the transaction specified by the given transaction identifier. After roll back the resource manager is allowed to forget about the associated transaction.

Specified by:
rollbackTransaction in interface ResourceManager
Parameters:
txId - identifier for the transaction to be rolled back
Throws:
ResourceManagerException - if an error occured

commitTransaction

public void commitTransaction(Object txId)
                       throws ResourceManagerException
Description copied from interface: ResourceManager
Commis the transaction specified by the given transaction identifier. After commit the resource manager is allowed to forget about the associated transaction.

Specified by:
commitTransaction in interface ResourceManager
Parameters:
txId - identifier for the transaction to be committed
Throws:
ResourceManagerException - if an error occured

resourceExists

public boolean resourceExists(Object resourceId)
                       throws ResourceManagerException
Description copied from interface: ResourceManager
Checks if a resource exists wihtout being in a transaction. This means only take into account resources already globally commited.

Specified by:
resourceExists in interface ResourceManager
Parameters:
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 txId,
                              Object resourceId)
                       throws ResourceManagerException
Description copied from interface: ResourceManager
Checks if a resource exists.

Specified by:
resourceExists in interface ResourceManager
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

deleteResource

public void deleteResource(Object txId,
                           Object resourceId)
                    throws ResourceManagerException
Description copied from interface: ResourceManager
Deletes a resource.

Specified by:
deleteResource in interface ResourceManager
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
Description copied from interface: ResourceManager
Deletes a resource.

Specified by:
deleteResource in interface ResourceManager
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
Description copied from interface: ResourceManager
Creates a resource.

Specified by:
createResource in interface ResourceManager
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
Description copied from interface: ResourceManager
Creates a resource.

Specified by:
createResource in interface ResourceManager
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 resourceId)
                         throws ResourceManagerException
Description copied from interface: ResourceManager
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.

Specified by:
readResource in interface ResourceManager
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

readResource

public InputStream readResource(Object txId,
                                Object resourceId)
                         throws ResourceManagerException
Description copied from interface: ResourceManager
Opens a streamable resource for reading.

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

Specified by:
readResource in interface ResourceManager
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

writeResource

public OutputStream writeResource(Object txId,
                                  Object resourceId)
                           throws ResourceManagerException
Description copied from interface: ResourceManager
Opens a resource for writing.

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

Specified by:
writeResource in interface ResourceManager
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

reset

public void reset()
Resets the store by deleting work and store directory.


sync

public void sync()
          throws ResourceManagerSystemException
Synchronizes persistent data with caches. Is implemented with an empty body, but called by other methods relying on synchronization. Subclasses that utilize caching must implement this method reasonably.

Throws:
ResourceManagerSystemException - if anything fatal hapened during synchonization

generatedUniqueTxId

public String generatedUniqueTxId()
                           throws ResourceManagerSystemException
Generates a transaction identifier unique to this resource manager. To do so it requires this resource manager to be started.

Returns:
generated transaction identifier
Throws:
ResourceManagerSystemException - if this resource manager has not been started, yet

fileInitialSaneCheck

protected void fileInitialSaneCheck(Object txId,
                                    Object path)
                             throws ResourceManagerException
Throws:
ResourceManagerException

assureStarted

protected void assureStarted()
                      throws ResourceManagerSystemException
Throws:
ResourceManagerSystemException

assureRMReady

protected void assureRMReady()
                      throws ResourceManagerSystemException
Throws:
ResourceManagerSystemException

assureNotMarkedForRollback

protected void assureNotMarkedForRollback(FileResourceManager.TransactionContext context)
                                   throws ResourceManagerException
Throws:
ResourceManagerException

txInitialSaneCheckForWriting

protected FileResourceManager.TransactionContext txInitialSaneCheckForWriting(Object txId)
                                                                       throws ResourceManagerException
Throws:
ResourceManagerException

txInitialSaneCheck

protected FileResourceManager.TransactionContext txInitialSaneCheck(Object txId)
                                                             throws ResourceManagerException
Throws:
ResourceManagerException

getContext

protected FileResourceManager.TransactionContext getContext(Object txId)

assureLeadingSlash

protected String assureLeadingSlash(Object pathObject)

getMainPath

protected String getMainPath(Object path)

getChangePath

protected String getChangePath(Object txId,
                               Object path)

getDeletePath

protected String getDeletePath(Object txId,
                               Object path)

undoScheduledDelete

protected boolean undoScheduledDelete(Object txId,
                                      Object resourceId)
                               throws ResourceManagerException
Throws:
ResourceManagerException

undoScheduledChangeOrCreate

protected boolean undoScheduledChangeOrCreate(Object txId,
                                              Object resourceId)
                                       throws ResourceManagerException
Throws:
ResourceManagerException

getPathForWrite

protected String getPathForWrite(Object txId,
                                 Object resourceId)
                          throws ResourceManagerException
Throws:
ResourceManagerException

getPathForRead

protected String getPathForRead(Object txId,
                                Object resourceId)
                         throws ResourceManagerException
Throws:
ResourceManagerException

getSharedLockLevel

protected int getSharedLockLevel(FileResourceManager.TransactionContext context)
                          throws ResourceManagerException
Throws:
ResourceManagerException

registerOpenResource

protected void registerOpenResource(Object openResource)

releaseGlobalOpenResources

protected void releaseGlobalOpenResources()

closeOpenResource

protected void closeOpenResource(Object openResource)

rollBackOrForward

protected boolean rollBackOrForward()

recoverContexts

protected void recoverContexts()

waitForAllTxToStop

protected boolean waitForAllTxToStop(long timeoutMSecs)

shutdown

protected boolean shutdown(int mode,
                           long timeoutMSecs)

setDirty

protected void setDirty(Object txId,
                        Throwable t)


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