28 Configuring a Relational Mapping

28.1 Introduction to Relational Mapping Configuration

Table 28-1 lists the types of relational mappings that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.

For more information, see the following:

• Chapter 17, "Introduction to Mappings"

• Chapter 27, "Introduction to Relational Mappings"

28.2 Configuring Common Relational Mapping Options

Table 28-2 lists the configurable options shared by two or more relational mapping types.

Table 28-2 Common Relational Mapping Options

Option to Configure	Oracle JDeveloper	TopLink Workbench	Java
Database field (see Section 28.3, "Configuring a Database Field")
Reference descriptor (see Section 28.4, "Configuring Reference Descriptor")
Container policy (see Section 121.14, "Configuring Container Policy")
Method or direct field access (see Section 121.6, "Configuring Method or Direct Field Accessing at the Mapping Level")
Default null value (see Section 121.5, "Configuring a Default Null Value at the Mapping Level")
Read-only mapping (see Section 121.2, "Configuring Read-Only Mappings")
Indirection (lazy loading) (see Section 121.3, "Configuring Indirection (Lazy Loading)")
Private or Independent relationships (see Section 121.7, "Configuring Private or Independent Relationships")
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")
Bidirectional relationship (see Section 121.18, "Configuring Bidirectional Relationship")
Batch reading (see Section 28.5, "Configuring Batch Reading")
Query key order (see Section 28.6, "Configuring Query Key Order")
Table and field references (see Section 28.7, "Configuring Table and Field References (Foreign and Target Foreign Keys)")
Joining (see Section 28.8, "Configuring Joining at the Mapping Level")

28.3 Configuring a Database Field

You can associate an object attribute with a database field.

Table 28-3 summarizes which relational mappings support this option.

Table 28-3 Relational Mapping Support for Database Field

Mapping	How to Use Oracle JDeveloper	How to Configure a Database Field Using TopLink Workbench	How to Use Java
Direct-to-Field Mapping
Direct-to-XMLType Mapping

When choosing the database field, you must consider Java and database field type compatibility.

TopLink supports the following Java types:

• java.lang: Boolean, Float, Integer, String, Double, Long, Short, Byte, Byte[ ], Character, Character[ ]; all the primitives associated with these classes

• java.math: BigInteger, BigDecimal

• java.sql: Date, Time, Timestamp

• java.util: Date, Calendar

While executing reads, the mappings in Table 28-6 perform the simple one-way data conversions that Table 28-4 describes. For two-way or more complex conversions, you must use converters (see Section 27.2.2, "Converters and Transformers").

The mappings in Table 28-3 also allow you to specify a null value. This may be required if primitive types are used in the object, and the database field allows null values. For more information, see Section 121.5, "Configuring a Default Null Value at the Mapping Level".

Support for oracle.sql.TimeStamp

TopLink provides additional support for mapping Java date and time data types to Oracle Database DATE, TIMESTAMP, and TIMESTAMPTZ data types when you use the Oracle JDBC driver with Oracle9i Database or later and the Oracle9Platform in TopLink.

In a direct-to-field mapping, you are not required to specify the database type of the field value; TopLink determines the appropriate data type conversion.

Table 28-5 lists the supported direct-to-field mapping combinations.

Note that some of these mappings result in a loss of precision: avoid these combinations if you require this level of precision. For example, if you create a direct-to-field mapping between a java.sql.Date attribute and a TIMESTAMPTZ database field, there is no loss of precision. However, if you create a direct-to-field mapping between a java.sql.Timestamp attribute and a DATE database field, the nanoseconds or milliseconds of the attribute are not stored in the database.

28.4 Configuring Reference Descriptor

In relational mappings that extend oracle.toplink.mappings.ForeignReferenceMapping, attributes reference other TopLink descriptors–not the data source. You can select any descriptor in the project.

Table 28-6 summarizes which relational mappings support this option.

Table 28-6 Relational Mapping Support for Reference Descriptor

Mapping	How to Use Oracle JDeveloper	How to Configure a Reference Descriptor Using TopLink Workbench	How to Use Java
One-to-one (see Section 27.5, "One-to-One Mapping")
Variable one-to-one (see Section 27.6, "Variable One-to-One Mapping")
One-to-many (see Section 27.7, "One-to-Many Mapping")
Many-to-many (see Section 27.8, "Many-to-Many Mapping")
Aggregate collection (see Section 27.9, "Aggregate Collection Mapping")
Aggregate object (see Section 27.12, "Aggregate Object Mapping")

28.5 Configuring Batch Reading

Batch reading can be used in most of the relational mappings. This feature should be used only if it is known that the related objects are always required with the source object.

Table 28-7 summarizes which relational mappings support this option.

public void customize(ClassDescriptor descriptor) { 
    OneToManyMapping phoneNumbersMapping = new OneToManyMapping();
    phoneNumbersMapping =
        (OneToManyMapping)descriptor.getMappingForAttributeName("phones"); 
    phoneNumbersMapping.useBatchReading();

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

28.6 Configuring Query Key Order

You can configure TopLink to maintain collections in order by query key.

Table 28-8 summarizes which relational mappings support this option.

public void customize(ClassDescriptor descriptor) {

    OneToManyMapping phoneNumbersMapping = new OneToManyMapping();

    phoneNumbersMapping =
        (OneToManyMapping)descriptor.getMappingForAttributeName("phones"); 

    phoneNumbersMapping.addAscendingOrdering("areaCode"); 

    ExpressionBuilder phone = 
        phoneNumbersMapping.getSelectionQuery().getExpressionBuilder();

    phoneNumbersMapping.getSelectionQuery().addOrdering(
        phone.get("type").toUpperCase().ascending());

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

28.7 Configuring Table and Field References (Foreign and Target Foreign Keys)

A foreign key is a combination of one or more database columns that reference a unique key, usually the primary key, in another table. Foreign keys can be any number of fields (similar to a primary key), all of which are treated as a unit. A foreign key and the parent key it references must have the same number and type of fields.

Mappings that extend oracle.toplink.mappings.ForeignReferenceMapping use foreign keys to find information in the database so that the target object(s) can be instantiated. For example, if every Employee has an attribute address that contains an instance of Address (which has its own descriptor and table) then, the one-to-one mapping for the address attribute would specify foreign key information to find an Address for a particular Employee.

TopLink classifies foreign keys into two categories in mappings–foreign keys and target foreign keys:

• In a foreign key, the key is found in the table associated with the mapping's own descriptor. For example, an Employee foreign key to ADDRESS would be in the EMPLOYEE table.

• In a target foreign key, the reference is from the target object's table back to the key from the mapping's descriptor's table. For example, the ADDRESS table would have a foreign key to EMPLOYEE.

  Caution:

  Make sure you fully understand the distinction between foreign key and target foreign key before defining a mapping.

The table reference is the database table that contains the foreign key references.

Table 28-9 summarizes which relational mappings support this option.

Using TopLink Workbench, you can either import this table from your database or create it. If you import tables from the database (see Section 5.5.1.3, "Importing Tables from a Database"), TopLink creates references that correspond to existing database constraints (if supported by the driver). You can also define references in TopLink without creating similar constraints on the database.

public void customize(ClassDescriptor descriptor) {

    OneToManyMapping phoneNumbersMapping = new OneToManyMapping();
    phoneNumbersMapping =
        (OneToManyMapping)descriptor.getMappingForAttributeName("cellPhones");
 
    ExpressionBuilder phone = 
        phoneNumbersMapping.getSelectionQuery().getExpressionBuilder();

    phoneNumbersMapping.addTargetForeignKeyFieldName("PHONE.EMP_ID", "EMP.ID");

    phoneNumbersMapping.getSelectionQuery(
        phone.getField("PHONE.EMP_ID").equal(phone.getParameter("EMP.ID").
        and(phone.getField("PHONE.TYPE').equal("CELL"))); 

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

28.8 Configuring Joining at the Mapping Level

TopLink supports configuring an inner or outer join at the mapping level for a ForeignReferenceMapping. When a class that owns the mapping is read, the TopLink runtime will always get the class and the target of the reference mapping with one database hit.

Use this feature only if the target object is always required with the source object, or when indirection (lazy loading) is not used. For more information, see Section 17.2.4, "Indirection (Lazy Loading)".

You can also configure join reading at the query level. For more information, see Section 108.7.1.5, "Join Reading and Object-Level Read Queries".

You can use Oracle JDeveloper, TopLink Workbench, or Java to configure joining at the mapping level.

For more information about joins, see Section 110.2.7, "Expressions for Joining and Complex Relationships".

public void customize(ClassDescriptor descriptor) {

    OneToManyMapping addressMapping = new OneToManyMapping();
    addressMapping =
        (OneToManyMapping)descriptor.getMappingForAttributeName("address");
    addressMapping.useJoining();
    ...
    // add mapping to descriptor
    descriptor.addMapping(addressMapping);
}