Package org.datanucleus.transaction

Interface Transaction

  • All Known Implementing Classes:
    JTAJCATransactionImpl, JTATransactionImpl, TransactionImpl
    public interface Transaction
    Representation of an ExecutionContext transaction within DataNucleus. Handling of transactions in DataNucleus is split into 4 layers:
    • API - The User Visible Transaction API
    • ExecutionContext Transaction - The Transaction assigned to an ExecutionContext
    • X/Open/JTA - The ResourcedTransactionManager managing ResourcedTransaction associated to the underlying datastore transaction
    • Resource - The Transaction handled by the datastore
    In the the API layer, there are interfaces provided to the user application, as such:
    • JDO Transaction - the JDO API interface
    • JPA EntityTransaction - the JPA API interface
    • UserTransaction - the JTA API interface
    In the ExecutionContext layer, the Transaction interface defines the contract for handling transactions for the ExecutionContext.

    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: DataNucleus and JTA. A JTA TransactionManager is external to DataNucleus, while the DataNucleus TransactionManager is implemented by DataNucleus as org.datanucleus.transaction. The DataNucleus 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 JavaEE application servers, however nowadays there are many JTA containers that can be used in JavaSE.

    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 an RDBMS database, the resource layer is handling the database transaction. For a treatment of isolation levels, refer to http://www.cs.umb.edu/~poneil/iso.pdf

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addTransactionEventListener​(TransactionEventListener listener)
      Adds a transaction listener.
      void begin()
      Begin a transaction.
      void bindTransactionEventListener​(TransactionEventListener listener)
      Listeners that are never cleared, and invoked for all transactions
      void close()
      Method to inform the transaction that it is closed.
      void commit()
      Commit the current transaction.
      void end()
      Method to notify that the transaction is ended.
      void flush()
      Method to allow the transaction to flush any resources.
      long getBeginTime()
      Accessor for the time (millisecs) from System.currentTimeMillis when the transaction started.
      boolean getIsActive()
      Return whether the transaction is active and return immediately.
      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 getNontransactionalWriteAutoCommit()
      Whether to auto-commit any non-tx writes.
      boolean getOptimistic()
      Optimistic transactions do not hold data store locks until commit time.
      Map<String,​Object> 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.
      Boolean getSerializeRead()
      Accessor for the setting for whether to serialize read objects (lock them).
      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 preFlush()
      Method to notify that flush is started.
      void releaseSavepoint​(String name)
      Method to deregister the current position as a savepoint with the provided name (assuming the datastore supports it).
      void removeTransactionEventListener​(TransactionEventListener listener)
      Removes the specified listener.
      void rollback()
      Rollback the current transaction.
      void rollbackToSavepoint​(String name)
      Method to rollback the transaction to the specified savepoint (assuming the datastore supports it).
      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 setNontransactionalWriteAutoCommit​(boolean autoCommit)
      Set whether to auto-commit any non-tx writes.
      void setOptimistic​(boolean optimistic)
      Optimistic transactions do not hold data store locks until commit time.
      void setOption​(String option, boolean value)  
      void setOption​(String option, int value)  
      void setOption​(String option, Object value)  
      void setOption​(String option, 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 setSavepoint​(String name)
      Method to register the current position as a savepoint with the provided name (assuming the datastore supports it).
      void setSerializeRead​(Boolean serializeRead)
      Mutator for whether to serialize (lock) any read objects in this transaction.
      void setSynchronization​(javax.transaction.Synchronization sync)
      The user can specify a Synchronization instance to be notified on transaction completions.

    • Field Detail

      • TRANSACTION_ISOLATION_OPTION

        static final String TRANSACTION_ISOLATION_OPTION
        Option to use when wanting to set the transaction isolation level.
        See Also:
        Constant Field Values

    • Method Detail

      • close

        void close()
        Method to inform the transaction that it is closed. This is only necessary for JBoss usage of JPA where it doesn't bother calling afterCompletion on the JTA txn until after it closes the EntityManager so we need a hook to inform the transaction that it is closed so ignore any subsequent afterCompletion.

      • 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 NucleusUserException is raised, then the transaction will not complete and the transaction remains active. The NucleusUserException 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 NucleusUserException is raised, then the transaction will not complete and the transaction remains active. The NucleusUserException 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. This can also attempt to join to any underlying transaction if the implementation requires it. Use 
        getIsActive
        if you just want the active flag.
        Returns:
        Whether the transaction is active.

      • getIsActive

        boolean getIsActive()
        Return whether the transaction is active and return immediately.
        Returns:
        Whether it is active

      • getBeginTime

        long getBeginTime()
        Accessor for the time (millisecs) from System.currentTimeMillis when the transaction started.
        Returns:
        Time at which the transaction started. -1 implies not yet started.

      • preFlush

        void preFlush()
        Method to notify that flush is started.

      • flush

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

      • end

        void end()
        Method to notify that the transaction is ended.

      • 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 NucleusUserException is thrown.
        Parameters:
        nontransactionalRead - Whether to have non-tx reads
        Throws:
        NucleusUserException - if not supported

      • 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

      • getNontransactionalWrite

        boolean getNontransactionalWrite()
        If true, allows persistent instances to be written without a transaction active.
        Returns:
        Whether we are allowing non-tx writes

      • setNontransactionalWriteAutoCommit

        void setNontransactionalWriteAutoCommit​(boolean autoCommit)
        Set whether to auto-commit any non-tx writes.
        Parameters:
        autoCommit - Whether to auto-commit any non-tx writes
        Throws:
        NucleusUserException - if not supported

      • getNontransactionalWriteAutoCommit

        boolean getNontransactionalWriteAutoCommit()
        Whether to auto-commit any non-tx writes.
        Returns:
        Whether to auto-commit any 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

      • 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

      • 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

      • getOptimistic

        boolean getOptimistic()
        Optimistic transactions do not hold data store locks until commit time.
        Returns:
        the value of the Optimistic property.

      • setSerializeRead

        void setSerializeRead​(Boolean serializeRead)
        Mutator for whether to serialize (lock) any read objects in this transaction.
        Parameters:
        serializeRead - Whether to serialise (lock) any read objects

      • getSerializeRead

        Boolean getSerializeRead()
        Accessor for the setting for whether to serialize read objects (lock them).
        Returns:
        the value of the serializeRead 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

      • setSavepoint

        void setSavepoint​(String name)
        Method to register the current position as a savepoint with the provided name (assuming the datastore supports it).
        Parameters:
        name - Savepoint name

      • releaseSavepoint

        void releaseSavepoint​(String name)
        Method to deregister the current position as a savepoint with the provided name (assuming the datastore supports it).
        Parameters:
        name - Savepoint name

      • rollbackToSavepoint

        void rollbackToSavepoint​(String name)
        Method to rollback the transaction to the specified savepoint (assuming the datastore supports it).
        Parameters:
        name - Savepoint name

      • addTransactionEventListener

        void addTransactionEventListener​(TransactionEventListener listener)
        Adds a transaction listener. After commit or rollback, listeners are cleared
        Parameters:
        listener - The listener to add

      • removeTransactionEventListener

        void removeTransactionEventListener​(TransactionEventListener listener)
        Removes the specified listener.
        Parameters:
        listener - Listener to remove

      • bindTransactionEventListener

        void bindTransactionEventListener​(TransactionEventListener listener)
        Listeners that are never cleared, and invoked for all transactions
        Parameters:
        listener - listener to bind

      • getOptions

        Map<String,​Object> getOptions()
        Obtain all settings for this Transaction
        Returns:
        a map with settings

      • setOption

        void setOption​(String option,
               int value)

      • setOption

        void setOption​(String option,
               boolean value)

      • setOption

        void setOption​(String option,
               String value)

      • setOption

        void setOption​(String option,
               Object value)