The Optional Transient-Transactional Feature

JDO gives its implementations the option to support the transient-transactional feature. When an implementation supports this feature, it supports application data objects in the transient-clean and transient-dirty states in addition to the JDO-transient state. An application data object in any of the three transient states may have persistent fields, but because the object is not persistent, these fields are not synchronized with persistent state in the datastore. The persistent fields of the transient and transactional object are managed as if they were transactional fields. An application data object in any of the three transient states does not have a JDO identity.

Note

Applications can determine whether an implementation supports the transient-transactional feature by looking for the "javax.jdo.option.TransientTransactional" string in the collection of strings returned from the supportedOptions method in the JDOHelper class. Chapter 7 describes the JDOHelper class.

Figure 4-13 illustrates the behavior for the three transient management states. As Figure 4-13 shows, a JDO-transient object becomes transient-clean when passed to the makeTransactional method in the persistence manager. The call succeeds whether a transaction is active or not. If the transient-transactional feature is not supported, calling the method yields a JDOUnsupportedOptionException.

Figure 4-13: Additional state transitions when JDO supports the transient-transactional feature

When a transaction is active, the persistence manager's makePersistent method can make any transient object persistent-new. Once an object becomes persistent-new, it can become JDO-transient, hollow, or persistent-nontransactional as the result of transaction commit or rollback. None of JDO's actions change persistent-new objects into either transient-clean or transient-dirty objects.

As Figure 4-13 shows, reading any field of an application data object in any of the three transient states never produces a state change. When a transaction is not active, writes to any fields in JDO-transient or transient-clean objects do not produce a state change. Once the transaction becomes active, writes to managed fields cause the transient-clean object to become transient-dirty. When weak or strong RestoreValues is true, JDO saves the before-image before making the object transient-dirty.

The evict, refresh, and retrieve operations of the persistence manager perform no operation and return silently when passed JDO-transient, transient-clean, and transient-dirty objects, with one exception. The evict method throws a JDOUserException when a JDO-transient object is passed to it. The transaction properties RetainValues, Optimistic, NontransactionalRead, and NontransactionalWrite have no effect on JDO-transient, transient-clean, or transient-dirty objects.

The transaction's commit operation discards any saved before-image and changes the transient-dirty object to transient-clean. Otherwise, no changes are made to the field values. In particular, setting RetainValues to false does not cause JDO to clear the persistent fields of the object.

The transaction's rollback operation retains the existing values of all managed fields in the transient-dirty object when RestoreValues is false. It restores the managed fields to the values saved in the object's before-image, when RestoreValues is true. Commit and rollback have no effect on JDO-transient and transient-clean objects.

Practical uses for the two transient and transactional states are likely to be specialized.