Transaction (Neo4j Community 2.1.0-M01 API)
Date: 2014-02-20

org.neo4j.graphdb

## Interface Transaction

- All Superinterfaces:
    AutoCloseable

      public interface Transaction
      extends AutoCloseable

  A programmatically handled transaction.

  All database operations that access the graph, indexes, or the schema must be performed in a transaction.

  If you attempt to access the graph outside of a transaction, those operations will throw `NotInTransactionException`.

  Transactions are bound to the thread in which they were created. Transactions can either be handled programmatically, through this interface, or by a container through the Java Transaction API (JTA). The Transaction interface makes handling programmatic transactions easier than using JTA programmatically. Here's the idiomatic use of programmatic transactions in Neo4j starting from java 7:

       try ( Transaction tx = graphDb.beginTx() )
       {
           // operations on the graph
           // ...

           tx.success();
       }

  Let's walk through this example line by line. First we retrieve a Transaction object by invoking the `GraphDatabaseService.beginTx()` factory method. This creates a new transaction which has internal state to keep track of whether the current transaction is successful. Then we wrap all operations that modify the graph in a try-finally block with the transaction as resource. At the end of the block, we invoke the `tx.success()` method to indicate that the transaction is successful. As we exit the block, the transaction will automatically be closed where `tx.close()` will be called and commit the transaction if the internal state indicates success or else mark it for rollback.

  If an exception is raised in the try-block, `success()` will never be invoked and the internal state of the transaction object will cause `close()` to roll back the transaction. This is very important: unless `success()` is invoked, the transaction will fail upon `close()`. A transaction can be explicitly marked for rollback by invoking the `failure()` method.

  Read operations inside of a transaction will also read uncommitted data from the same transaction.

  Here's the idiomatic use of programmatic transactions in Neo4j on java 6 or earlier:

       Transaction tx = graphDb.beginTx();
       try
       {
           // operations on the graph
           // ...

           tx.success();
       }
       finally
       {
           tx.close();
       }

  All `ResourceIterables` that where returned from operations executed inside a transaction will be automatically closed when the transaction is committed or rolled back. Note however, that the `ResourceIterator` should be `closed` as soon as possible if you don't intend to exhaust the iterator.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Lock` | `acquireReadLock(PropertyContainer entity)` Acquires a read lock for `entity` for this transaction.
    `Lock` | `acquireWriteLock(PropertyContainer entity)` Acquires a write lock for `entity` for this transaction.
    `void` | `close()` Commits or marks this transaction for rollback, depending on whether `success()` or `failure()` has been previously invoked.
    `void` | `failure()` Marks this transaction as failed, which means that it will unconditionally be rolled back when `close()` is called.
    `void` | `finish()` Deprecated. due to implementing `AutoCloseable`, where `close()` is called automatically when used in try-with-resource statements.
    `void` | `success()` Marks this transaction as successful, which means that it will be committed upon invocation of `close()` unless `failure()` has or will be invoked before then.

- - ### Method Detail

    - #### failure

          void failure()

      Marks this transaction as failed, which means that it will unconditionally be rolled back when `close()` is called. Once this method has been invoked, it doesn't matter if `success()` is invoked afterwards -- the transaction will still be rolled back.

    - #### success

          void success()

      Marks this transaction as successful, which means that it will be committed upon invocation of `close()` unless `failure()` has or will be invoked before then.

    - #### finish

          @Deprecated
          void finish()

      Deprecated. due to implementing `AutoCloseable`, where `close()` is called automatically when used in try-with-resource statements.
      Commits or marks this transaction for rollback, depending on whether `success()` or `failure()` has been previously invoked. All `ResourceIterables` that where returned from operations executed inside this transaction will be automatically closed by this method. Preferably this method will not be used, instead a `Transaction` should participate in a try-with-resource statement so that `close()` is automatically called instead. Invoking `close()` (which is unnecessary when in try-with-resource statement) or this method has the exact same effect.

    - #### close

          void close()

      Commits or marks this transaction for rollback, depending on whether `success()` or `failure()` has been previously invoked. All `ResourceIterables` that where returned from operations executed inside this transaction will be automatically closed by this method. This method comes from `AutoCloseable` so that a `Transaction` can participate in try-with-resource statements. It will not throw any declared exception. Invoking this method (which is unnecessary when in try-with-resource statement) or `finish()` has the exact same effect.
      Specified by:
        `close` in interface `AutoCloseable`

    - #### acquireWriteLock

          Lock acquireWriteLock(PropertyContainer entity)

      Acquires a write lock for `entity` for this transaction. The lock (returned from this method) can be released manually, but if not it's released automatically when the transaction finishes.
      Parameters:
        `entity` - the entity to acquire a lock for. If another transaction currently holds a write lock to that entity this call will wait until it's released.
      Returns:
        a `Lock` which optionally can be used to release this lock earlier than when the transaction finishes. If not released (with `Lock.release()` it's going to be released with the transaction finishes.

    - #### acquireReadLock

          Lock acquireReadLock(PropertyContainer entity)

      Acquires a read lock for `entity` for this transaction. The lock (returned from this method) can be released manually, but if not it's released automatically when the transaction finishes.
      Parameters:
        `entity` - the entity to acquire a lock for. If another transaction currently hold a write lock to that entity this call will wait until it's released.
      Returns:
        a `Lock` which optionally can be used to release this lock earlier than when the transaction finishes. If not released (with `Lock.release()` it's going to be released with the transaction finishes.

Copyright © 2002–2014 The Neo4j Graph Database Project. All rights reserved.