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 | |
---|---|
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
's
RestoreValues
property is set to
true
, 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
's
RestoreValues
property is
true
, 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.deletePersistent
method, 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 a
JDOUserException
.
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
, and
Optimistic
properties of the
Transaction
. 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
's
makeTransactional
method. 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
Transaction
is
rolled back and its RestoreValues
property is true
, 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.