| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
This chapter describes how to configure a relational mapping.
Table 34-1 lists the types of relational 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 34-1 Configuring Relational Mappings
Table 34-2 lists the configurable options shared by two or more relational mapping types.
For more information, see the following:
Table 34-2 lists the configurable options shared by two or more relational mapping types. In addition to the configurable options described here, you must also configure the options described for the specific Relational Mapping Types, as shown in Table 34-1.
Table 34-2 Common Relational Mapping Options
| Option | Type | TopLink Workbench |
Java |
|---|---|---|---|
|
"Configuring a Database Field" |
Basic |
 |
|
|
"Configuring Reference Descriptor" |
Basic |
|
|
|
"Configuring Container Policy" |
Basic |
|
|
|
"Configuring Method Accessing" |
Advanced |
|
|
|
"Configuring a Default Null Value at the Mapping Level" |
Basic |
|
|
|
"Configuring Read-Only Mappings" |
Advanced |
|
|
|
|
Basic |
|
|
|
"Configuring Private or Independent Relationships" |
Advanced |
|
|
|
"Configuring Mapping Comments" |
Advanced |
|
 |
|
"Configuring a Serialized Object Converter" |
Advanced |
|
|
|
"Configuring a Type Conversion Converter" |
Advanced |
|
|
|
"Configuring an Object Type Converter" |
Advanced |
|
|
|
"Configuring Bidirectional Relationship" |
Advanced |
|
|
|
|
Advanced |
|
|
|
|
Advanced |
|
|
|
"Configuring Table and Field References (Foreign and Target Foreign Keys)" |
Advanced |
|
|
You can associate an object attribute with a database field.
Table 34-3 summarizes which relational mappings support this option.
When choosing the database field, you must consider Java and database field type compatibility.
TopLink supports the following Java types:
java.lang: Boolean, Float, Integer, String, Double, Long, Short, Byte, Byte[ ], Character, Character[ ]; all the primitives associated with these classes
java.math: BigInteger, BigDecimal
java.sql: Date, Time, Timestamp
java.util: Date, Calendar
While executing reads, the mappings in Table 34-6 perform the simple one-way data conversions that Table 34-4 describes. For two-way or more complex conversions, You must use converters (see "Converters and Transformers").
The mappings in Table 34-3 also allow you to specify a null value. This may be required if primitive types are used in the object, and the database field allows null values. For more information, see "Configuring a Default Null Value at the Mapping Level".
Table 34-4 Type Conversions Provided by Direct-to-Field Mappings
| Java type | Database type |
|---|---|
|
Integer, Float, Double, Byte, Short, BigDecimal, BigInteger, int, float, double, byte, short |
NUMBER, NUMERIC, DECIMAL, FLOAT, DOUBLE, INT, SMALLINT, BIT, BOOLEAN |
|
Boolean, boolean |
BOOLEAN, BIT, SMALLINT, NUMBER, NUMERIC, DECIMAL, FLOAT, DOUBLE, INT |
|
String |
VARCHAR, CHAR, VARCHAR2, CLOB, TEXT, LONG, LONG VARCHAR, MEMO The following types apply only to Oracle9: NVARCHAR2, NCLOB, NCHAR |
|
byte[ ] |
BLOB, LONG RAW, IMAGE, RAW, VARBINARY, BINARY, LONG VARBINARY |
|
Time |
TIME |
|
sql.Date |
DATE (only applies to DB2) |
|
TIMESTAMP (only applies to DB2) |
|
|
sql.Date, Time, Timestamp, util.Date, Calendar To use |
DATE, DATETIME (applies to Oracle, Sybase, SQL Server) |
Support for oracle.sql.TimeStamp
TopLink provides additional support for mapping Java date and time data types to Oracle database DATE, TIMESTAMP, and TIMESTAMPTZ data types when you use the Oracle JDBC driver with Oracle9i Database Server or later and the Oracle9Platform in TopLink.
In a direct-to-field mapping, you are not required to specify the database type of the field value; TopLink determines the appropriate data type conversion.
Table 34-5 lists the supported direct-to-field mapping combinations.
Table 34-5 Supported Oracle Database Date and Time Direct-to-Field Mappings
| Java Type | Database Type | Description |
|---|---|---|
|
|
|
Full bidirectional support. |
|
|
Full bidirectional support. |
|
|
|
Full bidirectional support. |
|
|
|
|
Full bidirectional support. |
|
|
Full bidirectional support. |
|
|
|
Full bidirectional support. |
|
|
|
|
Full bidirectional support. |
|
|
Full bidirectional support. |
|
|
|
Nanoseconds are not stored in the database. |
|
|
|
|
Full bidirectional support. |
|
|
Full bidirectional support. |
|
|
|
Milliseconds are not stored in the database. |
|
|
|
Native SQL or binding gives Calendar timezone. Note: The TIMESTAMP database value has no timezone – the Calendar object provides the local timezone by default. If the database is not in this timezone, you must obtain the database timezone by some other means and update the Calendar object accordingly. For this reason, TIMESTAMPTZ may be a better choice. |
|
|
|
Native SQL or binding stores timezone; standard SQL is based on the local timezone. |
|
|
|
Neither timezone nor milliseconds are stored in the database. |
Note that some of these mappings result in a loss of precision: avoid these combinations if you require this level of precision. For example, if you create a direct-to-field mapping between a java.sql.Date attribute and a TIMESTAMPTZ database field, there is no loss of precision. However, if you create a direct-to-field mapping between a java.sql.Timestamp attribute and a DATE database field, the nanoseconds or milliseconds of the attribute are not stored in the database.
Use this procedure to select a specific database field for a direct mapping.
Select the direct mapping attribute in the Navigator. Its properties appear in the Editor.
Click the General tab. The General tab appears.
Figure 34-1 Direct Mapping General Tab, Database Field Option
Use the Database Field field to select a field for this direct mapping. You must have previously associated the descriptor with a database table as described in "Configuring Associated Tables".
|
Note: For direct to field mappings of a an Aggregate descriptor (see "Configuring a Relational Descriptor as a Class or Aggregate Type"), this field is for display only and cannot be changed. |
In relational mappings that extend oracle.toplink.mappings.ForeignReferenceMapping, attributes reference other TopLink descriptors–not the data source. You can select any descriptor in the project.
Table 34-6 summarizes which relational mappings support this option.
Table 34-6 Relational Mapping Support for Reference Descriptor
| Mapping | Using TopLink Workbench |
Using Java |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To specify a reference descriptor for a relational mapping, use this procedure.
Select the mapped attribute in the Navigator. Its properties appear in the Editor.
Click the General tab. The General tab appears.
Figure 34-2 General Tab, Reference Descriptor Field
Use the Reference Descriptor field to select the descriptor referenced by this relationship mapping.
|
Note: For aggregate mappings the Reference Descriptor must be an aggregate. See "Configuring a Relational Descriptor as a Class or Aggregate Type" for more information.For variable one-to-one mappings, the Reference Descriptor must be an interface. See Chapter 38, "Configuring a Relational Variable One-to-One Mapping" for more information. |
You can specify a reference descriptor that is not in the current TopLink Workbench project. For example, to create a mapping to an Employee class that does not exist in the current project, do the following:
Add the Employee class to your current project. See "Working With Projects".
Create the relationship mapping to the Employee descriptor.
Deactivate the Employee descriptor. See "Active and Inactive Descriptors".
When you generate the deployment XML for your project, the mapping to the Employee class will be included, but not the Employee class.
Batch reading can be used in most of the relational mappings. This feature should be used only if it is known that the related objects are always required with the source object.
Table 34-7 summarizes which relational mappings support this option.
To use batch reading in a relationship mapping, use this procedure:
Select the mapped attribute in the Navigator. Its properties appear in the Editor.
Click the General tab. The General tab appears.
Figure 34-3 General Tab, Batch Reading Option
To specify that this mapping using batch reading, select the Batch Reading option.
Example 34-1 Query Optimization Using Batching
The following code example illustrates using batch for query optimization.
// Queries on Employee are configured to always batch read Address
OneToManyMapping phoneNumbersMapping = new OneToManyMapping();
phoneNumbersMapping.setReferenceClass(" PhoneNumber.class")
phoneNumbersMapping.setAttributeName("phones");
phoneNumbersMapping.useBatchReading();
phoneNumbersMapping.privateOwnedRelationship();
You can configure TopLink to maintain collections in order by query key.
Table 34-8 summarizes which relational mappings support this option.
Table 34-8 Relational Mapping Support for Query Key Order
| Mapping | Using TopLink Workbench |
Using Java |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
To specify the order of a mapping's query keys, use this procedure:
Select the mapped attribute in the Navigator. Its properties appear in the Editor.
Click the Ordering tab. The Ordering tab appears.
| Field | Description |
|---|---|
| Query Key | Specify the query key to order by.
Click Add to add query keys to, or Remove to remove query keys from the ordering operation. Click Up or Down to change the sort order of selected query keys. |
| Order | Specify if TopLink orders the selected query key in Ascending or Descending (alphabetical) order. |
A foreign key is a combination of one or more database columns that reference a unique key, usually the primary key, in another table. Foreign keys can be any number of fields (similar to a primary key), all of which are treated as a unit. A foreign key and the parent key it references must have the same number and type of fields.
Mappings that extend oracle.toplink.mappings.ForeignReferenceMapping use foreign keys to find information in the database so that the target object(s) can be instantiated. For example, if every Employee has an attribute address that contains an instance of Address (which has its own descriptor and table) then, the one-to-one mapping for the address attribute would specify foreign key information to find an Address for a particular Employee.
TopLink classifies foreign keys into two categories in mappings–foreign keys and target foreign keys:
In a foreign key, the key is found in the table associated with the mapping's own descriptor. For example, an Employee foreign key to ADDRESS would be in the EMPLOYEE table.
In a target foreign key, the reference is from the target object's table back to the key from the mapping's descriptor's table. For example, the ADDRESS table would have a foreign key to EMPLOYEE.
|
Caution: Make sure you fully understand the distinction between foreign key and target foreign key before defining a mapping. |
The table reference is the database table that contains the foreign key references.
Table 34-9 summarizes which relational mappings support this option.
Table 34-9 Relational Mapping Support for Table Reference
| Mapping | Using TopLink Workbench |
Using Java |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using TopLink Workbench, you can either import this table from your database or create it. If you import tables from the database (see "Importing Tables From a Database"), TopLink creates references that correspond to existing database constraints (if supported by the driver). You can also define references in TopLink without creating similar constraints on the database.
To specify a table for a mapping reference, use this procedure:
Select the mapped attribute in the Navigator. Its properties appear in the Editor.
Click the Table Reference tab. The Reference tab appears.
Figure 34-5 Table Reference Tab, Table Reference Field
Use the following information to select the field references on the tab:
| Field | Description |
|---|---|
| Table Reference | Select an existing table, or click New to create a new table reference. |
| Source and Target Field | Click Add to create new foreign key reference.
To delete an existing key pair reference, select the Source and Target fields and click Remove. |
| Source Field | Select the database field from the source table for this foreign key reference. |
| Target Field | Select the database field from the target table for this foreign key reference. |
| Target Foreign Key | Specify whether or not the reference is from the target object's table back to the key from the mapping's descriptor's table. |
