36 Configuring a Relational Direct Collection Mapping

This chapter describes the various components that you must configure in order to use a relational direct collection mapping.

This chapter includes the following sections:

• Introduction to Relational Direct Collection Mapping Configuration

• Configuring Target Table

• Configuring Direct Value Field

For information on how to configure TopLink mappings options common to two or more mapping types, see Chapter 121, "Configuring a Mapping".

For information on how to create TopLink mappings, see Chapter 120, "Creating a Mapping".

Table 36-1 lists the configurable options for a relational direct collection mapping.

36.1 Introduction to Relational Direct Collection Mapping Configuration

Table 36-1 lists the configurable options for a relational direct collection mapping.

Table 36-1 Configurable Options for Relational Direct Collection Mapping

Option	Oracle JDeveloper	TopLink Workbench	Java
Target table (see Section 36.2, "Configuring Target Table")
Direct value field (see Section 36.3, "Configuring Direct Value Field")
Method or direct field access (see Section 121.6, "Configuring Method or Direct Field Accessing at the Mapping Level")
Read-only mapping (see Section 121.2, "Configuring Read-Only Mappings")
Batch reading (see Section 28.5, "Configuring Batch Reading")
Indirection (lazy loading) (see Section 121.3, "Configuring Indirection (Lazy Loading)")
Container policy (see Section 121.14, "Configuring Container Policy")
Mapping comments (see Section 121.8, "Configuring Mapping Comments")
Serialized object converter (see Section 121.9, "Configuring a Serialized Object Converter")
Type conversion converter (see Section 121.10, "Configuring a Type Conversion Converter")
Object type converter (see Section 121.11, "Configuring an Object Type Converter")
Table and field references (see Section 28.7, "Configuring Table and Field References (Foreign and Target Foreign Keys)")

Example 36-1 shows how to create a direct collection mapping and add it to a descriptor using Java code.

Example 36-1 Direct Collection Mapping

public void customize(ClassDescriptor descriptor) { 
    DirectCollectionMapping mapping = new DirectCollectionMapping();  

    // configure mapping
    ...   

    // add mapping to descriptor
    descriptor.addMapping(mapping);
}

For more information, see the following:

• Section 27.10, "Direct Collection Mapping"

• Chapter 28, "Configuring a Relational Mapping"

• Part XXVIII, "Creation and Configuration of Mappings"

For information on using JPA to configure direct collection mappings, see "How to Use the @BasicCollection Annotation" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_the_.40BasicCollection_Annotation.

36.2 Configuring Target Table

Each direct collection stores reference information in a target table. In Figure 27-6, the RESPONS table contains the primary key and object of the instance owning the collection. You must create this table in your database.

36.2.1 How to Configure a Target Table Using TopLink Workbench

To specify the direct collection specifics, use this procedure:

1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

   Figure 36-1 General Tab, Target Table Options

   
   Description of "Figure 36-1 General Tab, Target Table Options"
   
   

Use the Target Table list to select the table that contains the reference fields for the direct collection mapping.

36.2.2 How to Configure a Target Table Using Java

Direct collection mappings store collections of Java objects that are not TopLink-enabled. Direct collections usually store Java types, such as String.

Direct collection mappings are instances of the DirectCollectionMapping class and require the following elements:

• The attribute mapped, set by using the setAttributeName method.

• The database table that holds the values to be stored in the collection, set by using the setReferenceTableName method.

• The field in the reference table from which the values are read and placed into the collection; this is called the direct field. Set it using the setDirectFieldName method.

• The foreign key information, which you specify using the setReferenceKeyFieldName method and passing the name of the field that is a foreign reference to the primary key of the source object

  Note:

  If the target primary key is composite, call the addReferenceKeyFieldName method for each of the fields that make up the key.

Example 36-2 Configuring a Simple Direct Collection Mapping

public void customize(ClassDescriptor descriptor) { 
    DirectCollectionMapping directCollectionMapping = 
                                    new DirectCollectionMapping();
    directCollectionMapping.setAttributeName ("responsibilitiesList");
    directCollectionMapping.setReferenceTableName ("RESPONS"); // target table
    directCollectionMapping.setDirectFieldName ("DESCRIP");
    directCollectionMapping.setReferenceKeyFieldName ("EMP_ID");
    directCollectionMapping.useCollectionClass (Collection.class); // default

    // add this mapping to descriptor
    descriptor.addMapping (directCollectionMapping);
}

In addition to the API that Example 36-2 illustrates, other common API for use with direct collection mappings include the following:

• useBasicIndirection: implements TopLink value holder indirection.

• useTransparentCollection: if you use transparent indirection, this element places a special collection in the source object's attribute.

• dontUseIndirection: implements no indirection.

For more information about the available methods for DirectCollectionMapping, see the Oracle Fusion Middleware Java API Reference for Oracle TopLink.

36.3 Configuring Direct Value Field

The direct value field, located in the reference table, stores the primitive data value. In Figure 27-6, the DESCRIP field stores the collection.

36.3.1 How to Configure a Direct Value Field Using TopLink Workbench

To specify the direct collection specifics, use this procedure:

1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

   Figure 36-2 General Tab, Direct Value Field

   
   Description of "Figure 36-2 General Tab, Direct Value Field"
   
   

Use the Direct Value Field list to select the field from the Target Table table that contains the object of the collection.

36.3.2 How to Configure Direct Value Field Using Java

Example 36-2, "Configuring a Simple Direct Collection Mapping" demonstrates how to create and configure a direct collection mapping, including the setting of a direct field. The example also shows how to add this mapping to the descriptor.