Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.iapi.store.raw.Transaction

Modifier and Type	Field and Description
public static final int	KEEP_LOCKS
public static final int	RELEASE_LOCKS
public static final int	XA_OK
public static final int	XA_RDONLY

Method Summary

Modifier and Type	Method and Description
public 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.
public long	addAndLoadStreamContainer(long segmentId, Properties tableProperties, RowSource rowSource) Add a new stream container to the segment and load the stream container.
public long	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. addContainer(long segment to create the container in. segmentId, long 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. containerId, int 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. mode, Properties Implementation-specific properties of the conglomerate. tableProperties, int temporaryFlag) Add a new container to the segment.
public void	addPostAbortWork(Serviceable the post commit work that is added work) Add to the list of post abort work that may be processed after this transaction aborts.
public void	addPostCommitWork(Serviceable the post commit work that is added work) Add to the list of post commit work that may be processed after this transaction commits.
public void	addPostTerminationWork(Serviceable the post termination work that is added work) Add to the list of post termination work that may be processed after this transaction commits or aborts.
public boolean	anyoneBlocked() Return true if any transaction is blocked, even if not by this one.
public void	close() Close this transaction, the transaction must be idle.
public LogInstant	Returns: the commit instant of this transaction, or null if it didn't make any changes commit() Commit this transaction.
public LogInstant	commitNoSync(int commitflag) "Commit" this transaction without sync'ing the log.
public void	createXATransactionFromLocalTransaction(int the format id part of the Xid - ie. Xid.getFormatId(). format_id, byte[] the global transaction identifier part of XID - ie. Xid.getGlobalTransactionId(). global_id, byte[] The branch qualifier of the Xid - ie. Xid.getBranchQaulifier() branch_id) Convert a local transaction to a global transaction.
public void	destroy() If this transaction is not idle, abort it.
public void	dropContainer(ContainerKey containerId) Drop a container.
public void	dropStreamContainer(long segmentId, long containerId) Drop a stream container.
public String	getActiveStateTxIdString() get string ID of the actual transaction ID that will be used when transaction is in active state.
public CompatibilitySpace	Returns: The compatibility space of the transaction. getCompatibilitySpace() Get the compatibility space of the transaction.
public ContextManager	getContextManager() Return the context manager this transaction is associated with.
public DataValueFactory	Returns: a booted data value factory. getDataValueFactory() Get DataValueFactory.
public LockingPolicy	Returns: The current default locking policy in this transaction. getDefaultLockingPolicy() Get the current default locking policy for all operations within this transaction.
public FileResource	getFileHandler() Get an object to handle non-transactional files.
public GlobalTransactionId	getGlobalId() Return my transaction identifier.
public boolean	Returns: true If the transaction has never read or written data. isIdle() Reveals whether the transaction has ever read or written data.
public boolean	Returns: true if so, false otherwise isPristine() Reveal whether the transaction is in a pristine state, which means it hasn't done any updates since the last commit.
public void	logAndDo(Loggable the operation that is to be applied operation) Log an operation and then action it in the context of this transaction.
public LockingPolicy	Returns: A object that can be used in an openContainer call, null if a matching policy cannot be found. newLockingPolicy(int A constant of the form LockingPolicy.MODE_* mode, int A constant of the form LockingPolicy.ISOLATION_* isolation, boolean True if a stricter level of locking is acceptable, false if an exact match is required. stricterOk) Obtain a locking policy for use in openContainer().
public ContainerHandle	Returns: a valid ContainerHandle or null if the container does not exist. openContainer(ContainerKey containerId, int mode) Open a container, with the transaction's default locking policy.
public ContainerHandle	Returns: a valid ContainerHandle or null if the container does not exist. openContainer(ContainerKey containerId, LockingPolicy The lock policy to use, if null then then a no locking policy will be used. locking, int mode) Open a container, with the defined locking policy, otherwise as openContainer(int containerId, boolean forUpdate).
public StreamContainerHandle	Returns: a valid StreamContainerHandle or null if the container does not exist. openStreamContainer(long segmentId, long containerId, boolean hold) Open a stream container.
public int	Returns: returns total number of savepoints in the stack. releaseSavePoint(String The user provided name of the savepoint, set by the user in the setSavePoint() call. name, Object 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 kindOfSavepoint) Release the save point of the given name.
public int	Returns: returns total number of savepoints in the stack. rollbackToSavePoint(String The user provided name of the savepoint, set by the user in the setSavePoint() call. name, Object 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 kindOfSavepoint) Rollback all changes made since the named savepoint was set.
public void	setDefaultLockingPolicy(LockingPolicy The lock policy to use, if null then then a no locking policy will be installed as the default. policy) Set the default locking policy for all operations within this transaction.
public void	setNoLockWait(boolean if `true` never wait for a lock in this transaction, but time out immediately noWait) Tell this transaction whether it should time out immediately if a lock cannot be granted without waiting.
public int	Returns: returns total number of savepoints in the stack. setSavePoint(String The user provided name of the savepoint name, Object 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 kindOfSavepoint) Set a save point in the current transaction.
public void	setup(PersistentSet set) Called after the transaction has been attached to an Access Manger TransactionController.
public void	xa_commit(boolean If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of current xid. onePhase) This method is called to commit the current XA global transaction.
public int	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. xa_prepare() This method is called to ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
public void	xa_rollback() rollback the current global transaction.

KEEP_LOCKS	back to summary
public static final int KEEP_LOCKS

RELEASE_LOCKS	back to summary
public static final int RELEASE_LOCKS

XA_OK	back to summary
public static final int XA_OK

XA_RDONLY	back to summary
public static final int XA_RDONLY

Method Detail

abort	back to summary
public 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. Exceptions StandardException: Only exceptions with severities greater than ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.

abort

back to summary

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

Exceptions

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

addAndLoadStreamContainer	back to summary
public long addAndLoadStreamContainer(long segmentId, 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. Exceptions StandardException: Standard Derby error policy

addAndLoadStreamContainer

back to summary

public long addAndLoadStreamContainer(long segmentId, 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.

Exceptions

StandardException:: Standard Derby error policy

addContainer	back to summary
public long addContainer(long segmentId, long containerId, int mode, 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:long segment to create the container in. containerId:long 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:int 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:Properties Implementation-specific properties of the conglomerate. Returns:long 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. Exceptions StandardException: Standard Derby error policy

addContainer

back to summary

public long addContainer(long segmentId, long containerId, int mode, 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:long: segment to create the container in.
containerId:long: 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:int: 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:Properties: Implementation-specific properties of the conglomerate.

Returns:long

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.

Exceptions

StandardException:: Standard Derby error policy

addPostAbortWork	back to summary
public void addPostAbortWork(Serviceable work) Add to the list of post abort work that may be processed after this transaction aborts. Parameters work:Serviceable the post commit work that is added

addPostAbortWork

back to summary

public void addPostAbortWork(Serviceable work)

Add to the list of post abort work that may be processed after this transaction aborts.

Parameters

work:Serviceable: the post commit work that is added

addPostCommitWork	back to summary
public 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:Serviceable the post commit work that is added

addPostCommitWork

back to summary

public 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:Serviceable: the post commit work that is added

addPostTerminationWork	back to summary
public void addPostTerminationWork(Serviceable work) Add to the list of post termination work that may be processed after this transaction commits or aborts. Parameters work:Serviceable the post termination work that is added

addPostTerminationWork

back to summary

public void addPostTerminationWork(Serviceable work)

Add to the list of post termination work that may be processed after this transaction commits or aborts.

Parameters

work:Serviceable: the post termination work that is added

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

close back to summary

close	back to summary
public 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. Exceptions StandardException: A transaction level exception is thrown if the transaction is not idle. See Also `RawStoreFactory#startTransaction`

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

Exceptions

StandardException:: A transaction level exception is thrown if the transaction is not idle.

See Also

RawStoreFactory#startTransaction

commit	back to summary
public LogInstant commit() throws StandardException Commit this transaction. All savepoints within this transaction are released. Returns:LogInstant the commit instant of this transaction, or null if it didn't make any changes Exceptions 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. 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.

commit

back to summary

public LogInstant commit() throws StandardException

Commit this transaction. All savepoints within this transaction are released.

Returns:LogInstant

the commit instant of this transaction, or null if it didn't make any changes

Exceptions

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. 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	back to summary
public 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. Exceptions 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. 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

back to summary

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

Exceptions

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

createXATransactionFromLocalTransaction	back to summary
public 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:int the format id part of the Xid - ie. Xid.getFormatId(). global_id:byte[] the global transaction identifier part of XID - ie. Xid.getGlobalTransactionId(). branch_id:byte[] The branch qualifier of the Xid - ie. Xid.getBranchQaulifier() Exceptions StandardException: Standard exception policy.

createXATransactionFromLocalTransaction

back to summary

public 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:int: the format id part of the Xid - ie. Xid.getFormatId().
global_id:byte[]: the global transaction identifier part of XID - ie. Xid.getGlobalTransactionId().
branch_id:byte[]: The branch qualifier of the Xid - ie. Xid.getBranchQaulifier()

Exceptions

StandardException:: Standard exception policy.

destroy back to summary

destroy	back to summary
public void destroy() throws StandardException If this transaction is not idle, abort it. After this call close(). Exceptions StandardException: A transaction level exception is thrown if the transaction is not idle. See Also `RawStoreFactory#startTransaction`

public void destroy() throws StandardException

If this transaction is not idle, abort it. After this call close().

Exceptions

StandardException:: A transaction level exception is thrown if the transaction is not idle.

See Also

RawStoreFactory#startTransaction

dropContainer	back to summary
public 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. Exceptions StandardException: Standard Derby error policy

dropContainer

back to summary

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

Exceptions

StandardException:: Standard Derby error policy

dropStreamContainer	back to summary
public void dropStreamContainer(long segmentId, long containerId) throws StandardException Drop a stream container. Synchronisation This call will remove the container. Exceptions StandardException: Standard Derby error policy

dropStreamContainer

back to summary

public void dropStreamContainer(long segmentId, long containerId) throws StandardException

Drop a stream container.

Synchronisation

This call will remove the container.

Exceptions

StandardException:: Standard Derby error policy

getActiveStateTxIdString	back to summary
public String getActiveStateTxIdString() get string ID of the actual transaction ID that will be used when transaction is in active state.

getCompatibilitySpace	back to summary
public 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:CompatibilitySpace The compatibility space of the transaction.

getCompatibilitySpace

back to summary

public 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:CompatibilitySpace: The compatibility space of the transaction.

getContextManager	back to summary
public ContextManager getContextManager() Return the context manager this transaction is associated with.

getDataValueFactory	back to summary
public DataValueFactory getDataValueFactory() throws StandardException Get DataValueFactory. Return a DataValueFactory that can be used to allocate objects. Used to make calls to: DataValueFactory.getInstanceUsingFormatIdAndCollationType() Returns:DataValueFactory a booted data value factory. Exceptions StandardException: Standard exception policy.

getDataValueFactory

back to summary

public DataValueFactory getDataValueFactory() throws StandardException

Get DataValueFactory.

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

Returns:DataValueFactory

a booted data value factory.

Exceptions

StandardException:: Standard exception policy.

getDefaultLockingPolicy	back to summary
public 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:LockingPolicy The current default locking policy in this transaction.

getDefaultLockingPolicy

back to summary

public 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:LockingPolicy: The current default locking policy in this transaction.

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

getGlobalId	back to summary
public 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.

isIdle	back to summary
public boolean isIdle() Reveals whether the transaction has ever read or written data. Returns:boolean true If the transaction has never read or written data.

isIdle

back to summary

public boolean isIdle()

Reveals whether the transaction has ever read or written data.

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

isPristine	back to summary
public boolean isPristine() Reveal whether the transaction is in a pristine state, which means it hasn't done any updates since the last commit. Returns:boolean true if so, false otherwise

isPristine

back to summary

public boolean isPristine()

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

Returns:boolean: true if so, false otherwise

logAndDo back to summary

logAndDo	back to summary
public 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:Loggable the operation that is to be applied Exceptions StandardException: Standard Derby exception policy See Also `Loggable`

public 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:Loggable: the operation that is to be applied

Exceptions

StandardException:: Standard Derby exception policy

See Also

Loggable

newLockingPolicy	back to summary
public 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:int A constant of the form LockingPolicy.MODE_* isolation:int A constant of the form LockingPolicy.ISOLATION_* stricterOk:boolean True if a stricter level of locking is acceptable, false if an exact match is required. Returns:LockingPolicy A object that can be used in an openContainer call, null if a matching policy cannot be found.

newLockingPolicy

back to summary

public 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:int: A constant of the form LockingPolicy.MODE_*
isolation:int: A constant of the form LockingPolicy.ISOLATION_*
stricterOk:boolean: True if a stricter level of locking is acceptable, false if an exact match is required.

Returns:LockingPolicy

A object that can be used in an openContainer call, null if a matching policy cannot be found.

openContainer	back to summary
public 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:ContainerHandle a valid ContainerHandle or null if the container does not exist. Exceptions StandardException: Standard Derby exception policy

openContainer

back to summary

public 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:ContainerHandle

a valid ContainerHandle or null if the container does not exist.

Exceptions

StandardException:: Standard Derby exception policy

openContainer	back to summary
public 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:LockingPolicy The lock policy to use, if null then then a no locking policy will be used. Returns:ContainerHandle a valid ContainerHandle or null if the container does not exist. Exceptions StandardException: Standard Derby exception policy

openContainer

back to summary

public 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:LockingPolicy: The lock policy to use, if null then then a no locking policy will be used.

Returns:ContainerHandle

a valid ContainerHandle or null if the container does not exist.

Exceptions

StandardException:: Standard Derby exception policy

openStreamContainer	back to summary
public StreamContainerHandle openStreamContainer(long segmentId, long containerId, boolean hold) throws StandardException Open a stream container. Returns:StreamContainerHandle a valid StreamContainerHandle or null if the container does not exist. Exceptions StandardException: Standard Derby exception policy

openStreamContainer

back to summary

public StreamContainerHandle openStreamContainer(long segmentId, long containerId, boolean hold) throws StandardException

Open a stream container.

Returns:StreamContainerHandle

a valid StreamContainerHandle or null if the container does not exist.

Exceptions

StandardException:: Standard Derby exception policy

releaseSavePoint	back to summary
public int releaseSavePoint(String name, 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:String The user provided name of the savepoint, set by the user in the setSavePoint() call. kindOfSavepoint:Object 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:int returns total number of savepoints in the stack. Exceptions StandardException: A statement level exception is thrown if a savepoint already exists in the current transaction with the same name.

releaseSavePoint

back to summary

public int releaseSavePoint(String name, 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:String: The user provided name of the savepoint, set by the user in the setSavePoint() call.
kindOfSavepoint:Object: 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:int

returns total number of savepoints in the stack.

Exceptions

StandardException:: A statement level exception is thrown if a savepoint already exists in the current transaction with the same name.

rollbackToSavePoint	back to summary
public int rollbackToSavePoint(String name, 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:String The user provided name of the savepoint, set by the user in the setSavePoint() call. kindOfSavepoint:Object 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:int returns total number of savepoints in the stack. Exceptions StandardException: A statement level exception is thrown if no savepoint exists with the given name.

rollbackToSavePoint

back to summary

public int rollbackToSavePoint(String name, 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:String: The user provided name of the savepoint, set by the user in the setSavePoint() call.
kindOfSavepoint:Object: 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:int

returns total number of savepoints in the stack.

Exceptions

StandardException:: A statement level exception is thrown if no savepoint exists with the given name.

setDefaultLockingPolicy	back to summary
public 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:LockingPolicy The lock policy to use, if null then then a no locking policy will be installed as the default.

setDefaultLockingPolicy

back to summary

public 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:LockingPolicy: The lock policy to use, if null then then a no locking policy will be installed as the default.

setNoLockWait back to summary

setNoLockWait	back to summary
public 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:boolean if `true` never wait for a lock in this transaction, but time out immediately See Also `org.apache.derby.iapi.services.locks.LockOwner#noWait()`

public 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:boolean: if true never wait for a lock in this transaction, but time out immediately

setSavePoint	back to summary
public int setSavePoint(String name, 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:String The user provided name of the savepoint kindOfSavepoint:Object 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:int returns total number of savepoints in the stack. Exceptions StandardException: A statement level exception is thrown if a savepoint already exists in the current transaction with the same name.

setSavePoint

back to summary

public int setSavePoint(String name, 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:String: The user provided name of the savepoint
kindOfSavepoint:Object: 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:int

returns total number of savepoints in the stack.

Exceptions

StandardException:: A statement level exception is thrown if a savepoint already exists in the current transaction with the same name.

setup	back to summary
public 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. Exceptions StandardException: Standard Derby exception policy

setup

back to summary

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

Exceptions

StandardException:: Standard Derby exception policy

xa_commit	back to summary
public 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:boolean If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of current xid. Exceptions StandardException: Standard exception policy.

xa_commit

back to summary

public 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:boolean: If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of current xid.

Exceptions

StandardException:: Standard exception policy.

xa_prepare	back to summary
public 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:int 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. Exceptions StandardException: Standard exception policy.

xa_prepare

back to summary

public 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:int

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.

Exceptions

StandardException:: Standard exception policy.

xa_rollback	back to summary
public 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. Exceptions StandardException: Standard exception policy.

xa_rollback

back to summary

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

Exceptions

StandardException:: Standard exception policy.

public Interface Transaction

Field Summary

Method Summary

Field Detail

Method Detail