Locally-Managed Transactions

When using a JDO implementation such as DataNucleus in a J2SE environment, the transactions are by default Locally Managed Transactions. The users code will manage the transactions by starting, and commiting the transaction itself. With these transactions with JDO you would do something like

PersistenceManager pm = pmf.getPersistenceManager();
Transaction tx = pm.currentTransaction();
try
{
    tx.begin();
    
    {users code to persist objects}
    
    tx.commit();
}
finally
{
    if (tx.isActive())
    {
        tx.rollback();
    }
}
pm.close();

The basic idea with Locally-Managed transactions is that you are managing the transaction start and end.

JTA Transactions

When using a JDO implementation such as DataNucleus in a J2SE environment, you can also make use of JTA Transactions. You define the persistence property javax.jdo.option.TransactionType setting it to "JTA". Then you make use of JTA (or JDO) to demarcate the transactions. So you could do something like

UserTransaction ut = (UserTransaction)
    new InitialContext().lookup("java:comp/UserTransaction");
PersistenceManager pm = pmf.getPersistenceManager();
try
{
    ut.begin();
    
    {users code to persist objects}
    
    ut.commit();
}
finally
{
    pm.close();
}

So here we used the JTA API to begin/commit the controlling (javax.transaction.UserTransaction).

An alternative is where you don't have a UserTransaction started and just use the JDO API, which will start the UserTransaction for you.

UserTransaction ut = (UserTransaction)
    new InitialContext().lookup("java:comp/UserTransaction");
PersistenceManager pm = pmf.getPersistenceManager();
Transaction tx = pm.currentTransaction();
try
{
    tx.begin(); // Starts the UserTransaction
    
    {users code to persist objects}
    
    tx.commit(); // Commits the UserTransaction
}
finally
{
    pm.close();
}

Important : please note that you need to set both transactional and nontransactional datasources, and the nontransactional cannot be JTA.

Container-Managed Transactions

When using a JEE container you are giving over control of the transactions to the container. Here you have Container-Managed Transactions. In terms of your code, you would do like the previous example except that you would OMIT the tx.begin(), tx.commit(), tx.rollback() since the JEE container will be doing this for you.

Spring-Managed Transactions

When you use a framework like Spring you would not need to specify the tx.begin(), tx.commit(), tx.rollback() since that would be done for you.

No Transactions

DataNucleus allows the ability to operate without transactions. With JDO this is enabled by default (see the 2 properties datanucleus.NontransactionalRead, datanucleus.NontransactionalWrite set to true). This means that you can read objects and make updates outside of transactions. This is effectively "auto-commit" mode.

PersistenceManager pm = pmf.getPersistenceManager();
    
{users code to persist objects}

pm.close();

When using non-transactional operations, you need to pay attention to the persistence property datanucleus.nontx.atomic. If this is true then any persist/delete/update will be committed to the datastore immediately. If this is false then any persist/delete/update will be queued up until the next transaction (or pm.close()) and committed with that.

Flushing

During a transaction, depending on the configuration, operations don't necessarily go to the datastore immediately, often waiting until commit. In some situations you need persists/updates/deletes to be in the datastore so that subsequent operations can be performed that rely on those being handled first. In this case you can flush all outstanding changes to the datastore using

pm.flush();

A convenient vendor extension is to find which objects are waiting to be flushed at any time, like this

List<ObjectProvider> objs = 
    ((JDOPersistenceManager)pm).getExecutionContext().getObjectsToBeFlushed();

Transaction Isolation

JDO provides a mechanism for specification of the transaction isolation level. This can be specified globally via the PersistenceManagerFactory property datanucleus.transactionIsolation (javax.jdo.option.TransactionIsolationLevel). It accepts the following values

• read-uncommitted : dirty reads, non-repeatable reads and phantom reads can occur
• read-committed : dirty reads are prevented; non-repeatable reads and phantom reads can occur
• repeatable-read : dirty reads and non-repeatable reads are prevented; phantom reads can occur
• serializable : dirty reads, non-repeatable reads and phantom reads are prevented

The default (in DataNucleus) is read-committed. An attempt to set the isolation level to an unsupported value (for the datastore) will throw a JDOUserException. As an alternative you can also specify it on a per-transaction basis as follows (using the names above).

Transaction tx = pm.currentTransaction();
...
tx.setIsolationLevel("read-committed");

JDO Transaction Synchronisation

There are situations where you may want to get notified that a transaction is in course of being committed or rolling back. To make that happen, you would do something like

PersistenceManager pm = pmf.getPersistenceManager();
Transaction tx = pm.currentTransaction();
try
{
    tx.begin();

    tx.setSynchronization(new javax.transaction.Synchronization()
    {
        public void beforeCompletion()
        {
             // before commit or rollback
        }

        public void afterCompletion(int status)
        {
            if (status == javax.transaction.Status.STATUS_ROLLEDBACK)
            {
                // rollback
            }
            else if (status == javax.transaction.Status.STATUS_COMMITTED)
            {
                // commit
            }
        }
    });
    
    tx.commit();
}
finally
{
    if (tx.isActive())
    {
        tx.rollback();
    }
}
pm.close();

Read-Only Transactions

Obviously transactions are intended for committing changes. If you come across a situation where you don't want to commit anything under any circumstances you can mark the transaction as "read-only" by calling

PersistenceManager pm = pmf.getPersistenceManager();
Transaction tx = pm.currentTransaction();
try
{
    tx.begin();
    tx.setRollbackOnly();

    {users code to persist objects}
    
    tx.rollback();
}
finally
{
    if (tx.isActive())
    {
        tx.rollback();
    }
}
pm.close();

Any call to commit on the transaction will throw an exception forcing the user to roll it back.

Pessimistic (Datastore) Locking

Pessimistic locking is the default in JDO. It is suitable for short lived operations where no user interaction is taking place and so it is possible to block access to datastore entities for the duration of the transaction.

By default DataNucleus does not currently lock the objects fetched with pessimistic locking, but you can configure this behaviour for RDBMS datastores by setting the persistence property datanucleus.SerializeRead to true. This will result in all "SELECT ... FROM ..." statements being changed to be "SELECT ... FROM ... FOR UPDATE". This will be applied only where the underlying RDBMS supports the "FOR UPDATE" syntax. This can be done on a transaction-by-transaction basis by doing

Transaction tx = pm.currentTransaction();
tx.setSerializeRead(true);

Alternatively, on a per query basis, you would do

Query q = pm.newQuery(...);
q.setSerializeRead(true);

With pessimistic locking DataNucleus will grab a datastore connection at the first operation, and maintain it for the duration of the transaction. A single connection is used for the transaction (with the exception of any Identity Generation operations which need datastore access, so these can use their own connection).

In terms of the process of pessimistic (datastore) locking, we demonstrate this below.

So here whenever an operation is performed, DataNucleus pushes it straight to the datastore. Consequently any queries will always reflect the current state of all objects in use. However this mode of operation has no version checking of objects and so if they were updated by external processes in the meantime then they will overwrite those changes.

It should be noted that DataNucleus provides two persistence properties that allow an amount of control over when flushing happens with datastore transactions.

• datanucleus.flush.mode when set to MANUAL will try to delay all datastore operations until commit/flush.
• datanucleus.datastoreTransactionFlushLimit represents the number of dirty objects before a flush is performed. This defaults to 1.

Optimistic Locking

Optimistic locking is the other option in JDO. It is suitable for longer lived operations maybe where user interaction is taking place and where it would be undesirable to block access to datastore entities for the duration of the transaction. The assumption is that data altered in this transaction will not be updated by other transactions during the duration of this transaction, so the changes are not propagated to the datastore until commit()/flush(). The data is checked just before commit to ensure the integrity in this respect. The most convenient way of checking data for updates is to maintain a column on each table that handles optimistic locking data. The user will decide this when generating their MetaData.

Rather than placing version/timestamp columns on all user datastore tables, JDO2 allows the user to notate particular classes as requiring optimistic treatment. This is performed by specifying in MetaData or annotations the details of the field/column to use for storing the version - see versioning for JDO. With JDO the version is added in a surrogate column, whereas a vendor extension allows you to have a field in your class ready to store the version.

In JDO2 the version is stored in a surrogate column in the datastore so it also provides a method for accessing the version of an object. You can call JDOHelper.getVersion(object) and this returns the version as an Object (typically Long or Timestamp). This will return null for a transient object, and will return the version for a persistent object. If the object is not persistable then it will also return null.

In terms of the process of optimistic locking, we demonstrate this below.

Here no changes make it to the datastore until the user either commits the transaction, or they invoke flush(). The impact of this is that when performing a query, by default, the results may not contain the modified objects unless they are flushed to the datastore before invoking the query. Depending on whether you need the modified objects to be reflected in the results of the query governs what you do about that. If you invoke flush() just before running the query the query results will include the changes. The obvious benefit of optimistic locking is that all changes are made in a block and version checking of objects is performed before application of changes, hence this mode copes better with external processes updating the objects.

Please note that for some datastores (e.g RDBMS) the version check followed by update/delete is performed in a single statement.

See also :-

• JDO MetaData reference for <version> element
• JDO Annotations reference for @Version

Persistence-by-Reachability at commit()

When a transaction is committed JDO will, by default, run its reachability algorithm to check if any reachable objects have been persisted and are no longer reachable. If an object is found to be no longer reachable and was only persisted by being reachable (not by an explicit persist operation) then it will be removed from the datastore. You can turn off this reachability check for JDO by setting the persistence property datanucleus.persistenceByReachabilityAtCommit to false.