Configuring Wrapper Policy

TopLink lets you use wrappers (or proxies) in cases where the persistent class is not the same class that is to be presented to users.

For example, in the EJB specification, the entity bean class (the class that implements javax.ejb.EntityBean) is persistent, but is hidden from users who interact with a class that implements javax.ejb.EJBObject (local or remote interface class). In this example, the EJBObject acts as a proxy (or wrapper) for the EntityBean.

In cases where such a wrapper is used, TopLink continues to make the class specified in the descriptor persistent, but returns the appropriate instance of the wrapper whenever a persistent object is requested.

Table 28-37 summarizes which descriptors support a wrapper policy.

Table 28-37 Descriptor Support for Wrapper Policy

Descriptor	Using TopLink Workbench	Using Java
Relational Descriptors
Object-Relational Descriptors
EIS Descriptors
XML Descriptors

Use a wrapper policy to tell TopLink how to create wrappers for a particular persistent class, and how to obtain the underlying persistent object from a given wrapper instance.

If you specify a wrapper policy, TopLink uses the policy to wrap and unwrap persistent objects as required:

• Wrapper policies implement the interface oracle.toplink.descriptors.WrapperPolicy.

• A wrapper policy is specified by setting the wrapper policy for the TopLink descriptor.

• By default, no wrapper policy is used (the wrapper policy for a descriptor is null by default).

Note: Wrapper policies are advanced TopLink options. Using a wrapper policy may not be compatible with some TopLink Workbench features.

For EJB CMP descriptors, the EJB wrapper policy is automatically configured during deployment, so does not need to be set in the descriptor (see "Configuring a Descriptor With EJB Information").

For EJB BMP descriptors, you must set a BMPWrapperPolicy on the descriptor. The BMPWrapperPolicy includes the bean's information including the bean-name, primary-key-class, home-interface, and remote-interface.

Wrapper policies cannot be set using TopLink Workbench and can be set only using Java code (see "Using Java").

Using Java

Use the ClassDescriptor method setWrapperPolicy to set the appropriate instance of WrapperPolicy.

Example 28-25 shows how to amend a BMP descriptor with the required EJB BMP information.

Example 28-25 Configuring a BMP Wrapper Policy

public static void addToDescriptor(ClassDescriptor descriptor) {
    BMPWrapperPolicy policy = new BMPWrapperPolicy(
        "employee",
        EmployeeHome.class,
        EmployeePK.class,
        Employee.class,
        new Hashtable()
    );
    descriptor.setWrapperPolicy(policy);