7
Mapping Implementation

Mapping enables you to relate objects in your application to data in a database. This chapter discusses how you can use Java code to implement mappings in TopLink-based applications. It discusses

• Direct mappings

• Relationship mappings

• Object relational mappings

For detailed descriptions of these mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Direct mappings

Direct mappings define how a persistent object refers to objects that do not have descriptors, such as the JDK classes and primitives. There are several types of direct mappings, including

• Direct-to-field mappings

• Type conversion mappings

• Object type mappings

• Serialized object mappings

• Transformation mappings

Direct-to-field mappings

In Java, use the DirectToFieldMapping class to create direct-to-field mappings. The mapping requires you to set the following:

• Attribute mapped, set by sending the setAttributeName() message

• Field to store the value of the attribute, set by sending the setFieldName() message

The optional setGetMethodName() and setSetMethodName() messages allow TopLink to access the attribute through user-defined methods rather than directly through the attribute. You do not have to define the accessors when using Java 2.

The Descriptor class provides the addDirectMapping() method that can create a new DirectToFieldMapping, set the attribute and field name parameters, and register the mapping with the descriptor.

Example 7-1 Creating a direct-to-field mapping in Java and registering it with the descriptor.

// Create a new mapping and register it with the descriptor.
DirectToFieldMapping mapping = new DirectToFieldMapping();
mapping.setAttributeName("city");
mapping.setFieldName("CITY");
descriptor.addMapping(mapping);

Example 7-2 Creating a mapping that uses method access.

This mapping example assumes persistent class has getCity() and setCity() methods defined.

// Create a new mapping and register it with the descriptor. 
DirectToFieldMapping mapping = new DirectToFieldMapping();
mapping.setAttributeName("city");
mapping.setFieldName("CITY");
mapping.setGetMethodName("getCity");
mapping.setSetMethodName("setCity");
descriptor.addMapping(mapping);

Example 7-3 Using the two overloaded versions of the descriptor's addDirectMapping() method

// Alternate method which does the same thing.
descriptor1.addDirectMapping("city", "CITY");
descriptor2.addDirectMapping("city", "getCity", 

Reference

Table 7-1 summarizes the most common public methods for direct-to-field mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for direct-to-field mapping, see the TopLink JavaDocs.

Table 7-1 Elements for direct-to-field mapping  

setAttributeName(String name)

setFieldName(String name)

Type conversion mappings

Create type conversion mappings with the TypeConversionMapping class. The following elements are required for a type conversion mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The field to store the value of the attribute, set by setFieldName() message

• The Java type stored in the attribute, set by sending the setAttributeClassification() message

• The database type to be written, set by sending the setFieldClassification() message

The optional setGetMethodName() and setSetMethodName() messages allow TopLink to access the attribute through user-defined methods rather than directly through the attribute. You do not have to define the accessors when using Java 2.

Example 7-4 Creating a type conversion mapping and registering it with the descriptor

// Create a new mapping and register it with the descriptor.
TypeConversionMapping typeConversion = new TypeConversionMapping();
typeConversion.setFieldName("J_DAY");
typeConversion.setAttributeName("joiningDate");
typeConversion.setFieldClassification(java.sql.Date.class);
typeConversion.setAttributeClassification(java.util.Date.class);
descriptor.addMapping(typeConversion);

Reference

Table 7-2 summarizes the most common public methods for type conversion mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for type conversion mapping, see the TopLink JavaDocs.

Table 7-2 Elements for type conversion mapping  

setAttributeName(String name)

setFieldName(String name)

setAttributeClassification(Class aClass)
setFieldClassification(Class aClass)

Object type mappings

Object type mappings are instances of the ObjectTypeMapping class. The following elements are required for an object type mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The field to store the value of the attribute, set by setFieldName() message

• A set of values and their conversions, added by sending the addConversionValue() message

The optional setGetMethodName() and setSetMethodName() messages allow TopLink to access the attribute through user-defined methods rather than directly. You do not have to define the accessors when using Java.

The following two methods are useful in a legacy environment, or you want to change the values of the fields:

• addToAttributeOnlyConversionValue
(Object fieldValue, Object attributeValue) - adds conversion value only for the field value to attribute value. This is a one-way mapping from the field to the attribute. This can be used if multiple database values are to mapped to the same object value. When written to the database, the value entered by addConversionValue(Object fieldValue, Object attributeValue) is used and therefore the original values in the database change.

• setDefaultAttributeValue
(Object defaultAttributeValue) - the default value can be used if the database can store values in addition to those that have been mapped. Any value retrieved from database that is not mapped is substituted for the default value. When writing to the database, the value entered by addConversionValue(Object fieldValue, Object attributeValue) is used and therefore the original values in the database change.

Example 7-5 Creating an object type mapping and registering it with the descriptor

// Create a new mapping and register it with the descriptor.
ObjectTypeMapping typeMapping = new ObjectTypeMapping();
typeMapping.setAttributeName("gender");
typeMapping.setFieldName("GENDER");
typeMapping.addConversionValue("M", "Male");
typeMapping.addConversionValue("F", "Female");
typeMapping.setNullValue("F");
descriptor.addMapping(typeMapping);

Reference

Table 7-3 summarizes the most common public methods for object type mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for object type mapping, see the TopLink JavaDocs.

Table 7-3 Elements for object type mapping  

setAttributeName(String name)

setFieldName(String name)

Serialized object mappings

Serialized object mappings are instances of the SerializedObjectMapping class. The following elements are required for a serialized object mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The field that stores the value of the attribute, set by the setFieldName() message

The optional setGetMethodName() and setSetMethodName() messages allow TopLink to access the attribute through user-defined methods rather than directly through the attribute. You do not have to define accessors when using Java 2.

Example 7-6 Creating a serialized object mapping and registering it with the descriptor.

// Create a new mapping and register it with the descriptor.
SerializedObjectMapping serializedMapping = new SerializedObjectMapping();
serializedMapping.setAttributeName("jobDescription");
serializedMapping.setFieldName("JOB_DESC");
descriptor.addMapping(serializedMapping);

Reference

Table 7-4 summarizes the most common public methods for serialized object mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for serialized object mapping, see the TopLink JavaDocs.

Table 7-4 Elements for serialized object mapping  

setAttributeName(String name)

setFieldName(String name)

Transformation mappings

Transformation mappings enable you to create specialized translations between how a value is represented in Java and in the database. Use transformation mappings only when mapping multiple fields into a single attribute. Transformation mapping is often appropriate when values from multiple fields are used to create an object.

Implementing transformation mappings in Java

Transformation mappings are instances of the TransformationMapping class. The following elements are typically required for a mapping:

• The attribute mapped, set by sending the setAttributeName() message; not required for write-only mappings

• The method to be invoked that sets the value of the attribute from information in the database row; set by sending the setAttributeTransformation() message that expects one or two parameters, a DatabaseRow and optionally a Session

• A set of methods associated to fields in the database, where the value for each field is the result of invoking the associated method; associations are made by sending the addFieldTransformation() message, passing along the database field name and the method name

The optional setGetMethodName() and setSetMethodName() messages allow TopLink to access the attribute through user-defined methods rather than directly.

Example 7-7 Creating a transformation mapping and registering it with the descriptor.

This particular example provides custom support for two of the fields number of fields can be mapped using this approach.

// Create a new mapping and register it with the descriptor.
TransformationMapping transformation1 = new TransformationMapping();
transformation1.setAttributeName ("dateAndTimeOfBirth");
transformation1.setAttributeTransformation ("buildDateAndTime");
transformation1.addFieldTransformation("B_DAY", "getDateOfBirth");
transformation1.addFieldTransformation("B_TIME", "getTimeOfBirth");
descriptor.addMapping(transformation1);
// Define attribute transformation method to read from the database row
public java.util.Date buildDateAndTime(DatabaseRow row) {

   java.sql.Date sqlDateOfBirth = (java.sql.Date)row.get("B_DAY");
   java.sql.Time timeOfBirth = (java.sql.Time)row.get("B_TIME");
   java.util.Date utilDateOfBirth = new java.util.Date(

      sqlDateOfBirth.getYear(),
      sqlDateOfBirth.getMonth(),
      sqlDateOfBirth.getDate(),
      timeOfBirth.getHours(),
      timeOfBirth.getMinutes(),
      timeOfBirth.getSeconds());

   return utilDateOfBirth;

}

// Define a field transformation method to write to the database
public java.sql.Time getTimeOfBirth()
{

   return new java.sql.Time this.dateAndTimeOfBirth.getHours(), 
   this.dateAndTimeOfBirth.getMinutes(), this.dateAndTimeOfBirth.getSeconds()); 

}

// Define a field transformation method to write to the database
public java.sql.Date getDateOfBirth()
{

   return new java.sql.DateOfBirth this.dateAndTimeOfBirth.getYear(), 
   this.dateAndTimeOfBirth.getMonth(), this.dateAndTimeOfBirth.getDate());
}

Example 7-8 Creating a transformation mapping using indirection

// Create a new mapping and register it with the descriptor.
TransformationMapping transformation2 = new 
transformation2.setAttributeName("designation");
transformation2.setGetMethodName ("getDesignationHolder");
transformation2.setSetMethodName ("setDesignationHolder");
transformation2.setAttributeTransformation ("getRankFromRow");
transformation2.addFieldTransformation("RANK", "getRankFromObject");
transformation2.useIndirection();
descriptor.addMapping(transformation2);

//Define an attribute transformation method to read from database row.
public String getRankFromRow() 
{

   Integer value = new Integer(((Number)row.get("RANK)).intValue());
   String rank = null;
   if (value.intValue() == 1) {

      rank = "Executive";

   }
   if (value.intValue() == 2) {

      rank = "Non-Executive";

   }
   return rank;

}
//Define a field transformation method to write to the database.
public Integer getRankFromObject()
{

   Integer rank = null;

   if (getDesignation().equals("Executive"))

   rank = new Integer(1);
   if (getDesignation().equals("Non-Executive"))

   rank = new Integer(2);
   return rank;

}

//Provide accessor methods for the indirection.
private ValueHolderInterface designation;
public ValueHolderInterface getDesignationHolder()
{

   return designation;

}
public void setDesignationHolder(ValueHolderInterface value)
{

   designation = value;

}

Reference

Table 7-5 summarizes the most common public methods for transformation mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for transformation mapping, see the TopLink JavaDocs.

Table 7-5 Elements for transformation mapping  

setAttributeName(String name)

addFieldTransformation(String fieldName, 
String methodName)
setAttributeTransformation(String 
methodName)

Relationship mappings

Relational mappings define how persistent objects reference other persistent objects. These mappings include all of the following:

• Aggregate object mappings

• One-to-one mappings

• Variable one-to-one mappings

• Direct collection mappings

• Direct map mappings

• One-to-many mappings

• Many-to-many mappings

Aggregate object mappings

Aggregate object mappings are instances of the AggregateObjectMapping class. This mapping is associated to an attribute in each of the parent classes. The following elements are required for an aggregate object mapping to be viable:

• The attribute mapped, set by sending the setAttributeName() message

• The target (child) class, set by sending the setReferenceClass() message

The optional setGetMethodName() and setSetMethodName() messages allow TopLink to access the attribute through user-defined methods rather than directly.

By default the mapping allows null references to its target class, so it does not create an instance of the target object. To prevent a parent from having a null reference, send the dontAllowNull() message, which results in an instance of the child with its attributes set to null.

The following modifications to the target (child) class descriptor are required:

• an indication that all information will come from its parent's row(s); this is accomplished by sending the descriptorIsAggregate() message to the descriptor

• no table or primary key information

Example 7-9 Creating an aggregate object mapping for the Employee source class and registering it with the descriptor.

// Create a new mapping and register it with the source descriptor.
AggregateObjectMapping aggregateMapping = new AggregateObjectMapping();
aggregateMapping.setAttributeName("employPeriod");
aggregateMapping.setReferenceClass(Period.class);
descriptor.addMapping(aggregateMapping);

Example 7-10 Creating the descriptor of the Period aggregate target class.

The aggregate target descriptor does not need a mapping to its parent, and does not need any table or primary key information.

// Create a descriptor for the aggregate class. The table name and primary key 
are not specified in the aggregate descriptor.
Descriptor descriptor = new Descriptor();
descriptor.setJavaClass(Period.class);
descriptor.descriptorIsAggregate();

// Define the attribute mappings or relationship mappings.
descriptor.addDirectMapping("startDate", "START_DATE");
descriptor.addDirectMapping("endDate", "END_DATE");
return descriptor;

Example 7-11 Creating an aggregate object mapping for the Project which is another source class that contains a Period.

The field names must be translated in the Project descriptor as shown in Table 7-1. No changes need to be made to the Period class descriptor to implement this second parent.

// Create a new mapping and register it with the parent descriptor.
AggregateObjectMapping aggregateMapping = new AggregateObjectMapping();
aggregateMapping.setAttributeName("projectPeriod");
aggregateMapping.setReferenceClass(Period.class);
aggregateMapping.addFieldNameTranslation("S_DATE", "START_DATE");
aggregateMapping.addFieldNameTranslation("E_DATE", "END_DATE");
descriptor.addMapping(aggregateMapping);

Reference

Table 7-6 summarizes the most common public methods for aggregate object mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for aggregate object mapping, see the TopLink JavaDocs.

Table 7-6 Elements for aggregate object mapping  

setAttributeName(String name)

setReferenceClass(Class aClass)

One-to-one mappings

One-to-one mappings, are instances of the OneToOneMapping() class, that require the following:

• The attribute mapped, set by sending the setAttributeName() message

• The reference class, set by sending the setReferenceClass() message

• Foreign key information, normally specified by sending the setForeignKeyFieldName() message and passing the foreign key field from the source table that references the primary key of the target table.

  Note: If the target primary key is composite, send the addForeignKeyFieldName() message for each of the foreign fields and target primary key fields that make up the relationship.

If the mapping has a bi-directional relationship where the two classes in the relationship reference each other with one-to-one mappings, then to properly set up the foreign key information:

• One mapping must send the setForeignKeyFieldName() message.

• The other must send the setTargetForeignKeyFieldName() message.

It is also possible to set up composite foreign key information by sending the addForeignKeyFieldName() and addTargetForeignKeyFieldName() messages.

Example 7-12 Creating a simple one-to-one mapping and registering it with the descriptor.

// Create a new mapping and register it with the descriptor.
OneToOneMapping oneToOneMapping = new OneToOneMapping();
oneToOneMapping.setAttributeName("address");
oneToOneMapping.setReferenceClass(Address.class);
oneToOneMapping.setForeignKeyFieldName("ADDRESS_ID");
descriptor.addMapping(oneToOneMapping);

Example 7-13 Implementing a bidirectional mapping between two classes that reference each other.

The foreign key is stored in the Policy's table referencing the composite primary key of the Carrier.

// In the Policy class, which will hold the foreign key, create the mapping 
which references the Carrier class.
OneToOneMapping carrierMapping = new OneToOneMapping();
carrierMapping.setAttributeName("carrier");
carrierMapping.setReferenceClass(Carrier.class);
carrierMapping.addForeignKeyFieldName("INSURED_ID", "CARRIER_ID");
carrierMapping.addForeignKeyFieldName("INSURED_TYPE", "TYPE");
descriptor.addMapping(carrierMapping);. . .
// In the Carrier class, create the mapping which references the Policy class.
OneToOneMapping policyMapping = new OneToOneMapping();
policyMapping.setAttributeName("masterPolicy");
policyMapping.setReferenceClass(Policy.class);
policyMapping.addTargetForeignKeyFieldName("INSURED_ID", "CARRIER_ID");
policyMapping.addTargetForeignKeyFieldName("INSURED_TYPE", "TYPE");
descriptor.addMapping(policyMapping);

Reference

Table 7-7 summarizes the most common public methods for one-to-one mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for one-to-one mapping, see the TopLink JavaDocs.

Table 7-7 Elements for one-to-one mapping  

setAttributeName(String name)

addForeignKeyFieldName(

String foreignKeyFieldName, 

String targetKeyFieldName)

setReferenceClass(Class referenceClass)

Variable one-to-one mappings

Variable one-to-one mappings are instances of the VariableOneToOneMapping() class. The following elements are required for a variable one-to-one mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The reference class, set by sending the setReferenceClass() message

• Foreign key and target query key information, normally specified by sending the setForeignQueryKeyName() message and passing the source foreign key field name and the target abstract query key name on the interface descriptor.

  Note: If the target implementor descriptors' primary keys are composite, send the addForeignQueryKeyName() message for each of the foreign key fields and target query keys that make up the relationship.

If the mapping uses a class indicator field:

• A type indicator field must be specified.

• The class indicator values are specified on the mapping so that mapping can determine the class of object to create.

  Note: Indirection is enabled by default, requiring that the attribute be a ValueHolderInterface.

Example 7-14 Defining a variable one-to-one mapping using a class indicator field.

VariableOneToOneMapping variableOneToOneMapping = new VariableOneToOneMapping();
variableOneToOneMapping.setAttributeName("contact");
variableOneToOneMapping.setReferenceClass (Contact.class); 
variableOneToOneMapping.setForeignQueryKeyName ("C_ID", "id");
variableOneToOneMapping.setTypeFieldName("TYPE");
variableOneToOneMapping.addClassIndicator(Email.class, "Email");
variableOneToOneMapping.addClassIndicator(Phone.class, "Phone");
variableOneToOneMapping.dontUseIndirection();
variableOneToOneMapping.privateOwnedRelationship();

Example 7-15 Defining a variable one-to-one mapping using a unique primary key

VariableOneToOneMapping variableOneToOneMapping = new VariableOneToOneMapping();
variableOneToOneMapping.setAttributeName("contact");
variableOneToOneMapping.setReferenceClass (Contact.class);
variableOneToOneMapping.setForeignQueryKeyName ("C_ID", "id");
variableOneToOneMapping.dontUseIndirection();
variableOneToOneMapping.privateOwnedRelationship();

Reference

Table 7-8 summarizes the most common public methods for variable one-to-one mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for variable one-to-one mapping, see the TopLink JavaDocs.

Table 7-8 Elements for variable one-to-one mapping  

setAttributeName(String name)

setForeignQueryKeyName(String 
foreignKeyName, String abstractQueryKeyName)
addForeignQueryKeyName(String 
foreignKeyName, String abstractQueryKeyName)

setReferenceClass(Class referenceClass)

readWrite()
readOnly()
setIsReadOnly(boolean isReadOnly)

Direct collection mappings

Direct collection mappings are instances of the DirectCollectionMapping class. The following elements are required for a direct collection mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The database table that holds the values to be stored in the collection, set by sending the setReferenceTableName() message

• The field in the reference table from which the values are read and placed into the collection; this is called the direct field and is set by sending the setDirectFieldName() message

• Foreign key information, which is specified by sending the setReferenceKeyFieldName() message 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, send the addReferenceKeyFieldName() message for each of the fields that make up the key.

Example 7-16 Creating a simple direct collection mapping.

DirectCollectionMapping directCollectionMapping = new DirectCollectionMapping();
directCollectionMapping.setAttributeName ("responsibilitiesList");
directCollectionMapping.setReferenceTableName ("RESPONS");
directCollectionMapping.setDirectFieldName("DESCRIP");
directCollectionMapping.setReferenceKeyFieldName ("EMP_ID");
directCollectionMapping.useCollectionClass (Vector.class); // the default
descriptor.addMapping(directCollectionMapping);

Reference

Table 7-9 summarizes the most common public methods for direct collection mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for direct collection mapping, see the TopLink JavaDocs.

Table 7-9 Elements for direct collection mapping  

setAttributeName(String name)

addReferenceKeyFieldName(String 
referenceKey, String sourceKey)

setDirectFieldName(String fieldName)
setReferenceTableName(String tableName)

useBasicIndirection()
useTransparentCollection()
dontUseIndirection()

setGetMethodName(String name)
setSetMethodName(String name)

useCollectionClass(Class)

Aggregate collections

Aggregate collection mappings are used to represent the aggregate relationship between a single-source object and a collection of target objects. Unlike the TopLink one-to-many mappings, in which there should be a one-to-one back reference mapping from the target objects to the source object, there is no back reference required for the aggregate collection mappings because the foreign key relationship is resolved by the aggregation.

To implement an aggregate collection mapping:

• The descriptor of the target class must declare itself to be an aggregate collection object. Unlike the aggregate object mapping, in which the target descriptor does not have a specific table to associate with, there must be a target table for the target object.

• The descriptor of the source class must add an aggregate collection mapping that specifies the target class.

When to use aggregate collections

Although similar in behavior to 1-many mappings, an aggregate collection is not a replacement for 1-many mappings, and great care should be exercised when choosing an aggregate collection over a one-to-many mapping. aggregate collections should only be used in situations where the target collections are reasonable in size and having a one-to-one mapping from the target to the source is difficult.

Consider using a one-to-many relationship rather than an aggregate collection, because one-to-many relationships offer better performance and are more robust and scalable.

In addition, aggregate collections are privately owned by the source of the relationship and should not be shared or referenced by other objects.

Aggregate collections and inheritance

Aggregate collection descriptors can make use of inheritance. The subclasses must also be declared as aggregate collection. The subclasses can have their own mapped tables, or share the table with their parent class.

In a Java Vector, the owner references its parts. In a relational database, the parts reference their owners. Relational databases use this implementation to make querying more efficient.

Java implementation

Aggregate collection mappings are instances of the AggregateCollectionMapping class. The following elements are required for an aggregate collection mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The reference class, set by sending the setReferenceClass() message.

• Foreign key information, which is specified by sending the addTargetForeignKeyFieldName() message and passing the field name of the target foreign key and the source the primary key in the source table.

  Notes: If the source primary key is composite, send the addTargetForeignKeyFieldName() message to each of the fields that make up the key. Indirection is enabled by default for an aggregate collection mapping, requiring that the attribute implement ValueHolderInterface.

Example 7-17 Creating a simple aggregate collection mapping and registering it with the descriptor

// In the PolicyHolder class, create the mapping which references the Phone 
class
AggregateCollectionMapping phonesMapping = new AggregateCollectionMapping();
phonesMapping.setAttributeName("phones");
phonesMapping.setGetMethodName("getPhones");
phonesMapping.setSetMethodName("setPhones");
phonesMapping.setReferenceClass("Phone.class");
phonesMapping.dontUseIndirection();
phonesMapping.privateOwnedRelationship;
phonesMapping.addTargetForeignKeyFieldName ("INS_PHONE.HOLDER_
SSN","HOLDER.SSN");
descriptor.addMapping(phonesMapping);

Reference

Table 7-10 summarizes the most common public methods for aggregate collection mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for aggregate collection mapping, see the TopLink JavaDocs.

Table 7-10 Properties for aggregate collection mapping  

setAttributeName(String name)

addTargetForeignKeyFieldName (String 
targetForeignKeyFieldName, String 
sourceKeyFieldName)

setReferenceClass(Class aClass)

useBasicIndirection()
useTransparentCollection()
dontUseIndirection()

setGetMethodName(String name)
setSetMethodName(String name)

privateOwnedRelationship()

useCollectionClass(Class)

Direct map mappings

Direct map mappings store instances that implement java.util.Map. Unlike one-to-manys or many to manys, the keys and values of the map in this type of mapping are Java objects that do not have descriptors. The object type stored in the key and the value of direct map are Java primitive wrapper types such as String objects.

Support for primitive data types such as int is not provided since Java maps only hold objects.

Direct map mappings are instances of the DirectMapMapping class. The following elements are required for a direct map mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The database table that holds the keys and values to be stored in the map, set by sending the setReferenceTableName() message

• The field in the reference table from which the keys are read and placed into the map; this is called the direct key field and is set by sending the setDirectKeyFieldName() message

• Foreign key information, which is specified by sending the setReferenceKeyFieldName() message 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, you must send the addReferenceKeyFieldName() message for each of the fields that make up the key

• The field in the reference table from which the values are read and placed into the map; this is called the direct field and is set by sending the setDirectFieldName() message

• The Java type of key in map from which the keys are converted from keys read from the database placed into the map; this is set by sending the setKeyClass() message

• The Java type of value in map from which the values are converted from values read from the database placed into the map; this is set by sending the setValueClass() message

Example 7-18 Creating a simple direct map mapping.

DirectMapMapping directMapMapping = new DirectMapMapping();
directMapMapping.setAttributeName("cities");
directMapMapping.setReferenceTableName("CITY_TEMP");
directMapMapping.setReferenceKeyFieldName("RECORD_ID");
directMapMapping.setDirectKeyFieldName("CITY");
directMapMapping.setDirectFieldName("TEMPERATURE");
directMapMapping.setKeyClass(String.class);
directMapMapping.setValueClass(Integer.class);

descriptor.addMapping(directMapMapping);

Reference

Table 7-11 summarizes the most common public methods for direct map mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for direct map mapping, see the TopLink JavaDocs.

Table 7-11 Elements for direct map mapping  

setAttributeName(String name)

addReferenceKeyFieldName(String 
referenceKey, String sourceKey)

setDirectFieldName(String fieldName)
setReferenceTableName(String tableName)

useBasicIndirection()
dontUseIndirection()
useTransparentMap()

setGetMethodName(String name)
setSetMethodName(String name)

One-to-many mappings

One-to-many mappings are instances of the OneToManyMapping class. The following elements are required for a one-to-many mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The reference class, set by sending the setReferenceClass() message

• Foreign key information, which is specified by sending the setTargetForeignKeyFieldName() message and passing a field in the target object's associated table that refers to the primary key in the owning object's table.

  Note: If the target primary key is composite, send the addTargetForeignKeyFieldName() message for each of the fields that make up the key.

• A one-to-one mapping in the target class back to the source class; (see "Elements for direct-to-field mapping" for more information)

  Note: Indirection is enabled by default for a one-to-many mapping, requiring that the attribute implement ValueHolderInterface.

Example 7-19 Creating a simple one-to-many mapping and registering it with the descriptor

// In the Employee class, create the mapping which references the Phone class.
oneToManyMapping = new OneToManyMapping();
oneToManyMapping.setAttributeName("phoneNumbers");
oneToManyMapping.setReferenceClass(PhoneNumber.class);
oneToManyMapping.setTargetForeignKeyFieldName("EMPID");
descriptor.addMapping(oneToManyMapping);
. . .
// In the Phone class, which will hold the foreign key, create the mapping which 
references the Employee class.
OneToOneMapping oneToOneMapping = new OneToOneMapping();
oneToOneMapping.setAttributeName("owner");
oneToOneMapping.setReferenceClass(Employee.class);
oneToOneMapping.setForeignKeyFieldName("EMPID");
descriptor.addMapping(oneToOneMapping);

Reference

Table 7-12 summarizes the most common public methods for one-to-many mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for one-to-many mapping, see the TopLink JavaDocs.

Table 7-12 Elements for one-to-many mapping  

setAttributeName(String name)

addTargetForeignKeyFieldName(String 
targetForeignKeyFieldName, 

String sourceKeyFieldName)

setReferenceClass(Class aClass)

useBasicIndirection()
useTransparentCollection()
dontUseIndirection()

setGetMethodName(String name)
setSetMethodName(String name)

privateOwnedRelationship()
setIsPrivateOwned(Boolean 
isPrivateOwned)

useCollectionClass(Class)

Many-to-many mappings

Many-to-many mappings are instances of the ManyToManyMapping class. The following elements are required for a many-to-many mapping:

• The attribute mapped, set by sending the setAttributeName() message

• The reference class, set by sending the setReferenceClass() message

• The relation table, set by sending the setRelationTableName() message

• Foreign key information, which is specified by sending the setSourceRelationKeyFieldName() and setTargetRelationKeyFieldName() messages; if the source or target primary keys are composite, send the addSourceRelationKeyFieldName() or addTargetRelationKeyFieldName() messages

Example 7-20 Code that creates a simple many-to-many mapping

// In the Employee class, create the mapping which references the Project class.
ManyToManyMapping manyToManyMapping = new ManyToManyMapping();
manyToManyMapping.setAttributeName("projects");
manyToManyMapping.setReferenceClass(Project.class);
manyToManyMapping.setRelationTableName("PROJ_EMP");
manyToManyMapping.setSourceRelationKeyFieldName ("EMPID");
manyToManyMapping.setTargetRelationKeyFieldName ("PROJID");
descriptor.addMapping(manyToManyMapping); 

Reference

Table 7-13 summarizes the most common public methods for many-to-many mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for many-to-many mapping, see the TopLink JavaDocs.

Table 7-13 Elements for many-to-many mapping  

setAttributeName(String name)

setReferenceClass(Class aClass)

setRelationTableName(String tableName)

addSourceRelationKeyFieldName(

String sourceRelationKey, String 
sourceKey)
addTargetRelationKeyFieldName(

String targetRelationKey, String 
targetKey)

useBasicIndirection()
useTransparentCollection()
dontUseIndirection()

privateOwnedRelationship()

setGetMethodName(String name)
setSetMethodName(String name)

useCollectionClass(Class)

Object relational mappings

Relational mappings define how persistent objects reference other persistent objects. Object relational mappings allow for an object model to be persisted into an object-relational data-model. TopLink does not directly support these mappings - they must be defined in code through amendment methods.

TopLink enables you to leverage the following object relational mapping types:

• Array mappings

• Object array mappings

• Structure mappings

• Reference mappings

• Nested table mappings

Array mappings

In an object-relational data-model, structures can contain arrays (collections of other data types). These arrays can contain primitive data types or collections of other structures. TopLink stores the arrays with their parent structure in the same table.

TopLink supports arrays of primitive data through the ArrayMapping. This is similar to DirectCollectionMapping - it represents a collection of primitives in Java. However, the ArrayMapping does not require an additional table to store the values in the collection.

Implementing array mappings in Java

Array mappings are instances of the ArrayMapping class. You must associate this mapping to an attribute in the parent class. TopLink requires the following elements for an array mapping:

• Attribute mapped, set by sending the setAttributeName( ) message.

• Field mapped, set by sending the setFieldName() message.

• Name of the array, set by sending the setStructureName() message.

Example 7-21 Creating an array mapping for the Employee source class and registering it with the descriptor

// Create a new mapping and register it with the source descriptor.
ArrayMapping arrayMapping = new ArrayMapping();
arrayMapping.setAttributeName("responsibilities");
arrayMapping.setStructureName("Responsibilities_t");
arrayMapping.setFieldName("RESPONSIBILITIES");
descriptor.addMapping(arrayMapping);

Reference

Table 7-14 summarizes the most common public methods for array mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for array mapping, see the TopLink JavaDocs.

Table 7-14 Elements for array mapping  

Object array mappings

In an object-relational data-model, object arrays allow for an array of object types or structures to be embedded into a single column in a database table or an object table.

Implementing object array mappings in Java

Object array mappings are instances of the ObjectArrayMapping class. You must associate this mapping to an attribute in the parent class. TopLink requires the following elements for an array mapping:

• Attribute mapped, set by sending the setAttributeName() message.

• Field mapped, set by sending the setFieldName() message.

• Name of the array, set by sending the setStructureName () message.

Use the optional setGetMethodName() and setSetMethodName() messages to access the attribute through user-defined methods rather than directly.

Example 7-22 Creating an object array mapping for the Insurance source class and registering it with the descriptor.

// Create a new mapping and register it with the source descriptor.
ObjectArrayMapping phonesMapping = new ObjectArrayMapping();
phonesMapping.setAttributeName("phones");
phonesMapping.setGetMethodName("getPhones");
phonesMapping.setSetMethodName("setPhones");
phonesMapping.setStructureName("PHONELIST_TYPE");
phonesMapping.setReferenceClass(Phone.class);
phonesMapping.setFieldName("PHONES");
descriptor.addMapping(phonesMapping);

Reference

Table 7-15 summarizes the most common public methods for object array mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for object array mapping, see the TopLink JavaDocs.

Table 7-15 Elements for object array mapping  

Structure mappings

In an object-relational data-model, structures are user defined data-types or object-types. This is similar to a Java class - it denies attributes or fields in which each attribute is either:

• a primitive data type

• another structure

• reference to another structure

TopLink maps each structure to a Java class defined in your object model and defines a descriptor for each class. A StructureMapping maps nested structures, similar to an AggregateObjectMapping. However, the structure mapping supports null values and shared aggregates without requiring additional settings (because of the object-relational support of the database).

Implementing structure mappings in Java

Structure mappings are instances of the StructureMapping class. You must associate this mapping to an attribute in each of the parent classes. TopLink requires the following elements for an array mapping:

• Attribute mapped, set by sending the setAttributeName() message.

• Field mapped, set by sending the setFieldName() message.

• Target (child) class, set by sending the setReferenceClass() message.

Use the optional setGetMethodName() and setSetMethodName() messages to access the attribute through user-defined methods rather than directly.

You must make the following changes to the target (child) class descriptor:

• Send the descriptorIsAggregate() message to indicate it is not a root level.

• Remove table or primary key information.

Example 7-23 Creating a structure mapping for the Employee source class and registering it with the descriptor

// Create a new mapping and register it with the source descriptor.
StructureMapping structureMapping = new StructureMapping();
structureMapping.setAttributeName("address");
structureMapping.setReferenceClass(Address.class); 
structureMapping.setFieldName("address");
descriptor.addMapping(structureMapping);

Example 7-24 Creating the descriptor of the Address aggregate target class.

The aggregate target descriptor does not need a mapping to its parent, or any table or primary key information.

// Create a descriptor for the aggregate class. The table name and primary key 
are not specified in the aggregate descriptor.
ObjectRelationalDescriptor descriptor = new ObjectRelationalDescriptor ();
descriptor.setJavaClass(Address.class);
descriptor.setStructureName("ADDRESS_T");
descriptor.descriptorIsAggregate();

// Define the field ordering
descriptor.addFieldOrdering("STREET");
descriptor.addFieldOrdering("CITY");
...

// Define the attribute mappings or relationship mappings.
...

Reference

Table 7-16 summarizes the most common public methods for structure mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for structure mapping, see the TopLink JavaDocs.

Table 7-16 Elements for structure mapping  

Reference mappings

In an object-relational data-model, structures reference each other through refs - not through foreign keys (as in a traditional data-model). Refs are based on the target structure's ObjectID.

TopLink supports refs through the ReferenceMapping. They represent an object reference in Java, similar to a OneToOneMapping. However, the reference mapping does not require foreign key information.

Implementing reference mappings in Java

Reference mappings are instances of the ReferenceMapping class. You must associate this mapping to an attribute in the source class. TopLink requires the following elements for a reference mapping:

• Attribute mapped, set by sending the setAttributeName( ) message.

• Field mapped, set by sending the setFieldName( ) message.

• Target class, set by sending the setRefrenceClass ( ) message.

Use the optional setGetMethodName( ) and setSetMethodName( ) messages to access the attribute through user-defined methods rather than directly.

Example 7-25 Creating a reference mapping for the Employee source class and registering it with the descriptor.

// Create a new mapping and register it with the source descriptor.
ReferenceMapping referenceMapping = new ReferenceMapping();
referenceMapping.setAttributeName("manager");
referenceMapping.setReferenceClass(Employee.class);
referenceMapping.setFieldName("MANAGER");
descriptor.addMapping(refrenceMapping);

Reference

Table 7-17 summarizes the most common public methods for reference mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for reference mapping, see the TopLink JavaDocs.

Table 7-17 Elements for reference mapping  

Nested table mappings

Nested table types model an unordered set of elements. These elements may be built-in or user-defined types. Nested tables typically represent a one-to-many or many-to-many relationship of references to another independent structure. They support querying and joining better than Varrays that are inlined to the parent table.

TopLink supports nested table through the NestedTableMapping. They represent a collection of object references in Java, similar to a OneToManyMapping or ManyToManyMapping. However, the nested table mapping does not require foreign key information (like a one-to-many mapping) or the relational table (like a many-to-many mapping).

Implementing nested table mappings in Java

Nested table mappings are instances of the NestedTableMapping class. This mapping is associated to an attribute in the parent class. The following elements are required for a nested table mapping to be viable:

• The attribute mapped, set by sending the setAttributeName() message

• The field mapped, set by sending the setFieldName() message

• The name of the array structure, set by sending the setStructureName() message

Use the optional setGetMethodName() and setSetMethodName() messages to allow TopLink to access the attribute through user-defined methods rather than directly.

Example 7-26 Creating a nested table mapping for the Insurance source class and registering it with the descriptor.

// Create a new mapping and register it with the source descriptor.
NestedTableMapping policiesMapping = new NestedTableMapping();
policiesMapping.setAttributeName("policies");
policiesMapping.setGetMethodName("getPolicies");
policiesMapping.setSetMethodName("setPolicies");
policiesMapping.setReferenceClass(Policy.class);
policiesMapping.dontUseIndirection();
policiesMapping.setStructureName("POLICIES_TYPE");
policiesMapping.setFieldName("POLICIES");
policiesMapping.privateOwnedRelationship();
policiesMapping.setSelectionSQLString("select p.* from policyHolders ph, 
table(ph.policies) t, policies p where ph.ssn=#SSN and ref(p) = value(t)");
descriptor.addMapping(policiesMapping);

Reference

Table 7-18 summarizes the most common public methods for nested table mapping:

• the Default column describes default settings of the descriptor element

• in the Method Names column, arguments are bold, methods are not

For a complete description of all available methods for nested table mapping, see the TopLink JavaDocs.

Table 7-18 Elements for nested table mapping