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

  • Field Details

    • TRANSACTION_ISOLATION_OPTION

      static final String TRANSACTION_ISOLATION_OPTION
      Option to use when wanting to set the transaction isolation level.
      See Also:
  • Method Details

    • 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(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

      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)