When a class is detachable, the Kodo enhancer adds an additional field to the enhanced version of the class. This field of type Object. Kodo uses this field for bookkeeping information, such as the versioning data needed to detect optimistic concurrency violations when the object is re-attached.

It is possible to define this detached state field yourself. Declaring this field in your class metadata prevents the enhancer from adding any extra fields to the class, and keeps the enhanced class serialization-compatible with the unenhanced version (in case the client tier only has the unenhanced class definition to work with). The detached state field must not be persistent. See Section 6.4.1.3, “Detached State” for details on how to declare a detached state field.

EJB persistence:

import kodo.persistence.*;

@Entity
public class Magazine
    implements Serializable
{
    private String name;
    @DetachedState private Object state;
    ...
}

JDO:

public class Magazine
    implements Serializable
{
    private String name;
    private Object detachedState;
    ...
}


<?xml version="1.0"?>
<jdo>
  <package name="org.mag">
    <class name="Magazine" detachable="true">
      <extension vendor-name="kodo" key="detached-state-field"
        value="detachedState"/>
    </class>
  </package>
</jdo>

In EJB persistence, 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 KodoEntityManager, 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, Kodo 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 Kodo from assuming the transaction will commit by invoking setRollbackOnly prior to detaching your objects. Setting the RollbackOnly flag prevents Kodo from flushing when detaching dirty objects; instead Kodo just runs its pre-flush actions (see the KodoEntityManager.preFlush or KodoPersistenceManager.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.

inspecting instances about to be attached, Kodo uses several strategies to determine the optimal way to merge the changes made to the remote 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 an instance whose representation has changed in the datastore since detachment, Kodo 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, Kodo will throw an optimistic concurrency exception from the attach method. In these cases, Kodo sets the RollbackOnly flag on the transaction.

When detached objects lose their association with the Kodo 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, Kodo includes facilities for automatically populating objects when they detach. Kodo supports three modes for determining which fields and relations of an object get populated. All of the modes are recursive.

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.

KodoEntityManagers and KodoPersistenceManagers expose the following APIs for controlling detached state:

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

You can also change the default mode using the kodo.DetachState configuration property.

EJB XML format:

<!-- available settings are "loaded", "fgs", "all" -->
<property name="kodo.DetachState" value="fgs"/>

JDO properties format:

# available settings are "loaded", "fgs", "all"
kodo.DetachState: fgs

The EJB Persistence Overview describes EJB's automatic detach behavior in Section 7.3, “Persistence Context”. We describe Kodo's options for automatic detach in JDO below.

Detachable JDO objects automatically detach when they are serialized. Kodo expands this automatic detach behavior with optional automatic detachment on various events: close, commit, and non-transactional read. On each configured event, all managed objects in the PersistenceManager cache become detached. Non-detachable objects become transient.

By using the proper set of these options, you can avoid unnecessary detach calls in your code. Some common use cases for this functionality are:

No automatic detachment is performed in JDO by default. You can turn on automatic detachment at runtime through the KodoPersistenceManager.setAutoDetach methods. You can also set detach detachment triggers with the kodo.AutoDetach configuration property:

kodo.AutoDetach: close, commit, nontx-read