Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Configuring a Relational Direct Collection Mapping (ELUG)"

m (Introduction to Relational Direct Collection Mapping Configuration)
m
Line 6: Line 6:
  
 
For information on how to create EclipseLink mappings, see [[Creating%20a%20Mapping%20(ELUG)|Creating a Mapping]].
 
For information on how to create EclipseLink mappings, see [[Creating%20a%20Mapping%20(ELUG)|Creating a Mapping]].
 
[[#Table 41-1|Configurable Options for Relational Direct Collection Mapping]] lists the configurable options for a relational direct collection mapping.
 
 
 
 
==Introduction to Relational Direct Collection Mapping Configuration==
 
  
 
This table lists the configurable options for a relational direct collection mapping.
 
This table lists the configurable options for a relational direct collection mapping.
Line 17: Line 11:
  
 
<span id="Table 41-1"></span>
 
<span id="Table 41-1"></span>
''''' Configurable Options for Relational Direct Collection Mapping'''''
 
  
 
{| class="RuleFormalMax" dir="ltr" title="Configurable Options for Relational Direct Collection Mapping" summary="This table lists the configurable options for direct collection mappings and categorizes them as Basic and Advanced and indicates if the option can be configured with the EclipseLink Workbench, Java, or both." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormalMax" dir="ltr" title="Configurable Options for Relational Direct Collection Mapping" summary="This table lists the configurable options for direct collection mappings and categorizes them as Basic and Advanced and indicates if the option can be configured with the EclipseLink Workbench, Java, or both." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 26: Line 19:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t2" headers="r1c1-t2" align="left" |
 
| id="r2c1-t2" headers="r1c1-t2" align="left" |
Target table (see [[#Configuring Target Table]])
+
[[#Configuring Target Table|Target table]]
 
| headers="r2c1-t2 r1c2-t2" align="left" |
 
| headers="r2c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 33: Line 26:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t2" headers="r1c1-t2" align="left" |
 
| id="r3c1-t2" headers="r1c1-t2" align="left" |
Direct value field (see [[#Configuring Direct Value Field]])
+
[[#Configuring Direct Value Field|Direct value field ]]
 
| headers="r3c1-t2 r1c2-t2" align="left" |
 
| headers="r3c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 40: Line 33:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t2" headers="r1c1-t2" align="left" |
 
| id="r4c1-t2" headers="r1c1-t2" align="left" |
Method or direct field access (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring a Type Conversion Converter]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring Method or Direct Field Accessing at the Mapping Level|Method or direct field access ]]
 
| headers="r4c1-t2 r1c2-t2" align="left" |
 
| headers="r4c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 47: Line 40:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t2" headers="r1c1-t2" align="left" |
 
| id="r5c1-t2" headers="r1c1-t2" align="left" |
Read-only mapping (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring Read-Only Mappings]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring Read-Only Mappings|Read-only mapping ]]
 
| headers="r5c1-t2 r1c2-t2" align="left" |
 
| headers="r5c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 54: Line 47:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t2" headers="r1c1-t2" align="left" |
 
| id="r6c1-t2" headers="r1c1-t2" align="left" |
Batch reading (see [[Configuring%20a%20Relational%20Mapping%20(ELUG)|Configuring Batch Reading]])
+
[[Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring Batch Reading|Batch reading ]]
 
| headers="r6c1-t2 r1c2-t2" align="left" |
 
| headers="r6c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 61: Line 54:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r7c1-t2" headers="r1c1-t2" align="left" |
 
| id="r7c1-t2" headers="r1c1-t2" align="left" |
Indirection (lazy loading) (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring Mapping Comments]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring Indirection (Lazy Loading)|Indirection (lazy loading)]]
 
| headers="r7c1-t2 r1c2-t2" align="left" |
 
| headers="r7c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 68: Line 61:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r8c1-t2" headers="r1c1-t2" align="left" |
 
| id="r8c1-t2" headers="r1c1-t2" align="left" |
Container policy (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring Mapping Comments]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring Container Policy|Container policy ]]
 
| headers="r8c1-t2 r1c2-t2" align="left" |
 
| headers="r8c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 75: Line 68:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r9c1-t2" headers="r1c1-t2" align="left" |
 
| id="r9c1-t2" headers="r1c1-t2" align="left" |
Mapping comments (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring Mapping Comments]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring Mapping Comments|Mapping comments ]]
 
| headers="r9c1-t2 r1c2-t2" align="left" |
 
| headers="r9c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 82: Line 75:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r10c1-t2" headers="r1c1-t2" align="left" |
 
| id="r10c1-t2" headers="r1c1-t2" align="left" |
Serialized object converter (see [[Configuring%20a%20Mapping%20(ELUG)#Configuring a Serialized Object Converter|Configuring a Serialized Object Converter]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring a Serialized Object Converter|Configuring a Serialized Object Converter]]
 
| headers="r10c1-t2 r1c2-t2" align="left" |
 
| headers="r10c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 89: Line 82:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r11c1-t2" headers="r1c1-t2" align="left" |
 
| id="r11c1-t2" headers="r1c1-t2" align="left" |
Type conversion converter (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring a Type Conversion Converter]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring a Type Conversion Converter|Type conversion converter ]]
 
| headers="r11c1-t2 r1c2-t2" align="left" |
 
| headers="r11c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 96: Line 89:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r12c1-t2" headers="r1c1-t2" align="left" |
 
| id="r12c1-t2" headers="r1c1-t2" align="left" |
Object type converter (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring an Object Type Converter]])
+
[[Configuring%20a%20Mapping%20(ELUG)#Configuring an Object Type Converter|Object type converter ]]
 
| headers="r12c1-t2 r1c2-t2" align="left" |
 
| headers="r12c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 103: Line 96:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r13c1-t2" headers="r1c1-t2" align="left" |
 
| id="r13c1-t2" headers="r1c1-t2" align="left" |
Table and field references (see [[Configuring%20a%20Relational%20Mapping%20(ELUG)|Configuring Joining at the Mapping Level]])
+
[[Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring Table and Field References (Foreign and Target Foreign Keys)|Table and field references ]]
 
| headers="r13c1-t2 r1c2-t2" align="left" |
 
| headers="r13c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported]]
 
[[Image:support.gif|Supported]]
Line 129: Line 122:
  
 
For more information, see the following:
 
For more information, see the following:
 
 
* [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct Collection Mapping|Direct Collection Mapping]]
 
* [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct Collection Mapping|Direct Collection Mapping]]
 
* [[Configuring%20a%20Relational%20Mapping%20(ELUG)|Configuring a Relational Mapping]]
 
* [[Configuring%20a%20Relational%20Mapping%20(ELUG)|Configuring a Relational Mapping]]
Line 136: Line 128:
  
 
For information on using JPA to configure direct collection mappings, see [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How to Use the @BasicCollection Annotation|How to Use the @BasicCollection Annotation]].
 
For information on using JPA to configure direct collection mappings, see [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How to Use the @BasicCollection Annotation|How to Use the @BasicCollection Annotation]].
 +
 +
  
 
==Configuring Target Table==
 
==Configuring Target Table==
 
+
Each direct collection stores reference information in a target table. In the [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Figure 32-6|Direct Collection Mappings]] figure, the <tt>RESPONS</tt> table contains the primary key and object of the instance owning the collection. You must create this table in your database.
Each direct collection stores reference information in a target table. In [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Figure 32-6|Figure 32-6]], the <tt>RESPONS</tt> table contains the primary key and object of the instance owning the collection. You must create this table in your database.
+
  
  
  
 
===How to Configure a Target Table Using Workbench===
 
===How to Configure a Target Table Using Workbench===
 
 
To specify the direct collection specifics, use this procedure:
 
To specify the direct collection specifics, use this procedure:
 
 
# Select the mapped attribute in the '''Navigator'''. Its properties appear in the Editor.
 
# Select the mapped attribute in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''General''' tab. The General tab appears.<br><span id="Figure 41-1"></span>'''''General Tab, Target Table Options'''''<br>[[Image:dcmaptar.gif|General Tab, Target Table Options]]
 
# Click the '''General''' tab. The General tab appears.<br><span id="Figure 41-1"></span>'''''General Tab, Target Table Options'''''<br>[[Image:dcmaptar.gif|General Tab, Target Table Options]]
Line 156: Line 147:
  
 
===How to Configure a Target Table Using Java===
 
===How to Configure a Target Table Using Java===
 
 
Direct collection mappings store collections of Java objects that are not EclipseLink-enabled. Direct collections usually store Java types, such as <tt>String</tt>.
 
Direct collection mappings store collections of Java objects that are not EclipseLink-enabled. Direct collections usually store Java types, such as <tt>String</tt>.
  
 
Direct collection mappings are instances of the <tt>DirectCollectionMapping</tt> class and require the following elements:
 
Direct collection mappings are instances of the <tt>DirectCollectionMapping</tt> class and require the following elements:
 
 
* The attribute mapped, set by using the <tt>setAttributeName</tt> method.
 
* The attribute mapped, set by using the <tt>setAttributeName</tt> method.
 
* The database table that holds the values to be stored in the collection, set by using the <tt>setReferenceTableName</tt> method.
 
* The database table that holds the values to be stored in the collection, set by using the <tt>setReferenceTableName</tt> method.
Line 186: Line 175:
 
  }
 
  }
  
In addition to the API that [[#Example 41-1|Configuring a Simple Direct Collection Mapping]] illustrates, other common API for use with direct collection mappings include the following:
+
In addition to the API that the  [[#Example 41-1|Configuring a Simple Direct Collection Mapping]] example illustrates, other common API for use with direct collection mappings include the following:
 
+
 
+
 
+
 
* <tt>useBasicIndirection</tt><nowiki>: implements EclipseLink value holder indirection.</nowiki>
 
* <tt>useBasicIndirection</tt><nowiki>: implements EclipseLink value holder indirection.</nowiki>
 
* <tt>useTransparentCollection</tt><nowiki>: if you use transparent indirection, this element places a special collection in the source object's attribute.</nowiki>
 
* <tt>useTransparentCollection</tt><nowiki>: if you use transparent indirection, this element places a special collection in the source object's attribute.</nowiki>
Line 195: Line 181:
  
 
For more information about the available methods for <tt>DirectCollectionMapping</tt>, see the ''EclipseLink API Reference''.
 
For more information about the available methods for <tt>DirectCollectionMapping</tt>, see the ''EclipseLink API Reference''.
 +
 +
  
 
==Configuring Direct Value Field==
 
==Configuring Direct Value Field==
 
+
The direct value field, located in the reference table, stores the primitive data value. In the [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Figure 32-6|Direct Collection Mappings]] figure, the <tt>DESCRIP</tt> field stores the collection.
The direct value field, located in the reference table, stores the primitive data value. In [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Figure 32-6|Figure 32-6]], the <tt>DESCRIP</tt> field stores the collection.
+
  
  
  
 
===How to Configure a Direct Value Field Using Workbench===
 
===How to Configure a Direct Value Field Using Workbench===
 
 
To specify the direct collection specifics, use this procedure:
 
To specify the direct collection specifics, use this procedure:
 
 
# Select the mapped attribute in the '''Navigator'''. Its properties appear in the Editor.
 
# Select the mapped attribute in the '''Navigator'''. Its properties appear in the Editor.
 
# Click the '''General''' tab. The General tab appears.<br><span id="Figure 41-2"></span>''''' General Tab, Direct Value Field'''''<br>[[Image:dcmapdir.gif|General Tab, Direct Value Field]]
 
# Click the '''General''' tab. The General tab appears.<br><span id="Figure 41-2"></span>''''' General Tab, Direct Value Field'''''<br>[[Image:dcmapdir.gif|General Tab, Direct Value Field]]
 
+
#Use the '''Direct Value Field''' list to select the field from the '''Target Table''' table that contains the object of the collection.
Use the '''Direct Value Field''' list to select the field from the '''Target Table''' table that contains the object of the collection.
+
  
  
Line 215: Line 199:
  
 
===How to Configure Direct Value Field Using Java===
 
===How to Configure Direct Value Field Using Java===
 
+
The [[#Example 41-1|Configuring a Simple Direct Collection Mapping]] example demonstrates how to create and configure a direct collection mapping, including the setting of a direct field. The example also shows how to add this mapping to the descriptor.
[[#Example 41-1|Configuring a Simple Direct Collection Mapping]] demonstrates how to create and configure a direct collection mapping, including the setting of a direct field. The example also shows how to add this mapping to the descriptor.
+
  
  
Line 226: Line 209:
 
[[Category: Draft]]
 
[[Category: Draft]]
 
[[Category: Task]]
 
[[Category: Task]]
 +
[[Category: ORM]]

Revision as of 08:11, 17 December 2007

This section describes the various components that you must configure in order to use a relational direct collection mapping.

For information on how to configure EclipseLink mappings options common to two or more mapping types, see Configuring a Mapping.

For information on how to create EclipseLink mappings, see Creating a Mapping.

This table lists the configurable options for a relational direct collection mapping.


Option Workbench Java

Target table

Supported

Supported

Direct value field

Supported

Supported

Method or direct field access

Supported

Supported

Read-only mapping

Supported

Supported

Batch reading

Supported

Supported

Indirection (lazy loading)

Supported

Supported

Container policy

Supported

Supported

Mapping comments

Supported

Supported

Configuring a Serialized Object Converter

Supported

Supported

Type conversion converter

Supported

Supported

Object type converter

Supported

Supported

Table and field references

Supported

Supported


This example shows how to create a direct collection mapping and add it to a descriptor using Java code.

Direct Collection Mapping

public void customize(ClassDescriptor descriptor) { 
    DirectCollectionMapping mapping = new DirectCollectionMapping();  

    // configure mapping
    ... 

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

For more information, see the following:


For information on using JPA to configure direct collection mappings, see How to Use the @BasicCollection Annotation.


Configuring Target Table

Each direct collection stores reference information in a target table. In the Direct Collection Mappings figure, the RESPONS table contains the primary key and object of the instance owning the collection. You must create this table in your database.


How to Configure a Target Table Using Workbench

To specify the direct collection specifics, use this procedure:

  1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.
  2. Click the General tab. The General tab appears.
    General Tab, Target Table Options
    General Tab, Target Table Options

Use the Target Table list to select the table that contains the reference fields for the direct collection mapping.



How to Configure a Target Table Using Java

Direct collection mappings store collections of Java objects that are not EclipseLink-enabled. Direct collections usually store Java types, such as String.

Direct collection mappings are instances of the DirectCollectionMapping class and require the following elements:

  • The attribute mapped, set by using the setAttributeName method.
  • The database table that holds the values to be stored in the collection, set by using the setReferenceTableName method.
  • The field in the reference table from which the values are read and placed into the collection; this is called the direct field. Set it using the setDirectFieldName method.
  • The foreign key information, which you specify using the setReferenceKeyFieldName method 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, call the addReferenceKeyFieldName method for each of the fields that make up the key.


Configuring a Simple Direct Collection Mapping

public void customize(ClassDescriptor descriptor) { 
    DirectCollectionMapping directCollectionMapping = 
                                    new DirectCollectionMapping();
    directCollectionMapping.setAttributeName ("responsibilitiesList");
    directCollectionMapping.setReferenceTableName ("RESPONS"); // target table
    directCollectionMapping.setDirectFieldName ("DESCRIP");
    directCollectionMapping.setReferenceKeyFieldName ("EMP_ID");
    directCollectionMapping.useCollectionClass (Collection.class); // default

    // add this mapping to descriptor
    descriptor.addMapping (directCollectionMapping);
}

In addition to the API that the Configuring a Simple Direct Collection Mapping example illustrates, other common API for use with direct collection mappings include the following:

  • useBasicIndirection: implements EclipseLink value holder indirection.
  • useTransparentCollection: if you use transparent indirection, this element places a special collection in the source object's attribute.
  • dontUseIndirection: implements no indirection.

For more information about the available methods for DirectCollectionMapping, see the EclipseLink API Reference.


Configuring Direct Value Field

The direct value field, located in the reference table, stores the primitive data value. In the Direct Collection Mappings figure, the DESCRIP field stores the collection.


How to Configure a Direct Value Field Using Workbench

To specify the direct collection specifics, use this procedure:

  1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.
  2. Click the General tab. The General tab appears.
    General Tab, Direct Value Field
    General Tab, Direct Value Field
  3. Use the Direct Value Field list to select the field from the Target Table table that contains the object of the collection.



How to Configure Direct Value Field Using Java

The Configuring a Simple Direct Collection Mapping example demonstrates how to create and configure a direct collection mapping, including the setting of a direct field. The example also shows how to add this mapping to the descriptor.



Copyright Statement

Back to the top