org.apache.derby.iapi.store.raw
Interface Transaction

All Known Implementing Classes:
InternalXact, RawTransaction, Xact

public interface Transaction


Field Summary
static int KEEP_LOCKS
           
static int RELEASE_LOCKS
           
static int XA_OK
           
static int XA_RDONLY
           
 
Method Summary
 void abort()
          Abort all changes made by this transaction since the last commit, abort or the point the transaction was started, whichever is the most recent.
 long addAndLoadStreamContainer(long segmentId, java.util.Properties tableProperties, RowSource rowSource)
          Add a new stream container to the segment and load the stream container.
 long addContainer(long segmentId, long containerId, int mode, java.util.Properties tableProperties, int temporaryFlag)
          Add a new container to the segment.
 void addPostCommitWork(Serviceable work)
          Add to the list of post commit work that may be processed after this transaction commits.
 void addPostTerminationWork(Serviceable work)
          Add to the list of post termination work that may be processed after this transaction commits or aborts.
 boolean anyoneBlocked()
          Return true if any transaction is blocked, even if not by this one.
 void close()
          Close this transaction, the transaction must be idle.
 LogInstant commit()
          Commit this transaction.
 LogInstant commitNoSync(int commitflag)
          "Commit" this transaction without sync'ing the log.
 void createXATransactionFromLocalTransaction(int format_id, byte[] global_id, byte[] branch_id)
          Convert a local transaction to a global transaction.
 void destroy()
          If this transaction is not idle, abort it.
 void dropContainer(ContainerKey containerId)
          Drop a container.
 void dropStreamContainer(long segmentId, long containerId)
          Drop a stream container.
 java.lang.String getActiveStateTxIdString()
          get string ID of the actual transaction ID that will be used when transaction is in active state.
 CompatibilitySpace getCompatibilitySpace()
          Get the compatibility space of the transaction.
 ContextManager getContextManager()
          Return the context manager this transaction is associated with.
 DataValueFactory getDataValueFactory()
          Get DataValueFactory.
 LockingPolicy getDefaultLockingPolicy()
          Get the current default locking policy for all operations within this transaction.
 FileResource getFileHandler()
          Get an object to handle non-transactional files.
 GlobalTransactionId getGlobalId()
          Return my transaction identifier.
 boolean isIdle()
          Reveals whether the transaction has ever read or written data.
 boolean isPristine()
          Reveal whether the transaction is in a pristine state, which means it hasn't done any updates since the last commit.
 void logAndDo(Loggable operation)
          Log an operation and then action it in the context of this transaction.
 LockingPolicy newLockingPolicy(int mode, int isolation, boolean stricterOk)
          Obtain a locking policy for use in openContainer().
 ContainerHandle openContainer(ContainerKey containerId, int mode)
          Open a container, with the transaction's default locking policy.
 ContainerHandle openContainer(ContainerKey containerId, LockingPolicy locking, int mode)
          Open a container, with the defined locking policy, otherwise as openContainer(int containerId, boolean forUpdate).
 StreamContainerHandle openStreamContainer(long segmentId, long containerId, boolean hold)
          Open a stream container.
 int releaseSavePoint(java.lang.String name, java.lang.Object kindOfSavepoint)
          Release the save point of the given name.
 int rollbackToSavePoint(java.lang.String name, java.lang.Object kindOfSavepoint)
          Rollback all changes made since the named savepoint was set.
 void setDefaultLockingPolicy(LockingPolicy policy)
          Set the default locking policy for all operations within this transaction.
 void setNoLockWait(boolean noWait)
          Tell this transaction whether it should time out immediately if a lock cannot be granted without waiting.
 int setSavePoint(java.lang.String name, java.lang.Object kindOfSavepoint)
          Set a save point in the current transaction.
 void setup(PersistentSet set)
          Called after the transaction has been attached to an Access Manger TransactionController.
 void xa_commit(boolean onePhase)
          This method is called to commit the current XA global transaction.
 int xa_prepare()
          This method is called to ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
 void xa_rollback()
          rollback the current global transaction.
 

Field Detail

RELEASE_LOCKS

static final int RELEASE_LOCKS
See Also:
Constant Field Values

KEEP_LOCKS

static final int KEEP_LOCKS
See Also:
Constant Field Values

XA_RDONLY

static final int XA_RDONLY
See Also:
Constant Field Values

XA_OK

static final int XA_OK
See Also:
Constant Field Values
Method Detail

getContextManager

ContextManager getContextManager()
Return the context manager this transaction is associated with.


getCompatibilitySpace

CompatibilitySpace getCompatibilitySpace()
Get the compatibility space of the transaction.

Returns an object that can be used with the lock manager to provide the compatibility space of a transaction. 2 transactions with the same compatibility space will not conflict in locks. The usual case is that each transaction has it's own unique compatibility space.

Returns:
The compatibility space of the transaction.

setNoLockWait

void setNoLockWait(boolean noWait)
Tell this transaction whether it should time out immediately if a lock cannot be granted without waiting. This could be used in a nested transaction to prevent long waits if there is a lock conflict between the nested transaction and its parent. If it is used this way, the calling code should catch timeout exceptions from the nested transaction and retry the operation (without disabling waiting) in the parent transaction.

Parameters:
noWait - if true never wait for a lock in this transaction, but time out immediately
See Also:
LockOwner.noWait()

setup

void setup(PersistentSet set)
           throws StandardException
Called after the transaction has been attached to an Access Manger TransactionController. Thus may not be called for all transactions. Purpose is to allow a transaction access to database (service) properties. Will not be called for transactions early in the boot process, ie. before the property conglomerate is set up.

Throws:
StandardException - Standard Derby exception policy

getGlobalId

GlobalTransactionId getGlobalId()
Return my transaction identifier. Transaction identifiers may be re-used for transactions that do not modify the raw store. May return null if this transaction has no globalId.


getDefaultLockingPolicy

LockingPolicy getDefaultLockingPolicy()
Get the current default locking policy for all operations within this transaction. The transaction is initially started with a default locking policy equivalent to
                         newLockingPolicy(
              LockingPolicy.MODE_RECORD, LockingPolicy.ISOLATION_SERIALIZABLE, true);
                
This default can be changed by subsequent calls to setDefaultLockingPolicy(LockingPolicy policy).

Returns:
The current default locking policy in this transaction.

newLockingPolicy

LockingPolicy newLockingPolicy(int mode,
                               int isolation,
                               boolean stricterOk)
Obtain a locking policy for use in openContainer(). The mode and isolation must be constants from LockingPolicy. If higherOK is true then the object returned may implement a stricter form of locking than the one requested.
A null LockingPolicy reference is identical to a LockingPolicy obtained by using MODE_NONE which is guaranteed to exist.

Parameters:
mode - A constant of the form LockingPolicy.MODE_*
isolation - A constant of the form LockingPolicy.ISOLATION_*
stricterOk - True if a stricter level of locking is acceptable, false if an exact match is required.
Returns:
A object that can be used in an openContainer call, null if a matching policy cannot be found.

setDefaultLockingPolicy

void setDefaultLockingPolicy(LockingPolicy policy)
Set the default locking policy for all operations within this transaction. The transaction is intially started with a default locking policy equivalent to
                         newLockingPolicy(
              LockingPolicy.MODE_RECORD, LockingPolicy.ISOLATION_SERIALIZABLE, true);
                

Parameters:
policy - The lock policy to use, if null then then a no locking policy will be installed as the default.

commit

LogInstant commit()
                  throws StandardException
Commit this transaction. All savepoints within this transaction are released.

Returns:
the commit instant of this transaction, or null if it didn't make any changes
Throws:
StandardException - A transaction level exception is thrown if the transaction was aborted due to some error. Any exceptions that occur of lower severity than Transaction severity are caught, the transaction is then aborted and then an exception of Transaction severity is thrown nesting the original exception.
StandardException - Any exception more severe than a Transaction exception is not caught and the transaction is not aborted. The transaction will be aborted by the standard context mechanism.

commitNoSync

LogInstant commitNoSync(int commitflag)
                        throws StandardException
"Commit" this transaction without sync'ing the log. Everything else is identical to commit(), use this at your own risk.
bits in the commitflag can turn on to fine tuned the "commit": KEEP_LOCKS - no locks will be released by the commit and no post commit processing will be initiated. If, for some reasons, the locks cannot be kept even if this flag is set, then the commit will sync the log, i.e., it will revert to the normal commit.

Throws:
StandardException - A transaction level exception is thrown if the transaction was aborted due to some error. Any exceptions that occur of lower severity than Transaction severity are caught, the transaction is then aborted and then an exception of Transaction severity is thrown nesting the original exception.
StandardException - Any exception more severe than a Transaction exception is not caught and the transaction is not aborted. The transaction will be aborted by the standard context mechanism.

abort

void abort()
           throws StandardException
Abort all changes made by this transaction since the last commit, abort or the point the transaction was started, whichever is the most recent. All savepoints within this transaction are released.

Throws:
StandardException - Only exceptions with severities greater than ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.

close

void close()
           throws StandardException
Close this transaction, the transaction must be idle. This close will pop the transaction context off the stack that was pushed when the transaction was started.

Throws:
StandardException - Standard Derby error policy
StandardException - A transaction level exception is thrown if the transaction is not idle.
See Also:
RawStoreFactory.startTransaction(org.apache.derby.iapi.services.context.ContextManager, java.lang.String)

destroy

void destroy()
             throws StandardException
If this transaction is not idle, abort it. After this call close().

Throws:
StandardException - Standard Derby error policy
StandardException - A transaction level exception is thrown if the transaction is not idle.
See Also:
RawStoreFactory.startTransaction(org.apache.derby.iapi.services.context.ContextManager, java.lang.String)

setSavePoint

int setSavePoint(java.lang.String name,
                 java.lang.Object kindOfSavepoint)
                 throws StandardException
Set a save point in the current transaction. A save point defines a point in time in the transaction that changes can be rolled back to. Savepoints can be nested and they behave like a stack. Setting save points "one" and "two" and the rolling back "one" will rollback all the changes made since "one" (including those made since "two") and release savepoint "two".

Parameters:
name - The user provided name of the savepoint
kindOfSavepoint - A NULL value means it is an internal savepoint (ie not a user defined savepoint) Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint A String value for kindOfSavepoint would mean it is SQL savepoint A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
Returns:
returns total number of savepoints in the stack.
Throws:
StandardException - Standard Derby exception policy
StandardException - A statement level exception is thrown if a savepoint already exists in the current transaction with the same name.

releaseSavePoint

int releaseSavePoint(java.lang.String name,
                     java.lang.Object kindOfSavepoint)
                     throws StandardException
Release the save point of the given name. Relasing a savepoint removes all knowledge from this transaction of the named savepoint and any savepoints set since the named savepoint was set.

Parameters:
name - The user provided name of the savepoint, set by the user in the setSavePoint() call.
kindOfSavepoint - A NULL value means it is an internal savepoint (ie not a user defined savepoint) Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint A String value for kindOfSavepoint would mean it is SQL savepoint A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
Returns:
returns total number of savepoints in the stack.
Throws:
StandardException - Standard Derby exception policy
StandardException - A statement level exception is thrown if a savepoint already exists in the current transaction with the same name.

rollbackToSavePoint

int rollbackToSavePoint(java.lang.String name,
                        java.lang.Object kindOfSavepoint)
                        throws StandardException
Rollback all changes made since the named savepoint was set. The named savepoint is not released, it remains valid within this transaction, and thus can be named it future rollbackToSavePoint() calls. Any savepoints set since this named savepoint are released (and their changes rolled back).

Parameters:
name - The user provided name of the savepoint, set by the user in the setSavePoint() call.
kindOfSavepoint - A NULL value means it is an internal savepoint (ie not a user defined savepoint) Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint A String value for kindOfSavepoint would mean it is SQL savepoint A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
Returns:
returns total number of savepoints in the stack.
Throws:
StandardException - Standard Derby exception policy
StandardException - A statement level exception is thrown if no savepoint exists with the given name.

openContainer

ContainerHandle openContainer(ContainerKey containerId,
                              int mode)
                              throws StandardException
Open a container, with the transaction's default locking policy.

Note that if NOWAIT has been specified lock will be requested with no wait time, and if lock is not granted a SQLState.LOCK_TIMEOUT exception will be thrown.

The release() method of ContainerHandle will be called when this transaction is aborted or commited, it may be called explicitly to release the ContainerHandle before the end of the transaction.

Returns:
a valid ContainerHandle or null if the container does not exist.
Throws:
StandardException - Standard Derby exception policy

openContainer

ContainerHandle openContainer(ContainerKey containerId,
                              LockingPolicy locking,
                              int mode)
                              throws StandardException
Open a container, with the defined locking policy, otherwise as openContainer(int containerId, boolean forUpdate).

Calls locking.lockContainer(this, returnValue, forUpdate) to lock the container. Note that if NOWAIT has been specified lock will be requested with no wait time, and if lock is not granted a SQLState.LOCK_TIMEOUT exception will be thrown.

Parameters:
locking - The lock policy to use, if null then then a no locking policy will be used.
Returns:
a valid ContainerHandle or null if the container does not exist.
Throws:
StandardException - Standard Derby exception policy

addContainer

long addContainer(long segmentId,
                  long containerId,
                  int mode,
                  java.util.Properties tableProperties,
                  int temporaryFlag)
                  throws StandardException
Add a new container to the segment. The new container initially has one page, page Container.FIRST_PAGE_NUMBER.
If pageSize is equal to ContainerHandle.DEFAULT_PAGESIZE or invalid then a default page size will be picked.
SpareSpace indicates that percent (0% - 100%) of page space that will be attempted to be reserved for updates. E.g. with a value of 20 a page that would normally hold 40 rows will be limited to 32 rows, actual calculation for the threshold where no more inserts are all accepted is up to the implementation. Whatever the value of spaceSpace an empty page will always accept at least one insert. If spare space is equal to ContainerHandle.DEFAULT_PAGESIZE or invalid then a default value will be used.

Synchronisation

The new container is exclusivly locked by this transaction until it commits.

Parameters:
segmentId - segment to create the container in.
containerId - If not equal to 0 then this container id will be used to create the container, else if set to 0 then the raw store will assign a number.
mode - mode description in @see ContainerHandle. This mode is only effective for the duration of the addContainer call and not stored persistently for the lifetime of the container.
tableProperties - Implementation-specific properties of the conglomerate.
Returns:
a container identifer that can be used in openContainer() This id is only valid within this RawStoreFactory. Returns a negative number if a container could not be allocated.
Throws:
StandardException - Standard Derby error policy

dropContainer

void dropContainer(ContainerKey containerId)
                   throws StandardException
Drop a container.

Synchronisation

This call will mark the container as dropped and then obtain an CX lock on the container. Once a container has been marked as dropped it cannot be retrieved by any openContainer() call.

Once the exclusive lock has been obtained the container is removed and all its pages deallocated. The container will be fully removed at the commit time of the transaction.

Throws:
StandardException - Standard Derby error policy

addAndLoadStreamContainer

long addAndLoadStreamContainer(long segmentId,
                               java.util.Properties tableProperties,
                               RowSource rowSource)
                               throws StandardException
Add a new stream container to the segment and load the stream container. This stream container doesn't not have locks, and do not log. It does not have the concept of a page. It is used by the external sort only.

Synchronisation

This call will mark the container as dropped and then obtain an CX lock on the container. Once a container has been marked as dropped it cannot be retrieved by any openContainer() call.

Once the exclusive lock has been obtained the container is removed and all its pages deallocated. The container will be fully removed at the commit time of the transaction.

Throws:
StandardException - Standard Derby error policy

openStreamContainer

StreamContainerHandle openStreamContainer(long segmentId,
                                          long containerId,
                                          boolean hold)
                                          throws StandardException
Open a stream container.

Returns:
a valid StreamContainerHandle or null if the container does not exist.
Throws:
StandardException - Standard Derby exception policy

dropStreamContainer

void dropStreamContainer(long segmentId,
                         long containerId)
                         throws StandardException
Drop a stream container.

Synchronisation

This call will remove the container.

Throws:
StandardException - Standard Derby error policy

logAndDo

void logAndDo(Loggable operation)
              throws StandardException
Log an operation and then action it in the context of this transaction. The Loggable Operation is logged in the transaction log file and then its doMe method is called to perform the required change. If this transaction aborts or a rollback is performed of the current savepoint (if any) then a compensation Operation needs to be generated that will compensate for the change of this Operation.

Parameters:
operation - the operation that is to be applied
Throws:
StandardException - Standard Derby exception policy
See Also:
Loggable

addPostCommitWork

void addPostCommitWork(Serviceable work)
Add to the list of post commit work that may be processed after this transaction commits. If this transaction aborts, then the post commit work list will be thrown away. No post commit work will be taken out on a rollback to save point.

Parameters:
work - the post commit work that is added

addPostTerminationWork

void addPostTerminationWork(Serviceable work)
Add to the list of post termination work that may be processed after this transaction commits or aborts.

Parameters:
work - the post termination work that is added

isIdle

boolean isIdle()
Reveals whether the transaction has ever read or written data.

Returns:
true If the transaction has never read or written data.

isPristine

boolean isPristine()
Reveal whether the transaction is in a pristine state, which means it hasn't done any updates since the last commit.

Returns:
true if so, false otherwise

getFileHandler

FileResource getFileHandler()
Get an object to handle non-transactional files.


anyoneBlocked

boolean anyoneBlocked()
Return true if any transaction is blocked, even if not by this one.


createXATransactionFromLocalTransaction

void createXATransactionFromLocalTransaction(int format_id,
                                             byte[] global_id,
                                             byte[] branch_id)
                                             throws StandardException
Convert a local transaction to a global transaction.

Get a transaction controller with which to manipulate data within the access manager. Tbis controller allows one to manipulate a global XA conforming transaction.

Must only be called a previous local transaction was created and exists in the context. Can only be called if the current transaction is in the idle state.

The (format_id, global_id, branch_id) triplet is meant to come exactly from a javax.transaction.xa.Xid. We don't use Xid so that the system can be delivered on a non-1.2 vm system and not require the javax classes in the path.

Parameters:
format_id - the format id part of the Xid - ie. Xid.getFormatId().
global_id - the global transaction identifier part of XID - ie. Xid.getGlobalTransactionId().
branch_id - The branch qualifier of the Xid - ie. Xid.getBranchQaulifier()
Throws:
StandardException - Standard exception policy.

xa_commit

void xa_commit(boolean onePhase)
               throws StandardException
This method is called to commit the current XA global transaction.

RESOLVE - how do we map to the "right" XAExceptions.

Parameters:
onePhase - If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of current xid.
Throws:
StandardException - Standard exception policy.

xa_prepare

int xa_prepare()
               throws StandardException
This method is called to ask the resource manager to prepare for a transaction commit of the transaction specified in xid.

Returns:
A value indicating the resource manager's vote on the the outcome of the transaction. The possible values are: XA_RDONLY or XA_OK. If the resource manager wants to roll back the transaction, it should do so by throwing an appropriate XAException in the prepare method.
Throws:
StandardException - Standard exception policy.

xa_rollback

void xa_rollback()
                 throws StandardException
rollback the current global transaction.

The given transaction is roll'ed back and it's history is not maintained in the transaction table or long term log.

Throws:
StandardException - Standard exception policy.

getActiveStateTxIdString

java.lang.String getActiveStateTxIdString()
get string ID of the actual transaction ID that will be used when transaction is in active state.


getDataValueFactory

DataValueFactory getDataValueFactory()
                                     throws StandardException
Get DataValueFactory.

Return a DataValueFactory that can be used to allocate objects. Used to make calls to: DataValueFactory.getInstanceUsingFormatIdAndCollationType()

Returns:
a booted data value factory.
Throws:
StandardException - Standard exception policy.

Built on Thu 2010-12-23 20:49:13+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.