Class COM.odi.Transaction

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

public class Transaction
extends Object

PSE/PSE Pro uses the Transaction class to represent a logical unit of work. A transaction is a consistent and reliable portion of the execution of a program. In your code, you place calls to the PSE/PSE Pro API to mark the beginning and end of transactions. Access to persistent data must always occur inside a transaction.

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.

If an application terminates at anytime other than during a Transaction.commit() operation, PSE/PSE Pro returns the database to the state it was in before the transaction started. If an application terminates during a call to Transaction.commit()

PSE is not able to recover the database.
PSE Pro is able to recover the database if the operating system succeeds in flushing the database to disk. This happens if the operating system does nott crash.
If PSE Pro is using the natives library it is always able to recover the database, even if the operating system crashes during a commit.

readOnly: Deprecated.
RETAIN_HOLLOW: Deprecated.
RETAIN_READONLY: Deprecated.
RETAIN_STALE: Deprecated.
RETAIN_UPDATE: Deprecated.
update: Deprecated.

abort(): Aborts a transaction.
abort(int): Aborts a transaction and retains objects that were referenced in the transaction.
begin(byte): Starts 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.
getType(): Obtains the type of a transaction.
inTransaction(): Determines whether or not there is a transaction in progress for the current thread.
setDefaultAbortRetain(int): Sets the default retain operation for the current session for calls to Transaction.abort() that have no argument.

readOnly

  public final static byte readOnly

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

update

  public final static byte update

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

RETAIN_STALE

  public final static int RETAIN_STALE

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

RETAIN_HOLLOW

  public final static int RETAIN_HOLLOW

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

RETAIN_READONLY

  public final static int RETAIN_READONLY

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

RETAIN_UPDATE

  public final static int RETAIN_UPDATE

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

begin

  public static Transaction begin(byte 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: TransactionInProgressException: If there is already a transaction in progress.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread.
Throws: IllegalArgumentException: If the transaction type is not ObjectStore.READONLY or ObjectStore.UPDATE.

current

  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 PSE/PSE Pro is not initialized for the current thread.

inTransaction

  public static boolean inTransaction()

Determines whether or not there is a transaction in progress for the current thread.

Returns:: The true constant if there is a transaction in progress for the current thread. The false constant if there is not.

commit

  public abstract void commit()

Commits a transaction. This ends the transaction. When PSE/PSE Pro 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: NoTransactionInProgressException: If a transaction is not in progress.
Throws: ObjectStoreException: If ObjectStore is not initialized for the current thread or if the transaction object is not associated with this thread.

commit

  public abstract void commit(int retainType)

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.

Decides the disposition of persistent objects for after the transaction is over depending on the value of the retain argument.

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 retains all persistent objects. References to objects from this transaction can be used in the next one.
ObjectStore.RETAIN_READONLY -- Retains the contents of persistent objects as well as the objects themselves. Objects whose contents were available in this transaction can be read between the end of this transaction and the next transaction, although attempting to modify a persistent object before the next transaction will throw an exception.
ObjectStore.RETAIN_UPDATE -- Retains the contents of persistent objects as well as the objects themselves. Objects whose contents were available in this transaction can be read or modified between the end of this transaction and the next transaction, although modifications to persistent objects will be discarded at the start of the next transaction.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If ObjectStore is not initialized for the current thread or if the transaction object is not associated with this thread.

Throws: IllegalArgumentException

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

abort

  public abstract void abort()

Aborts a transaction. abort() restores the persistent state to what it was when the transaction was started.

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

Throws: NoTransactionInProgressException: If a transaction is not in progress.
Throws: ObjectStoreException: If #PSE/PSE-Pro# is not initialized for the current thread or if the transaction object is not associated with the current session.

abort

  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. abort() restores the persistent state to what it was when the transaction was started.

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 (1) not been called or (2) 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 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, #PSE/PSE-Pro# throws NoTransactionInProgressException. If you modified any persistent objects during the aborted transaction, #PSE/PSE-Pro# 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 -- 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. 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, #PSE/PSE-Pro# 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: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If #PSE/PSE-Pro# is not initialized for the current thread or if the transaction object is not associated with the current session.

setDefaultAbortRetain

  public abstract void setDefaultAbortRetain(int newRetain)

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, #PSE/PSE-Pro# throws NoTransactionInProgressException. If you modified any persistent objects during the aborted transaction, #PSE/PSE-Pro# 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, #PSE/PSE-Pro# 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.

getType

  public abstract byte getType()

Obtains the type of a transaction.

Returns:: The ObjectStore.UPDATE constant if it is an update transaction. The ObjectStore.READONLY constant if it is a read-only transaction.
Throws: NoTransactionInProgressException: If a transaction is not in progress.
Throws: ObjectStoreException: If PSE/PSE Pro is not initialized for the current thread or if the transaction object is not associated with this thread.