5
Understanding Direct Mappings

In TopLink, direct mappings define how a persistent object refers to objects without descriptors, such as the JDK classes and primitives.

You can create the following direct mappings in TopLink:

• Direct-to-field mappings - Map a Java attribute directly to a database field (see "Working with Direct-to-field Mappings").

• Type conversion mappings - Map Java values with simple type conversions, such as from character to string (see "Working with Type Conversion Mappings").

• Object type mappings - Use an association to map values to the database (see "Working with Object Type Mappings").

• Serialized object mappings - Map serializable objects, such as multimedia objects, to database BLOB fields (see "Working with Serialized Object Mappings").

• Transformation mappings - Allow you to create custom mappings where one or more fields can be used to create the object be stored in the attribute (see "Working with Transformation Mappings").

Working with Direct Mappings

There are two basic ways of storing object attributes directly in a database table:

• The information can be stored directly if the attribute type is comparable to a database type.

• If there is no database primitive type that is logically comparable to the attribute's type, it must be transformed on its way to and from the database.

TopLink provides the following classes of direct mappings:

• Direct-to-field

• Type conversion

• Object type

• Transformation

• Serialized object

If the application's objects contain attributes that cannot be represented as direct-to-field, type conversion, or object-type mappings, the application must provide transformation routines for saving the attributes.

If a direct-to-field mapping cannot be used to perform the desired conversion, try type conversion and object type mappings before attempting to define a custom transformation mapping.

Working with Direct-to-field Mappings

Direct-to-field mappings map a Java attribute directly to a value database column. When the application writes a Java instance to database, it stores the value of the attribute in a field of the table column. TopLink supports the following types:

• java.lang: Boolean, Float, Integer, String, Double, Long, Short, Byte, Byte[ ], Character, Character[ ]; all of the primitives associated with these classes

• java.math: BigInteger, BigDecimal

• java.sql: Date, Time, Timestamp

• java.util: Date, Calendar

While reading, direct-to-field mappings perform some simple one data conversions, as described in Table 5-1. You must use other direct mappings for two-way or more complete conversions.

Table 5-1 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
Character, char	CHAR
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	DATE, DATETIME (applies to Oracle, Sybase, SQL Server)

Direct-to-field mappings 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.

Creating Direct-to-field Mappings

Use this procedure to create a basic direct-to-field mapping to map a Java attribute directly to a value in a database.

To create a direct-to-field mapping:

1. Select the attribute to be mapped from the Project Tree pane.

2. Click the Direct to Field Mapping button from the mapping toolbar.

3. Use the Database Field drop-down list on the General tab on the Properties pane to select the appropriate database field.

4. Select the Use Default Value When Database Field is Null option to specify a default Type and Value to use if the database field is null.

   Figure 5-1 Direct-to-field Mapping Properties

   

   Text description of the illustration dtfmptab.gif

You can also specify:

• Read-only attributes - See "Specifying Read-only Settings"

• Access methods - See "Specifying Direct Access and Method Access"

• Null values - See "Defaulting Null Values"

Working with Type Conversion Mappings

Type conversion mappings explicitly map a database type to a Java type. For example, a Number in the database can be mapped to a String in Java, or a java.util.Date in Java can be mapped to a java.sql.Date in the database.

Creating Type Conversion Mappings

Use this procedure to create a type conversion mapping.

To create a type conversion mapping:

1. Select the attribute to be mapped from the Project Tree pane.

2. Click the Type Conversion Mapping button from the mapping toolbar.

3. Use the Database field and Database type drop-down lists on the General tab in the Properties pane to select the appropriate database field and database type.

   Figure 5-2 Type Conversion Mapping Properties

   

   Text description of the illustration tcmaptab.gif

You can also specify:

• Read-only attributes - See "Specifying Read-only Settings"

• Access methods - See "Specifying Direct Access and Method Access"

Working with Object Type Mappings

Object type mappings match a fixed number of database values to Java objects. Use these mappings when the values in the database differ from those in Java. Object types mappings are similar to direct-to-field mappings in all other respects.

Example 5-1 Object Type Mapping Example

The following figure illustrates an object type mapping between the Employee attribute gender and the relational database column GENDER. If the gender value in the Java class = Male, the system stores it in the GENDER database field as M; Female is stored as F.

Figure 5-3 Object Type Mappings

Text description of the illustration obmapfig.gif

Creating Object Type Mappings

Use this procedure to create an object type mapping between an attribute and a database column.

To create a basic object type mapping:

1. In the Project Tree pane, choose the attribute to be mapped.

2. Click the Object-Type Mapping button from the mapping toolbar. The Object type mapping tab appears in the Properties pane.

   Figure 5-4 Object Type Mapping General Properties

   

   Text description of the illustration obmaptab.gif

3. Choose the appropriate database field in the Database Field drop-down list.

4. Select Use Default Value When Database Field is Null to specify a default Type and Value to use if the database field is null.

5. Set the database type from the Database Type drop-down list and the Java type from the Object type drop-down list.

6. Click on Add to add Database Value and Object Value pairs to the table. Select the Default Attribute Value option for the value to use as the default.

   To remove a database value, select the value and click Remove.

You can also specify:

• Read-only attributes - See "Specifying Read-only Settings"

• Access methods - See "Specifying Direct Access and Method Access"

Working with Serialized Object Mappings

Serialized object mappings are used to store large data objects, such as multimedia files and BLOBs, in the database. Serialization transforms these large objects as a stream of bits.

Example 5-2 Serialized Object Mapping Example

Like direct-to-field mappings, serialized object mappings require an attribute and field to be specified, as illustrated in the following illustration.

Figure 5-5 Serialized Object Mappings

Text description of the illustration serobjfg.gif

Creating Serialized Object Mappings

Use this procedure to create serialized object mappings.

To create a serialized object mapping:

1. In the Project Tree pane, choose the attribute to be mapped.

2. Click the Serialized Mapping button from the mapping toolbar.

   Figure 5-6 Serialized Object Mapping Properties

   

   Text description of the illustration srmaptab.gif

3. Choose the appropriate database field in the Database Field drop-down list.

You can also specify:

• Read-only attributes - See "Specifying Read-only Settings"

• Access methods - See "Specifying Direct Access and Method Access"

Working with Transformation Mappings

Use transformation mappings for specialized translations between how a value is represented in Java and in the database.

Tip: Use transformation mappings only when mapping multiple fields into a single attribute. Because of the complexity of transformation mappings, it is often easier to perform the transformation with get/set methods of a direct-to-field mapping.

Often, a transformation mapping is appropriate when values from multiple fields are used to create an object. This type of mapping requires that you provide an attribute transformation method that is invoked when reading the object from the database. This method must have at least one parameter that is an instance of DatabaseRow. In your attribute transformation method, you can send the get() message to the DatabaseRow to get the value in a specific column. Your attribute transformation method may specify a second parameter, when is an instance of Session. The Session performs queries on the database to get additional values needed in the transformation. The method should return the value to be stored in the attribute.

Transformation mappings also require a field transformation method for each field to be written to the database when the object is saved. The transformation methods are specified in a dictionary associating each field with a method. The method returns the value to be stored in that field.

Example 5-3 Transformation Mapping Example

Figure 5-7 illustrates a transformation mapping. The values from the B_DATE and B_TIME fields are used to create a java.util.Date to be stored in the birthDate attribute.

Figure 5-7 Transformation Mappings

Text description of the illustration trmapfig.gif

Creating Transformation Mappings

Use this procedure to create transformation mappings in the Mapping Workbench.

To create a transformation mapping:

1. In the Project Tree pane choose the attribute to be mapped.

2. Click the Transformation Mapping button from the Mapping toolbar.

   Figure 5-8 Transformation Mapping Tab

   

   Text description of the illustration trmaptab.gif

3. Use the Database Row --> Object Method drop-down list to select a method to convert the database row into an object.

   Note: The method must have parameter (DatabaseRow) or parameters (DatabaseRow, Session).

4. Click on Add to add field transformation methods to the descriptor.

   To remove a transformation method, select the method and click on Remove.

5. Use the Use indirection check box to specify if the creation of the target object requires extensive computational resources. If selected, TopLink uses indirection objects. See "Working with Indirection" for more information.

6. After specifying the details of the mapping, create the attribute field transformation methods in the associated Java class (see Example 5-4, "Transformation Mapping Code Example").

You can also specify:

• Read-only attributes - See "Specifying Read-only Settings"

• Access methods - See "Specifying Direct Access and Method Access"

Example 5-4 Transformation Mapping Code Example

The following code example illustrates the methods required for a transformation mapping.

// Get method for the normalHours attribute since method access indicated
access public Time[] getNormalHours()
{

   return normalHours;

}
// Set method for the normalHours attribute since method access indicated
access public void setNormalHours(Time[] theNormalHours)
{

   normalHours = theNormalHours;

}
// Create attribute transformation method to read from the database row
//** Builds the normalHours Vector. IMPORTANT: This method builds the value but 
does not set it. The mapping will set it using method or direct access as 
defined in the descriptor. */
public Time[] getNormalHoursFromRow(DatabaseRow row)
{

   Time[] hours = new Time[2];
   hours[0] = (Time)row.get("START_TIME");
   hours[1] = (Time)row.get("END_TIME");
   return hours;

}
// Define a field transformation method to write out the start time. Return the 
first element of the normalHours attribute.
public java.sql.Time getStartTime()
{

   return getNormalHours()[0];

}
// Define a field transformation method to write out the end time. Return the 
last element of the normalHours attribute.
public java.sql.Time getEndTime()
{

   return getNormalHours()[1];

}

Specifying Advanced Features Available by Amending the Descriptor

In TopLink, transformation mappings do not require you to specify an attribute.

A field may be mapped from a computed value that does not map to a logical attribute. This, in effect, constitutes a write-only mapping. In the Mapping Workbench, all mappings are associated with an attribute before any other information can be specified. Therefore, to use a write-only mapping, you must build it by amending the descriptor. The mapping itself has no attribute name, get and set methods, or attribute method. In your amendment method, simply create an instance of TransformationMapping and send addFieldTransformation() message for each field to be written.

Example 5-5 Descriptor Amendment Examples

The following code example illustrates creating a write-only transformation mapping and adding it to the descriptor.

public static void addToDescriptor(Descriptor descriptor) {
// Create a Transformation mapping and add it to the descriptor.
TransformationMapping transMapping = new 
transMapping.addFieldTransformation("WRITE_DATE", 
"descriptor.addMapping(transMapping);
}

The following example illustrates how to create a one-way transformation mapping by using the inheritance indicator field of the primary key. Map the class as a normal, including the other part of the primary key, and the inheritance through the type field.

Note: The Mapping Workbench will display a neediness error because the class indicator field part of the primary key is not mapped. Use the following code to create an amendment method to map the indicator field.

Create an amendment method for the class:

public void addToDescriptor(Descriptor descriptor) {

   TransformationMapping keyMapping = new TransformationMapping();
   keyMapping.addFieldTranslation("PROJECT.PROJ_TYPE", "getType");
   descriptor.addMapping(keyMapping);}

Define the getType method on the class to return its type value:

Project>>public abstract String getType();
LargeProject>>public String getType() { return "L"; }
SmallProject>>public String getType() { return "S"; }

Refer to "Amending Descriptors After Loading" for more information.