5
Understanding Direct Mappings

In Oracle Application Server 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 OracleAS 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.

OracleAS TopLink furnishes 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, then 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 the database, it stores the value of the attribute in a field of the table column. OracleAS 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
nSting	NVARCHAR2 (applies to Oracle9)
nClob	NCLOB (applies to Oracle9)
Character, char	CHAR
nChararcter	NCHAR (applies to Oracle9)
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.

Example 5-1 Direct-to-Field Mapping Example

Figure 5-1 illustrates a direct-to-field mapping between the Java attribute city and the relational database column CITY. Similarly, direct-to-field mappings could be defined from country to COUNTRY, id to ADDRESS_ID, established to EST_DATE, and province to PROVINCE.

Figure 5-1 Direct-to-Field Mapping

Text description of the illustration dtfmpfig.gif

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 Navigator pane.

2. Click the Direct to Field Mapping button

   Text description of the illustration dtfmpbtn.gif

   on the mapping toolbar.

3. From the Database Field drop-down list on the General tab on the Editor pane, choose 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-2 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.

For Oracle9 databases, OracleAS TopLink supports NCHAR, NAVRCHAR2, and NCLOB database types. Use the Ncharacter, NString, and NClob target types, respectively.

Example 5-2 Type Conversion Mapping Example

Figure 5-3 illustrates a type conversion mapping. Because the java.util.Date class is stored by default as a Timestamp in the database, it must first be converted to an explicit database type such as java.sql.Date (required only for DB2--most other databases have a single date data-type that can store any date or time).

Figure 5-3 Type Conversion Mappings

Text description of the illustration tcmapfig.gif

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 Navigator pane.

2. Click the Type Conversion Mapping button

   Text description of the illustration tcmapbtn.gif

   on the mapping toolbar.

3. From the Database field and Database type drop-down lists on the General tab in the Editor pane, choose the appropriate database field and database type.

   Figure 5-4 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.

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-5 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 Navigator pane, select the attribute to be mapped.

2. Click the Object-Type Mapping button

   Text description of the illustration obmapbtn.gif

   on the mapping toolbar. The Object type mapping tab appears in the Editor pane.

   Figure 5-6 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.

As with direct-to-field mappings, serialized object mappings require you to specify an attribute and field, as shown in the following illustration.

Figure 5-7 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 Navigator pane, select the attribute to be mapped.

2. Click the Serialized Mapping button

   Text description of the illustration srmapbtn.gif

   on the mapping toolbar.

   Figure 5-8 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 can specify a second parameter, when it 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.

Figure 5-9 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-9 Transformation Mappings

Text description of the illustration trmapfig.gif

Creating Transformation Mappings

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

To create a transformation mapping:

1. In the Navigator pane select the attribute to be mapped.

2. Click the Transformation Mapping button

   Text description of the illustration trmapbtn.gif

   from the Mapping toolbar.

   Figure 5-10 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 the parameter (DatabaseRow) or parameters (DatabaseRow, Session).

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

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

5. Select the Use indirection option to specify if the creation of the target object requires extensive computational resources. If selected, OracleAS 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-3).

You can also specify:

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

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

Example 5-3 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 OracleAS TopLink, transformation mappings do not require you to specify an attribute.

A field can be mapped from a computed value that does not map to a logical attribute. This, in effect, constitutes a write-only mapping. In the OracleAS TopLink 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, create an instance of TransformationMapping and send addFieldTransformation() message for each field to be written.

Example 5-4 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 normal, including the other part of the primary key, and the inheritance through the type field.

Note: The OracleAS TopLink Mapping Workbench displays 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.