7
Understanding Object Relational Mappings

Relational mappings define how persistent objects reference other persistent objects. Oracle9iAS TopLink supports the following object relational mapping types:

• Array mappings are similar to direct collection mappings but map to object-relational array data-types (the Array type in JDBC 2.0 and the VARRAY type in Oracle8i). Use array mappings to map a collection of primitive data. See "Working with Array Mappings" for more information.

• Object array mappings are similar to array mappings but map to object-relational array data types. See "Working with Object Array Mappings" for more information.

• Structure mappings are similar to aggregate object mappings but map to object-relational aggregate structures (the Struct type in JDBC 2.0 and the OBJECT TYPE in Oracle8i). See "Working with Structure Mappings" for more information.

• Reference mappings are similar to one-to-one mappings but map to object-relational references (the Ref type in JDBC 2.0 and the REF type in Oracle8i). See "Working with Reference Mappings" for more information.

• Nested table mappings are similar to many-to-many mappings but map to object-relational nested tables (the NESTED TABLE type in Oracle8i). See "Working with Nested Table Mappings" for more information.

These mappings allow for an object model to be persisted into an object-relational data-model. Currently the Mapping Workbench does not support object-relational mappings - they must be defined in code or through amendment methods. See "Working with Object-relational Descriptors" for more information.

Working with Object Relational Mappings

Object relational mappings allow for an object model to be persisted into an object-relational data-model. The Mapping Workbench does not directly support these mappings - they must be defined in code through amendment methods.

TopLink supports the following object relational mappings:

• Array

• Object array

• Structure

• Reference

• Nested table

Working with 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.

All elements in the array must be the same data type. The number of elements in an array controls the size of the array. An Oracle database allows arrays of variable sizes (called Varrays).

Oracle8i provides two collection types:

• Varray - Used to represent a collection of primitive data or aggregate structures.

• Nested table - Similar to varrays except they store information in a separate table from the parent structure's 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.

TopLink supports arrays of aggregate structures through the ObjectArrayMaping.

TopLink supports nested tables through the NestedTableMapping.

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 being mapped - Set by sending the setAttributeName( ) message.

• Field being mapped - Set by sending the setFieldName( ) message.

• Name of the array - Set by sending the setStructureName( ) message.

Table 7-1 summarizes all array mapping properties:

Example 7-1 Array Mapping Example

The following code example illustrates 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

The following table summarizes all array mapping properties. In the Method Names column, arguments are bold, methods are not.

Table 7-1 Properties for ArrayMapping methods 

Property	Default	Method Names
Attribute to be mapped *	not applicable	setAttributeName(String name)
Set parent class *	not applicable	setReferenceClass(Class referenceClass)
User-defined data type *	not applicable	setStructureName(String Structurename)
Field to be mapped *	not applicable	setFieldName(String fieldName)
Method access	direct access	setGetMethodName(String name) setSetMethodName(String name)
Read only	read / write	readWrite() readOnly() setIsReadOnly(boolean readOnly)
* Required property

Working with 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.

TopLink supports object array mappings to define a collection-aggregated relationship in which the target objects share the same row as the source object.

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 being mapped - Set by sending the setAttributeName( ) message.

• Field being 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. See "Specifying Direct Access and Method Access" for more information.

Table 7-2 summarizes all object array mapping properties.

Example 7-2 Object Array Mapping Example

The following code example illustrates 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

The following table summarizes all object array mapping properties. In the Method Names column, arguments are bold, methods are not.

Table 7-2 Properties for ObjectArrayMapping Methods 

Property	Default	Method Names
Attribute to be mapped *	not applicable	setAttributeName(String name)
Set parent class *	not applicable	setReferenceClass(Class referenceClass)
User-defined data type *	not applicable	setStructureName(String structureName)
Field to be mapped *	not applicable	setFieldName(String fieldName)
Method access	direct access	setGetMethodName(String name) setSetMethodName(String name)
Read only	read / write	readWrite() readOnly() setIsReadOnly(boolean readOnly)
* Required property

Working with 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 being mapped - Set by sending the setAttributeName( ) message.

• Field being 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. See "Specifying Direct Access and Method Access" for more information.

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.

Table 7-3 summarizes all structure mapping properties:

Example 7-3 Structure Mapping Examples

The following code example illustrates 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);

The following code example illustrates 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

The following table summarizes all structure mapping properties. In the Method Names column, arguments are bold, methods are not.

Table 7-3 Properties for StructureMapping Methods 

Property	Default	Method Names
Attribute to be mapped *	not applicable	setAttributeName(String name)
Set parent class *	not applicable	setReferenceClass(Class aClass)
Field to be mapped *	not applicable	setFieldName(String fieldName)
Method access	direct access	setGetMethodName(String name) setSetMethodName(String name)
Read only	read / write	readWrite() readOnly() setIsReadOnly(boolean readOnly)
* Required property

Working with 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 being mapped - Set by sending the setAttributeName( ) message.

• Field being mapped - Set by sending the setFieldName( ) message.

• Target 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. See "Specifying Direct Access and Method Access" for more information.

Table 7-4 summarizes all reference mapping properties.

Example 7-4 Reference Mapping Example

The following code example illustrates 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 refrenceMapping = new ReferenceMapping();
referenceMapping.setAttributeName("manager");
referenceMapping.setReferenceClass(Employee.class);
referenceMapping.setFieldName("MANAGER");
descriptor.addMapping(refrenceMapping);

Reference

The following table summarizes all reference mapping properties. In the Method Names column, arguments are bold, methods are not.

Table 7-4 Properties for ReferenceMapping Methods 

Property	Default	Method Names
Attribute to be mapped *	not applicable	setAttributeName(String name)
Set parent class *	not applicable	setReferenceClass(Class aClass)
Field to be mapped *	not applicable	setFieldName(String fieldName)
Method access	direct access	setGetMethodName(String name) setSetMethodName(String name)
Indirection	use indirection	useBasicIndirection() dontUseIndirection()
Privately owned relationship	independent	independentRelationship() privateOwnedRelationship() setIsPrivateOwned(boolean isPrivateOwned)
Read only	read / write	readWrite() readOnly() setIsReadOnly(boolean readOnly)
* Required property

Working with Nested Table Mappings

Nested table types model an unordered set of elements. These elements may be built-in or user-defined types. You can view a nested table as a single-column table or, if the nested table is an object type, as a muticolumn table (with a column for each attribute of the object type).

Typically, nested tables 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 being mapped, which is set by sending the setAttributeName() message

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

• The name of the array structure, which is 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. See "Specifying Direct Access and Method Access" for more information.

Table 7-5 summarizes all nested table mapping properties.

Example 7-5 Nested Table Example

The following code example illustrates 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

The following table summarizes all nested table mapping properties. In the Method Names column, arguments are bold, methods are not.

Table 7-5 Properties for NestedTableMapping Methods  

Property	Default	Method Names
Attribute to be mapped *	not applicable	setAttributeName(String name)
Set parent class *	not applicable	setReferenceClass(Class referenceClass)
User-defined data type *	not applicable	setStructureName(String structureName)
Field to be mapped *	not applicable	setFieldName(String fieldName)
Method access	direct access	setGetMethodName(String name) setSetMethodName(String name)
Indirection	use indirection	useIndirection() dontUseIndirection() setUsesIndirection(boolean usesIndirection)
Privately owned relationship	independent	independentRelationship() privateOwnedRelationship() setIsPrivateOwned(Boolean isPrivateOwned)
Read only	read / write	readWrite() readOnly() setIsReadOnly(boolean readOnly)
* Required property