Class COM.odi.Transaction

java.lang.Object
   |
   +----COM.odi.Transaction

public class Transaction

extends Object

implements ObjectStoreConstants

Either all of a transaction's changes to persistent objects are made successfully, or none is made at all. If a failure occurs in the middle of a transaction, none of its database updates is made.

Transaction is an abstract class. When you invoke the Transaction.begin() method, ObjectStore automatically finds the subclass of Transaction, creates an instance of that subclass, and uses it to represent your transaction. You are not expected to extend the Transaction class, and ObjectStore will not work if you do.

If an application terminates at anytime, ObjectStore returns the database to the state it was in before the transaction started. ObjectStore sometimes automatically aborts a transaction because of deadlock. A simple deadlock occurs when one transaction holds a lock on a page that another transaction is waiting to access, while at the same time this other transaction holds a lock on a page that the first transaction is waiting to access. Neither process can proceed until the other does.

ObjectStore does not retry transactions that are aborted because of deadlock. If you want to retry a transaction that was aborted because of deadlock, you must include code to do this in your application. An example of this code is in the API User Guide.

readOnly

Deprecated.

update

Deprecated.

abort()

Aborts a transaction.

abort(int)

Aborts a transaction and retains objects that were referenced in the transaction.

begin(int)

Starts a transaction.

checkpoint(int)

Checkpoints a transaction.

commit()

Commits a transaction.

commit(int)

Commits a transaction and specifies what should happen to persistent objects after the transaction is over.

current()

Obtains the instance of Transaction that is associated with the current thread.

getPriority()

Gets the priority specified for transactions started by the current session.

getSession()

Returns the session associated with this Transaction.

getType()

Obtains the type of a transaction.

hasLockContention()

Indicates whether or not a Server involved in the current transaction has experienced contention for some persistent objects that the application is using.

inTransaction()

Determines whether or not there is a transaction in progress in the session to which the current thread belongs.

isAborted()

Returns true if the transaction has been aborted, otherwise false.

isActive()

Returns true if the transaction has not been aborted or committed, otherwise false.

setDefaultAbortRetain(int)

Sets the default retain operation for the current session for calls to Transaction.abort() that have no argument.

setPriority(int)

Sets the priority for transactions started by the current session.

  public final static int readOnly

Note: readOnly is deprecated. This constant has been changed to ObjectStore.READONLY.

  public final static int update

Note: update is deprecated. This constant has been changed to ObjectStore.UPDATE.

  public static Transaction begin(int type)

Starts a transaction. Nested transactions are not allowed.

Parameters:

type - The type of transaction to start. This value must be either ObjectStore.READONLY or ObjectStore.UPDATE.

Returns:

A Transaction object that represents the transaction that was initiated.

Throws: DatabaseLockedException

If you specify a nonblocking transaction begin type and the kind of lock needed for the database is not available.

Throws: IllegalArgumentException

If the transaction type is not ObjectStore.READONLY, ObjectStore.UPDATE, ObjectStore.READONLY_NON_BLOCKING, or ObjectStore.UPDATE_NON_BLOCKING.

Throws: ObjectStoreException

If the current thread is not associated with a session and there is no global session.

Throws: TransactionInProgressException

If there is already a transaction in progress.

  public static Transaction current()

Obtains the instance of Transaction that is associated with the current thread.

Returns:

A Transaction object for the transaction in progress for the current thread.

Throws: NoTransactionInProgressException

If no transaction is in progress for the current thread.

Throws: ObjectStoreException

If the current thread is not associated with a session and there is no global session.

  public static boolean inTransaction()

Determines whether or not there is a transaction in progress in the session to which the current thread belongs.

Returns:

The true constant if there is a transaction in progress for the session to which the current thread belongs. The false constant if a transaction is not in progress. This method also returns false if the current thread is not associated with a session. This behavior is compatible with previous releases of ObjectStore, but it is not consistent with other methods. Other methods throw ObjectStoreException when the current thread does not belong to a session.

  public abstract void commit()

Commits a transaction. This ends the transaction. When ObjectStore commits a transaction, it

• Checks whether or not there are any transient objects that are referred to by persistent objects. If there are such objects, ObjectStore stores them in the database.

• Checks for modified persistent objects. If there are such objects, ObjectStore saves the changes in the database.

• Resets the contents of the persistent objects to the default values, which removes any references to other objects. The persistent objects become stale objects. To do this, ObjectStore calls the Persistent.clearContents() method on each persistent object.

Throws: AbortException

If ObjectStore detects a reference from an object in one segment to an unexported object in another segment. If one or more safe cursors to persistent classes exist. If ObjectStore reaches an object while it is performing transitive persistence and that object is not persistence-capable.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the transaction has been terminated or if the current thread is associated with a session other than the session implied by the transaction.

  public abstract void commit(int retain)

Commits a transaction and specifies what should happen to persistent objects after the transaction is over. This ends the transaction. When ObjectStore commits a transaction, it:

Checks whether or not there are any transient objects that are referred to by persistent objects. If there are such objects, ObjectStore stores them in the database.

Checks for modified persistent objects. If there are such objects, ObjectStore saves the changes in the database.

Determines the disposition of persistent objects for after the transaction according to the value of the retain argument.

The retain argument provides a mechanism for using persistent objects between transactions. When you start a new transaction, you can use the references to retained objects. However, if you retained the contents of the objects, (if you specified ObjectStore.RETAIN_READONLY or ObjectStore.RETAIN_UPDATE) the state of these objects might have been changed since the commit operation by another process. ObjectStore automatically refreshes the state of any modified objects, when they are first touched in the new transaction. This means that the application code cannot assume that the state of a retained object remains constant even when a new transaction is started. It is also possible that trying to read or write a retained object in a new transaction could result in a transaction waiting for a lock, or a transaction abort due to a deadlock situation.

Parameters:

retain - Possible values are:

• ObjectStore.RETAIN_STALE -- Resets the contents of persistent objects to default values and makes all persistent objects stale. This is the same as calling commit().

• ObjectStore.RETAIN_HOLLOW -- Resets the contents of persistent objects to default values but makes them hollow. References to objects from this transaction can be used in the next one.

• ObjectStore.RETAIN_READONLY -- Retains persistent objects and their contents. Objects whose contents were available in this transaction can be read between the end of this transaction and the start of the next transaction. If you attempt to modify a persistent object before the next transaction ObjectStore throws NoTransactionInProgressException.

• ObjectStore.RETAIN_UPDATE -- Retains persistent objects and their contents and allows modifications. Objects whose contents were available in this transaction can be read or modified between the end of this transaction and the start of the next transaction. ObjectStore discards any modifications to persistent objects at the start of the next transaction. During the next transaction, objects that you modified contain the most recent contents of the object in the database.

Additional information about hollow, active, and stale object state is the API User Guide.

For additional information about retaining persistent objects, see the API User Guide.

Throws: AbortException

If ObjectStore detects a reference from an object in one segment to an unexported object in another segment. If one or more safe cursors to persistent classes exist. If ObjectStore reaches an object while it is performing transitive persistence and that object is not persistence-capable.

Throws: IllegalArgumentException

If retain is not one of ObjectStore.RETAIN_STALE, ObjectStore.RETAIN_HOLLOW, ObjectStore.RETAIN_READONLY, or ObjectStore.RETAIN_UPDATE.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the transaction has been terminated or if the current thread is associated with a session other than the session implied by the transaction.

  public abstract void abort()

Aborts a transaction. abort() restores the persistent state to what it was when the transaction was started. If you opened any databases during the aborted transaction, ObjectStore closes them. Any databases that were open before the aborted transaction was started remain open.

Objects that were referenced in the transaction are retained according to the value of Transaction.setDefaultAbortRetain(). If Transaction.setDefaultAbortRetain() has not been called, calling abort() is the same as calling abort(ObjectStore.RETAIN_STALE).

Sometimes, when ObjectStore throws an exception, it also aborts the current transaction. If it does, you must not call the abort() method if you catch the exception. The exceptions that can abort transactions are

• ObjectStoreException
• FatalException or any of its descendents
• AbortException or any of its descendents

If you set up an exception handler that handles one of these exceptions, the handler body must not call abort() unless it has determined that there is still a transaction in progress. You can call Transaction.inTransaction() to determine if there is a transaction in progress.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the transaction has been terminated or if the current thread is associated with a session other than the session implied by the transaction.

  public abstract void abort(int retain)

Aborts a transaction and retains objects that were referenced in the transaction. The value you specify for the retain argument determines the state of the retained objects. The abort operation restores the persistent state to what it was when the transaction was started. If you opened any databases during the aborted transaction, ObjectStore closes them. Any databases that were open before the aborted transaction was started remain open.

The retain argument provides a mechanism for using persistent objects between transactions. When you start a new transaction, you can use the references to retained objects. However, if you retained the contents of the objects, (if you specified ObjectStore.RETAIN_READONLY or ObjectStore.RETAIN_UPDATE) the state of these objects might have been changed since the abort operation by another process. ObjectStore automatically refreshes the state of any modified objects, when they are first touched in the new transaction. This means that the application code cannot assume that the state of a retained object remains constant even when a new transaction is started. It is also possible that trying to read or write a retained object in a new transaction could result in a transaction waiting for a lock, or a transaction abort due to a deadlock situation.

Sometimes, when ObjectStore throws an exception, it also aborts the current transaction. If it does, you must not call the abort() method if you catch the exception. The exceptions that can abort transactions are

ObjectStoreException

FatalException or any of its descendents

AbortException or any of its descendents

If you set up an exception handler that handles one of these exceptions, the handler body must not call abort() unless it has determined that there is still a transaction in progress. You can call Transaction.inTransaction() to determine if there is a transaction in progress.

Parameters:

retain - Possible values are:

• ObjectStore.RETAIN_STALE -- Resets the contents of all persistent objects to their default values and makes them stale. This is the same as calling abort() when Transaction.setDefaultAbortRetain() has either not been called or been called with ObjectStore.RETAIN_STALE as its argument.

• ObjectStore.RETAIN_HOLLOW -- Resets the contents of all persistent objects to default values but retains them. In the next transaction, you can use references to persistent objects from this transaction.

• ObjectStore.RETAIN_READONLY -- Retains the contents of unmodified persistent objects that were read during the aborted transaction. Any objects that were modified become hollow objects, as if ObjectStore.RETAIN_HOLLOW had been specified. Objects whose contents were not modified in the aborted transaction can be read after the aborted transaction. If you try to modify a persistent object before the next transaction, ObjectStore throws NoTransactionInProgressException. If you modified any persistent objects during the aborted transaction, ObjectStore discards these modifications and makes these objects hollow as part of the abort operation. During the next transaction, the contents of persistent objects that were not modified during the aborted transaction are still available.

• ObjectStore.RETAIN_UPDATE -- Retains the contents of persistent objects as well as the objects themselves. The values that are retained are the last values that the objects contained before the transaction was aborted. Even though the changes to to the modified objects are undone with regard to the database, the changes are not undone in the objects in the Java VM. While you are between transactions, the changes that were aborted are still visible in the Java objects. At the start of the next transaction, ObjectStore discards the modifications and reads in the contents from the database. Objects that were read or modified in the aborted transaction can be modified between the aborted transaction and the next transaction. If you modify any persistent objects during or after the aborted transaction, ObjectStore discards these modifications and makes these objects hollow at the start of the next transaction. During the next transaction, the contents of persistent objects that were not modified during or after the aborted transaction are still available.

Throws: IllegalArgumentException

If the value of the retain argument is not one of ObjectStore.RETAIN_STALE, ObjectStore.RETAIN_HOLLOW, ObjectStore.RETAIN_READONLY, or ObjectStore.RETAIN_UPDATE.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the transaction has been terminated or if the current thread is associated with a session other than the session implied by the transaction.

  public abstract void checkpoint(int retain)

Checkpoints a transaction. A transaction checkpoint is similar to a transaction commit followed by beginning a new transaction and acquiring read locks on most everything that was locked in the previous transaction. A transaction checkpoint is an efficient way to make database changes made in the current transaction permanent and permit an MVCC refresh (resynchronization) opportunity. After a checkpoint, locks on objects locked for update are at most retained as read locks.

The retain argument determines the disposition of persistent objects after the checkpoint. Because checkpoint() immediately starts a new transaction after committing the current one, the retain argument does not affect the behavior of persistent objects outside of a transaction.

Parameters:

retain - Possible values are:

• ObjectStore.RETAIN_STALE resets the contents of persistent objects to default values and makes all persistent objects stale.
• ObjectStore.RETAIN_HOLLOW resets the contents of persistent objects to default values but makes them hollow. References to objects from this transaction can be used in the new transaction started by checkpoint().

Throws: AbortException

If ObjectStore detects a reference from an object in one segment to an unexported object in another segment, if one or more safe cursors to persistent classes exist, or if ObjectStore reaches an object while it is performing transitive persistence and that object is not persistence-capable.

Throws: IllegalArgumentException

If retain is not one of ObjectStore.RETAIN_STALE or ObjectStore.RETAIN_HOLLOW.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the transaction has been terminated or if the current thread is associated with a session other than the session implied by the transaction.

  public static void setDefaultAbortRetain(int retain)

Sets the default retain operation for the current session for calls to Transaction.abort() that have no argument.

Parameters:

retain - Possible values are:

• ObjectStore.RETAIN_STALE causes abort() to reset the contents of all persistent objects to their default values and makes them stale.

• ObjectStore.RETAIN_HOLLOW causes abort() to reset the contents of all persistent objects to default values but retain them as hollow objects.

• ObjectStore.RETAIN_READONLY causes abort() to retain the contents of persistent objects as well as the objects themselves. The values that are retained are the last values that the objects contained before the transaction was aborted. Objects whose contents were available in the aborted transaction can be read after the aborted transaction. If you try to modify a persistent object before the next transaction, ObjectStore throws NoTransactionInProgressException. If you modified any persistent objects during the aborted transaction, ObjectStore discards these modifications and makes these objects hollow at the start of the next transaction. During the next transaction, the contents of persistent objects that were not modified during the aborted transaction are still available.

• ObjectStore.RETAIN_UPDATE causes abort() to retain the contents of persistent objects as well as the objects themselves. The values that are retained are the last values that the objects contained before the transaction was aborted. Objects whose contents were available in the aborted transaction can be modified between the aborted transaction and the next transaction. If you modified any persistent objects during or after the aborted transaction, ObjectStore discards these modifications and makes these objects hollow at the start of the next transaction. During the next transaction, the contents of persistent objects that were not modified during or after the aborted transaction are still available.

  public abstract int getType()

Obtains the type of a transaction.

Returns:

ObjectStore.READONLY, ObjectStore.UPDATE, ObjectStore.READONLY_NON_BLOCKING, or ObjectStore.UPDATE_NON_BLOCKING.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the transaction has been terminated or if the current thread is associated with a session other than the session implied by the transaction.

  public static boolean hasLockContention()

Indicates whether or not a Server involved in the current transaction has experienced contention for some persistent objects that the application is using.

This function can be used in conjunction with MVCC to help determine whether or not to start a new transaction to make available more up-to-date data. If your application has a database open for MVCC, and during the current transaction another application has write-locked an object read by your application, hasLockContention() returns true.

This method is advisory; it does not have to be called and its return value can be ignored without jeopardizing the correctness of ObjectStore's behavior.

Returns:

True If there is lock contention, otherwise false. Always returns false in PSE and PSE Pro.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the transaction has been terminated or if the current thread is associated with a session other than the session implied by the transaction.

  public static int getPriority()

Gets the priority specified for transactions started by the current session.

Returns:

The transaction priority for the current session.

Throws: ObjectStoreException

If the current thread is not associated with a session and there is no global session.

See Also:

setPriority

  public static void setPriority(int priority)

Sets the priority for transactions started by the current session.

Every client has a transaction priority. The value is an integer that can range from 0 to 0xffff. The default value is 0x8000 (which is right in the middle). Note that the value 0 is special, as described below.

When two clients deadlock, the transaction priority is used as part of the decision as to which client should be the victim, that is, which one should be forced to abort, and possibly restart, its transaction.

When it makes this decision, the first thing the Server does is to compare the transaction priorities of all the participants. If they do not all have equal priority, the ones with the higher priority are not considered as deadlock victims. That is, it looks at the lowest priority number of all the participants, and any participant with a higher priority number is no longer considered as a possible victim.

If there is only one participant left, it is the victim. Otherwise, if there are several participants that all share the same lowest priority number, it chooses a victim in accordance with the Server parameter Deadlock Victim. See ObjectStore Management.

There is one important special case. If all the participants have priority zero, the Server will victimize all the participants! This is not a useful mode of operation for actually running a program, but it can be useful for debugging: you can run several clients under debuggers, have them all set their priorities to zero, and then when a deadlock happens, all of them abort, and you can see what each one of them was doing. You should never use a priority of zero unless you want this special debugging behavior.

Parameters:

priority - The transaction priority.

Throws: IllegalArgumentException

If the priority argument is negative or greater than 0xffff.

Throws: ObjectStoreException

If the current thread is not associated with a session and there is no global session.

  public abstract Session getSession()

Returns the session associated with this Transaction. Returns null if the session has been terminated.

Returns:

The session or null.

  public abstract boolean isAborted()

Returns true if the transaction has been aborted, otherwise false. Note that this entrypoint does not require the calling thread to belong to a session or for the session that started the transaction to be active.

  public abstract boolean isActive()

Returns true if the transaction has not been aborted or committed, otherwise false. Note that this entrypoint does not require the calling thread to belong to a session or for the session that started the transaction to be active.