1
Understanding the OracleAS TopLink Mapping Workbench

The Oracle Application Server TopLink Mapping Workbench is a separate component from Oracle Application Server TopLink -- it allows you to graphically configure descriptors and map your project. The OracleAS TopLink Mapping Workbench can verify the descriptor options, access the data source, and create the database schema. With the OracleAS TopLink Mapping Workbench you can define OracleAS TopLink descriptors without using code.

This chapter includes the following subjects:

• Starting the OracleAS TopLink Mapping Workbench

• Working with the OracleAS TopLink Mapping Workbench

• Working with Workbench Preferences

• Working with the OracleAS TopLink Mapping Workbench in a Team Environment

To Use the OracleAS TopLink Mapping Workbench in a Java Application:

1. Define an object model (a set of Java classes) to describe and solve your problem domain.

2. Use the OracleAS TopLink Mapping Workbench to create a project, import your Java classes and relational tables, and specify descriptors to describe how the classes map to your relational model.

3. In your Java application, create an OracleAS TopLink session and register your descriptors. Add logic to your application to use the session to retrieve and store objects from and to the database.

   Figure 1-1 Using the OracleAS TopLink Mapping Workbench

   

   Text description of the illustration mapovr.gif

Starting the OracleAS TopLink Mapping Workbench

Use this procedure to start the OracleAS TopLink Mapping Workbench.

To Start the OracleAS TopLink Mapping Workbench:

Use one of the following methods to start the OracleAS TopLink Mapping Workbench:

• For Windows environments: From the Start menu, choose Program Files > OracleAS TopLink > Mapping Workbench.

• For non-Windows environments: Execute the <ORACLE_HOME>\toplink\
bin\workbench.sh file.

The splash screen appears, followed by the OracleAS TopLink Mapping Workbench window.

Working with the OracleAS TopLink Mapping Workbench

The OracleAS TopLink Mapping Workbench window includes these parts:

• Menu

  Pull-down menus for each OracleAS TopLink Mapping Workbench function. Some objects also contain context-sensitive pop-up menus. See "Using the Menus" for more information.

• Toolbars

  Shortcuts to specific functions. See "Using the Toolbars" for more information.

• Navigator pane

  The project tree for all open projects (see "Using the Navigator Pane"). Click the plus or minus ( +/- ) next to an object (or double-click the object) to expand/collapse the tree. When you select an object in the Navigator pane, its properties appear in the Editor pane.

• Editor pane

  Specific property sheets and option tabs for the currently selected object. See "Using the Editor Pane" for more information.

• Status bar

  Provides instant information regarding the status of projects, descriptors, and mappings.

  Figure 1-2 OracleAS TopLink Mapping Workbench

  

  Text description of the illustration mw.gif

Figure 1-2 calls out the following user-interface components.

1. Menu bar

2. Toolbars

3. Navigator pane

4. Editor pane

5. Status bar

Using the Menus

The OracleAS TopLink Mapping Workbench contains two types of menus:

• Menu Bar Menus

• Pop-Up Menus

Menu Bar Menus

The menu bar provides pull-down menus for each OracleAS TopLink Mapping Workbench function. Some menus (such as Selected) are context-sensitive -- the available options may vary, depending on the currently selected object.

Figure 1-3 Sample Menu Bar Menu

Text description of the illustration menubar.gif

Pop-Up Menus

When you right-click objects in the Navigator pane, a pop-up menu appears with functions specific to the selected object.

Figure 1-4 Sample Pop-up Menu

Text description of the illustration popup.gif

Using the Toolbars

The OracleAS TopLink Mapping Workbench contains two types of toolbars:

• Standard Toolbar

• Mapping Toolbar

• OracleAS TopLink Sessions Editor Navigator Toolbar

Use these toolbars to select options and functions.

Standard Toolbar

The standard toolbar furnishes quick access to the standard (File, Edit, Selected, and so on) menu options.

Button	Description
Text description of the illustration exitbtn.gif	Exit
Text description of the illustration prefbtn.gif	Preferences
Text description of the illustration newprjt.gif	New project
Text description of the illustration openbtn.gif	Open project
Text description of the illustration savebtn.gif	Save
Text description of the illustration saveall.gif	Save all
Text description of the illustration saveasbt.gif	Save as
Text description of the illustration closbtn.gif	Close
Text description of the illustration clsalbtn.gif	Close all
Text description of the illustration expjava.gif	Export Java source
Text description of the illustration export.gif	Export deployment XML
Text description of the illustration addclbt.gif	Add or refresh classes
Text description of the illustration remclass.gif	Remove class
Text description of the illustration addtable.gif	Add table
Text description of the illustration addtbldb.gif	Add or update existing tables from database
Text description of the illustration remtable.gif	Remove table
Text description of the illustration loginbtn.gif	Login to database
Text description of the illustration logotbtn.gif	Logout of database
Text description of the illustration helpbtn.gif	Online help

Mapping Toolbar

The mapping toolbar provides quick access to create mapping and descriptor types. You can specify a mapping or descriptor type by selecting the object in the Navigator pane, then clicking the appropriate button on the mapping toolbar.

You can also right-click the object and choose the appropriate mapping from the pop-up menu.

Button	Description
Text description of the illustration dtfmpbtn.gif	Direct-to-Field mapping
Text description of the illustration 11mapbtn.gif	One-to-One mapping
Text description of the illustration v11mapbt.gif	Variable One-to-One mapping
Text description of the illustration 1mmapbtn.gif	One-to-Many mapping
Text description of the illustration mmmapbtn.gif	Many-to-Many mapping
Text description of the illustration obmapbtn.gif	Object Type mapping
Text description of the illustration agmapbtn.gif	Aggregate mapping
Text description of the illustration dcmapbtn.gif	Direct Collection mapping
Text description of the illustration trmapbtn.gif	Transformation mapping
Text description of the illustration tcmapbtn.gif	Type conversion mapping
Text description of the illustration srmapbtn.gif	Serialized mapping
Text description of the illustration unmapbtn.gif	Unmap
Text description of the illustration agdesbtn.gif	Aggregate descriptor
Text description of the illustration cldesbtn.gif	Class descriptor
Text description of the illustration ejbbtn.gif	EJB descriptor

OracleAS TopLink Sessions Editor Navigator Toolbar

The OracleAS TopLink Sessions Editor contains a toolbar that appears in the Navigator pane and offers quick access to create and modify configurations, sessions, and connection pools.

Button	Description
Text description of the illustration cachbtn.gif	Caching
Text description of the illustration loginbtn.gif	Login
Text description of the illustration conpolbt.gif	Connection Pool
Text description of the illustration renambtn.gif	Rename
Text description of the illustration sessbtn.gif	Session
Text description of the illustration sesbkbtn.gif	Session Broker

Using the Navigator Pane

OracleAS TopLink displays each project's descriptors, mappings, and database tables in the Navigator pane on the left side of the workbench.

Figure 1-5 Sample Navigator Pane

Text description of the illustration city.gif

Figure 1-5 identifies the following user-interface components:

1. Project

2. Descriptor

3. Attribute/mapping

4. Database

5. Database table

Click the +/- symbol next to the item, or double-click the item name to expand and collapse the item.

When you select an item in the Navigator pane, its properties appear in the Editor pane (see "Using the Editor Pane"). You can perform specific functions for an item by selecting the item in the Navigator pane and:

• Right-clicking on the object and selecting the function from the pop-up menu (see "Pop-Up Menus").

• Choosing a function from the Selected menu (see "Menu Bar Menus").

Inactive descriptors appear dimmed in the Navigator pane. Inactive descriptors are not registered with the session when the project is loaded into Java. This feature allows you to define and test subsets of descriptors. To activate or inactivate a descriptor, right-click the descriptor and select Activate/Deactivate Descriptor from the pop-up menu.

Figure 1-6 Sample Active/inactive Descriptors

Text description of the illustration inactive.gif

Figure 1-6 shows the following user-interface components.

1. Inactive descriptor

2. Active descriptor

If an element in the project (such as a descriptor mapping), contains an error or deficiency (sometimes called neediness), a warning icon

Text description of the illustration catnicon.gif

appears beside the element icon in the Navigator pane, and a message displays in the status bar detailing the error. Appendix C, "Troubleshooting" contains complete information on each OracleAS TopLink Mapping Workbench error message.

Using the Editor Pane

The Editor pane, on the right side of the OracleAS TopLink Mapping Workbench (see Figure 1-2), displays the property sheet associated with the currently selected item in the Navigator pane.

Working with Workbench Preferences

This section includes information on customizing the following aspects of the OracleAS TopLink Mapping Workbench:

• General Preferences

• Warning and Confirmation Preferences

• Class Preferences

• EJB Preferences

• Database Preferences

• Help Preferences

General Preferences

Use the General preferences to customize the "look and feel" (the graphical user interface) of the OracleAS TopLink Mapping Workbench.

To Change the General Preferences:

1. Click the Preferences button

   Text description of the illustration prefbtn.gif

   on the toolbar. The Preferences dialog appears.

   You can also display the Preferences dialog box by choosing Tools > Preferences from the menu.

2. Select General in the Category pane.

   Figure 1-7 General Preferences

   

   Text description of the illustration prefgen.gif

3. Use this table to enter data in each field and click OK.

   Field	Description
   Text Editor	Click Browse and select a text editor (used when viewing the session configuration source). See "Working with the Source" for more information. Note: This field appears for the OracleAS TopLink Sessions Editor only.
   Look and Feel	Select the "look and feel" to use for the OracleAS TopLink Mapping Workbench. See Figure 1-8 for a sample of each option.
   Size of Recently Opened Documents List	Select the number of projects to maintain in the File > Reopen option. See "Opening Existing Projects" for more information.
   Log Unit of Work Messages and SQL	Specify if the OracleAS TopLink Mapping Workbench logs runtime messages to help troubleshoot projects. Click Browse to select a filename (default mw_xml.txt) and Location.

You must restart the OracleAS TopLink Mapping Workbench to apply the changes.

Figure 1-8 Look and Feel Samples

Text description of the illustration lfsample.gif

Figure 1-8 shows the following "look and feel" samples:

1. Oracle

2. Windows

3. Metal (Java)

4. CDE/Motif

Warning and Confirmation Preferences

Use the Warnings preferences to specify if the OracleAS TopLink Mapping Workbench displays certain warning and confirmation dialog boxes.

To Specify Warnings Preferences:

1. Click the Preferences button

   Text description of the illustration prefbtn.gif

   on the toolbar. The Preferences dialog box appears.

   You can also display the Preferences dialog box by choosing Tools > Preferences from the menu.

2. Select Warning in the Category pane.

   Figure 1-9 Warning Preferences

   

   Text description of the illustration prefwarn.gif

3. Use this table to enter data in each field and click OK.

   Field	Description
   Show All Warning and Confirmation Dialogs	Specify which (if any) of the following confirmation and warning messages are displayed.
   Descriptors Without an Associated Table	Specify if the OracleAS TopLink Mapping Workbench displays a warning message if you attempt to create a table reference before defining the descriptor's associated table.
   Direct Mappings Without a Database Field	Specify if the OracleAS TopLink Mapping Workbench displays a warning message if you attempt to create a table reference for a direct collection mapping before mapping's direct field and target table.
   Mappings Without a Reference Descriptor	Specify if the OracleAS TopLink Mapping Workbench displays a warning message if you attempt to create a mapping before defining a reference descriptor.
   Aggregate Descriptors Without Mapped Attributes	Specify if the OracleAS TopLink Mapping Workbench displays a warning message if you attempt to create field references for an aggregate mapping before mapping the aggregate descriptor's attributes.
   Mappings Without a Relation Table	Specify if the OracleAS TopLink Mapping Workbench displays a warning message if you attempt to create a table reference for a many-to-many mapping before defining the mapping's relation table.
   Define Reference Descriptor First	Specify if the OracleAS TopLink Mapping Workbench displays a warning message if you attempt to create a table reference before defining the mapping's reference descriptor.
   Invalid or Incomplete Data	Specify if the OracleAS TopLink Sessions Editor displays a warning message if your session configuration contains invalid or incomplete data.

Class Preferences

Use this procedure to specify how the OracleAS TopLink Mapping Workbench imports and edits classes. See "Working with Classes" for more information.

To Specify Class Import Options:

1. Click the Preferences button

   Text description of the illustration prefbtn.gif

   on the toolbar. The Preferences dialog box appears.

   You can also display the Preferences dialog box by choosing Tools > Preferences from the menu.

2. Select Class in the Category pane.

3. Click the Importing Classes tab.

   Figure 1-10 Class Preferences -- Importing Classes

   

   Text description of the illustration prefclas.gif

4. Select Never Verify Classes in Chooser if you do not want to verify the classes when performing an Add or Refresh.

   Caution: By default, the OracleAS TopLink Mapping Workbench always verifies the classes. Select this option only if you encounter errors when displaying classes in the Select Classes dialog box.

5. Click the Editing Classes tab.

   Figure 1-11 Class Preferences -- Editing Classes

   

   Text description of the illustration prefedcl.gif

6. Specify how the OracleAS TopLink Mapping Workbench maintains classes when renaming or editing a zero-argument constructor.

7. Click OK.

EJB Preferences

Use this procedure to specify how the OracleAS TopLink Mapping Workbench updates the ejb-jar.xml file when saving projects.

To Specify EJB Preferences:

1. Click the Preferences button

   Text description of the illustration prefbtn.gif

   on the toolbar. The Preferences dialog box appears.

   You can also display the Preferences dialog box by choosing Tools > Preferences from the menu.

2. Select EJB in the Category pane.

   Figure 1-12 EJB Preferences

   

   Text description of the illustration prefejb.gif

3. Specify whether the OracleAS TopLink Mapping Workbench prompts before updating the ejb-jar.xml file when you save the project.

4. Click OK.

Database Preferences

Use the Database preferences to specify custom database divers and connection URLs for the OracleAS TopLink Mapping Workbench. These drivers and URLs can then be used when defining database logins.

To Specify Database Preferences:

1. Click the Preferences button

   Text description of the illustration prefbtn.gif

   on the toolbar. The Preferences dialog appears.

   You can also display the Preferences dialog box by choosing Tools > Preferences from the menu.

2. Select Database in the Category pane.

   Figure 1-13 Database Preferences

   

   Text description of the illustration preflogi.gif

3. Use this table to enter data in each field and click OK.

   Field	Description
   Database Drivers	Click Add to add a custom database driver.
   Connection URLs	Select a Database Driver, then click Add to add a custom database connection URL.

To edit or remove an existing driver or URL, select the driver or URL and click Remove or Edit.

Help Preferences

Use the Help preferences to select a Web browser to use the online help and Web-based support.

To Specify the Help Preferences:

1. Click the Preferences button

   Text description of the illustration prefbtn.gif

   on the toolbar. The Preferences dialog box appears.

   You can also display the Preferences dialog box by choosing Tools > Preferences from the menu.

2. Select Help in the Category pane.

   Figure 1-14 Help Preferences

   

   Text description of the illustration prefhelp.gif

3. Use this table to enter data in each field and click OK.

   Field	Description
   Web Browser	Click Browse and select the location of your default Web browser. You must specify a Web browser to use the online help and Web-based support.

Working with the OracleAS TopLink Mapping Workbench in a Team Environment

When using an OracleAS TopLink Mapping Workbench project in a team environment, you must synchronize your changes with other developers. See "Merging Files" for more information.

You can use the OracleAS TopLink Mapping Workbench with a source control system (see "Using a Source Control Management System") to facilitate enterprise-level team development. If you have a small development team, you can manage the changes from within XML files (see "Sharing Project Objects").

Using a Source Control Management System

If you use an enterprise, file-based, source control management system to manage your Java source files, you can use the same system with your OracleAS TopLink Mapping Workbench project files. These project files are maintained by the OracleAS TopLink Mapping Workbench and written in XML file format.

The source control system's check in and out mechanism defines how to manage the source (the XML source and OracleAS TopLink Mapping Workbench project file) in a multi-user environment.

To Check Out and In OracleAS TopLink Mapping Workbench Project Files:

Although your actual development process will vary, depending on your SCM tool, a typical process involves:

1. Determine (based on your SCM system) which files to retrieve from the source management system.

2. Edit the project using the OracleAS TopLink Mapping Workbench.

3. Save the edited project. If the OracleAS TopLink Mapping Workbench displays the Read Only Files dialog (see Figure 1-15), make a note of these files, they must be unlocked and possibly merged.

4. Merge the required project files. See "Merging Files" for details.

5. Check in the modified files, then retrieve from the repository any files that have been added or modified for this OracleAS TopLink Mapping Workbench project.

Merging Files

The most difficult aspect of team development is merging changes from two (or more) members that have simultaneously edited the same file. If one developer checks in his or her changes, a merge condition exists. Use a file comparison tool to determine the merged aspects of the project. The files to edit will vary, depending on the type of merge:

• Merging Project Files

• Merging Table, Descriptor, and Class Files

Example 1-1 and Example 1-2 demonstrate a "merge out" merging technique.

Merging Project Files

Project files contain references to the objects in the project. Generally, your project <projectName>.mwp contains:

• Database information - <database>
  • Database tables - <tables>

• Descriptors - <descriptors>

• Repository - <repository>
  • Classes - <classpath-entries>

Changes in these parts of the .mwp file are normally caused by adding, deleting, or renaming project elements.

To Merge Project Files:

Generally, you will need to merge a project file if another developer has added or removed a descriptor, table, or class, and checked in the project while you were adding or removing descriptors, tables, or classes from the same project. Use this procedure to merge the project's .mwp file:

1. Perform a file comparison between the <projectName>.mwp file in the repository and the your local copy. The file comparison shows the addition or removal of an element inside the owner (i.e., <database>, <descriptors>, or <repository>).

2. Insert or delete the XML into your local <projectName>.mwp file (inside the corresponding owner element). This brings your local code up to date to the current code in the code repository.

3. Retrieve any updated files, as indicated by your source control system. Your local source now matches the repository.

Example 1-1 Merging Projects

Another developer has added and checked in a new Employee class descriptor to the com.demo package while you were working with the same OracleAS TopLink Mapping Workbench project. To merge your work with the newly changed project:

1. Perform a file comparison on the <projectName>.mwp to determine the differences between your local file and the file in the repository. Your SCM system may show the file in merge status.

   The file comparison shows the addition of the <package-descriptor> tag and a <name> element inside that tag:

   <package-descriptor>
       <name>com.demo.Employee.ClassDescriptor</name>
   </package-descriptor>
   
   

2. Insert this XML into your <projectName>.mwp file (inside the <descriptors> element) to bring it up to date to the current files the source repository.

3. Retrieve any new or updated files from your source control system. This includes the newly added Employee class descriptor.

4. Check in files that you have modified.

Merging Table, Descriptor, and Class Files

Developers who concurrently modify the same existing table, descriptor, or class file will create a merge condition for the following files:

• Table - <tableName>.xml (one for each table)

• Descriptor - <descriptorName.type>.xml (one for each descriptor)

• Class - <className>.xml (one for each class)

The OracleAS TopLink Mapping Workbench changes these files when saving a project if you have changed any of the contents within them (such as adding a mapping to a descriptor, adding an attribute to a class, or a changing a field reference in a table).

To Merge a Table, Descriptor, or Class File:

If another developer has changed an attribute in a table, descriptor, or class, while you were changing a different mapping on that same descriptor, you will need to merge your project.

1. Perform a file comparison on the specific .xml file(s) in merge status (i.e., table, descriptor, or class). The file comparison shows the addition or removal of an XML element.

2. Insert or remove the XML into your local .xml file to bring it up to date to the current files the source repository.

Example 1-2 Merging Files

Another developer has added and checked in the firstName mapping to the Employee class descriptor while you were changing a different mapping on that same descriptor. To merge your work with the newly changed project:

1. Perform a file comparison on the com.demo.Employee.ClassDescriptor.xml file located in <projectRoot>/Descriptor/ that is in merge status.

   The file comparison shows the addition of the <mapping> tag and the elements inside that tag:

   <mapping>
       <uses-method-accessing>false</uses-method-accessing>
       <inherited>false</inherited>
       <read-only>false</read-only>
       <instance-variable-name>firstName</instance-variable-name>
       <default-field-names>
           <default-field-name>direct field=</default-field-name>
       </default-field-names>
       <field-handle>
           <field-handle>
               <table>EMPLOYEE</table>
               <field-name>F_NAME</field-name>
           </field-handle>
       </field-handle>
   <mapping-class>MWDirectToFieldMapping </mapping-class>
   </mapping>
   
   

2. Insert this XML block into your local com.demo.Employee.ClassDescriptor.xml file (inside the existing <mappings> element) to bring it up to date to the current files in the source repository.

3. Retrieve any new files noted as missing by your source control system. This includes any tables or descriptors that may be referenced by the new mapping.

4. Check in files that you have modified.

Sharing Project Objects

You can also share project objects by copying the table or descriptor file(s) into the appropriate directories in the target project.

After copying the file(s), insert a reference to the table, descriptor, or class in the appropriate place in the <projectName>.mwp file. All references contained within the project file must refer to an existing object in the project.

Managing the ejb-jar.xml File

When working in a team environment, manage the ejb-jar.xml file similarly to the .xml project files. The OracleAS TopLink Mapping Workbench edits and updates the ejb-jar.xml file, if necessary, when working with an EJB project.

If you use a version control system, perform the same check in and check out procedures. For merge conditions, use a file comparison tool to determine which elements have been added or removed. Modify the file as necessary and check in the file to version control your work.

Working with Locked Files

When working in a team environment, your source control system may lock files when you retrieve them from the repository. If the OracleAS TopLink Mapping Workbench attempts to save a locked file, the Version Control Assistance dialog box appears, showing the locked files.

Figure 1-15 Version Control Assistance

Text description of the illustration readonly.gif

Select one of the following methods to save your project:

• Use your source control system to unlock the files, then click Save.

• Click Save As to save the project to a new location.

See "Saving Projects" for more information.