2
Understanding Projects

The Mapping Workbench project ( .mwp file) stores the information about how classes map to database tables. These are language independent XML files, different from the deployment XML files generated by the Mapping Workbench, read in by the application using the XMLProjectReader class.

You can edit each component of project, including:

• Project settings, such as the project classpath and sequence information

• Database information, such as driver, URL, and login information

• Table schema information for the database

• Packages and classes associated with the project

• Descriptor information for each class

Working with Projects

The Mapping Workbench displays projects and their contents in the Project Tree pane. When you select a project, its attributes display in the Properties pane.

The Mapping Workbench can log runtime XML calls (in the mw_xml.log file) to help troubleshoot projects. Refer to the Oracle9iAS TopLink Troubleshooting Guide for additional information.

Creating new Projects

Use this procedure to create a new Mapping Workbench project.

To Create a New Project:

1. Click on the Create New Project button in the toolbar. The Create New Project window appears.

   You can also create a new project by selecting File > New Project from the menu.

   Figure 2-1 Create New Project

   

   Text description of the illustration create.gif

2. Enter the database name and platform for the new project and click on OK. The Save As window appears.

   See "Working with Databases" for more information.

3. Select a directory location in which to save the project and click on Save.

   Note: Always use a new folder to save a project. After creating the .mwp project do not rename the file. See "Saving Projects" to save your project with a different name.

   The mapping workbench appears showing the project name in the Project Tree pane. Continue with "Working with Project Properties" to create a project.

Opening Existing Projects

Use this procedure to open an existing project.

Caution: To upgrade from a previous version of TopLink, you must follow specific upgrade procedures and use the TopLink Package Renamer. Refer to the TopLink Release notes and Oracle9iAS TopLink Getting Started Guide for more information.

To Open an Existing Project:

1. Click on the Open Project button in the toolbar. The Choose a File window appears.

   You can also open a project by selecting File > Open Project from the menu.

   Note: The File menu also contains a list of recently opened projects. You may select one of these projects to open.

2. Select the TopLink Mapping Workbench project file ( .mwp) to open and click on Open. The Mapping Workbench displays the project information.

   If you open a 3.x Mapping Workbench project that contains EJBs, the Potential EJB Descriptors window appears.

   Figure 2-2 Potential EJB Descriptors

   

   Text description of the illustration potentl.gif

3. Select which of the descriptors should be imported as EJB descriptors, the project persistence type, and click on OK.

   You can also specify if the Mapping Workbench generates methods and attributes that comply with the EJB specification if they are not found within the current class descriptor(s).

Saving Projects

The Mapping Workbench does not automatically save your project. Be sure to save your project often to avoid losing data.

To Save Your Project(s):

Click on the Save Selected Project button or Save All Projects button to save your project(s).

You can also save a project by selecting File > Save Project or File > Save All from the menu.

To Save Your Project with a Different Name or Location:

1. Select File > Save As. The Save As window appears.

2. Browse to the directory in which to save the project. In the File Name field, type the name of the project and click on Save.

   Caution: Do not simply rename the .mwp file outside of Mapping Workbench. Always rename a project by using the Save As option.

Refreshing the Project Tree

If the Mapping Workbench interface becomes corrupt, use the Refresh Tree option to redraw the Project Tree.

To Refresh the Project Tree:

Right-click on the project icon in the Project Tree pane and select Refresh from the pop-up panel.

You can also refresh the project tree by choosing the project icon and selecting File > Refresh from the menu or pressing Ctrl+T.

Working with Project Properties

Each project in the Project Tree pane contains various editable parameters. To edit the project's properties, select the project object in the Project Tree pane. The following tabs appear in the Properties pane.

• General project properties (persistence type and classpath)

• Default project properties (identity map, existence checking and field access method)

• Sequencing

• Table generation (primary key and primary key search pattern)

Working with General Project Properties

Use the project's General tab to specify the default persistence type and classpath information.

Each TopLink project uses a classpath - a set of directories, .jar files, and .zip files - when importing Java classes and defining object types.

To create a descriptor for a persistent class, the Mapping Workbench reads a compiled Java .class file to read its attributes and relationships.

To Specify the General Properties:

1. Choose the project object in the Project Tree pane.

2. Click on the General tab in the Properties pane. The General tab appears.

   Figure 2-3 General Tab

   

   Text description of the illustration general.gif

3. Specify the project's persistence type. For EJB projects, you can specify the location of the ejb-jar.xml file. See "Mapping EJB 2.0 Entities" and "Working with the ejb-jar.xml File" for more information.

   Note: This field applies for EJB projects only.

4. To add a new classpath entry, click on Add Entry and select the directory, .jar file, or .zip file to add.

   To add the system's classpath entries to the project, click on Add System Entries.

   To remove a classpath entry, select the entry and click on Remove.

   To create a relative classpath, select an entry and edit the path, as necessary. The path will be relative to the Project Save Location.

See "Working with Classes" for information.

Mapping EJB 2.0 Entities

You can create a Mapping Workbench project based on information in the ejb-jar.xml file. Use this file to map the EJB 2.0 CMP entity beans' virtual fields (called Container Managed Fields, defined by <cmp-field> tag) or relationships (called Container Managed Relationship, defined by <cmr-field> tag) to database tables. You must specify an .xml file or a .jar file that contains an ejb-jar.xml file.

The Mapping Workbench defines all descriptors for entity classes (as defined in the ejb-jar.xml file) as EJB descriptors . The Mapping Workbench does not create (or remove) descriptors for the interfaces and primary key class for the entity when refreshing from the ejb-jar.xml.

Note: The Mapping Workbench creates class descriptors for entity classes not defined in the ejb-jar.xml file. You must manually change the descriptor type (see "Specifying Descriptor Types").

To update your project from the .xml file, right-click on an EJB descriptor and select Update Descriptors from ebj-jar.xml. You can also update the project by selecting Selected > Update Descriptors from ebj-jar.xml from the menu. See "Working with the ejb-jar.xml File" for more information.

Working with Default Properties

Use the project's Default tab to specify the default:

• identity map and existence checking policy for descriptors (if they do not have a specific identity policy)

• field accessing applied to newly created descriptors

To Specify Default Project Properties:

1. Choose the project object in the Project Tree pane.

2. Click on the Defaults tab in the Properties pane. The Defaults tab displays.

   Figure 2-4 Defaults Tab

   

   Text description of the illustration defaults.gif

3. Use this table to enter data in each field:

   Field	Description
   Identity Map	Use the Type drop-down list to select the default identity map and its size for descriptors in this project (see "Working with Identity Maps").
   Specify Project Package	Default package to use for this project. See "Renaming Packages" for information on renaming packages.
   Existence Checking	Specify the type of existence checking to use.
   Field Accessing	Specify if the descriptors use Method or Direct field accessing (see "Specifying Direct Access and Method Access").

Renaming Packages

To rename your packages, you must edit each of the project's associated .xml files in the following sub-directories:

• Class

• ClassRepository

• Descriptor

• Package

You must also edit the package and class names in the .mwp file. After changing the package names in all files, open the project in the Mapping Workbench. TopLink will now use the new package name.

Working with Sequencing Properties

Sequence numbers are artificial keys that uniquely identify the records in a table. Use the project's Sequencing tab to specify default sequencing properties for all descriptors in the project.

To Specify Default Sequencing Properties:

1. Choose the project object in the Project Tree pane.

2. Click on the Sequencing tab in the Properties pane. The Sequencing tab displays.

   Figure 2-5 Sequencing Tab

   

   Text description of the illustration sequence.gif

3. Use this table to enter data in each field:

   Field	Description
   Sequencing Preallocation Size	Default pre-allocation size. Default is 50.
   Sequencing Type	Specify if the project uses: Default sequencing Native sequencing Custom sequencing table
   Custom Sequence Table Information	Use these fields to select the sequence table, and name and counter fields. These fields apply only when Use Sequencing Table is selected.

Working with Table Generation Properties

Use the project's Table Generation tab to specify the default primary key name and primary key search pattern (database schema) to use when generating tables. The resulting tables and columns will conform to the naming restrictions of the project's target database.

To Specify Default Table Generation Properties:

1. Choose the project object in the Project Tree pane.

2. Click on the Table Generation tab in the Properties pane. The Table Generation tab displays.

   Figure 2-6 Table Generation Tab

   

   Text description of the illustration tblgen.gif

3. Use this table to enter data in each field:

   Field	Description
   Default Primary Key Name	Default name to use when generating primary keys.
   Primary Key Search Pattern	Default search pattern to use when generating primary keys.

Setting Default Advanced Properties

In addition to a descriptor's standard property tabs, you can specify advanced properties for each descriptor. You can also specify which of these advanced properties appear, by default, for new descriptors.

To Specify the Default Advanced Properties for Descriptors:

1. Right-click on the project object in the Project Tree pane and select Set Advanced Property Defaults from the pop-up menu. The Advanced Property Defaults window appears.

   You can also set the default advanced properties by choosing the project object and selecting Selected > Set Advanced Property Defaults from the menu.

   Figure 2-7 Advanced Property Default

   

   Text description of the illustration advprop.gif

2. Select each advanced property to display, by default, when creating and editing descriptors.

3. Click on OK.

Working with Classes

The Mapping Workbench creates descriptors from Java classes and packages.

Creating Classes

Use this procedure to create a new class and/or package from within the Mapping Workbench.

To Create a New Class:

1. Right-click on the project in the Project Tree pane and select Create New Class from the pop-up menu.

   You can also create a new class by clicking on the Create Class button or select the project and select Selected > Create New Class from the menu.

   Figure 2-8 Add New Class

   

   Text description of the illustration addclass.gif

2. Use the Package Name drop-down list to select a package or type a new package name.

3. In the New Class Name field enter a class name and click on OK. The Mapping Workbench adds the new class to your project in the Project Tree pane.

   Note: The Class Name must be unique within the package.

To Update Classes from Available Packages and Classes:

1. Define the available class(es) and package(s) for the project on the General tab. See "Working with General Project Properties" for information on classes and packages.

2. Clicking on the Add/Update Class button . The Select Classes window appears.

   You can also update the classes by selecting Selected > Add/Refresh Classes from the menu.

   Figure 2-9 Select Classes

   

   Text description of the illustration select.gif

3. Select the package(s) and/or class(es) to add to the project and click on OK. The Mapping Workbench adds the new classes to your project in the Project Tree pane.

   Note: The Mapping Workbench creates class descriptors for each package/class. You must manually change the descriptor type, if needed (see "Specifying Descriptor Types").

To Remove a Class from a Project:

Select on the descriptor and click on the Remove Class button or select Selected > Remove Class from the menu.

Exporting Projects

To use your project with the TopLink Foundation Library, you must either generate deployment XML or export the project to Java source code.

Exporting Project to Java Source

Use this procedure to convert the project to Java code. Generally, this generated code executes faster and deploys easier than XML files.

To Export the Project to Java Source Code:

1. Right-click on the project in the Project Tree pane and select Export Project to Java Source from the pop-up menu. The Choose an Export File window appears.

   You can also export the project by clicking on the Export to Java Source button or by selecting File > Export to Java Source or Selected > Export to Java Source from the menu.

2. Select a directory location, file name (.java), and click on OK.

Exporting Table Creator Files

Use this procedure to create Java source code to generate database tables.

To Export Table Creator Files:

1. Right-click on the project in the Project Tree pane and select Export Table Creator Java Source from the pop-up menu. The Choose an Export File window appears.

   You can also export the table creator files by selecting File > Export Table Creator Java Source or Selected > Export Table Creator Java Source from the menu.

2. Select a directory location, file name (.java), and click on OK.

Generating Deployment XML

Use this procedure to generate XML files from your project that can be read by the TopLink Foundation Library. Using this option reduces development time by eliminating the need to regenerate and recompile Java code each time the project changes.

To generate deployment XML:

1. Right-click on the project in the Project Tree pane and select Generate Deployment XML from the pop-up menu. The Choose an Export File window appears.

   You can also export the project by selecting File > Generate Deployment XML or Selected > Generate Deployment XML from the menu.

2. Select a directory location, file name (.xml), and click on OK.

Working with the ejb-jar.xml File

For Mapping Workbench projects that use EJB 2.0 CMP persistence, use the ejb-jar.xml file to store persistence information for the application server. With the Mapping Workbench, you can import information from an existing ejb-jar.xml file into your project, or you can create/update the ejb-jar.xml from your project.

Each Mapping Workbench project uses a single ejb-jar.xml file. For each entities from the file you should have an EJB descriptors in the project. All entities must use the same persistence type.

As you make changes in your project, you can update the ejb-jar.xml file to reflect your project. Also, if you edit the ejb-jar.xml file outside of the Mapping Workbench, you can update your project to reflect the current file.

The following table describes how fields in the ejb-jar.xml file correspond to specific functions in the Mapping Workbench:

Table 2-1 ejb-jar.xml Fields and Mapping Workbench

ejb-jar.xml	Mapping Workbench
primkey	Bean attribute mapped to the primary key in the database table (see "Setting Descriptor Information")
ejb-name, prim-key-class, local, local-home, remote, home, and ejb-class	EJB descriptor information on the EJB Info tab (see "Displaying EJB descriptor Information")
abstract-schema-name	Descriptor Alias field on the Name Queries tab (see "Named Queries")
cmp-field	Non-relational attributes on the Descriptor Info tab (see "Setting Descriptor Information")
cmp-version	Persistence Type field on the General tab (see "Working with General Project Properties") The persistence-type is set to container.
query	Queries listed in Queries tab (see "Specifying Queries") Note: The findByPrimaryKey query is not in the ejb-jar.xml file, as per the EJB 2.0 specification.
relationships	One-to-one, one-to-many, and many-to-many mappings (see "Working with Relationship Mappings")

Writing to the ejb-jar.xml File

Use this procedure to update the ejb-jar.xml file, based on the current Mapping Workbench information. Use the EJB preferences to specify if the Mapping Workbench automatically updates the ejb-jar.xml file when you save the project.

Note: You can also write the information to a .jar file. The Mapping Workbench will automatically place the ejb-jar.xml file in the proper location (META-INF/ejb-jar.xml).

To Write the ejb-jar.xml File:

Select Selected > Write Project to ejb-jar.xml from the menu. You can also write the ejb-jar.xml file by right-clicking on the project in the Project Tree pane and select Write Project to ejb-jar.xml from the pop-up menu.

• If the project does not currently contain an ejb-jar.xml, the system prompts you to create a new file.

• If the system detects that changes were made to the ejb-jar.xml file but not yet read into the Mapping Workbench (i.e., you changed the file outside of the Mapping Workbench), the system prompts you to read the file before writing the changes.

Reading from the ejb-jar.xml File

Use this procedure to read the ejb-jar.xml information and update your Mapping Workbench project.

Tip: To automatically create EJB descriptors in the Mapping Workbench for all entities, read the ejb-jar.xml file before adding any classes in the Mapping Workbench.

To read the ejb-jar.xml file:

Select Selected > Update Project from ejb-jar.xml from the menu. You can also read the ejb-jar.xml file by right-clicking on the project in the Project Tree pane and select Update Project from ejb-jar.xml from the pop-up menu.