public static boolean isDirty (Object pc); public static boolean isTransactional (Object pc); public static boolean isPersistent (Object pc); public static boolean isNew (Object pc); public static boolean isDeleted (Object pc);
JDO recognizes several lifecycle states for persistence-capable
objects. Instances transition between these
states according to strict rules defined in the JDO specification.
State transitions can be triggered by both explicit actions, such
as calling the deletePersistent method of
a PersistenceManager to delete a persistent
object, and by implicit actions, such as reading or writing a
persistent field.
The list below enumerates the lifecycle states for persistence-capable instances. Unless otherwise noted, each state must be supported by all JDO implementations. Do not concern yourself with memorizing the states and transitions presented; you will rarely need to think about them in practice.
![[Note]](img/note.gif) | Note |
|---|---|
Some of the state transitions below occur at transaction boundaries. If you are unfamiliar with transactions, you may want to read the first few paragraphs of Chapter 9, Transaction to become familiar with the concepts involved before continuing. |
Transient. Objects that are created via a user-defined constructor and have no association with the persistence framework are called transient objects. Transient objects behave exactly as if JDO does not exist.
Persistent-new. The persistent-new state is reserved for objects that have been made persistent within the current transaction. On flush or transaction commit, the information in the persistent-new object is inserted into the datastore. On transaction rollback, a persistent-new instance returns to the transient state. The datastore is not affected. If the
Transaction'sRestoreValuesproperty is set totrue, the instance's persistent and transactional fields will be restored to the values they had when the transaction began.Persistent-new-deleted. Objects that have been both persisted and then deleted in the current transaction wind up in the persistent-new-deleted state. When objects are in this state, you are only allowed to access their primary key fields. Attempting to access any other persistent field will result in a
JDOUserException.A persistent-new-deleted object transitions to transient on transaction commit. The values of its persistent fields are replaced with Java default values. A persistent-new-deleted object also becomes transient if the transaction is rolled back. In this case, its persistent and transactional fields will be restored to the values they had when the transaction began if the
Transaction'sRestoreValuesproperty istrue, else they will be left untouched.Persistent-clean. Objects that represent specific state in the datastore and whose persistent fields have not been changed in the current transaction are persistent-clean.
Persistent-dirty. Persistent objects that have been changed within the current transaction are persistent-dirty. On transaction commit, the datastore will be updated to reflect the object's persistent state.
Persistent-deleted. If a persistent object is the parameter of a call to the
PersistenceManager.deletePersistentmethod, is deleted by query, or is orphaned from a dependent relation, it becomes persistent-deleted. When an object is in this state, you are only allowed to access its primary key fields. Attempting to access any other persistent field may result in aJDOUserException.A persistent-deleted object transitions to transient on transaction commit. The datastore record for the object is removed.
Hollow. Persistent objects whose values have not been loaded from the datastore are in the hollow state. Whenever an instance transitions to hollow, its persistent fields are cleared and replaced with their Java default values. The fields will be re-loaded with their datastore values the first time you access them. Delaying the loading of persistent information until it is needed is known as lazy loading.
JDO implementations use only weak or soft references to track hollow instances, so they may be garbage collected if your application does not hold strong references to them.
Persistent-nontransactional. Persistent-nontransactional objects represent persistent data in the datastore, but are not guaranteed to reflect the most current values of that data. A lifecycle state that allows access to data that may be stale might sound useless; if they are utilized carefully, however, persistent-nontransactional objects can sometimes offer large performance gains, with little danger of employing outdated data in your application.
The persistent-nontransactional state is an optional feature of JDO, and may not be supported in some implementations. It is also by far the most complex lifecycle state. It is governed by the
NontransactionalRead, NontransactionalWrite, RetainValues, andOptimisticproperties of theTransaction. Implementations may support any or all of these properties. These properties are detailed in Section 7.2.2, “PersistenceManager and Transaction Defaults”.Outside of a transaction, reading and writing persistent fields of a persistent-nontransactional instance does not result in any state change. If the instance enters a datastore transaction, its persistent fields are discarded. Within this type of transaction, reading a persistent field of a persistent-nontransactional instance causes a transition to persistent-clean, and writing a persistent field causes a transition to persistent-dirty.
When a persistent-nontransactional instance enters an optimsitic transaction, on the other hand, its persistent field values are retained. Within an optimistic transaction, reading a persistent field of a persistent-nontransactional instance does not change the instance's state; writing a persistent field causes a transition to persistent-dirty.
Transient-clean. The transient-clean and transient-dirty states are grouped together in the transient-transactional lifecycle category. Transient-transactional objects are not persistent, but their fields can be restored to their previous values when a transaction is rolled back. You can make a transient instance transient-transactional by passing it to the
PersistenceManager'smakeTransactionalmethod. Some JDO vendors may not support the transient-transactional states; they are an optional feature of the JDO specification.Transient-dirty. Transient-transactional instances that have been modified in the current transaction are transient-dirty. On transaction completion, a transient-dirty object transitions to transient-clean. If the
Transactionis rolled back and itsRestoreValuesproperty istrue, the persistent and transactional fields of a transient-dirty object will be restored to the values they had when the transaction began.
| Note |
|---|---|
Kodo supports all JDO lifecycle states, including all optional states. |
The following diagram displays the state transitions for persistent
objects. Each arrow represents a change from one state to another,
and the text next to the arrow indicates the event that triggers
change. Method names in blue are methods of the
Transaction interface. Method names in red
are methods of the PersistenceManager interface.
These interfaces are covered later in this document.
After reviewing the JDO lifecycle states, the purpose of the
JDOHelper's lifecycle operations -
isDirty, isTransactional, isPersistent,
isNew, isDeleted - should be clear. Each one tells
you whether or not the given persistence-capable instance has has
the named property, where these properties are determined by the
lifecycle state of the instance. In fact, you can calculate the exact
state of the instance based on these properties according to the table
below. Once again, however, you will rarely worry about the lifecycle
state of your persistence-capable objects in practice.
