Using Value Holder Indirection

Persistent classes that use indirection must replace relationship attributes with value holder attributes. A value holder is an instance of a class that implements the ValueHolderInterface interface, such as ValueHolder. This object stores the information necessary to retrieve the object it is replacing from the database. If the application does not access the value holder, the replaced object is never read from the database.

When using method access, the get and set methods specified for the mapping must access an instance of ValueHolderInterface, rather than the object referenced by the value holder.

To obtain the object that the value holder replaces, use the getValue() and setValue() methods of the ValueHolderInterface class. A convenient way of using these methods is to hide the getValue and setValue methods of the ValueHolderInterface inside get and set methods, as in the following example.

Example 5-1 Value Holder Indirection

The following figure illustrates the Employee object being read from the database. The Address object is not read and will not be created unless it is accessed.

Figure 5-5 Address Object Not Read

This figure shows a an object being read from the database.
The object is not read and created unless it is accessed.

The first time the address is accessed, as in the following figure, the ValueHolder reads and returns the Address object.

Figure 5-6 Initial Request

The first time the object is accessed, the ValueHolder reads and returns the object.

Subsequent requests for the address do not access the database, as shown in the following figure.

Figure 5-7 Subsequent Requests

Each subsequent request for the object access the ValueHolder - not the database.