JDO2 also provides a mechanism whereby all objects that were enlisted in a transaction are automatically detached when the transaction is committed. You can enable this in one of 3 ways. If you want to use this mode globally for all PersistenceManager s (PMs) from a PersistenceManagerFactory (PMF) you could either set the PMF property "datanucleus.DetachAllOnCommit", or you could create your PMF and call the PMF method setDetachAllOnCommit(true) . If instead you wanted to use this mode only for a particular PM, or only for a particular transaction for a particular PM, then you can call the PM method setDetachAllOnCommit(true) before the commit of the transaction, and it will apply for all transaction commits thereafter, until turned off ( setDetachAllOnCommit(false) . Here's an example

// Create a PMF
...

// Create an object
MyObject my = new MyObject();

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

    // We want our object to be detached when it's been persisted
    pm.setDetachAllOnCommit(true);

    // Persist the object that we created earlier
    pm.makePersistent(my);

    tx.commit();
    // The object "my" is now in detached state and can be used further
}
finally
{
    if (tx.isActive)
    {
        tx.rollback();
    }
}

By default when you are attaching a detached object it will return an attached copy of the detached object. JDO2.1 provides a new feature that allows this attachment to just migrate the existing detached object into attached state.

You enable this by setting the PersistenceManagerFactory (PMF) property datanucleus.CopyOnAttach to false. Alternatively you can use the methods PersistenceManagerFactory.setCopyOnAttach(boolean flag) or PersistenceManager.setCopyOnAttach(boolean flag) . If we return to the example at the start of this page, this now becomes

// Reattach the updated object
pm.setCopyOnAttach(false);
tx = pm.currentTransaction();
try
{
    tx.begin();

    // working product is currently in detached state

    pm.makePersistent(working_product);
    // working_product is now in persistent (attached) state

    tx.commit();
}
catch (Exception e)
{
    // Handle the exception
}
finally
{
    if (tx.isActive())
    {
        tx.rollback();
    }
}

Please note that if you try to attach two detached objects representing the same underlying persistent object within the same transaction (i.e a persistent object with the same identity already exists in the level 1 cache), then a JDOUserException will be thrown.

A backup to the above programmatic detachment of instances is that when you close your PersistenceManager you can opt to have all instances currently cached in the Level 1 Cache of that PersistenceManager detached automatically. This means that you can persist instances, and then when you close the PM the instances will be detached and ready for further work. This is a DataNucleus extension. It is recommended that you use "detachAllOnCommit" since that is standard JDO and since this option will not work in J2EE environments where the PersistenceManager close is controlled by the J2EE container

You enable this by setting the PersistenceManagerFactory (PMF) property datanucleus.DetachOnClose when you create the PMF. Let's give an example

// Create a PMF with the datanucleus.DetachOnClose property set to "true"
...

// Create an object
MyObject my = new MyObject();

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

    // Persist the object that we created earlier
    pm.makePersistent(my);

    tx.commit();

    pm.close();
    // The object "my" is now in detached state and can be used further
}
finally
{
    if (tx.isActive)
    {
        tx.rollback();
    }
}

That is about as close to transparent persistence as you will find. When the PM is closed all instances found in the L1 Cache are detached using the current FetchPlan, and so all fields in that plan for the instances in question will be detached at that time.

When an object is detached it is typically passed to a different layer of an application and potentially changed. During the course of the operation of the system it may be required to know what is loaded in the object and what is dirty (has been changed since detaching). DataNucleus provides an extension to allow interrogation of the detached object.

String[] loadedFieldNames = NucleusJDOHelper.getDetachedObjectLoadedFields(obj, pm);
String[] dirtyFieldNames = NucleusJDOHelper.getDetachedObjectDirtyFields(obj, pm);

So you have access to the names of the fields that were loaded when detaching the object, and also to the names of the fields that have been updated since detaching.

During enhancement of Detachable classes, a field called jdoDetachedState is added to the class definition. This field allows reading and changing tracking of detached objects while they are not managed by a PersistenceManager.

When serialization occurs on a Detachable object, the jdoDetachedState field is written to the serialized object stream. On deserialize, this field is written back to the new deserialized instance. This process occurs transparently to the application. However, if deserialization occurs with an un-enhanced version of the class, the detached state is lost.

Serialization and deserialization of Detachable classes and un-enhanced versions of the same class is only possible if the field serialVersionUID is added. It's recommended during development of the class, to define the serialVersionUID and make the class to implement the java.io.Serializable interface, as the following example:

class MyClass implements java.io.Serializable
{
    private static final long serialVersionUID = 2765740961462495537L; // any random value here
    
    //.... other fields
}