1
Understanding the Workbench

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

To Use the 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 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 a TopLink session and register your descriptors. Add logic to your application to use the session to retrieve/store objects from/to the database.

   Figure 1-1 Using the Mapping Workbench

   

   Text description of the illustration usingmw.gif

Starting the Mapping Workbench

Use this procedure to start the Mapping Workbench.

To Start the Mapping Workbench:

For Windows environments: From the Start menu, select Program Files > Oracle9iAS TopLink > Mapping Workbench.

or

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

The splash screen appears, followed by the workbench window.

Working with the Workbench

The Mapping Workbench interface includes these parts:

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

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

• Project Tree pane - The project tree for all open projects (see "Using the Project Tree Pane"). Click on 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 Project Tree pane, its properties appear in the Properties pane.

• Properties pane - Specific property tabs for the currently selected object. See "Using the Properties Pane" for more information.

• Status bar - Provides instant information regarding the status of descriptors and mappings.

  Figure 1-2 Mapping Workbench

  

  Text description of the illustration mw.gif

User-interface components called out in Figure 1-2:

1. Menu bar

2. Toolbars

3. Project Tree pane

4. Properties pane

5. Status bar

Using the Menus

The 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 TopLink Mapping Workbench function. Some menus (such as Selected) are context-sensitive - the available options may vary, depending on the currently selected object.

Pop-up Menus

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

Figure 1-3 Sample Pop-up Menu

Text description of the illustration popup.gif

Using the Toolbars

The Mapping Workbench contains two types of toolbars:

• Standard Toolbar

• Mapping Toolbar

Use these toolbars to select options and functions.

Standard Toolbar

The standard toolbar provides quick access to the standard (File, Edit, Selected, etc.) menu options.

Figure 1-4 Standard Toolbar

Text description of the illustration toolbar.gif

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 from the Project Tree pane then clicking on the appropriate button in the mapping toolbar.

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

Figure 1-5 Mapping Toolbar

Text description of the illustration maptlbar.gif

To move a toolbar, click on a blank area of the toolbar and drag it to your desktop. To re-dock the toolbar to the Mapping Workbench, click on the toolbars's move handle and drag the toolbar back to the Mapping Workbench.

Using the Project Tree Pane

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

Figure 1-6 Sample Project Tree Pane

Text description of the illustration city.gif

User-interface components called out in Figure 1-6:

1. Project

2. Descriptor

3. Attribute/mapping

4. Database

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

When you select an item in the Project Tree pane, its properties appear in the Properties pane (see "Using the Properties Pane").

You can perform specific functions for an item by selecting the item in the Project Tree pane and:

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

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

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

Figure 1-7 Sample Active/inactive Descriptors

Text description of the illustration inactive.gif

User-interface components called out in Figure 1-7:

1. Inactive descriptor

2. Active descriptor

If a descriptor contains an error (sometimes called a "neediness" message), a warning icon appears beside the descriptor's icon in the Project Tree pane and a message displays in the status bar detailing the error. The Oracle9iAS TopLink: Troubleshooting Guide contains complete information on each Mapping Workbench error message.

Using the Properties Pane

The Properties pane, on the right side of the Mapping Workbench, displays the properties associated with the currently selected item in the Project Tree pane.

The properties of the selected item are displayed using tab pages, grouped according to their subject.

Working with Workbench Preferences

You can customize several aspects of the TopLink Mapping Workbench.

Changing the Look and Feel

Use this procedure to customize the "look and feel" (the graphical user interface) of the Mapping Workbench.

To Change the Look and Feel:

1. Click on the Preferences button in the toolbar. The Preferences window appears.

   You can also display the preferences window by selecting Tools > Preferences from the menu.

2. Click on Look and Feel in the Category pane.

   Figure 1-8 Look and feel Preferences

   

   Text description of the illustration preflook.gif

3. Select the look and feel and click on OK. You must restart the TopLink Mapping Workbench to apply the changes.

   Figure 1-9 Look and Feel Samples

   

   Text description of the illustration lfsample.gif

User-interface "look and feel" samples in Figure 1-9:

1. Windows

2. Metal (Java)

3. CDE/Motif

Specifying a Web Browser

Use this procedure to specify a web browser to use with the Mapping Workbench. You must specify a web browser to use the online help and web-based support.

To Change the Web Browser:

1. Click on the Preferences button in the toolbar. The Preferences window appears.

   You can also display the preferences window by selecting Tools > Preferences from the menu.

2. Click on Web Browser in the Category pane.

   Figure 1-10 Web Browser Preferences

   

   Text description of the illustration prefweb.gif

3. Select the web browser to use and click on OK.

Specifying Class Import Options

Use this option to specify if the Mapping Workbench verifies classes on import, when using the Add/Refresh Class function (see "To Update Classes from Available Packages and Classes:").

To Specify Class Import Options:

1. Click on the Preferences button in the toolbar. The Preferences window appears.

   You can also display the preferences window by selecting Tools > Preferences from the menu.

2. Click on Class import in the Category pane.

   Figure 1-11 Class import Options

   

   Text description of the illustration prefclas.gif

3. Select if the Mapping Workbench does not verify the classes in the chooser when performing an Add or Refresh.

   Caution: By default, the Mapping Workbench will always verify the classes. Select this option only if you encounter errors when displaying classes in the Select Classes window.

4. Click on OK.

Setting EJB Preferences

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

To Specify EJB Options:

1. Click on the Preferences button in the toolbar. The Preferences window appears.

   You can also display the preferences window by selecting Tools > Preferences from the menu.

2. Click on EJB in the Category pane.

   Figure 1-12 EJB Options

   

   Text description of the illustration prefejb.gif

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

4. Click on OK.

Working with the Mapping Workbench in a Team Environment

When using a Mapping Workbench project in a team environment, you must keep your changes "in-sync" with the other developers. See "Merging Files" for more information.

You can use the 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 files, you can use the same system with TopLink Mapping Workbench. The Mapping Workbench source files are edited by the Mapping Workbench and are written out in XML file format.

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

To Check Out/in Mapping Workbench Project Files:

1. Check out the files from the source management system to the users system.

   Note: Normally, leave all locked and unlocked files in the project in read-write status. This allows the Mapping Workbench to updated the files, as necessary. If you know specifically which files will be changed, you can leave the remaining files in read-only status. The Mapping Workbench will display an error if it attempts to update a read-only file.

2. Edit the project using the Mapping Workbench.

3. Save the edited project. Some project XML files may have been altered. The source control tool will notify the user that several files have been modified locally, on their system.

4. Check-in the modified files, and add any files that have been added to the source control system for this 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 their changes a merge condition exists. Usually, this condition exists in one of the root objects in the Mapping Workbench project.

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 a Root File

• Merging an Aggregate File

Because a typical project may involve many changes (especially in a team environment), merging your project before checking it in may require quite a bit of development time.

Merging a Root File

These files contain references to the objects that they hold onto. The root files are:

• Project - <projectName>.mwp (one for each project - holds database, packages, and repository)

• Database - <databaseName>.xml (one for each project - holds tables)

• Package - <packageName>.xml (one for each package - holds descriptors)

• Class Repository - repository.xml (one for each project - holds classes)

Changes in these files are normally caused by adding, deleting, or renaming a Table, Class, or Descriptor.

To Merge a Root File:

Another developer has added a descriptor and checked-in the project while you were adding or removing descriptors from the same project.

1. Perform a file comparison on the <packageName>.xml file in merge status. The file comparison shows the addition of the descriptor XML tag and an element inside the tag.

2. Insert the XML into your <packageName>.xml file (inside the Package element). This brings your local code up to date to the current code in the code repository.

3. Check out any new files indicated as "missing" by your source control system. This will include the new Descriptor that has been added.

4. Check in all files that you have modified.

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 package. To merge your work with the newly changed project:

• Perform a file comparison on the com.demo.xml file located in <projectRoot>/Package/ directory that is in merge status

  The file comparison shows the addition of the descriptor XML tag and an element inside that tag:

  <descriptor>
     <descriptor>com.demo.Employee.ClassDescriptor</descriptor>
  </descriptor>
  

• Insert this XML into your com.demo.xml file (inside the Package element) to bring it up to date to the current code in the code repository.

• Check out any new files identified as "missing" by your source control system. This will include the new Employee class descriptor that has been added.

• Check in files that you have modified.

Merging an Aggregate File

Developers simultaneously changing the Mapping Workbench that have altered the contents of an aggregate file will also cause a merge condition. Aggregated files include:

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

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

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

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

To Merge an Aggregate File:

If another developer has added a mapping to a descriptor and checked-in the project while you were changing a different mapping on that same descriptor:

1. Perform a file comparison on the <descriptorName>.xml file in merge status. The file comparison shows the addition of the Mapping XML tag and elements inside the tag.

2. Insert this XML into your <descriptorName>.xml file (inside the Mappings element). This brings your local code up to date to the current code in the code repository.

3. Check out any new files indicated as "missing" by your source control system. This will include any tables or descriptors referenced by the new mapping.

4. Check in all files that you have modified.

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.

• 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> XML tag and elements inside that tag:

  <Mapping>
  
     <comment></comment>
     <descriptor>com.demo.Employee.ClassDescriptor</descriptor>
     <usesMethodAccessing>false</usesMethodAccessing>
     <inherited>false</inherited>
     <readOnly>false</readOnly>
     <instanceVariableName>firstName</instanceVariableName>
     <defaultFieldNames>
  
        <defaultFieldName>direct field=</defaultFieldName>
  
     </defaultFieldNames>
     <fieldHandle>
  
        <FieldHandle>
           <table>EMPLOYEE</table>
           <fieldName>F_NAME</fieldName>
        </FieldHandle>
  
     </fieldHandle>
     <classIndicator>BldrDirectToFieldMapping </classIndicator>
  </Mapping>
  

• Insert this XML block into your com.demo.Employee.ClassDescriptor.xml file (inside the <Mapping> element) to bring it up to date to the current code in the code repository.

• Check out any new files that should be noted as missing by your source control system. This will include any tables or descriptors that may be referenced by the new mapping.

• Check in files that you have modified.

Sharing Project Objects

You can also share project objects by simply 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 or descriptor in the appropriate <databaseName>.xml or <packageName>.xml file. All references contained within these files 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 Mapping Workbench will edit and update 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/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 your work.