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.

Select the direct mapping attribute in the Navigator. Its properties appear in the Editor.
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.