In JPA, objects detach automatically when they are serialized or when a persistence context ends. The specification does not define any way to explicitly detach objects. The extended OpenJPAEntityManager, however, allows you to explicitly detach objects at any time.

public Object detach(Object pc):
public Object[] detachAll(Object... pcs):
public Collection detachAll(Collection pcs):

Each detach method returns detached copies of the given instances. The copy mechanism is similar to serialization, except that only certain fields are traversed. We will see how to control which fields are detached in a later section.

When detaching an instance that has been modified in the current transaction (and thus made dirty), the current transaction is flushed. This means that when subsequently re-attaching the detached instances, OpenJPA assumes that the transaction from which they were originally detached was committed; if it has been rolled back, then the re-attachment process will throw an optimistic concurrency exception.

You can stop OpenJPA from assuming the transaction will commit by invoking OpenJPAEntityManager.setRollbackOnly prior to detaching your objects. Setting the RollbackOnly flag prevents OpenJPA from flushing when detaching dirty objects; instead OpenJPA just runs its pre-flush actions (see the OpenJPAEntityManager.preFlush Javadoc for details).

This allows you to use the same instances in multiple attach/modify/detach/rollback cycles. Alternatively, you might also prevent a flush by making your modifications outside of a transaction (with NontransactionalWrite enabled) before detaching.

When attaching, OpenJPA uses several strategies to determine the optimal way to merge changes made to the detached instance. As you will see, these strategies can even be used to attach changes made to a transient instance which was never detached in the first place.

These strategies will be assigned on a per-instance basis, such that during the attachment of an object graph more than one of the above strategies may be used.

If you attempt to attach a versioned instance whose representation has changed in the datastore since detachment, OpenJPA will throw an optimistic concurrency exception upon commit or flush, just as if a normal optimistic conflict was detected. When attaching an instance whose database record has been deleted since detaching, or when attaching a detached instance into a manager that has a stale version of the object, OpenJPA will throw an optimistic concurrency exception from the attach method. In these cases, OpenJPA sets the RollbackOnly flag on the transaction.

When detached objects lose their association with the OpenJPA runtime, they also lose the ability to load additional state from the datastore. It is important, therefore, to populate objects with all the persistent state you will need before detaching them. While you are free to do this manually, OpenJPA includes facilities for automatically populating objects when they detach. The openjpa.DetachState configuration property determines which fields and relations are detached by default. All settings are recursive. They are:

Any field that is not included in the set determined by the detach mode is set to its Java default value in the detached instance.

The openjpa.DetachState option is actually a plugin string (see Section 4, “ Plugin Configuration ”) that allows you to also configure the following options related to detached state:

<property name="openjpa.DetachState" value="fetch-groups(DetachedStateField=true)"/>

You can also alter the set of fields that will be included in the detached graph at runtime. OpenJPAEntityManagers expose the following APIs for controlling detached state:

public static final int DETACH_LOADED;
public static final int DETACH_FETCH_GROUPS;
public static final int DETACH_ALL;
public int getDetachState();
public void setDetachState(int mode);

import org.apache.openjpa.persistence.*;

@Entity
public class Magazine
    implements Serializable {

    private String name;
    @DetachedState private Object state;
    ...
}