Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Configuring an Object-Relational Data Type Mapping (ELUG)
This section describes how to configure an object-relational data type 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. ==Introduction to Object-Relational Data Type Mapping Configuration
== [#CHDJAFEJ Table 50-1] lists the types of object-relational data type mappings that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type. Table 50-1 Configuring Object-Relational Data Type Mappings {| class="HRuleFormalMax" dir="ltr" title="Configuring Object-Relational Data Type Mappings" summary="This table provides a cross-reference to additional configuration options for each specific object-relational mapping type." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows" |- align="left" valign="top" ! id="r1c1-t2" align="left" valign="bottom" | If you are creating... ! id="r1c2-t2" align="left" valign="bottom" | See Also... |- align="left" valign="top" | id="r2c1-t2" headers="r1c1-t2" align="left" | Object-relational data type structure mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABJHEJF Object-Relational Data Type Structure Mapping]) | headers="r2c1-t2 r1c2-t2" align="left" | [Configuring%20an%20Object-Relational%20Data%20Type%20Structure%20Mapping%20(ELUG).htm#CHDBHDIF Chapter 46, "Configuring an Object-Relational Data Type Structure Mapping"] |- align="left" valign="top" | id="r3c1-t2" headers="r1c1-t2" align="left" | Object-relational data type reference mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABGBBGG Object-Relational Data Type Reference Mapping]) | headers="r3c1-t2 r1c2-t2" align="left" | [Configuring%20an%20Object-Relational%20Data%20Type%20Reference%20Mapping%20(ELUG).htm#CHDEBAAA Chapter 47, "Configuring an Object-Relational Data Type Reference Mapping"] |- align="left" valign="top" | id="r4c1-t2" headers="r1c1-t2" align="left" | Object-relational data type array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBAEH Object-Relational Data Type Array Mapping]) | headers="r4c1-t2 r1c2-t2" align="left" | [Configuring%20an%20Object-Relational%20Data%20Type%20Array%20Mapping%20(ELUG).htm#CHDGGIDH Chapter 48, "Configuring an Object-Relational Data Type Array Mapping"] |- align="left" valign="top" | id="r5c1-t2" headers="r1c1-t2" align="left" | Object-relational data type object array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBGDG Object-Relational Data Type Object Array Mapping]) | headers="r5c1-t2 r1c2-t2" align="left" | [Configuring%20an%20Object-Relational%20Data%20Type%20Object%20Array%20Mapping%20(ELUG).htm#CHDDDJFD Chapter 49, "Configuring an Object-Relational Data Type Object Array Mapping"] |- align="left" valign="top" | id="r6c1-t2" headers="r1c1-t2" align="left" | Object-relational data type nested table mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIFDFC Object-Relational Data Type Nested Table Mapping]) | headers="r6c1-t2 r1c2-t2" align="left" | [Configuring%20an%20Object-Relational%20Data%20Type%20Nested%20Table%20Mapping%20(ELUG).htm#CHDHADED Chapter 51, "Configuring an Object-Relational Data Type Nested Table Mapping"] |} For more information, see the following: * Introduction to Mappings * Transformation Mapping ==Configuring Common Object-Relational Data Type Mapping Options== [#CHDIEAJA Table 50-2] lists the configurable options shared by two or more object-relational data type mapping types. In addition to the configurable options described here, you must also configure the options described for the specific object-relational data type mapping types (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABEJHHF Object-Relational Data Type Mapping Types]), as shown in [#CHDJAFEJ Table 50-1]. Table 50-2 Common Options for Object-Relational Data Type Mappings {| class="RuleFormalMax" dir="ltr" title="Common Options for Object-Relational Data Type Mappings" summary="This table lists the configurable options shated by two or more object relational mapping types 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" |- align="left" valign="top" ! id="r1c1-t3" align="left" valign="bottom" | Option to Configure ! id="r1c2-t3" align="left" valign="bottom" | JDeveloper ! id="r1c3-t3" align="left" valign="bottom" | Workbench ! id="r1c4-t3" align="left" valign="bottom" | Java |- align="left" valign="top" | id="r2c1-t3" headers="r1c1-t3" align="left" | Reference class (see [#CHDFJJAB Configuring Reference Class]) | headers="r2c1-t3 r1c2-t3" align="left" | 
| headers="r2c1-t3 r1c3-t3" align="left" | | headers="r2c1-t3 r1c4-t3" align="left" | 
|- align="left" valign="top" | id="r3c1-t3" headers="r1c1-t3" align="left" | Attribute name (see [#CHDJADIH Configuring Attribute Name]) | headers="r3c1-t3 r1c2-t3" align="left" | | headers="r3c1-t3 r1c3-t3" align="left" | | headers="r3c1-t3 r1c4-t3" align="left" | |- align="left" valign="top" | id="r4c1-t3" headers="r1c1-t3" align="left" | Field name (see [#CHDEBEHF Configuring Field Name]) | headers="r4c1-t3 r1c2-t3" align="left" | | headers="r4c1-t3 r1c3-t3" align="left" | | headers="r4c1-t3 r1c4-t3" align="left" | |- align="left" valign="top" | id="r5c1-t3" headers="r1c1-t3" align="left" | Structure name (see [#CHDCFBGE Configuring Structure Name]) | headers="r5c1-t3 r1c2-t3" align="left" | | headers="r5c1-t3 r1c3-t3" align="left" | | headers="r5c1-t3 r1c4-t3" align="left" | |- align="left" valign="top" | id="r6c1-t3" headers="r1c1-t3" align="left" | Read-only (see [Configuring%20a%20Mapping%20(ELUG).htm#CEGDDEDA Configuring Read-Only Mappings]) | headers="r6c1-t3 r1c2-t3" align="left" | | headers="r6c1-t3 r1c3-t3" align="left" | | headers="r6c1-t3 r1c4-t3" align="left" | |- align="left" valign="top" | id="r7c1-t3" headers="r1c1-t3" align="left" | Method or direct field access (see [Configuring%20a%20Mapping%20(ELUG).htm#CEGCFIGE Configuring Method or Direct Field Accessing at the Mapping Level]) | headers="r7c1-t3 r1c2-t3" align="left" | | headers="r7c1-t3 r1c3-t3" align="left" | | headers="r7c1-t3 r1c4-t3" align="left" | |- align="left" valign="top" | id="r8c1-t3" headers="r1c1-t3" align="left" | Indirection (lazy loading) (see [Configuring%20a%20Mapping%20(ELUG).htm#CEGDDEEA Configuring Indirection (Lazy Loading)]) | headers="r8c1-t3 r1c2-t3" align="left" | | headers="r8c1-t3 r1c3-t3" align="left" | | headers="r8c1-t3 r1c4-t3" align="left" | |- align="left" valign="top" | id="r9c1-t3" headers="r1c1-t3" align="left" | Container policy (see [Configuring%20a%20Mapping%20(ELUG).htm#CHDFGJAI Configuring Container Policy]) | headers="r9c1-t3 r1c2-t3" align="left" | | headers="r9c1-t3 r1c3-t3" align="left" | | headers="r9c1-t3 r1c4-t3" align="left" | |} ==Configuring Reference Class== When mapping an attribute that involves a relationship to another class, you must specify the reference class–the Java class to which the mapped attribute refers. [#CHDGAIGG Table 50-3] summarizes which object-relational data type mappings support this option. Table 50-3 Mapping Support for Reference Class {| class="RuleFormal" dir="ltr" title="Mapping Support for Reference Class" summary="This table summarizes which mappings support Reference Class" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all" |- align="left" valign="top" ! id="r1c1-t4" align="left" valign="bottom" | Mapping ! id="r1c2-t4" align="left" valign="bottom" | How to Use Workbench ! id="r1c3-t4" align="left" valign="bottom" | [#CHDFGCEA How to Configure Reference Class Using Java] |- align="left" valign="top" | id="r2c1-t4" headers="r1c1-t4" align="left" | Object-relational data type structure mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABJHEJF Object-Relational Data Type Structure Mapping]) | headers="r2c1-t4 r1c2-t4" align="left" | | headers="r2c1-t4 r1c3-t4" align="left" | |- align="left" valign="top" | id="r3c1-t4" headers="r1c1-t4" align="left" | Object-relational data type reference mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABGBBGG Object-Relational Data Type Reference Mapping]) | headers="r3c1-t4 r1c2-t4" align="left" | | headers="r3c1-t4 r1c3-t4" align="left" | |- align="left" valign="top" | id="r4c1-t4" headers="r1c1-t4" align="left" | Object-relational data type array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBAEH Object-Relational Data Type Array Mapping]) | headers="r4c1-t4 r1c2-t4" align="left" | | headers="r4c1-t4 r1c3-t4" align="left" | |- align="left" valign="top" | id="r5c1-t4" headers="r1c1-t4" align="left" | Object-relational data type object array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBGDG Object-Relational Data Type Object Array Mapping]) | headers="r5c1-t4 r1c2-t4" align="left" | | headers="r5c1-t4 r1c3-t4" align="left" | |- align="left" valign="top" | id="r6c1-t4" headers="r1c1-t4" align="left" | Object-relational data type nested table mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIFDFC Object-Relational Data Type Nested Table Mapping]) | headers="r6c1-t4 r1c2-t4" align="left" | | headers="r6c1-t4 r1c3-t4" align="left" | |} ===How to Configure Reference Class Using Java=== Use org.eclipse.persistence.mappings.ForeignReferenceMapping method setReferenceClass to specify the target class of the attribute being mapped. [#CHDHHCJI Example 50-1] shows how to use this method with a ReferenceMapping that maps the manager attribute of the Employee class. Example 50-1 Configuring Reference Class in Java public void customize(ClassDescriptor descriptor) { ReferenceMapping managerMapping = new ReferenceMapping(); managerMapping.setReferenceClass("Employee.class"); // set reference class managerMapping.setAttributeName("manager"); // add this mapping to descriptor descriptor.addMapping (managerMapping); } For more information, see the [olinkSRC%20JITAR EclipseLink API Reference]. ==Configuring Attribute Name== All object-relational data type mappings map an attribute in a Java object to field in the database. The attribute name is the name of the attribute being mapped. The name is as specified in the reference class (see [#CHDFJJAB Configuring Reference Class]). [#CHDFGHBG Table 50-4] summarizes which object-relational data type mappings support this option. Table 50-4 Mapping Support for Attribute Name {| class="RuleFormal" dir="ltr" title="Mapping Support for Attribute Name" summary="This table summarizes which mappings support ort for Attribute Name" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all" |- align="left" valign="top" ! id="r1c1-t5" align="left" valign="bottom" | Mapping ! id="r1c2-t5" align="left" valign="bottom" | How to Use Workbench ! id="r1c3-t5" align="left" valign="bottom" | [#CHDEAEDI How to Configure Attribute Name Using Java] |- align="left" valign="top" | id="r2c1-t5" headers="r1c1-t5" align="left" | Object-relational data type structure mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABJHEJF Object-Relational Data Type Structure Mapping]) | headers="r2c1-t5 r1c2-t5" align="left" | | headers="r2c1-t5 r1c3-t5" align="left" | |- align="left" valign="top" | id="r3c1-t5" headers="r1c1-t5" align="left" | Object-relational data type reference mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABGBBGG Object-Relational Data Type Reference Mapping]) | headers="r3c1-t5 r1c2-t5" align="left" | | headers="r3c1-t5 r1c3-t5" align="left" | |- align="left" valign="top" | id="r4c1-t5" headers="r1c1-t5" align="left" | Object-relational data type array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBAEH Object-Relational Data Type Array Mapping]) | headers="r4c1-t5 r1c2-t5" align="left" | | headers="r4c1-t5 r1c3-t5" align="left" | |- align="left" valign="top" | id="r5c1-t5" headers="r1c1-t5" align="left" | Object-relational data type object array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBGDG Object-Relational Data Type Object Array Mapping]) | headers="r5c1-t5 r1c2-t5" align="left" | | headers="r5c1-t5 r1c3-t5" align="left" | |- align="left" valign="top" | id="r6c1-t5" headers="r1c1-t5" align="left" | Object-relational data type nested table mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIFDFC Object-Relational Data Type Nested Table Mapping]) | headers="r6c1-t5 r1c2-t5" align="left" | | headers="r6c1-t5 r1c3-t5" align="left" | |} ===How to Configure Attribute Name Using Java=== Use org.eclipse.persistence.mappings.DatabaseMapping method setAttributeName to specify the name of the attribute being mapped. [#CHDIJEBJ Example 50-2] shows how to use this method with a ReferenceMapping that maps the manager attribute of the Employee class. Example 50-2 Configuring Attribute Name in Java public void customize(ClassDescriptor descriptor) { ReferenceMapping managerMapping = new new ReferenceMapping(); managerMapping.setReferenceClass("Employee.class"); managerMapping.setAttributeName("manager"); // set attribute name // add this mapping to descriptor descriptor.addMapping (managerMapping); } For more information, see the [olinkSRC%20JITAR EclipseLink API Reference]. ==Configuring Field Name== All object-relational data type mappings require the name of database field to which their specified attribute is mapped. This field name can be the column name of a database table or the name of a field in an object type created on the database. [#CHDCCDDE Table 50-5] summarizes which object-relational data type mappings support this option. Table 50-5 Mapping Support for Field Name {| class="RuleFormal" dir="ltr" title="Mapping Support for Field Name" summary="This table summarizes which mappings support Field Name" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all" |- align="left" valign="top" ! id="r1c1-t6" align="left" valign="bottom" | Mapping ! id="r1c2-t6" align="left" valign="bottom" | How to Use Workbench ! id="r1c3-t6" align="left" valign="bottom" | [#CHDICHFF How to Configure Field Name Using Java] |- align="left" valign="top" | id="r2c1-t6" headers="r1c1-t6" align="left" | Object-relational data type structure mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABJHEJF Object-Relational Data Type Structure Mapping]) | headers="r2c1-t6 r1c2-t6" align="left" | | headers="r2c1-t6 r1c3-t6" align="left" | |- align="left" valign="top" | id="r3c1-t6" headers="r1c1-t6" align="left" | Object-relational data type reference mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABGBBGG Object-Relational Data Type Reference Mapping]) | headers="r3c1-t6 r1c2-t6" align="left" | | headers="r3c1-t6 r1c3-t6" align="left" | |- align="left" valign="top" | id="r4c1-t6" headers="r1c1-t6" align="left" | Object-relational data type array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBAEH Object-Relational Data Type Array Mapping]) | headers="r4c1-t6 r1c2-t6" align="left" | | headers="r4c1-t6 r1c3-t6" align="left" | |- align="left" valign="top" | id="r5c1-t6" headers="r1c1-t6" align="left" | Object-relational data type object array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBGDG Object-Relational Data Type Object Array Mapping]) | headers="r5c1-t6 r1c2-t6" align="left" | | headers="r5c1-t6 r1c3-t6" align="left" | |- align="left" valign="top" | id="r6c1-t6" headers="r1c1-t6" align="left" | Object-relational data type nested table mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIFDFC Object-Relational Data Type Nested Table Mapping]) | headers="r6c1-t6 r1c2-t6" align="left" | | headers="r6c1-t6 r1c3-t6" align="left" | |} ===How to Configure Field Name Using Java=== Use the object-relational data type mapping method setFieldName to specify the database field to which the attribute is mapped. [#CHDCCAFJ Example 50-3] shows how to use this method with an ObjectArrayMapping that maps the Employee class attribute phone to database field name PHONE_NUMBER. Example 50-3 Configuring Field Name in Java public void customize(ClassDescriptor descriptor) { ObjectArrayMapping phonesMapping = new ObjectArrayMapping(); phonesMapping.setReferenceClass("Employee.class"); phonesMapping.setAttributeName("phone"); phonesMapping.setFieldName("PHONE_NUMBER"); // set field name // add this mapping to descriptor descriptor.addMapping (phonesMapping); } For more information, see the [olinkSRC%20JITAR EclipseLink API Reference]. ==Configuring Structure Name== Certain object-relational data type mappings require the specification of the data type or structure name of the field being mapped. The structure name is the name of the array or table type that defines the field. [#CHDDHBJD Table 50-6] summarizes which object-relational data type mappings support this option. Table 50-6 Mapping Support for Structure Name {| class="RuleFormal" dir="ltr" title="Mapping Support for Structure Name" summary="This table summarizes which mappings support Structure Name" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all" |- align="left" valign="top" ! id="r1c1-t7" align="left" valign="bottom" | Mapping ! id="r1c2-t7" align="left" valign="bottom" | How to Use JDeveloper ! id="r1c3-t7" align="left" valign="bottom" | How to Use Workbench ! id="r1c4-t7" align="left" valign="bottom" | [#CHDIHHHJ How to Configure Structure Name Using Java] |- align="left" valign="top" | id="r2c1-t7" headers="r1c1-t7" align="left" | Object-relational data type structure mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABJHEJF Object-Relational Data Type Structure Mapping]) | headers="r2c1-t7 r1c2-t7" align="left" | | headers="r2c1-t7 r1c3-t7" align="left" | | headers="r2c1-t7 r1c4-t7" align="left" | |- align="left" valign="top" | id="r3c1-t7" headers="r1c1-t7" align="left" | Object-relational data type reference mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABGBBGG Object-Relational Data Type Reference Mapping]) | headers="r3c1-t7 r1c2-t7" align="left" | | headers="r3c1-t7 r1c3-t7" align="left" | | headers="r3c1-t7 r1c4-t7" align="left" | |- align="left" valign="top" | id="r4c1-t7" headers="r1c1-t7" align="left" | Object-relational data type array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBAEH Object-Relational Data Type Array Mapping]) | headers="r4c1-t7 r1c2-t7" align="left" | | headers="r4c1-t7 r1c3-t7" align="left" | | headers="r4c1-t7 r1c4-t7" align="left" | |- align="left" valign="top" | id="r5c1-t7" headers="r1c1-t7" align="left" | Object-relational data type object array mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIBGDG Object-Relational Data Type Object Array Mapping]) | headers="r5c1-t7 r1c2-t7" align="left" | | headers="r5c1-t7 r1c3-t7" align="left" | | headers="r5c1-t7 r1c4-t7" align="left" | |- align="left" valign="top" | id="r6c1-t7" headers="r1c1-t7" align="left" | Object-relational data type nested table mapping (see [Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG).htm#BABIFDFC Object-Relational Data Type Nested Table Mapping]) | headers="r6c1-t7 r1c2-t7" align="left" | | headers="r6c1-t7 r1c3-t7" align="left" | | headers="r6c1-t7 r1c4-t7" align="left" | |} ===How to Configure Structure Name Using Java=== Use the object-relational data type mapping method setStructureName to specify the structure of the attribute being mapped. [#CHDEFJFH Example 50-4] shows how to use this method with an ObjectArrayMapping that maps the Employee class attribute phones to database field name PHONE_NUMBERS of type PHONE_ARRAY_TYPE. Example 50-4 Configuring Structure Name in Java public void customize(ClassDescriptor descriptor) { ObjectArrayMapping phonesMapping = new ObjectArrayMapping(); phonesMapping.setReferenceClass("Employee.class"); phonesMapping.setAttributeName("phones"); phonesMapping.setFieldName("PHONE_NUMBERS"); phonesMapping.setStructureName("PHONE_ARRAY_TYPE"); // set structure name // add this mapping to descriptor descriptor.addMapping (phonesMapping); } For more information, see the [olinkSRC%20JITAR EclipseLink API Reference].