Working with Mappings

In OracleAS TopLink, mappings define how an object's attributes are represented in the database.

Direct mappings define how a persistent object refers to objects that do not have descriptors (for example, the JDK classes and primitives). See Chapter 5, "Understanding Direct Mappings" for details.
Relationship mappings define how a persistent object refers to other persistent objects. See Chapter 6, "Understanding Relationship Mappings", and Chapter 7, "Understanding Object-Relational Mappings", for details.

All the mapping classes are derived from the DatabaseMapping class, as Figure 4–37 illustrates.

Figure 4-37 Mapping Classes Hierarchy

Description of the illustration mapclass.gif

Working with Common Mapping Properties

OracleAS TopLink associates each mapping with the attribute whose persistence it describes. To create a mapping in the OracleAS TopLink Mapping Workbench, select the attribute to map from the Navigator pane and then click the appropriate button on the mapping toolbar (see "Mapping Toolbar" on page 1-7).

Use the mapping's Editor pane to enter specific information for the mapping. Some mappings require more information that others and have multiple tabs in the Editor pane.

Figure 4-38 Sample Properties for a Mapping

Description of the illustration 1mmapgen.gif

Mapping properties called out in Figure 4-38:

Specify if read-only.
Specify access method.

Specifying Direct Access and Method Access

By default, OracleAS TopLink uses direct access to access public attributes. Alternatively, you can use accessor methods to access object attributes when writing the attributes of the object to the database or reading the attributes of the object from the database. This is known as method access.

The attribute's visibility (public, protected, private, or package visibility) and the supported version of JDK may restrict the type of access that you can use.

Starting with JDK 1.2, the Java Core Reflection API provides a means to suppress default Java language access control checks when using reflection. OracleAS TopLink uses reflection to access the application's persistent objects. This means that if you are using a VM that supports the API, then OracleAS TopLink can access an attribute directly, regardless of its declared visibility.

Note:

Private variable access under JDK 1.2 requires you to enable the security setting. Consult the JDK documentation for more information.

Oracle recommends using direct access whenever possible to improve performance and avoid executing any application-specific behavior while building objects.

Setting the Access Type

Use the General tab of the mapping Editor pane (see Figure 4-38) to set the access type as direct or method-based

To change the default access type used by all new mappings, use the Defaults tab on the project Editor pane. See "Working with Default Properties" on page 2-9 for more information.

Note:

If you change the access default, existing mappings retain their current access settings, but new mappings will be created with the new default.

Specifying Read-Only Settings

Use the Read Only check-box on the General tab of the mapping Editor pane (see Figure 4-38) to set a mapping to be read only. OracleAS TopLink will not consider attributes associated with read-only mappings during update and delete operations.

Because these operations are not actually performed for the mapping, any processes dependent on these operations (such as custom SQL or descriptor events) are not called for read-only. The attributes are still used for read operations.

Note:

The primary key mappings must not be read-only.

Mappings defined for the write-lock or class indicator field must be read-only, unless the write-lock is configured not to be stored in the cache and the class indicator is part of the primary key.

Defaulting Null Values

Direct mappings include a

Null values translate in two directions: from null values read from the database to the specified value, and from the specified value back to null when writing or querying. You can also use OracleAS TopLink to set global default null values on a per-class basis. For more information, refer to the Oracle Application Server TopLink Application Developer's Guide.

Click the Use Default Value when Database Field is Null option on the General tab (see Figure 4-38) and the Type and Value drop-down lists to specify the null value.

Note:

You must specify the Type and Value in the mapping form.

Maintaining Bidirectional Relationships

Select the Maintain Bidirectional Relationship Only option on the General tab of the mapping Editor pane (see Figure 4-38) to maintain a bidirectional relationship for a one-to-one or one-to-many mapping. You can also specify the relationship partner.

Specifying Field Names and Multiple Tables

When defining mappings in code, OracleAS TopLink assumes all mappings are in the first table specified by the descriptor's setTableName() or addTableName() method. If the persistent class stores information in multiple tables, any messages sent that require field names should be implemented to pass fully qualified names (that include the table name). Use the following syntax to fully qualify a field:

someMessage("tablename.fieldname");

Specifying Collection Properties

Some relationship mapping types (direct collection, one-to-many, and many-to-many) contain a Collection Options tab to allow you to specify collection options.

OracleAS TopLink can populate a collection in ascending or descending order, upon your specification. Query keys are automatically created for and with the same name as all attributes mapped as direct-to-field, type conversion, object type, and serialized object mappings.

Figure 4-39 Collection Options

Description of the illustration collects.gif

Use this table to enter data in each field:

Field	Description
Container Policy
Collection or Map Class	Select the collection or map class to use for this collection mapping.
Use Default Container Class	If Container Policy = Use Collection Class, select the default Collection Class for the mapping.
Use Default Map Class	If Container Policy = Use Map Class, select the default Map Class and Key Method for the mapping.
Order Query Results	Specify how the collection results are sorted for queries.

Specifying Mapping information in ejb-jar.xml File

For 2.0 CMP projects, the ejb-jar.xml files stores information on bean-to-bean relationships (mappings) in the <relationship> element. By updating this information in the ejb-jar.xml, the OracleAS TopLink Mapping Workbench creates new mappings. You can then update the mapping information (such as reference tables).

If the information does not exist in the ejb-jar.xml file, you can build the mappings in the OracleAS TopLink Mapping Workbench, then write the information to the file. See "Writing to the ejb-jar.xml File" on page 2-19 for more information.