com.objy.db.app
Class Transaction

java.lang.Object
  |
  +--com.objy.db.app.Transaction

public final class Transaction

extends Object

Represents an ODMG transaction.

API Summary

An ODMG transaction object provides the transaction services for ODMG applications.

Note: Your application should work with an instance of this class only if it requires ODMG compliance; otherwise, it should work with a session instead. For additional information about ODMG applications, see ODMG Application Objects.

After you have obtained an ODMG database object, you can create an ODMG transaction and use it to interact with the connected federated database. Your application can create multiple transaction objects, each corresponding to a particular subtask that your application performs.

An Objectivity for Java application can use multiple Java threads to execute concurrent persistent operations. However, persistent operations performed while a given transaction object is open are treated serially by Objectivity/DB. To obtain truly concurrent operations, each of several concurrent threads must have its own transaction object.

Transactions are long-lived objects which can be used for many begin(), commit(), abort() sequences.

A thread policy governs the interaction between threads and transaction objects. Objectivity for Java provides two different thread policies: unrestricted and restricted. ODMG applications use the restricted thread policy.

Associated Objects

When you create an ODMG transaction object, the transaction's session is created automatically. The session, in turn, creates a local representation of the connected federated database and a clustering strategy.

The transaction and federated-database objects belong to their associated session object; in addition, the local representation of every persistent object and storage object that you retrieve or create while a particular transaction object is open belongs to that transaction's session. Objectivity for Java does not allow a transaction object to interact with any object that belongs to a different session; see Object Isolation.

API Summary

Constant Types

Lock modes (ODMG) Control how to lock a persistent object.

READ WRITE NONE

Functionality

Constructors	Transaction() (ODMG)
Controlling Transactions	begin() (ODMG) checkpoint() (ODMG) checkpoint(int) commit() (ODMG) abort() (ODMG)
Getting Information	getSession() current() (ODMG)
Testing	isOpen() (ODMG) isJoined()
Managing Interactions With Threads	join() (ODMG) isJoined() leave() (ODMG)
Locking Objects	lock(Object, int) (ODMG)
Static Utilities	current() (ODMG)

Field Summary

static int	NONE Lock mode: The persistent object is not locked.
static int	READ (ODMG) Lock mode: The persistent object is locked for read.
static int	UPGRADE (ODMG) Not supported.
static int	WRITE (ODMG) Lock mode: The persistent object is locked for write.

Constructor Summary

Transaction()
(ODMG) Constructs an ODMG transaction object and creates its associated session and federated-database object.

Transaction(PTransaction persistor)
Reserved for internal use.

Method Summary

void	abort() (ODMG) Aborts the current transaction.
void	begin() (ODMG) Begins a transaction.
void	checkpoint() (ODMG) Commits all persistent operations executed since the last checkpoint, retaining all locks acquired during the current transaction.
void	checkpoint(int downGradeMode) Commits all persistent operations executed since the last checkpoint and potentially downgrades all locks acquired during the current transaction.
void	commit() (ODMG) Commits the current transaction.
static Transaction	current() (ODMG) Gets the transaction joined with the currently active Java thread.
Session	getSession() Gets the session that owns this transaction.
boolean	isJoined() Tests whether the currently active Java thread is joined with this transaction.
boolean	isOpen() (ODMG) Tests whether this transaction is open.
void	join() (ODMG) Joins the currently active Java thread with this transaction.
void	leave() (ODMG) Causes the currently active Java thread to leave this transaction.
void	lock(Object object, int mode) (ODMG) Explicitly locks the specified object for the specified access and propagates the lock to related objects.
void	setPersistor(PTransaction persistor) Reserved for internal use; you should not call this method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

READ

public static final int READ

(ODMG) Lock mode: The persistent object is locked for read.

WRITE

public static final int WRITE

(ODMG) Lock mode: The persistent object is locked for write.

UPGRADE

public static final int UPGRADE

(ODMG) Not supported. Do not use this constant.

NONE

public static final int NONE

Lock mode: The persistent object is not locked.

Constructor Detail

Transaction

public Transaction()

(ODMG) Constructs an ODMG transaction object and creates its associated session and federated-database object.

The newly created transaction interacts with the connected federated database.

Note: The constructor throws an ObjyRuntimeException if there is no open connection.

The constructor joins the current thread to the newly created transaction.

Transaction

public Transaction(PTransaction persistor)

Reserved for internal use.

You should not use this constructor directly.

Method Detail

current

public static Transaction current()

(ODMG) Gets the transaction joined with the currently active Java thread.

Returns:

The transaction object joined with the currently active Java thread, or null if the current thread is not joined to any transaction object.

begin

public void begin()

(ODMG) Begins a transaction.

This transaction object must be closed when you call this method. The thread that calls this method must be joined to this transaction object.

This method begins a transaction; when the method returns, this transaction object will be open.

abort

public void abort()

(ODMG) Aborts the current transaction.

This transaction object must be open when you call this method. The thread that calls this method must be joined to this transaction object.

This method aborts the transaction started by the most recent call to begin and releases all locks held by this transaction object. Any persistent operations executed during the aborted transaction are undone; that is, the affects of the operations do not appear in the connected federated database.

All the objects that belong to this transaction's session are marked as needing to have their data fetched; those objects are no longer marked as modified.

When the method returns, this transaction object will be closed.

commit

public void commit()

(ODMG) Commits the current transaction.

This transaction object must be open when you call this method. The thread that calls this method must be joined to this transaction object.

This method terminates the transaction started by the most recent call to begin and releases all locks held by this transaction object. All persistent operations executed since the most recent call to begin or checkpoint are reflected in the connected federated database.

All the objects that belong to this transaction's session are marked as needing to have their data fetched; those objects are no longer marked as modified.

When the method returns, this transaction object will be closed.

checkpoint

public void checkpoint()

(ODMG) Commits all persistent operations executed since the last checkpoint, retaining all locks acquired during the current transaction.

This transaction object must be open when you call this method. The thread that calls this method must be joined to this transaction object.

All persistent operations executed since the most recent call to begin or checkpoint are reflected in the connected federated database. The objects that belong to this transaction's session are no longer marked as modified.

When the method returns, this transaction object will still be open.

See Also:

commit()

checkpoint

public void checkpoint(int downGradeMode)

Commits all persistent operations executed since the last checkpoint and potentially downgrades all locks acquired during the current transaction.

This transaction object must be open when you call this method. The thread that calls this method must be joined to this transaction object.

All persistent operations executed since the most recent call to begin or checkpoint are reflected in the connected federated database. The objects that belong to this transaction's session are no longer marked as modified.

When the method returns, this transaction object will still be open.

Parameters:

downGradeMode - The lock downgrade mode; one of the following constants defined in the oo interface:

NO_DOWNGRADE

Preserve all locks held by this transaction object.

DOWNGRADE_ALL

Downgrade all locks to read locks.

See Also:

commit()

isOpen

public boolean isOpen()

(ODMG) Tests whether this transaction is open.

A transaction is open once begin is called and until commit or abort is called.

Returns:

True if a transaction is open; otherwise, false.

join

public void join()

(ODMG) Joins the currently active Java thread with this transaction.

If the thread is already joined with this transaction, then this method has no effect. If the thread was joined with another transaction, it leaves that transaction and joins this transaction.

See Also:

isJoined(), leave()

leave

public void leave()

(ODMG) Causes the currently active Java thread to leave this transaction.

Threads should call this method before terminating.

This method will throw a NotJoinedException if the thread is not joined with this transaction. You can call isJoined to test whether the thread is joined with this transaction.

See Also:

join()

isJoined

public boolean isJoined()

Tests whether the currently active Java thread is joined with this transaction.

Returns:

True if the currently active thread is joined with this transaction; otherwise, false.

lock

public void lock(Object object,
                 int mode)

(ODMG) Explicitly locks the specified object for the specified access and propagates the lock to related objects.

This transaction object must be open when you call this method. The thread that calls this method must be joined to this transaction object.

Parameters:

object - The object to be locked. The object must be a persistent basic object or a persistent container, and it must belong to this transaction's session. If object is a basic object, this method implicitly locks that object's container. If object is a container, this method implicitly locks all basic objects in that container.

This method propagates the lock to any objects associated to the specified object through relationships for which lock propagation is enabled.

mode - The type of lock to obtain for the specified object; one of the following constants defined in this class (and also in the oo interface):

READ

Obtain a read lock.

WRITE

Obtain a write lock.

The lock mode is limited by the open mode of the ODMG database object. If you try to set the lock mode to WRITE when the open mode of the database object is openReadOnly, this method throws a runtime exception.

If object is already locked, you can call this method to upgrade a read lock to a write lock, but not to downgrade a write lock to a read lock.

getSession

public Session getSession()

Gets the session that owns this transaction.

Returns:

The session that owns this transaction.

setPersistor

public void setPersistor(PTransaction persistor)

Reserved for internal use; you should not call this method.