34 Configuring a Relational Many-to-Many Mapping

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

This chapter includes the following sections:

Introduction to Relational Many-to-Many Mapping Configuration
Configuring a Relation Table

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 34-1 lists the configurable options for a relational many-to-many mapping.

34.1 Introduction to Relational Many-to-Many Mapping Configuration

Table 34-1 lists the configurable options for a relational many-to-many mapping.

Table 34-1 Configurable Options for Relational Many-to-Many Mapping

Option to Configure	Oracle JDeveloper	TopLink Workbench	Java
Reference descriptor (see Section 28.4, "Configuring Reference Descriptor")
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")
Private or Independent relationships (see Section 121.7, "Configuring Private or Independent Relationships")
Batch reading (see Section 28.5, "Configuring Batch Reading")
Indirection (lazy loading) (see Section 121.3, "Configuring Indirection (Lazy Loading)")
Bidirectional relationship (see Section 121.18, "Configuring Bidirectional Relationship")
Container policy (see Section 121.14, "Configuring Container Policy")
Mapping comments (see Section 121.8, "Configuring Mapping Comments")
Relational table (see Section 34.2, "Configuring a Relation Table")
Table and field references (see Section 28.7, "Configuring Table and Field References (Foreign and Target Foreign Keys)") (Source)
Table and field references (see Section 28.7, "Configuring Table and Field References (Foreign and Target Foreign Keys)") (Target)
Query key order (see Section 28.6, "Configuring Query Key Order")

Example 34-1 shows how to create a many-to-many mapping and add it to a descriptor using Java code.

Example 34-1 Many-to-Many Mapping

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

    // configure mapping
    ...   

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

For more information, see the following:

For information on using JPA to configure many-to-many mappings, see "@ManyToMany" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Introduction_to_EclipseLink_JPA_%28ELUG%29#.40ManyToMany.

34.2 Configuring a Relation Table

The relation table contains the columns for the primary keys of the source table and target table involved in the many-to-many mapping. You must create this table in the database before completing the mapping. See Section 5.5, "Using Databases" for information on creating database tables.

In Figure 27-5, the PROJ_EMP table serves as the relation table between the PROJECT and EMPLOYEE tables.

34.2.1 How to Configure a Relation Table Using TopLink Workbench

To select a relation table for a mapping, use this procedure:

Select the mapped attribute in the Navigator. Its properties appear in the Editor.
Click the General tab. The General tab appears.

Figure 34-1 Table Reference Tab, Relation Table Option

Description of "Figure 34-1 Table Reference Tab, Relation Table Option"

Use the Relation Table field to select a database table to define this mapping.

34.2.2 How to Configure a Relation Table Using Java

Many-to-many mappings represent the relationships between a collection of source objects and a collection of target objects. This requires an intermediate table that manages the associations between the source and target records.

Many-to-many mappings are instances of the ManyToManyMapping class and requires the following elements:

The attribute mapped, set by using the setAttributeName method.
The reference class, set by using the setReferenceClass method.
The relation table, set by using the setRelationTableName() method.
The foreign key information (for noncomposite target primary keys), which you specify by calling the setSourceRelationKeyFieldName and setTargetRelationKeyFieldName methods.
The foreign key information if the source or target primary keys are composite, which you specify by sending the addSourceRelationKeyFieldName or addTargetRelationKeyFieldName methods.

Example 34-2 Configuring a Relational Table

public void customize(ClassDescriptor descriptor) { 
    // In the Employee class, create the mapping that references Project class
    ManyToManyMapping manyToManyMapping = new ManyToManyMapping();
    manyToManyMapping.setAttributeName("projects");
    manyToManyMapping.setReferenceClass(Project.class);

    // Configure the relational table
    manyToManyMapping.setRelationTableName("PROJ_EMP");
    manyToManyMapping.setSourceRelationKeyFieldName ("EMPID");
    manyToManyMapping.setTargetRelationKeyFieldName ("PROJID");

    // Add mapping to descriptor
    descriptor.addMapping(manyToManyMapping);
}

In addition to the API that Example 34-2 illustrates, other common API for use with many-to-many 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 ManyToManyMapping, see the Oracle Fusion Middleware Java API Reference for Oracle TopLink.