4.3. Operations That Change State

In the previous section, we introduced basic states, and obvious methods—like reading a field or deleting a persistent instance from the datastore—were taken for granted. This section drills deeper into operations and explains behaviors in more detail. Some methods alter the object's state by a direct call; others indirectly change the state of multiple objects.

4.3.1. PersistentManager.makePersistent

The PersistenceManager method makePersistent causes transient objects to become persistent-new. In a call to makePersistent, the object graph is traversed to find other reachable, still transient objects. Those objects may indirectly become persistent-new as well.

4.3.2. PersistenceManager.deletePersistent

A call to deletePersistent makes clean, dirty, or hollow objects persistent-deleted, whereas persistent-new objects become persistent-new-deleted. This operation does not involve other reachable objects.

4.3.3. PersistenceManager.makeTransient

An object can be made transient if the previous state is persistent-clean or hollow. The persistent object is detached from the PersistenceManager and loses its identity. This PersistenceManager method does not involve other reachable objects; only the passed instance is made transient.

4.3.4. Transaction.commit

Instances that are part of a PersistenceManager's current transaction are processed by the JDO implementation during commit. Hollow instances are not changed. New, clean, and dirty objects become hollow; all other objects become transient. After commit, either hollow objects or regular, transient Java objects are associated with a PersistenceManager.

4.3.5. Transaction.rollback

Clean, dirty, and deleted objects become hollow at rollback. Other objects become transient. As a rule, hollow and transient objects are set back to their previous state after rollback.

4.3.6. PersistenceManager.refresh

A call to the PersistenceManager method refresh reloads the object's data and any modifications are lost. Persistent-dirty objects become persistent-clean after refresh.

4.3.7. PersistenceManager.evict

Evict helps the PersistenceManager caching implementation to save memory. Persistent-clean objects that are evicted become hollow. The fields of the objects are cleared to allow garbage collection of unreferenced subobjects.

4.3.8. Reading fields within a transaction

After reading the data from the datastore, hollow objects become persistent-clean. If pessimistic concurrency control is used, the object may be locked against concurrent modifications.

4.3.9. Writing fields within a transaction

When a field of an object that is attached to a PersistenceManager is modified inside of a transaction, the persistent object must be remembered by the JDO implementation to later update the object's data in the datastore. A persistent-clean or hollow object becomes persistent-dirty in this case. If pessimistic locking is used, a JDO implementation might also lock the object against access by other clients of the same datastore. Field modification of transient objects or objects that are persistent-dirty or persistent-new has no effect on the object's state. Whenever another object is assigned to a field, the modified object is marked persistent-dirty, but the referenced object is kept unchanged.

4.3.10. PersistenceManager.retrieve

The PersistenceManager.retrieve() method performs essentially the same operation as reading of a field within an active transaction.