5.1 Introduction to TopLink Workbench

TopLink Workbench is a separate component from the TopLink runtime–it lets you graphically configure descriptors and map your project. TopLink Workbench can verify the descriptor options, access the data source (either a database or an XML schema), and create the database schema. Using TopLink Workbench, you can define TopLink descriptors and configurations without using code.

The <projectName>.mwp file is used only by TopLink Workbench. Typically, the only time you need to modify the <projectName>.mwp file is to merge changes during application development by a team of developers (Section 7.2.2, "How to Merge Files").

Using TopLink Workbench, you export this information into a project.xml file that your TopLink enabled application reads at run time.

For more information on using TopLink Workbench as the development environment, see Figure 3-2.

5.2 Configuring the TopLink Workbench Environment

TopLink Workbench reads its environment variables from the setenv script in the <TOPLINK_HOME>/bin directory.

Before you launch TopLink Workbench, you must configure its environment as follows:

Use a text editor to open the <TOPLINK_HOME>/bin/setenv script.

For Windows, open the setenv.cmd file.

For UNIX, open the setenv.sh file.

Ensure that the JAVA_HOME environment variable is set:

For Windows: set JAVA_HOME=C:/j2sdk1.5.0_04

For UNIX: JAVA_HOME=/usr/local/packages/java; export JAVA_HOME

Update the DRIVER_CLASSPATH environment variable to add the location of the following (if necessary):

Note:

Do not include any Java classes for your persistent business objects in the DRIVER_CLASSPATH variable. Instead, add these persistent business objects in your TopLink Workbench project classpath (see Section 117.3, "Configuring Project Classpath").

The connector.jar file contains javax.resource.cci and javax.resource.spi interfaces that TopLink EIS uses. By default, TopLink Workbench updates its classpath to include the Java 1.5.nconnector.jar file from <ORACLE_HOME>/lib/java/api. If this version of the connector.jar file is incompatible with your environment, edit the workbench.cmd or workbench.sh file in <TOPLINK_HOME>/utils/workbench to change the path to this file.

At run time, this connector.jar file (or its equivalent) must be on your application or application server classpath.

To launch TopLink Workbench, double-click the workbench.cmd file located in <TOPLINK_HOME>/utils/workbench directory.

5.2.1 How to Configure the Language Preference

To use TopLink Workbench in a language different than your default, add the -Duser.language and -Duser.country options to the JVM_ARGS variable in the workbench.cmd or .sh file. For example, the following arguments will start TopLink Workbench in US English, regardless of default language of your operating system:

The Navigator window section shows the project navigation tree for all open projects (see Section 5.3.3, "How to Use the Navigator"). Click the plus ( + ) or minus ( – ) sign next to an object (or double-click the object) to expand or collapse the tree. When you select an object in the Navigator window section, its properties appear in the Editor window.

5.3.1 How to Use Menus

5.3.1.1 Using Menu Bar Menus

The menu bar, located at the top of the TopLink Workbench window, provides menus for each TopLink Workbench function. Some menus (such as Selected) are context-sensitive; the available options may vary, depending on the currently selected object.

5.3.2.2 Using Context Toolbar

The context toolbar provides quick access to functions for the currently selected object in the Navigator (see Section 5.3.3, "How to Use the Navigator"). The available buttons will vary, depending on which item you have selected.

You can also right-click the item and choose the appropriate option from the context menu.

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

Figure 5-5 numbered callouts show the following user interface components:

Inactive descriptor

Active descriptor

Errors and Missing Information

If an element in the project (such as a descriptor or mapping) contains an error or some deficiency (sometimes called neediness), a warning icon appears beside the element icon in the Navigator, and TopLink Workbench displays a message in the Problems window (see Section 5.3.5, "How to Use the Problems Window").

5.3.5 How to Use the Problems Window

If an element in the project (such as a descriptor or mapping) contains an error or some deficiency (sometimes called neediness), the TopLink Workbench displays a caution icon (represented by a yellow triangle with a black exclamation point in the middle) to the left of the deficient element in the Navigator (see Section 5.3.3, "How to Use the Navigator") and displays a message in the Problems window as Figure 5-7 shows.

Double-click any error message in the Problems window to automatically highlight the specific node in the Navigator. To display or hide the Problems window, select Window > Show Problems from the menu.

Use this dialog box to configure TopLink Workbench preferences. After changing preferences, you must restart TopLink Workbench.

To import your preferences from an existing file, click Import and select the file.

To export your preferences, click Export and select a directory location and filename.

5.4.1 How to Use General Preferences

Use the General preferences to customize the look and feel (the graphical user interface) of TopLink Workbench as well as to specify any proxy information required to access the Internet (for example, to allow TopLink to access XML schemas hosted on Internet sites). Follow these steps to customize the General preferences:

5.4.6 How to Use Database Preferences

Use the Database preferences to specify custom database divers and connection URLs for TopLink Workbench. These drivers and URLs can then be used when defining database logins. Follow these steps to set the Database preferences:

5.4.7 How to Use Sessions Configuration Preferences

Use the Sessions preferences to specify default classpaths to be added to each newly created TopLink sessions configuration for features that require an external Java class (for example, session event listeners). The entries added here will automatically appear on the Sessions Configuration property sheet (see Section 88.3, "Configuring a Sessions Configuration"). Follow these steps to set the Sessions Configuration preferences:

5.4.9 How to Use Session Platform Preferences

Use the Platform preferences to specify the default data source type for newly created sessions. The type selected here will automatically appear on the Create New Session dialog box. Follow these steps to set the Platform preferences:

In relational projects, when you expand the database object in the Navigator, TopLink Workbench displays the database tables associated with the project. You can associate tables by importing them from the database, or by creating them within TopLink Workbench.

Select the database object in the Navigator, and click Add or Update Existing Tables from Database. The Import Tables from Database dialog box appears.

You can also right-click on the database object in the Navigator and choose Add or Update Existing Tables from Database from the context menu or choose Selected > Add or Update Existing Tables from Database from the menu.

5.5.2.3 Creating Table References

References are table properties that contain the foreign key; they may or may not correspond to an actual constraint that exists on the database. TopLink Workbench uses these references when you define relationship mappings and multiple table associations.

Copy the script and paste it into a file. You may need to edit the file to include additional SQL information that TopLink Workbench could not generate. If the database table or column name is an SQL reserved word, you must edit the SQL script and enclose the database table or column in quotes. See "Oracle Database Reserved Words" in the Oracle Database SQL Reference Guide for more information.

Note:

If TopLink cannot determine how a particular table feature should be implemented in SQL, it generates a descriptive message in the script.

5.5.3.2 Generating Classes and Descriptors from Database Tables

TopLink Workbench can automatically generate Java class definitions, descriptor definitions, and associated mappings from the information in database tables. You can later edit the generated information if necessary.

For each table, TopLink Workbench does the following:

Creates a class definition and a descriptor definition.

Adds attributes to the class for each column in the table.

Automatically generates access methods, if specified.

Creates direct-to-field mappings for all direct (nonforeign key) fields in the table.

Creates relationship mappings (one-to-one and one-to-many) if there is sufficient foreign key information. You may be required to determine the exact mapping type.

Note:

Class and attribute names are generated based on the table and column names. You can edit the class properties to change their names.

To generate classes and descriptors from database tables, use the following procedure:

Select the database table(s) in the Navigator.

Right-click the table(s) and choose Generate Classes and Descriptors from > Selected Tables or All Tables from the context menu. TopLink Workbench prompts you to save your project.

You can also choose Selected > Generate Classes and Descriptors from > Selected Tables or All Tables from the menu.

Select an entry from Potential Relationships and click the 1:1 Mapping or 1:M Mapping button, located between the Potential Relationships and Selected Relationships windows. See Chapter 27, "Introduction to Relational Mappings" for more information on mappings.

If the table contains foreign key fields that may represent relationship mappings, then the Choose Relationships to Generate dialog box appears. Select a potential relationship and click the 1:1 Mapping or 1:M Mapping button, located between the Potential Relationships and Selected Relationships windows.

5.6.1 How to Use XML Schemas in the Navigator

After you import one or more XML schemas into your project (see Section 5.6.3, "How to Import an XML Schema") and you expand the schema object in the Navigator, TopLink Workbench displays the schemas associated with the project.

Specify that TopLink Workbench should import the schema from the project classpath.

Resource Name

Enter the fully qualified name of the XML schema file including the name of the package of which it is a part. For example, if your XML schema mySchema.xsd is in C:\project\config and you add this directory to your project classpath (see Table 117-4, "Project Support for Project Classpath"), specify a resource name of project.config.mySchema.xsd.

To reimport a specific schema, right-click on the specific schema in the Navigator and select Reimport Schema from the context menu.

To reimport all schemas in a project, right-click on Schemas in the Navigator and select Reimport All Schemas from the context menu.

To change a schema's source, right-click on the specific schema in the Navigator window and select Properties from the context menu. The Schema Properties dialog appears.

Specify that TopLink Workbench should import the schema from the project classpath.

Resource Name

Enter the fully qualified name of the XML schema file including the name of the package of which it is a part. For example, if your XML schema mySchema.xsd is in C:\project\config and you add this directory to your project classpath (see Section 117.3, "Configuring Project Classpath", specify a resource name of project.config.mySchema.xsd.

5.6.4.2 How to Configure an XML Schema Reference Using Java

Use Java to configure schema reference. Create a descriptor amendment method (see Section 119.35, "Configuring Amendment Methods") that instantiates the appropriate type of XMLSchemaReference (XMLSchemaClassPathReference, XMLSchemaFileReference, or XMLSchemaURLReference) and configures the descriptor with it, as follows:

If you are using EISDescriptors, the TopLink runtime does not use the schema reference; no further configuration is required.

If you are using XMLDescriptors, configure the descriptor with the XMLSchemaReference using XMLDescriptor method setSchemaReference.

5.6.5 How to Configure XML Schema Namespace

As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.

Use the following information to complete each Namespaces field in the tab:

Field

Description

Built-in Namespaces

All namespaces defined by xmlns:<prefix>="<URI>".

Note that when a schema is imported to the TopLink Workbench (see Section 5.6.3, "How to Import an XML Schema"), none of the built-in namespaces' URLs are selected. If you are using inheritance, declare the built-in namespace with xsi prefix. Otherwise, TopLink will throw exceptions.

Target Namespaces

All namespaces defined by targetNamespace="<URI>".

Imported Namespaces

All namespaces defined by xsd:import.

Prefix

Double-click in the Prefix field to specify the prefix that corresponds to the given namespace.

When the TopLink runtime marshalls (writes) an object to an XML document, it uses the namespace prefixes you specify here.

When selected, XML documents must use the corresponding URI qualifier when referring to types from this namespace. XML documents may use a different prefix value as long as that value is associated with the appropriate namespace URI. For more information, see Section 15.4.3, "TopLink Runtime Namespace Resolution".

However, it is sometimes convenient to create (see Section 5.7.1, "How to Create Classes") and configure classes in TopLink Workbench: for example, when generating an object model from a database schema.

This section describes using TopLink Workbench to edit classes, including the following:

Use the following information to enter data in Type Declaration fields on the Attributes tab:

Field

Description

Type

Click Browse and select a class and package for the attribute.

Dimensionality

Specify the length of an array. This field applies only if Type is an array.

Value Type

Click Browse and select a class and package for the attribute.

This field applies for ValueHolderInterface types only.

Map Key Type

Click Browse and select a class and package for the attribute.

This field applies for Map types only.

Map Value Type

Click Browse and select a class and package for the attribute.

This field applies for Map types only.

Element Type

Click Browse and select a class and package for the attribute.

This field applies for List types only.

5.7.2.7 Configuring Attribute Accessing Methods

This section includes information on Using TopLink Workbench to configure attribute accessing methods. If you change an attribute and regenerate the accessing methods, TopLink does not remove any previously generated methods.

5.7.3 How to Import and Update Classes

You can import any class on the system classpath or project classpath.

If a class exists on both the system classpath and the project classpath, TopLink Workbench will update the class from the system classpath. To update or refresh from the project classpath, remove the class from the system classpath and restart TopLink Workbench.

If the class exists on both the system classpath and the project classpath, TopLink Workbench will update the class from the system classpath. To update or refresh from the project classpath, remove the class from the system classpath and restart TopLink Workbench.

To Remove a Class from a Project, do the following:

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

5.7.4 How to Manage Nondescriptor Classes

Some of the mappings in your TopLink project may reference classes that do not have TopLink descriptors or are not included in the project.

To add, remove, or refresh Java classes that do not have TopLink descriptors, use this procedure:

5.7.5 How to Rename Packages

You can use TopLink Workbench to change the package statements in all the Java classes of a selected package (to move the all the classes contained by the selected package to a new package). This is useful if you are refactoring an existing TopLink Workbench project.

Note:

The TopLink Workbench package rename feature is not intended for migrating projects from older versions of TopLink: for this, you must still use the TopLink Package Renamer. The Package Renamer updates import statements for TopLink classes–it does not change the package statements in user application classes.

For information on the TopLink Package Renamer, refer to Oracle TopLink Release Notes.

5.8 Integrating TopLink Workbench with Apache Ant

If you use the Apache Ant Java-based build tool, you can use the Ant task and type definitions that TopLink provides to invoke certain TopLink Workbench functions from an Ant build file. Using these tasks, you can integrate TopLink Workbench into your automated build process.

5.8.1.2 Declaring TopLink Workbench Tasks

After you declare the TopLink Workbench task definitions (see Table 5-6) and data definitions (see Table 5-4) in the toplink-ant-lib.xml file (see Example 5-5), you can use a TopLink Workbench task in a build.xml file, as Example 5-6 shows:

5.8.6 How to Create the mappings.export Task

The mappings.export task is a generation task that you use to generate a TopLink deployment XML file for a given TopLink Workbench project (.mwp). The mappings.export task executes a mappings.validate (see Section 5.8.4, "How to Create the mappings.validate Task") before executing. A BuildException is thrown if validation fails.

5.8.9.2 Specifying Parameters Specified as Nested Elements

5.8.9.3 Examples

Example 5-13 shows a typical ignoreerrorset element. This element instructs a mappings.export task to ignore all of TopLink Workbench error codes 0402 and 0570. Note that the mappings.export task also uses an explicitly ignoreerror element: this means that the mappings.export task will ignore all of error codes 0402, 0570, and 0545.

5.8.10 How to Create the loginspec Task

Use the loginspec element to instruct a TopLink Ant task to override the project database login information in a TopLink Workbench project. For more information, see Chapter 96, "Introduction to Data Access".