|Oracle Fusion Middleware Developer's Guide for Oracle TopLink
11g Release 1 (11.1.1)
Part Number B32441-03
This chapter describes how to create TopLink mappings.
This chapter includes the following sections:
For more information on creating mappings in Java, see Oracle Fusion Middleware Java API Reference for Oracle TopLink
For complete information on the various types of mapping that TopLink supports, see Section 17.1, "Mapping Types".
During development, you can create mappings individually (see Section 120.2, "Creating Mappings Manually During Development") or you can allow TopLink Workbench to automatically map all attributes (see Section 120.3, "Creating Mappings Automatically During Development").
For CMP projects using OC4J, you can also configure TopLink to create mappings automatically at deployment time (see Section 120.4, "Creating Mappings Automatically During Deployment").
For JPA projects, you can create mappings using JPA annotations (see "Using Metadata Annotations" section of EclipseLink Developer's Guide at
http://wiki.eclipse.org/Introduction_to_EclipseLink_JPA_%28ELUG%29#Using_Metadata_Annotations). JPA lets you create mappings automatically at run time.
After you create a mapping, you must configure its various options (see Chapter 121, "Configuring a Mapping").
You can manually create a mapping from each persistent field of a class to a data source using Oracle JDeveloper, TopLink Workbench, or Java code. Oracle recommends that you use Oracle JDeveloper or TopLink Workbench.
To manually create a mapping using TopLink Workbench, use this procedure:
Select a descriptor in the Navigator. Its properties appear in the Editor.
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 TopLink Workbench populates this menu with tables from the database login you associated with your project. For more information, see Section 20.4, "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 TopLink Workbench displays the schema context from the XML schema you associated with your project. For more information, see Section 5.6, "Using XML Schemas".
In the Navigator, expand the descriptor to display its attributes.
Select an attribute and do one of the following:
Continue with Chapter 121, "Configuring a Mapping" to complete the mapping.
You create mappings using the constructor of the particular mapping type, as the following examples show:
Example 120-1 Creating Relational One-to-One Mapping
oracle.toplink.mappings.OneToOneMapping oom = new OneToOneMapping();
Example 120-2 Creating Relational Direct Collection Mapping
oracle.toplink.mappings.DirectCollectionMapping dcm = new DirectCollectionMapping();
Example 120-3 Creating Object-Relational Data Type Structure Mapping
oracle.toplink.objectrelational.StructureMapping sm = new StructureMapping();
For relational database projects, Oracle JDeveloper and TopLink 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
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 Section 23.2, "Configuring Associated Tables") before using the Automap function can aid the automapper if it cannot guess the correct table for a class.
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.
If you create a project from an OC4J EJB CMP EAR at deployment time, you can take advantage of the TopLink default mapping feature to automatically create mappings at deployment time.
For more information, see the following:
In 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 version, the value may be stored either inside or outside of the table, as follows:
With Oracle8i Database Release 1.6 and earlier,
LOB values less than 4K are stored inline; values more than 4K are stored outside the table.
With Oracle8i Database Release 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 Oracle TopLink) 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.
When using the Oracle JDBC thin driver, TopLink is responsible for acquiring the LOB locator before writing the value. You can use a type conversion mapping (see Section 121.10, "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:
Use a type conversion mapping to map the attributes of a TopLink descriptor to a
LOB value. Figure 120-1 shows a type conversion mapping to a
BLOB value in TopLink Workbench. Example 120-5 shows the Java code for the same mapping.
Figure 120-1 Mapping a BLOB in TopLink Workbench
DatabaseLogin from the session.
DatabaseLogin login = session.getLogin();
Configure a platform that provides locator support, as follows:
For Oracle8i Database, use the
For Oracle9i Database, use the
Oracle Database 10g, use the
Oracle Database 11g, use the
In TopLink Workbench, select the appropriate platform in the Database editor.
Figure 120-2 Selecting Database Platform in TopLink Workbench
If you are using Oracle JDeveloper or TopLink Workbench, you can unmap any mapped attribute.
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:
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.