2
Understanding Projects

The Oracle Application Server TopLink 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 OracleAS TopLink Mapping Workbench, that are read in by the application using the XMLProjectReader class.

You can edit each component of the project, including:

• Project settings, such as the project class path 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 OracleAS TopLink Mapping Workbench displays projects and their contents in the Navigator pane. When you select a project, its attributes display in the Editor pane. The OracleAS TopLink Mapping Workbench can log runtime XML calls (in the mw_xml.log file) to help troubleshoot projects (see "General Preferences" for more information).

Creating new Projects

Use this procedure to create a new OracleAS TopLink Mapping Workbench project.

To Create a New Project:

1. Click the Create New Project button on the toolbar. The Create New Project dialog box appears.

   You can also create a new project by choosing File > New Project.

   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 OK. The Save As dialog box appears.

   To select a different database, click Browse. See "Working with Databases" for more information.

3. Select a location in which to save the project and click 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 OracleAS TopLink Mapping Workbench window appears, showing the project name in the Navigator pane. Continue with "Working with Project Properties".

Opening Existing Projects

Use this procedure to open an existing project.

Caution: To upgrade from a previous version of OracleAS TopLink, you must follow specific upgrade procedures and use the Package Rename tool. Refer to the Oracle Application Server TopLink Release Notes and Oracle Application Server TopLink Getting Started Guide for more information.

To Open an Existing Project:

1. Click the Open Project button on the toolbar. The Choose a File dialog box appears. You can also open a project by choosing File > Open Project from the menu.

   Note: The File > Reopen menu option contains a list of recently opened projects. You can select one of these projects to open.

2. Select the OracleAS TopLink Mapping Workbench project file ( .mwp) to open and click Open. The OracleAS TopLink Mapping Workbench displays the project information. If you open an OracleAS TopLink Mapping Workbench version 3.x project that contains EJBs, the Potential EJB Descriptors dialog box 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 OK.

   You can also specify whether the OracleAS TopLink 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 OracleAS TopLink 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 the Save Selected Project button or Save All Projects button to save your project(s). You can also save a project by choosing File > Save Project or File > Save All from the menu.

To Save Your Project with a Different Name or Location:

1. Choose File > Save As. The Save As dialog box 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 Save.

   Caution: Do not rename the .mwp file outside of the OracleAS TopLink Mapping Workbench; instead use the Save As option.

Refreshing the Navigator Pane

If the OracleAS TopLink Mapping Workbench interface becomes corrupt, use the Refresh Tree option to refresh the Navigator pane.

To Refresh the Navigator:

Choose File > Refresh from the menu, or press Ctrl+T.

Generating the Project Status Report

Use the Project Status Report to display a list of all warnings and errors in the OracleAS TopLink Mapping Workbench project. This report will quickly identify any incomplete mappings and indicate the project's current status.

To Generate the Status Report:

Choose Tools > Generate Project Status Report from the menu. The Project Status Report dialog box appears, displaying the status of each OracleAS TopLink Mapping Workbench project.

Figure 2-3 Project Status Report

Text description of the illustration statrpt.gif

See "Error Messages" for information on each reported error.

To copy the report to another application (such as a text editor or e-mail message), click Copy.

Working with Project Properties

Each project in the Navigator pane contains different editable parameters. To edit the project's properties, select the project object in the Navigator pane. The following tabs appear in the Editor pane.

• General project properties (persistence type and class path)

• Sequencing table defaults

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

• Options (when generating Java source and creating Java information)

Working with General Project Properties

Use the project's General tab to specify the default persistence type and class path information. Each OracleAS TopLink project uses a class path -- 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 OracleAS TopLink Mapping Workbench reads a compiled Java .class file to read its attributes and relationships.

To Specify the General Properties:

1. Select the project object in the Navigator pane.

2. Select the General tab in the Editor pane. The General tab appears.

   Figure 2-4 General Tab

   

   Text description of the illustration general.gif

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

   Field	Description
   Project Save Location	Location of the project's .mwp file and associated folders. This field is for display only. All relative locations are based on the Project Save Location.
   Persistence Type	Specify the project's persistence type. For EJB projects, specify the location of the ejb-jar.xml file.
   ejb-jar.xml Location	Location of the ejb-jar.xml file for this project. 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.
   Class Path	Location of the classes and packages for this project. See "Working with Classes" for information. To add a new class path entry, click Add Entries and select the directory, .jar file, or .zip file to add. To remove a class path entry, select the entry and click Remove. To change the order of the entries, select the entry and click Up or Down. To create a relative class path, select an entry and edit the path, as necessary. The path will be relative to the Project Save Location.

Mapping EJB 2.0 Entities

You can create an OracleAS TopLink Mapping Workbench project based on information in the ejb-jar.xml file. Use this file to map the EJB 2.0 Container Managed Persistence (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 OracleAS TopLink Mapping Workbench defines all descriptors for entity classes (as defined in the ejb-jar.xml file) as EJB descriptors . The OracleAS TopLink 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 OracleAS TopLink 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 an EJB descriptor and select Update Descriptors from ebj-jar.xml. You can also update the project by choosing Selected > Update Descriptors from ebj-jar.xml from the menu. See "Working with the ejb-jar.xml File" for more information.

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. See "Working with Sequencing" for more information.

To Specify Default Sequencing Properties:

1. Select the project object in the Navigator pane.

2. Click the Sequencing tab in the Editor 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 preallocation size. Default is 50.
   Sequencing Type	Specify whether the project uses: OracleAS TopLink Default sequencing The database's Native sequencing Custom sequencing table
   Custom Sequence Table Information	Use these fields to specify a sequence name, the name field, and counter field. These fields apply only you select Use Custom Sequencing Table.

Working with Default Properties

Use the project's Default tab to specify the default identity map, existence checking, and field access method.

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. Select the project object in the Navigator pane.

2. Select the Defaults tab in the Editor pane. The Defaults tab displays.

   Figure 2-6 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").
   Existence Checking	Specify the type of existence checking to use.
   Field Accessing	Specify whether the descriptors use Method or Direct field accessing (see "Specifying Direct Access and Method Access").
   Named Queries	Specify if OracleAS TopLink Caches All Statements or Binds All Parameters for named queries. See "Named Queries" for more information, including how to override this setting for specific queries.

Renaming Packages

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

• 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 OracleAS TopLink Mapping Workbench. OracleAS TopLink now uses the new package name.

Working with Project Options

Use the project's Options tab to specify the default file names, class names, and directories, when exporting or generating Java source code and deployment XML. In addition, you can specify the 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 Project Options:

1. Select the project object in the Navigator pane.

2. Click the Options tab in the Editor pane. The Options tab displays.

   Figure 2-7 Options Tab

   

   Text description of the illustration projopt.gif

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

   Field	Description
   Deployment and Java Source Code Generation	Specify the defaults to use when exporting project information. Directories are relative to the project location and will contain folders for each generated package.
   Project Java Source	Java class name and project root directory when generating Java source. See "Exporting Project to Java Source" for more information.
   Project Deployment XML	Filename (*.xml) and directory when generating Java source. See "Exporting Deployment XML" for more information.
   Table Creator Java Source	Java class name and project root directory when generating table source. See "Exporting Table Creator Files" for more information.
   Model Java Source	Project root directory when generating Java model source. See "Generating Java Code for Descriptors" for more information.
   Table Generation
   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 (see "Working with Advanced Properties" for more information). 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 the project object in the Navigator pane and choose Set Advanced Property Defaults from the pop-up menu. The Advanced Property Defaults dialog box appears.

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

   Figure 2-8 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 OK.

Working with Classes

This section describes how to create descriptors from Java classes and packages and includes information on the following:

• Creating Classes

• Updating Classes

Creating Classes

Use this procedure to create new classes and packages from within the OracleAS TopLink Mapping Workbench.

To Create a New Class:

1. Right-click the project in the Navigator pane and choose Create New Class from the pop-up menu.

   You can also choose Selected > Create New Class from the menu.

   Figure 2-9 Add New Class

   

   Text description of the illustration addclass.gif

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

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

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

Updating Classes

Use this procedure to update or refresh the classes in the OracleAS TopLink Mapping Workbench project.

Note: If the class exists on both the system class path and the project class path, the OracleAS TopLink Mapping Workbench will update the class from the system class path. To update or refresh from the project class path, remove the class from the system class path and restart the OracleAS TopLink Mapping Workbench.

To Update 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. Click on Add/Refresh Class button . The Select Classes dialog box appears.

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

   Figure 2-10 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 OK. The OracleAS TopLink Mapping Workbench adds the new classes to your project in the Navigator pane.

   Note: The OracleAS TopLink Mapping Workbench creates class descriptors for each package/class. See "Specifying Descriptor Types" for to change the descriptor type.

To Remove a Class from a Project:

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

Exporting Project Information

To use your project with the Oracle Application Server TopLink Foundation Library, you must either generate deployment XML or export the project to Java source code. The OracleAS TopLink Mapping Workbench can generate and export the following project information:

• Exporting Project to Java Source

• Exporting Deployment XML

• Exporting Table Creator Files

• Exporting Java Model Source

  Note: When exporting Java source and deployment XML, the OracleAS TopLink Mapping Workbench writes the password using JCE encryption (when using JDK 1.4). Refer to the Oracle Application Server TopLink Getting Started Guide for information on using password encryption with pre-JDK 1.3. Use the OracleAS TopLink Sessions Editor to specify custom password encryption (see "Setting Login Properties").

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:

Right-click the project in the Navigator pane and choose Export > Project to Java Source from the pop-up menu.

You can also click the Export to Java Source button , or choose File > Export > Export to Java Source or Selected > Export > Export to Java Source from the menu.

If you have not defined deployment and source code generation defaults (see "Working with Project Options") the OracleAS TopLink Mapping Workbench prompts for a project class name and source directory.

Note: If your OracleAS TopLink Mapping Workbench project uses UTF-8 character set, you must use a compatible JDK when compiling the exported Java source.

Exporting Deployment XML

Use this procedure to generate XML files from your project that can be read by the OracleAS 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 Export Deployment XML:

Right-click the project in the Navigator pane and choose Export > Deployment XML from the pop-up menu.

You can also click the Export to Deployment XML button or choose File > Export > Generate Deployment XML or Selected > Export > Generate Deployment XML from the menu.

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

Exporting Table Creator Files

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

To Export Table Creator Files:

Right-click the project in the Navigator pane and choose Export > Export Table Creator Java Source from the pop-up menu.

You can also choose File > Export > Table Creator Java Source or Selected > Export > Table Creator Java Source from the menu.

If you have not defined deployment and source code generation defaults (see "Working with Project Options") the OracleAS TopLink Mapping Workbench prompts for a class name and root directory.

Exporting Java Model Source

Use this procedure to generate the project model's Java source.

To Export Java Model Source:

Right-click the project, package, or specific descriptor in the Navigator pane and choose Export > Export Java Model Source from the pop-up menu. The OracleAS TopLink Mapping Workbench creates a .java file for each selected descriptor.

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

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

Note: If your OracleAS TopLink Mapping Workbench project uses UTF-8 character set, you must use a compatible JDK when compiling the exported Java source.

Working with the ejb-jar.xml File

For OracleAS TopLink 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 OracleAS TopLink 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 OracleAS TopLink Mapping Workbench project uses a single ejb-jar.xml file. For each entity from the file, you should have an EJB descriptor 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. Additionally, if you edit the ejb-jar.xml file outside the OracleAS TopLink Mapping Workbench, you can update your project to reflect the current file.

Table 2-1 describes how fields in the ejb-jar.xml file correspond to specific functions in the OracleAS TopLink Mapping Workbench:

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

ejb-jar.xml	OracleAS TopLink 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	Nonrelational 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 and Named Finders") 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 OracleAS TopLink Mapping Workbench information. Use the EJB preferences to specify whether the OracleAS TopLink 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 OracleAS TopLink Mapping Workbench automatically places the ejb-jar.xml file in the proper location (META-INF/ejb-jar.xml).

To Write the ejb-jar.xml File:

Choose Selected > Write Project to ejb-jar.xml from the menu. You can also right-click the project in the Navigator pane and choose 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 OracleAS TopLink Mapping Workbench (for example, you changed the file outside the OracleAS TopLink Mapping Workbench), then 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 OracleAS TopLink Mapping Workbench project.

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

To Read the ejb-jar.xml File:

Choose Selected > Update Project from ejb-jar.xml from the menu. You can also right-click the project in the Navigator pane and choose Update Project from ejb-jar.xml from the pop-up menu.