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:

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")

Supported Supported Supported

Direct value field (see Section 36.3, "Configuring Direct Value Field")

Supported Supported Supported

Method or direct field access (see Section 121.6, "Configuring Method or Direct Field Accessing at the Mapping Level")

Supported Supported Supported

Read-only mapping (see Section 121.2, "Configuring Read-Only Mappings")

Supported Supported Supported

Batch reading (see Section 28.5, "Configuring Batch Reading")

Supported Supported Supported

Indirection (lazy loading) (see Section 121.3, "Configuring Indirection (Lazy Loading)")

Supported Supported Supported

Container policy (see Section 121.14, "Configuring Container Policy")

Supported Supported Supported

Mapping comments (see Section 121.8, "Configuring Mapping Comments")

Supported Supported Supported

Serialized object converter (see Section 121.9, "Configuring a Serialized Object Converter")

Supported Supported Supported

Type conversion converter (see Section 121.10, "Configuring a Type Conversion Converter")

Supported Supported Supported

Object type converter (see Section 121.11, "Configuring an Object Type Converter")

Supported Supported Supported

Table and field references (see Section 28.7, "Configuring Table and Field References (Foreign and Target Foreign Keys)")

Supported Supported Supported

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:

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 follows
    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 follows
    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.