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 "Creating a Mapping (ELUG)"

m (New page: <div style="float:right;border:1px solid #000000;padding:5px">__TOC__ Related Topics</div> This section describes how to create EclipseL...)
 
m
Line 9: Line 9:
 
For more information on creating mappings in Java, see EclipseLink API Reference
 
For more information on creating mappings in Java, see EclipseLink API Reference
  
For complete information on the various types of mapping that EclipseLink supports, see [[Introduction%20to%20Mappings%20(ELUG)|Mapping Types]].
+
For complete information on the various types of mapping that EclipseLink supports, see [[Introduction%20to%20Mappings%20(ELUG)#Mapping Types|Mapping Types]].
  
 
During development, you can create mappings individually (see [[#Creating Mappings Manually During Development|Creating Mappings Manually During Development]]) or you can allow Workbench to automatically map all attributes (see [[#Creating Mappings Automatically During Development|Creating Mappings Automatically During Development]]).
 
During development, you can create mappings individually (see [[#Creating Mappings Manually During Development|Creating Mappings Manually During Development]]) or you can allow Workbench to automatically map all attributes (see [[#Creating Mappings Automatically During Development|Creating Mappings Automatically During Development]]).
  
 
After you create a mapping, you must configure its various options (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring a Mapping]]).
 
After you create a mapping, you must configure its various options (see [[Configuring%20a%20Mapping%20(ELUG)|Configuring a Mapping]]).
 +
 +
  
 
==Creating Mappings Manually During Development==
 
==Creating Mappings Manually During Development==
Line 26: Line 28:
 
# On the '''Descriptor Info''' tab, associate the descriptor with its data source:
 
# On the '''Descriptor Info''' tab, associate the descriptor with its data source:
 
## For a relational project, in the '''Editor''', select the table for this descriptor from the '''Associated Table''' menu.The Workbench populates this menu with tables from the database login you associated with your project. For more information, see [[Configuring%20a%20Relational%20Project%20(ELUG)|Configuring Login Information at the Project Level]].
 
## For a relational project, in the '''Editor''', select the table for this descriptor from the '''Associated Table''' menu.The Workbench populates this menu with tables from the database login you associated with your project. For more information, see [[Configuring%20a%20Relational%20Project%20(ELUG)|Configuring Login Information at the Project Level]].
## For an XML project, in the '''Editor''', select the appropriate schema context for this descriptor by clicking on the '''Browse''' button next to the '''Schema Context''' field.The Workbench displays the schema context from the XML schema you associated with your project. For more information, see [[Using%20Workbench%20(ELUG)|Using XML Schemas]].
+
## For an XML project, in the '''Editor''', select the appropriate schema context for this descriptor by clicking on the '''Browse''' button next to the '''Schema Context''' field.The Workbench displays the schema context from the XML schema you associated with your project. For more information, see [[Using%20Workbench%20(ELUG)#Using XML Schemas|Using XML Schemas]].
 
# In the '''Navigator''', expand the descriptor to display its attributes.
 
# In the '''Navigator''', expand the descriptor to display its attributes.
 
# Select an attribute and do one of the following:
 
# Select an attribute and do one of the following:
## Click the appropriate mapping on the toolbar (see [[Using%20Workbench%20(ELUG)|Using Context Toolbar]]).
+
## Click the appropriate mapping on the toolbar (see [[Using%20Workbench%20(ELUG)#Using Context Toolbar|Using Context Toolbar]]).
## Right-click the attribute and select '''Map As >''' to choose a specific mapping type from the context menu (see [[Using%20Workbench%20(ELUG)|Using Context Menus]]).
+
## Right-click the attribute and select '''Map As >''' to choose a specific mapping type from the context menu (see [[Using%20Workbench%20(ELUG)#Using Context Menus|Using Context Menus]]).
  
 
Continue with [[Configuring%20a%20Mapping%20(ELUG)|Configuring a Mapping]] to complete the mapping.
 
Continue with [[Configuring%20a%20Mapping%20(ELUG)|Configuring a Mapping]] to complete the mapping.
  
 
'''See Also'''
 
'''See Also'''
: [[Configuring%20a%20Mapping%20(ELUG)|Configuring a Mapping]]
+
: [[Configuring%20a%20Mapping%20(ELUG)#Configuring a Mapping|Configuring a Mapping]]
 
: [[#Creating Mappings Automatically During Development|Creating Mappings Automatically During Development]]
 
: [[#Creating Mappings Automatically During Development|Creating Mappings Automatically During Development]]
  
Line 50: Line 52:
 
<span id="Example 116-2"></span>
 
<span id="Example 116-2"></span>
 
''''' Creating Relational Direct Collection Mapping'''''
 
''''' Creating Relational Direct Collection Mapping'''''
  org.eclipse.persistence.mappings.DirectCollectionMappiing dcm =  
+
  org.eclipse.persistence.mappings.DirectCollectionMappiing dcm =
 
                                       new DirectCollectionMappiing();
 
                                       new DirectCollectionMappiing();
  
Line 57: Line 59:
 
''''' Creating Object-Relational Data Type Structure Mapping'''''
 
''''' Creating Object-Relational Data Type Structure Mapping'''''
 
  org.eclipse.persistence.mappings.structures.StructureMappiing sm = new StructureMappiing();
 
  org.eclipse.persistence.mappings.structures.StructureMappiing sm = new StructureMappiing();
 +
  
  
Line 76: Line 79:
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
| align="left" |
 
| align="left" |
''''''Note'''<nowiki>:</nowiki>''' Associating a descriptor with a database table (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)|Configuring Associated Tables]]) before using the Automap function can aid the automapper if it cannot guess the correct table for a class.
+
''''''Note'''<nowiki>:</nowiki>''' Associating a descriptor with a database table (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|Configuring Associated Tables]]) before using the Automap function can aid the automapper if it cannot guess the correct table for a class.
 
|}
 
|}
  
Line 118: Line 121:
 
<ol>
 
<ol>
 
<li> Use any mapping type to map the attributes of a EclipseLink descriptor to a LOB value. [[#Example 116-5|Mapping a BLOB with a Direct-To-Field Mapping]] shows the use of a direct-to-field mapping to a <tt>BLOB</tt> value.<br>
 
<li> Use any mapping type to map the attributes of a EclipseLink descriptor to a LOB value. [[#Example 116-5|Mapping a BLOB with a Direct-To-Field Mapping]] shows the use of a direct-to-field mapping to a <tt>BLOB</tt> value.<br>
 +
 
<span id="Example 116-5"></span>
 
<span id="Example 116-5"></span>
 
''''' Mapping a BLOB with a Direct-To-Field Mapping'''''  
 
''''' Mapping a BLOB with a Direct-To-Field Mapping'''''  
Line 139: Line 143:
 
<span id="Example 116-9"></span>
 
<span id="Example 116-9"></span>
 
''''' Configuring String Binding in Java Code'''''  
 
''''' Configuring String Binding in Java Code'''''  
 
 
<div class="pre">  
 
<div class="pre">  
 
login.useStringBinding();
 
login.useStringBinding();
Line 192: Line 195:
 
To unmap an attribute (that is, remove its mapping), use this procedure:
 
To unmap an attribute (that is, remove its mapping), use this procedure:
  
[[Image:unmapbtn.gif|Unmap button]]<br /> Select the attribute in the '''Navigator''' window and click '''Unmap'''. You can also unmap the attribute by right-clicking the attribute and selecting '''Map As > Unmapped''' from the context menu.
+
[[Image:unmapbtn.gif|Unmap button]] Select the attribute in the '''Navigator''' window and click '''Unmap'''. You can also unmap the attribute by right-clicking the attribute and selecting '''Map As > Unmapped''' from the context menu.
  
 
To unmap all the attributes in a descriptor or Java package, use this procedure:
 
To unmap all the attributes in a descriptor or Java package, use this procedure:
  
[[Image:unmapbtn.gif|Unmap all Descriptors button]]<br /> Right-click the descriptor or Java package in the '''Navigator''' window and select '''Unmap > Unmap Selected Descriptor''' or '''Unmap All Descriptors in Package''' from the context menu.
+
[[Image:unmapbtn.gif|Unmap all Descriptors button]] Right-click the descriptor or Java package in the '''Navigator''' window and select '''Unmap > Unmap Selected Descriptor''' or '''Unmap All Descriptors in Package''' from the context menu.
  
  

Revision as of 08:09, 3 December 2007

This section describes how to create EclipseLink mappings.


Introduction to Mapping Creation

You can create a database mapping using the Workbench or Java code. We recommend using the Workbench to create and manage your mappings.

For more information on creating mappings in Java, see EclipseLink API Reference

For complete information on the various types of mapping that EclipseLink supports, see Mapping Types.

During development, you can create mappings individually (see Creating Mappings Manually During Development) or you can allow Workbench to automatically map all attributes (see Creating Mappings Automatically During Development).

After you create a mapping, you must configure its various options (see Configuring a Mapping).


Creating Mappings Manually During Development

You can manually create a mapping from each persistent field of a class to a data source using Workbench or Java code. We recommend that you use Workbench.


How to Create Mappings Manually During Development Using Workbench

To manually create a mapping using Workbench, use this procedure:

  1. Select a descriptor in the Navigator. Its properties appear in the Editor.
  2. On the Descriptor Info tab, associate the descriptor with its data source:
    1. For a relational project, in the Editor, select the table for this descriptor from the Associated Table menu.The Workbench populates this menu with tables from the database login you associated with your project. For more information, see Configuring Login Information at the Project Level.
    2. For an XML project, in the Editor, select the appropriate schema context for this descriptor by clicking on the Browse button next to the Schema Context field.The Workbench displays the schema context from the XML schema you associated with your project. For more information, see Using XML Schemas.
  3. In the Navigator, expand the descriptor to display its attributes.
  4. Select an attribute and do one of the following:
    1. Click the appropriate mapping on the toolbar (see Using Context Toolbar).
    2. Right-click the attribute and select Map As > to choose a specific mapping type from the context menu (see Using Context Menus).

Continue with Configuring a Mapping to complete the mapping.

See Also

Configuring a Mapping
Creating Mappings Automatically During Development


How to Create Mappings During Development Using Java

You create mappings using the constructor of the particular mapping type, as the following examples show:

Creating Relational One-to-One Mapping

 org.eclipse.persistence.mappings.OneToOneMappiing oom = new OneToOneMappiing();


Creating Relational Direct Collection Mapping

org.eclipse.persistence.mappings.DirectCollectionMappiing dcm =
                                     new DirectCollectionMappiing();


Creating Object-Relational Data Type Structure Mapping

org.eclipse.persistence.mappings.structures.StructureMappiing sm = new StructureMappiing();


Creating Object-Relational Data Type Array Mapping

org.eclipse.persistence.mappings.structures.ArrayMappiing am = new ArrayMappiing();


Creating Mappings Automatically During Development

For relational database projects, JDeveloper and Workbench can automatically map class attributes to a similarly named database field. For example, these tools can map the attribute province to the database field PROV, the attribute street to the field ST, and the attribute postalCode to the field POSTAL_CODE.

The Automap function creates mappings only for unmapped attributes–it does not change previously defined mappings.

You can automatically map classes for an entire project or for specific classes or descriptors.


'Note': Associating a descriptor with a database table (see Configuring Associated Tables) before using the Automap function can aid the automapper if it cannot guess the correct table for a class.



How to Create Mappings Automatically During Development Using Workbench

To automatically map all the descriptors in a project, right-click the project icon in the Navigator window and choose Automap from the context menu or choose Selected > Automap from the menu.

To automatically map a specific descriptor or attribute, choose the descriptor or attributes and right-click, and then select Automap from the context menu or choose Selected > Automap from the menu.

See Also

Creating Mappings Manually During Development
Configuring a Mapping


Creating Mappings Automatically During Deployment

If you create a project from an OC4J EJB CMP EAR at deployment time, you can take advantage of the EclipseLink default mapping feature to automatically create mappings at deployment time.


Creating Mappings to Oracle LOB Database Objects

In an Oracle Database, large amounts of binary or character data is stored as a BLOB (binary large object) or CLOB (character large object), respectively. Depending on the size of the LOB value and your Oracle Database database version, the value may be stored either inside or outside of the table, as follows:

  • With Oracle8i version 8.1.6 and earlier, LOB values less than 4K are stored inline; values more than 4K are stored outside the table.
  • With Oracle8i version 8.1.7 and later, LOB values less than 5.9K are stored inline; values more than 5.9K are stored outside the table.

A client application (such as EclipseLink) must use a LOB locator to write a LOB value, if the value is stored outside of the database. The Oracle JDBC OCI driver and server driver handle these LOB (large object) values differently than the Oracle JDBC thin driver.


How to Create Mappings to Oracle LOB Database Objects Using the Oracle JDBC OCI Driver or Server Driver

When using the Oracle JDBC OCI or Server driver, the driver is responsible for acquiring the LOB locator before writing the value–not EclipseLink. You can use any EclipseLink mapping type to read and write a LOB value.

Use this procedure to map LOB values using the Oracle JDBC OCI driver:

  1. Use any mapping type to map the attributes of a EclipseLink descriptor to a LOB value. Mapping a BLOB with a Direct-To-Field Mapping shows the use of a direct-to-field mapping to a BLOB value.
    Mapping a BLOB with a Direct-To-Field Mapping
    DirectToField pictureMapping = new DirectToField();pictureMapping.setAttributeName("picture");pictureMapping.setFieldName("IMAGE.PICTURE");descriptor.addMapping(pictureMapping);
    
  2. Acquire the DatabaseLogin from the session.
    DatabaseLogin login = session.getLogin();
    
  3. Configure the parameter bindings for the specific LOB value:
    login.setUsesByteArrayBinding(true);
    login.setUsesStreamsForBinding(true);
    

    Configuring String Binding in Workbench
    Configuring String Binding in Workbench

    Configuring String Binding in Java Code

    login.useStringBinding();


How to Create Mappings to Oracle LOB Database Objects Using the Oracle JDBC Thin Driver

When using the Oracle JDBC thin driver, EclipseLink is responsible for acquiring the LOB locator before writing the value. You can use a type conversion mapping (see Configuring a Type Conversion Converter) to retrieve the locator during a commit operation.

Use this procedure to map LOB values using the Oracle JDBC thin driver:

  1. Use a type conversion mapping to map the attributes of a EclipseLink descriptor to a LOB value. Mapping a BLOB in Workbench shows a type conversion mapping to a BLOB value in Workbench. Mapping a BLOB in Java Code shows the Java code for the same mapping.
    Mapping a BLOB in Workbench
    Mapping a BLOB in Workbench



    Mapping a BLOB in Java Code
    TypeConversionMapping pictureMapping = new TypeConversionMapping();
    pictureMapping.set.AttributeName("picture");
    pictureMapping.setFieldName("IMAGE.PICTURE");
    pictureMapping.setFieldClassification(java.sql.Blob.class);
    descriptor.addMapping(pictureMapping);
    
  2. Acquire the DatabaseLogin from the session. DatabaseLogin login = session.getLogin();
  3. Configure a platform that provides locator support, as follows:
    • For Oracle8i, use the org.eclipse.persistence.oraclespecific.Oracle8Platform class:

    login.usePlatform(new Oracle8Platform());
    • For Oracle9i Database Server, use the org.eclipse.persistence.oraclespecific.Oracle9Platform class:

    login.usePlatform(new Oracle9Platform());
    • Oracle Database 10g, use the org.eclipse.persistence.oraclespecific.Oracle10Platform class:

    login.usePlatform(new Oracle10Platform()); In Workbench, select the appropriate platform in the Database editor.
    Selecting Database Platform in Workbench
    Selecting Database Platform in Workbench


Removing Mappings

If you are using the Workbench, you can unmap any mapped attribute.


How to Remove Mappings Using Workbench

To unmap an attribute (that is, remove its mapping), use this procedure:

Unmap button Select the attribute in the Navigator window and click Unmap. You can also unmap the attribute by right-clicking the attribute and selecting Map As > Unmapped from the context menu.

To unmap all the attributes in a descriptor or Java package, use this procedure:

Unmap all Descriptors button Right-click the descriptor or Java package in the Navigator window and select Unmap > Unmap Selected Descriptor or Unmap All Descriptors in Package from the context menu.




Copyright Statement

Back to the top