Working with Indirection

Understanding Indirection

Indirection is available for transformation mappings and for direct collection, one-to-one, one-to-many, and many-to-many relationship mappings.

You can enable or disable indirection for each mapping individually. By default, indirection is enabled for relationship mappings and disabled for transformation mappings. Indirection should be enabled only for transformation mappings if the execution of the transformation method is a resource-intensive task, such as accessing the database.

• Indirection disabled: An indirection object is not used. Whenever an object is retrieved from the database, all the objects associated with it through the mapping are also read.

• Indirection enabled: A value holder is used to represent the entire relationship. When an object is retrieved from the database, a value holder is created and stored in the attribute corresponding to the mapping. The first time the value holder is accessed, it retrieves the related object from the database.

In addition to this standard version of indirection, collection mappings (direct collection, one-to-many, and many-to-many) can use indirect containers.

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.

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 6-2 Address Object Not Read

Description of the illustration vhstep1.gif

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

Figure 6-3 Initial Request

Description of the illustration vhstep2.gif

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

Figure 6-4 Subsequent Requests

Description of the illustration vhstep3.gif

Specifying Indirection

Use this procedure to specify that a mapping uses indirection.

To specify indirection:

1. In the Navigator pane, select the mapping to be mapped, and click the appropriate button on the mapping toolbar.

   The mapping tab appears in the Editor pane.

   Figure 6-5 Sample Mapping Properties

   
   Description of the illustration indroptn.gif
   
   

2. On the General tab, click Use Indirection to specify that the mapping uses indirection.

Changing Java Classes to Use Indirection

Attributes using indirection must conform to the ValueHolderInterface. You can change your attribute types in the Class Editor without re-importing your Java classes. Ensure that you change the attribute types in your Java code as well. Attributes typed incorrectly will be marked as deficient.

In addition to changing the attribute's type, you may also need to change its accessor methods. If you use method access, OracleAS TopLink requires accessors to the indirection object itself, so your get method returns an instance that conforms to ValueHolderInterface, and your set method accepts one argument that conforms to the same. If the instance variable returns a Vector instead of an object, then the value holder should be defined in the constructor as follows:

addresses = new ValueHolder(new Vector());

In any case, the application uses the getAddress() and setAddress() methods to access the Address object. With indirection, OracleAS TopLink uses the getAddressHolder() and setAddressHolder() methods when saving and retrieving instances to and from the database.

Refer to the Oracle Application Server TopLink Application Developer's Guide for details.

/ Initialize ValueHolders in Employee Constructor
public Employee() {
address = new ValueHolder();
}
protected ValueHolderInterface address;

// 'Get' and 'Set' accessor methods registered with the mapping and used by OracleAS TopLink.
public ValueHolderInterface getAddressHolder() {
return address;
}
public void setAddressHolder(ValueHolderInterface holder) {
address = holder;
}

// 'Get' and 'Set' accessor methods used by the application to access the attribute.
public Address getAddress() {
return (Address) address.getValue();
}
public void setAddress(Address theAddress) {
address.setValue(theAddress);
}