Skip Headers

Oracle9iAS TopLink Mapping Workbench Reference Guide
Release 2 (9.0.3)

Part Number B10063-01
Go To Documentation Library
Home
Go To Solution Area
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

7
Understanding Object Relational Mappings

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

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:

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:

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:

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)

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:

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)

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:

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:

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:

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)

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:

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)

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:

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)


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Solution Area
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index