The Ten Management States of Data Objects

JDO defines ten management states for application data objects. The management state of an application data object determines the implicit actions that JDO takes on the object and the explicit actions that JDO allows on the object. Table 1-1 shows these ten states grouped by the two management dimensions.

Table 1-1: JDO Managed Life Cycle States

Management Dimension	Transactional	Nontransactional
Persistent	Persistent-clean Persistent-new Persistent-dirty Persistent-deleted Persistent-new-deleted	Persistent-nontransactional Hollow
Transient	Transient-clean Transient-dirty	Transient (JDO-transient)

Data objects of the supported system classes do not directly have management state. They have management state indirectly as a result of their relationship to application data objects. If the persistent field of a persistent application data object refers to an embedded object, then the embedded object is persistent; otherwise, it is not. The embedded object's transactional state is likewise acquired indirectly. If a persistent or transactional field of a transactional application data object refers to an embedded object, then the embedded object is transactional; otherwise, it is not.

Three of the states in Table 1-1 occur only when the JDO implementation supports optional features. The transient-clean and transient-dirty states occur only when the implementation supports the javax.jdo.option.TransientTransactional option. The persistent-nontransactional state occurs only when the implementation supports any of the five transactional options of JDO, such as NontransactionalRead or RetainValues. The remaining seven management states occur in all JDO implementations.

Note

The supportedOptions method in the PersistenceManagerFactory interface returns a string for each optional feature of JDO that the implementation supports. Chapter 6 describes this interface and the various option strings.

As Table 1-1 shows, when JDO manages the object both transactionally and persistently, the object is in one of five management states:

• It is persistent-clean when its persistent fields hold the values that are, or will be verified to be, consistent with the datastore in the current transaction.

• It is persistent-dirty when at least one transactional or persistent field has been modified during the current transaction.

• It is persistent-new when the transient object has been added to the current transaction for insertion into the datastore as a result of a call to the persistence manager's makePersistent method. An object can also be persistent-new because it can be reached by persistent fields from an object that was made persistent. This feature is called persistence by reachability.

• It is persistent-deleted when the object existed in the datastore but has been marked for deletion within the current transaction as a result of a call to the persistence manager's deletePersistent method.

• It is persistent-new-deleted when the object is both added for insertion and later marked for deletion within the current transaction.

When an application data object is not persistent, its management state is one of the three transient states:

• It is JDO-transient when it is neither persistent nor transactional. In this case, JDO is not managing the object, so this state is also called the unmanaged state.

• It is transient-clean when the JDO implementation supports the javax.jdo.option.TransientTransactional option and the JDO-transient object is passed to the persistence manager's makeTransactional method. An object can be in the transient-clean state even when a transaction is not active.

• A transient-clean object becomes transient-dirty when any of its transactional or persistent fields are changed within a transaction. After the transaction commits or rolls back, the transient-dirty object becomes transient-clean again.

When an application data object is persistent but not transactional, its management state is one of the two persistent and nontransactional states:

• It is hollow when the values of its persistent fields have not been read from the datastore. An application data object might be returned in the hollow state after any retrieval operation. After a transaction is committed or rolled back, a transactional and persistent application data object will become hollow when the transaction is not configured to retain values.

• It is persistent-nontransactional when some or all of its persistent fields have values that were synchronized with the datastore either outside of a transaction or in a previous transaction. Because the state is not transactional, the values of the persistent fields may no longer match the values in the datastore.

The Attributes of Management States

As you read this book, you will find that the following adjectives are continually applied to application data objects:

• Persistent

• Transient

• Clean

• Dirty

• New

• Deleted

Table 1-2 defines, by JDO management states, when these adjectives can be properly applied to objects. Note that the term transient applies when the object is not persistent, and the term clean applies when the object is transactional but not dirty.

Table 1-2: Attributes of the JDO Management States

State	Persistent	Transactional	Dirty	New	Deleted
JDO-transient
Transient-clean		x
Transient-dirty		x	x
Hollow	x
Persistent-nontransactional	x
Persistent-clean	x	x
Persistent-dirty	x	x	x
Persistent-new	x	x	x	x
Persistent-deleted	x	x	x		x
Persistent-new-deleted	x	x	x	x	x

Table 1-2 shows no distinguishing mark between an object in the hollow state and an object in the persistent-nontransactional state. An object is hollow when it does not hold any of its persistent state, and it is persistent-nontransactional when it holds at least some of its persistent state.

As Table 1-2 shows, an object cannot be new or deleted unless it is persistent. When a transaction is not active, the only objects that can be transactional are the objects in the transient-clean state.