Configuring a Relational Direct Collection Mapping (ELUG)

Related Topics

For information on how to create EclipseLink mappings, see Creating a Mapping.

This table lists the configurable options for a relational direct collection mapping.

Option	Workbench	Java
Target table
Direct value field
Method or direct field access
Read-only mapping
Batch reading
Indirection (lazy loading)
Container policy
Mapping comments
Configuring a Serialized Object Converter
Type conversion converter
Object type converter
Table and field references

This example shows how to create a direct collection mapping and add it to a descriptor using Java code.

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:

• Direct Collection Mapping
• Configuring a Relational Mapping
• Configuring a Mapping.

For information on using JPA to configure direct collection mappings, see How to Use the @BasicCollection Annotation.

Configuring Target Table

Each direct collection stores reference information in a target table. In the Direct Collection Mappings figure, the RESPONS table contains the primary key and object of the instance owning the collection. You must create this table in your database.

How to Configure a Target Table Using 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.
   General Tab, Target Table Options
   

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

How to Configure a Target Table Using Java

Direct collection mappings store collections of Java objects that are not EclipseLink-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.

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 the Configuring a Simple Direct Collection Mapping example illustrates, other common API for use with direct collection mappings include the following:

• useBasicIndirection: implements EclipseLink 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 EclipseLink API Reference.

Configuring Direct Value Field

The direct value field, located in the reference table, stores the primitive data value. In the Direct Collection Mappings figure, the DESCRIP field stores the collection.

How to Configure a Direct Value Field Using 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.
   General Tab, Direct Value Field
   
3. Use the Direct Value Field list to select the field from the Target Table table that contains the object of the collection.

How to Configure Direct Value Field Using Java

The Configuring a Simple Direct Collection Mapping example 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.

---

Copyright Statement