Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Configuring a Database Field

You can associate an object attribute with a database field.

Table 37-3 summarizes which relational mappings support this option.

Table 37-3 Relational Mapping Support for Database Field

Mapping | Using TopLink Workbench | Using Java
--- | --- | ---
Direct-to-Field Mapping |  |
Direct to XMLType Mapping |  |

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 37-6 perform the simple one-way data conversions that Table 37-4 describes. For two-way or more complex conversions, You must use converters (see "Converters and Transformers").

The mappings in Table 37-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 37-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, util.Date, Calendar | TIMESTAMP (only applies to DB2)
sql.Date, Time, Timestamp, util.Date, Calendar To use `oracle.sql.TimeStamp`, see "Support for oracle.sql.TimeStamp". | 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 37-5 lists the supported direct-to-field mapping combinations.

Table 37-5 Supported Oracle Database Date and Time Direct-to-Field Mappings

Java Type | Database Type | Description
--- | --- | ---
`java.sql.Time` | `TIMESTAMP` | Full bidirectional support.
`TIMESTAMPTZ` | Full bidirectional support.
`DATE` | Full bidirectional support.
`java.sql.Date` | `TIMESTAMP` | Full bidirectional support.
`TIMESTAMPTZ` | Full bidirectional support.
`DATE` | Full bidirectional support.
`java.sql.Timestamp` | `TIMESTAMP` | Full bidirectional support.
`TIMESTAMPTZ` | Full bidirectional support.
`DATE` | Nanoseconds are not stored in the database.
`java.util.Date` | `TIMESTAMP` | Full bidirectional support.
`TIMESTAMPTZ` | Full bidirectional support.
`DATE` | Milliseconds are not stored in the database.
`java.util.Calendar` | `TIMESTAMP` | 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.
`TIMESTAMPTZ` | Native SQL or binding stores timezone; standard SQL is based on the local timezone.
`DATE` | 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.

## Using TopLink Workbench

Use this procedure to select a specific database field for a direct mapping.

1. Select the direct mapping attribute in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

   Figure 37-1 Direct Mapping General Tab, Database Field option

   Description of "Figure 37-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.