Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
This chapter includes information on the following:
You can create a database mapping using TopLink Workbench or Java code. Oracle recommends using TopLink Workbench to create and manage your mappings.
For more information on creating mappings in Java, see Oracle TopLink API Reference
For complete information on the various types of mapping that TopLink supports, see "Mapping Types".
During development, you can create mappings individually (see "Creating Mappings Manually During Development") or you can allow TopLink Workbench to automatically map all attributes (see "Creating Mappings Automatically During Development").
For CMP projects using OC4J, you can also configure TopLink to create mappings automatically at deployment time (see "Creating Mappings Automatically During Deployment").
After you create a mapping, you must configure its various options (see Chapter 32, "Configuring a Mapping").
You can manually create a mapping from each persistent field of a class to a data source using TopLink Workbench or Java code. Oracle recommends that you use 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 the data source (see Chapter 25, "Configuring a Descriptor"). You must associate descriptors with a database table or schema context before mapping their attributes.
In the Navigator, expand the descriptor to display its attributes.
Select an attribute and click the appropriate mapping on the toolbar (see "Context Toolbar"), or right-click the attribute and select Map As > specific mapping from the menu (see "Context Menus").
Continue with Chapter 32, "Configuring a Mapping" to complete the mapping.
For relational database projects, TopLink Workbench can automatically map class attributes to a similarly named database field. For example, TopLink Workbench 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. If TopLink cannot
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. |
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.
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 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.
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 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 OCI or Server driver, the driver is responsible for acquiring the LOB locator before writing the value–not TopLink. You can use any TopLink mapping type to read and write a LOB
value.
Use this procedure to map LOB values using the Oracle JDBC OCI driver:
Use any mapping type to map the attributes of a TopLink descriptor to a LOB value. Example 31-1 shows an example of a direct-to-field mapping to a BLOB
value.
Acquire the DatabaseLogin from the session.
DatabaseLogin login = session.getLogin();
Configure the parameter bindings for the specific LOB value:
For BLOB
values, enable byte array binding to ensure that byte arrays are bound (in the event that shouldBindAllParamters
is false) and enable the streams for binding to ensure that stream binding is used for byte arrays. Example 31-2 shows configuring the parameter bindings in TopLink Workbench. Example 31-3 shows configuring the parameter bindings in TopLink Workbench.
Example 31-2 Configuring Parameter Bindings in TopLink Workbench
For CLOB
values, enable string binding to ensure that long string values (more than 255 characters) are bound as character streams. Example 31-4 shows configuring string binding in TopLink Workbench. Example 31-5 shows configuring string binding in TopLink Workbench.
Example 31-4 Configuring String Binding in TopLink Workbench
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 "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. Example 31-6 shows a type conversion mapping to a BLOB
value in TopLink Workbench. Example 31-6 shows the Java code for the same mapping.
Acquire the DatabaseLogin from the session.
DatabaseLogin login = session.getLogin();
Configure a platform that provides locator support.
For Oracle8i, use the oracle.toplink.oraclespecific.Oracle8Platform
class:
login.usePlatform(new Oracle8Platform());
For Oracle9i Database Server, use the oracle.toplink.oraclespecific.Oracle9Platform
class:
login.usePlatform(new Oracle9Platform());
Oracle Database 10g, use the oracle.toplink.oraclespecific.Oracle10Platform
class:
login.usePlatform(new Oracle10Platform());
In TopLink Workbench, select the appropriate platform in the Database editor.
Figure 31-1 Selecting Database Platform in TopLink Workbench
If you are using TopLink Workbench, you can unmap any mapped attribute.
To unmap an attribute (that is, remove its mapping), use this procedure:
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.