Working with Descriptors

A descriptor stores all the information describing how an instance of a particular class can be represented in a relational database. The OracleAS TopLink Mapping Workbench reads a project .mwp file to load all a project's information (including descriptor information).

You may need to amend a descriptor (for example, to specify a property not supported by the OracleAS TopLink Mapping Workbench) after reading a project file (see "Amending Descriptors After Loading"). However, do not modify any descriptors after registering them with the session.

OracleAS TopLink descriptors contain the following information:

The persistent Java class it describes and the corresponding database table(s) for storing instances of that class
A collection of mappings, which describe how the attributes and relationships for that class are stored in the database
The primary key information of the table(s)
A list of query keys (or aliases) for field names
Information for sequence numbers
A set of optional properties for tailoring the behavior of the descriptor, including support for identity maps, optimistic locking, the Event Manager, and the Query Manager
Caching refresh options

Understanding Persistent Classes

Any class that registers a descriptor with an OracleAS TopLink Mapping Workbench database session is called a persistent class. OracleAS TopLink does not require that persistent classes provide public accessor methods for any private or protected attributes stored in the database.

See Appendix A, "Object Model Requirements" for more information on persistent classes object model requirements.

Specifying Descriptor Types

OracleAS TopLink descriptors can be a class descriptor, an aggregate descriptor, or an EJB descriptor. After creating a descriptor, use this procedure to change the descriptor type.

Note:

An EJB descriptor cannot be an aggregate.

To specify a descriptor's type:

Select the descriptor in the Navigator pane.
Description of the illustration cldesbtn.gif

Description of the illustration agdesbtn.gif

Description of the illustration ejbbtn.gif

Click the appropriate descriptor icon (Class, Aggregate, or EJB) on the mapping toolbar.

You can also select the descriptor and choose Selected > Descriptor Type > specific descriptor type from the menu or by right-clicking on the descriptor in the Navigator pane and selecting Descriptor Type > specific descriptor type from the pop-up menu.

Note:
EJB 2.0 descriptors are created only by reading the {/Emphasis>specifying

When changing a descriptor's type, the OracleAS TopLink Mapping Workbench adds or removes property tabs, as needed.

Converting a class or EJB descriptor to an aggregate descriptor removes the Descriptor Info and Queries tabs. Some advanced properties are not available for aggregate descriptors and will be removed from the Editor pane.

Converting an aggregate descriptor to a class descriptor adds the Descriptor Info and Queries tabs.

Mapping Descriptors

Descriptors define mappings between classes and tables. To display the attributes in a specific class, expand the descriptor item in the Navigator pane (see Figure 1–5).

Use the mapping toolbar (see "Mapping Toolbar" on page 1-7) to choose a mapping type for each attribute.

To map a descriptor:

Select a descriptor in the Navigator pane. Its properties appear in the Editor pane.
On the Descriptor Info tab, associate the descriptor with a database table (see "Setting Descriptor Information").
In the Navigator pane, expand the descriptor to display its attributes.
Select an attribute and click the appropriate mapping button on the Mapping toolbar (see "Mapping Toolbar" on page 1-7).

Continue with "Working with Mappings" to modify the mapping.

Automapping Descriptors

The OracleAS TopLink Mapping Workbench can automatically map class attributes to a similarly named database field. The Automap function only creates mappings for unmapped attributes — it does not change previously defined mappings.

You can automap classes for an entire project or for specific tables.

Note:

You must associate a descriptor with a database table before using the Automap function. See "Setting Descriptor Information" for more information.

To automap attributes:

To automap all descriptors in a project, right-click the project icon in the Navigator pane and choose Automap from the pop-up menu or choose Selected > Automap from the menu.

To automap a specific descriptor or attribute choose the descriptor/attribute(s). Right-click and select Automap from the pop-up menu or choose Selected > Automap from the menu.

Generating Java Code for Descriptors

Use this procedure to generate the Java class code for the selected descriptor or package.

To generate Java code:

Right-click the descriptor or package and choose Export Java Model Source from the pop-up menu. The Choose a Directory dialog box appears.

You can also choose Selected > Export Java Model Source from the menu.

If you have not defined deployment and source code generation defaults (see "Working with Project Options" on page 2-10) the OracleAS TopLink Mapping Workbench prompts for a filename and directory.

OracleAS TopLink creates the <DescriptorName>.java file in the specified directory.

Note:

If you attempt to generate source code for a descriptor but cancel the process before the OracleAS TopLink Mapping Workbench writes the new source code, a dialog indicates that the source code was successfully updated. However, if you cancelled the process, the OracleAS TopLink Mapping Workbench did not overwrite any existing code.

In this release, the OracleAS TopLink Mapping Workbench does not support generating Project Java Source for Descriptors mapped to inner classes.

If you attempt to generate source code from a table with BLOBs, the generated Java code may contain errors in the type definition and method parameters. You must edit the source code to eliminate the errors.