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 defines attributes or fields in which each attribute is either:

A primitive data type
Another structure
Reference to another structure

OracleAS TopLink maps each structure to a Java class defined in your object model and defines a descriptor for each class. A StructureMapping class maps nested structures, similar to an AggregateObjectMapping class. 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. OracleAS TopLink requires the following elements for structure 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" on page 4-71 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
* Required property
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)`