org.datanucleus
Interface Transaction

All Known Implementing Classes:
JTAJCATransactionImpl, JTATransactionImpl, TransactionImpl

public interface Transaction

Representation of a transaction within JPOX. This interface is not user application visible. Handling of transactions in JPOX is split in 4 layers:

  • In the the API layer, there are interfaces provided to the user application, as such:
  • In the ObjectManager layer, the Transaction interface defines the contract for handling transactions for the ObjectManager. In the X/Open/JTA layer the handling of XA resources is done. It means, XAResources are obtained and enlisted to a TransactionManager. The TransactionManager will commit or rollback the resources at the end of the transactions. There are two kinds of TransactionManager: JPOX and JTA. A JTA TransactionManager is external to JPOX, while the JPOX TransactionManager is implemented by JPOX as org.datanucleus.transaction. The JPOX TransactionManager is used when the DataSource used to obtain connections to the underlying database is not enlisted in an external JTA TransactionManager. The JTA TransactionManager is usually found when running in J2EE application servers, however nowadays there are many JTA containers that can be used in J2SE. The scenarios where a JTA TransactionManager is used is: When an JTA TransactionManager exists, and the connections to the underlying databases are acquired via transactional DataSources. That means, when you ask a connection to the DataSource, it will automatically enlist it in a JTA TransactionManager. The Resource layer is handled by the datastore. For example, with RDBMS databases, the javax.sql.Connection is the API used to demarcate the database transactions. In The RBDMS database, the resource layer, it is handling the database transaction.

    Version:
    $Revision: 1.27 $

    Method Summary
     void addTransactionEventListener(TransactionEventListener listener)
               
     void begin()
              Begin a transaction.
     void commit()
              Commit the current transaction.
     void end()
              Method to allow the transaction to flush any resources.
     void flush()
              Method to allow the transaction to flush any resources.
     boolean getNontransactionalRead()
              If true, allows persistent instances to be read without a transaction active.
     boolean getNontransactionalWrite()
              If true, allows persistent instances to be written without a transaction active.
     boolean getOptimistic()
              Optimistic transactions do not hold data store locks until commit time.
     java.util.Map getOptions()
              Obtain all settings for this Transaction
     boolean getRestoreValues()
              Return the current value of the restoreValues property.
     boolean getRetainValues()
              If true, at commit time instances retain their field values.
     boolean getRollbackOnly()
              Returns the rollback-only status of the transaction.
     javax.transaction.Synchronization getSynchronization()
              The user-specified Synchronization instance for this Transaction instance.
     boolean isActive()
              Returns whether there is a transaction currently active.
     boolean isCommitting()
              Checks whether a transaction is committing.
     void removeTransactionEventListener(TransactionEventListener listener)
               
     void rollback()
              Rollback the current transaction.
     void setNontransactionalRead(boolean nontransactionalRead)
              If true, allow persistent instances to be read without a transaction active.
     void setNontransactionalWrite(boolean nontransactionalWrite)
              If true, allow persistent instances to be written without a transaction active.
     void setOptimistic(boolean optimistic)
              Optimistic transactions do not hold data store locks until commit time.
     void setOption(java.lang.String option, boolean value)
               
     void setOption(java.lang.String option, int value)
               
     void setOption(java.lang.String option, java.lang.String value)
               
     void setRestoreValues(boolean restoreValues)
              If true, at rollback, fields of newly persistent instances are restored to their values as of the beginning of the transaction, and the instances revert to transient.
     void setRetainValues(boolean retainValues)
              If true, at commit instances retain their values and the instances transition to persistent-nontransactional.
     void setRollbackOnly()
              Sets the rollback-only status of the transaction to true.
     void setSynchronization(javax.transaction.Synchronization sync)
              The user can specify a Synchronization instance to be notified on transaction completions.
     

    Method Detail

    begin

    void begin()
    Begin a transaction. The type of transaction (datastore/optimistic) is determined by the setting of the Optimistic flag.

    Throws:
    NucleusUserException - if transactions are managed by a container in the managed environment, or if the transaction is already active.

    commit

    void commit()
    Commit the current transaction. The commit will trigger flushing the transaction, will invoke the preCommit, commit the resources and invoke postCommit listeners. If during flush or preCommit phases a JPOXUserException is raised, then the transaction will not complete and the transaction remains active. The JPOXUserException is cascaded to the caller.

    Throws:
    NucleusUserException - if transactions are managed by a container in the managed environment, or if the transaction is not active.

    rollback

    void rollback()
    Rollback the current transaction. The commit will trigger flushing the transaction, will invoke the preRollback, rollback the resources and invoke postRollback listeners. If during flush or preRollback phases a JPOXUserException is raised, then the transaction will not complete and the transaction remains active. The JPOXUserException is cascaded to the caller.

    Throws:
    NucleusUserException - if transactions are managed by a container in the managed environment, or if the transaction is not active.

    isActive

    boolean isActive()
    Returns whether there is a transaction currently active.

    Returns:
    Whether the transaction is active.

    flush

    void flush()
    Method to allow the transaction to flush any resources.


    end

    void end()
    Method to allow the transaction to flush any resources.


    getRollbackOnly

    boolean getRollbackOnly()
    Returns the rollback-only status of the transaction. When begun, the rollback-only status is false. Either the application or the JDO implementation may set this flag using setRollbackOnly.

    Returns:
    Whether the transaction has been marked for rollback.

    setRollbackOnly

    void setRollbackOnly()
    Sets the rollback-only status of the transaction to true. After this flag is set to true, the transaction can no longer be committed.

    Throws:
    NucleusUserException - if the flag is true and an attempt is made to commit the txn

    setNontransactionalRead

    void setNontransactionalRead(boolean nontransactionalRead)
    If true, allow persistent instances to be read without a transaction active. If an implementation does not support this option, a

    Parameters:
    nontransactionalRead - Whether to have non-tx reads
    Throws:
    NucleusUserException - if not supported (supported by JPOX)

    getNontransactionalRead

    boolean getNontransactionalRead()
    If true, allows persistent instances to be read without a transaction active.

    Returns:
    Whether we are allowing non-tx reads

    setNontransactionalWrite

    void setNontransactionalWrite(boolean nontransactionalWrite)
    If true, allow persistent instances to be written without a transaction active.

    Parameters:
    nontransactionalWrite - Whether requiring non-tx writes
    Throws:
    NucleusUserException - if not supported (JPOX doesnt support it!)

    getNontransactionalWrite

    boolean getNontransactionalWrite()
    If true, allows persistent instances to be written without a transaction active.

    Returns:
    Whether we are allowing non-tx writes

    setRetainValues

    void setRetainValues(boolean retainValues)
    If true, at commit instances retain their values and the instances transition to persistent-nontransactional.

    Parameters:
    retainValues - the value of the retainValues property
    Throws:
    NucleusUserException - if not supported (JPOX supports it)

    getRetainValues

    boolean getRetainValues()
    If true, at commit time instances retain their field values.

    Returns:
    the value of the retainValues property

    setRestoreValues

    void setRestoreValues(boolean restoreValues)
    If true, at rollback, fields of newly persistent instances are restored to their values as of the beginning of the transaction, and the instances revert to transient. Additionally, fields of modified instances of primitive types and immutable reference types are restored to their values as of the beginning of the transaction.

    If false, at rollback, the values of fields of newly persistent instances are unchanged and the instances revert to transient. Additionally, dirty instances transition to hollow.

    Parameters:
    restoreValues - the value of the restoreValues property
    Throws:
    NucleusUserException - if not supported (JPOX supports it)

    getRestoreValues

    boolean getRestoreValues()
    Return the current value of the restoreValues property.

    Returns:
    the value of the restoreValues property

    setOptimistic

    void setOptimistic(boolean optimistic)
    Optimistic transactions do not hold data store locks until commit time.

    Parameters:
    optimistic - the value of the Optimistic flag.
    Throws:
    NucleusUserException - if not supported (JPOX supports it)

    getOptimistic

    boolean getOptimistic()
    Optimistic transactions do not hold data store locks until commit time.

    Returns:
    the value of the Optimistic property.

    setSynchronization

    void setSynchronization(javax.transaction.Synchronization sync)
    The user can specify a Synchronization instance to be notified on transaction completions. The beforeCompletion method is called prior to flushing instances to the data store.

    The afterCompletion method is called after performing state transitions of persistent and transactional instances, following the data store commit or rollback operation.

    Only one Synchronization instance can be registered with the Transaction. If the application requires more than one instance to receive synchronization callbacks, then the single application instance is responsible for managing them, and forwarding callbacks to them.

    Parameters:
    sync - the Synchronization instance to be notified; null for none

    getSynchronization

    javax.transaction.Synchronization getSynchronization()
    The user-specified Synchronization instance for this Transaction instance.

    Returns:
    the user-specified Synchronization instance.

    isCommitting

    boolean isCommitting()
    Checks whether a transaction is committing.

    Returns:
    Whether the transaction is committing

    addTransactionEventListener

    void addTransactionEventListener(TransactionEventListener listener)

    removeTransactionEventListener

    void removeTransactionEventListener(TransactionEventListener listener)

    getOptions

    java.util.Map getOptions()
    Obtain all settings for this Transaction

    Returns:
    a map with settings

    setOption

    void setOption(java.lang.String option,
                   int value)

    setOption

    void setOption(java.lang.String option,
                   boolean value)

    setOption

    void setOption(java.lang.String option,
                   java.lang.String value)


    Copyright © 2009. All Rights Reserved.