Introduction to the Workbench

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

You can use Workbench during the development phase of the development process. Typically, this phase includes the following:

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

Creating a Workbench project, importing your Java classes and data sources, and using descriptors to describe how the Java classes map to your data source model.

Creating an EclipseLink session and registering your descriptors. In your application, use the session to retrieve and store objects from and to the data source.

The <projectName>.mwp file is used only by 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 (How to Merge Files).

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

Configuring the Workbench Environment

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

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

Use a text editor to open the <ECLIPSELINK_HOME>/workbench/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 Workbench project classpath.

JCA connector.jar file – if you are using EIS Projects.The connector.jar file contains javax.resource.cci and javax.resource.spi interfaces that EclipseLink EIS uses. Edit the workbench.cmd or workbench.sh file in <ECLIPSELINK_HOME>/workbench/bin 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.

Oracle Database ORACLE_HOME/rdbms/jlib/xdb.jar file – if you are using Direct-to-XMLType Mappings with an Oracle9i or later database.

Custom Collection class that you use to override the default Collection class that EclipseLink uses with a mapping container policy. The following examples shows how to set the DRIVER_CLASSPATH variable for Windows system and for UNIX.

Example: Setting DRIVER_CLASSPATH on Windowsset DRIVER_CLASSPATH=C:\OraHome\jdbc\lib\ojdbc14.jar;C:\Attunity\Connect\Java\lib\attunityResourceAdapter.jar;C:\OraHome\rdbms\jlib\xdb.jarNote: If the path to your driver(s) contains spaces, you must enclose the path in double-quotes in the setenv.cmd file. For example: set DRIVER_CLASSPATH="C:\Program Files\some directory\driver.jar"

To use 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 Workbench in US English, regardless of default language of your operating system:

JVM_ARGS="-Duser.language=en -Duser.country=en_US"

Using Workbench

The following figure shows the primary parts of the Workbench window.

Workbench Window

The numbered callouts in the previous figure identify the following user interface components:

Menu bar: The menu bar contains menus for each Workbench function. Some objects also contain context-sensitive menus. See How to Use Menus for more information.

Toolbars: The toolbars contain shortcuts to specific functions. See How to Use Toolbars for more information.

Navigator window section: The Navigator window section shows the project navigation tree for all open projects (see 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.

Editor window section: The Editor window section contains specific property sheets and option tabs for the currently selected object. See How to Use the Editor for more information.

How to Use Menus

Using Menu Bar Menus

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

Sample Menu Bar Menu

Using Context Menus

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

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.

Sample Active and Inactive Descriptors

The 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 Workbench displays a message in the Problems window.

How to Use the Editor

The Editor, on the right side of the Workbench window, displays the property sheet associated with the currently selected item in the Navigator, as this figure shows.

Sample Editor

The numbered callouts identify the following user interface components:

Selected element (from the Navigator)

Editor property tabs

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 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 How to Use the Navigator) and displays a message in the Problems window as the Sample Deficient Mapping figure 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 Workbench preferences. After changing preferences, you must restart 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.

How to Use General Preferences

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

How to Use Database Preferences

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

Enter data in each field on the Preferences – Mappings – Database dialog box and click OK.

Use the following information to enter data in each field:

Field

Description

Database Driver

Enter the custom database driver class name.

Connection URL

Enter the custom database connection URL.

How to Use Sessions Configuration Preferences

Use the Sessions preferences to specify default classpaths to be added to each newly created EclipseLink 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. Follow these steps to set the Sessions Configuration preferences:

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:

Complete each field on the Preferences – Sessions Configuration – Platform dialog box and click OK.

Use the following information to enter data in each field:

Field

Description

Use Server Platform

Specify the default application server platform for newly created sessions configuration files (default, sessions.xml). See Creating a Sessions Configuration for more information.

Default Data Source Type

Select the default data source type (Database, EIS, or XML) and platform for newly created sessions. See Configuring the Server Platform for more information.

Using Databases

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

Sample Database Tables

The following numbered callouts identify the following database icons.

Project

Database

Database table

Each database table property sheet contains the following tabs in the Editor:

Columns – Add or modify the table's fields, and specify each field's properties.

Logging In and Out of a Database

To log in to a relational database, right-click the database object in the Navigator, and choose Log In to Database from the context menu or choose Selected > Log In to Database from the menu.

To log out of a relational database, right-click the database object in the Navigator and choose Log Out of Database from the context menu or choose Selected > Log Out of Database from the menu.

Creating New Tables

To create a new database table within Workbench, use the following procedure:

Select the database object in the Navigator window and click Add New Table. The New Table dialog box appears.You can also right-click the database object and choose Add New Table from the context menu, or choose Selected > Add New Table from the menu.New Table Dialog Box

Complete each field on the New Table dialog box and click OK.

Use the following information to enter data in each field:

Field

Description

Catalog

Use to identify specific database information for the table. Consult your database administrator for more information.

Schema

Use to identify specific database information for the table. Consult your database administrator for more information.

Table Name

Specify the name of this database table.

Workbench adds the database table to the project.

Although the database table has been added to the project, it has not been written to the actual database. See Generating Tables on the Database for more information on creating the table in the database.

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/Update Existing Tables from Database from the menu.Import Tables from Database Dialog Box

The following numbered callouts identify the following user interface components:

Filters

Database tables that match the filters

Complete each field on the Import Tables from Database dialog box and click OK.

Use the following information to enter data in each field of the dialog box:

Field

Description

Table Name Pattern

Specify the name of database table(s) to import. Use percent character ( %) as a wildcard. Tables that match the Table Name Pattern can be imported.

Select the tables in the Available Tables area to import, and click the right-arrow button. EclipseLink adds the table to the Selected Tables field. Click OK to import the tables from the database into the Workbench project.

Import Fully Qualified Names

Specify whether or not the tables' names are fully qualified against the schema and catalog.

Removing Tables

To remove a database table from the project, use the following procedure:

Select a database table in the Navigator, and click Remove Selected Item on the toolbar. Workbench prompts for confirmation.You can also right-click on the database object and choose Remove from the context menu or choose Selected > Remove from the menu.

Click OK. Workbench removes the table from the project.

Note: Although you have removed the table from the Workbench project, the table remains in the database.

Renaming Tables

To rename a database table in the Workbench project, use the following procedure:

Select a database table in the Navigator, and click Rename on the toolbar. The Rename dialog box appears.You can also right-click on the table and choose Rename from the context menu or choose Selected > Rename from the menu.

Enter a new name and click OK. Workbench renames the table.

Note: Although you have renamed the table in the Workbench project, the original table name remains in the database.

Refreshing Tables from the Database

To refresh (that is, reload) the database tables in the Workbench project, use this procedure:

Select a database table in the Navigator, and click Refresh from Database on the toolbar.You can also select the table and choose Selected > Refresh from Database from the menu, or click Refresh. Workbench reloads the database table.

When refreshing tables from the database, if there are multiple database tables with similar names, the Duplicate Tables dialog box appears. Duplicate Table Dialog Box

Select the specific database table to update, and then click OK.

How to Use Database Tables in the Editor Window

When you select a database table in the Navigator, its properties appear in the Editor. Each database table contains the following property tabs:

Columns – Add or modify the table fields, and specify each field properties.

References – Specify references between tables.

This section describes how to use these tabs to configure the following:

Setting a Primary Key for Database Tables

Select a database table in the Navigator. Its property sheet appears in the Editor.

Click the Columns tab.Click the Columns tab.Setting Primary Key for a Database Table

Select the Primary Key field(s) for the table.

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. Workbench uses these references when you define relationship mappings and multiple table associations.

When importing tables from the database, Workbench can automatically create references (if the driver supports this), or you can define references from the workbench. See Importing Tables from a Database.

To create a new table reference, use this procedure:

Select a database table in the Navigator. The table's properties display in the Editor.

Generating SQL Creation Scripts

Using the Workbench, you can generate SQL scripts that you can use to create tables in a relational database.

To automatically generate SQL scripts to create the tables in a project, use this procedure:

Select the database table(s) in the Navigator.

Right-click the table(s) and choose Generate Creation Script for > Selected Tables or All Tables from the context menu. The SQL Creation Script dialog box appears.You can also choose Selected > Generate Creation Script for > Selected Tables or All Tables from the menu. SQL Creation Script Dialog Box

Copy the script and paste it into a file. You may need to edit the file to include additional SQL information that 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.

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

Generating Classes and Descriptors from Database Tables

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, 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. 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 Introduction to Relational Mappings for more information on mappings.
You can also specify whether the relationships are bidirectional. See Configuring Bidirectional Relationship for more information.

Click OK to automatically create the relationships.

The newly created descriptors appear in the Navigator of Workbench.

Generating Tables on the Database

To create a table in the database, based on the information in Workbench, use this procedure:

Right-click the table(s) and choose Create on Database > Selected Tables or All Tables from the context menu.You can also create tables by selecting Selected > Create on Database > Selected Tables or All Tables from the menu.

How to Use XML Schemas in the Navigator

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

How to Use an XML Schema Structure

When you select a specific XML schema in the Navigator, you can display the structure and details of the schema using the Schema Structure tab.

To display the structure and details of a schema, use this procedure:

Select a schema element in the Navigator. Its properties appear in the Editor.

Click the Schema Structure tab. The Schema Structure tab appears.

Select an element in the schema. The element's details appear. Schema Structure Tab

Review the fields on the Schema Structure tab.

Use the following information to verify data in each field in the Schema Document Info tab:

Field

Description

Schema Structure

Displays the elements of the schema, listed in alphabetical order, in an expandable or collapsible tree structure.

Details

Displays detailed information (such as name and type) for the currently selected element in the Schema Structure area.

These fields are for display only and cannot be changed in Workbench.

How to Import an XML Schema

The first step in configuring an EIS project (using XML records) or XML project is importing the XML schema(s) that your project uses.

When you import a schema, you define a schema reference that gives EclipseLink the information it needs to locate the schema itself. Anytime after you import an XML schema, you can update the schema reference (see How to Configure an XML Schema Reference) if necessary.

Specify that 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 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 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 Configuring Project Classpath, specify a resource name of project.config.mySchema.xsd.

How to Configure an XML Schema Reference Using Java

Use Java to configure schema reference. Create a descriptor amendment method (see 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 EclipseLink 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.

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 Workbench (see 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, EclipseLink 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 EclipseLink runtime marshalls (writes) an object to an XML document, it uses the namespace prefixes you specify here.

When the EclipseLink runtime unmarshalls (reads) an XML document, the document may use any prefix value as long as it corresponds to the appropriate namespace. For more information, see EclipseLink Runtime Namespace Resolution.

Declare

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 EclipseLink Runtime Namespace Resolution.

How to Create Classes Using Workbench

To create new classes and packages from within Workbench, use this procedure:

Select the project in the Navigator and click Create New Class.You can also right-click the project in the Navigator and choose Create New Class from the context menu or choose Selected > Create New Class from the menu. Add Class Dialog Box

Enter data in each field on the Add Class dialog box and click OK. Workbench will add the new class to the project in the Navigator.

Use the following information to enter data in each field on the Add Class dialog box:

Field

Description

Package Name

Choose an existing package or enter a new package name. If blank, Workbench uses the default package name.

New Class Name

Enter a class name. The New Class Name must be unique within the package.

Specify whether the attribute is Final, Static, Transient, or Volatile.

Note: Selecting some modifiers may disable others.

Configuring Attribute Type Declaration

This section includes information on using the workbench to configure attribute type declaration.

Using Workbench

To specify attribute type declaration, use this procedure:

Select a class in the Navigator. Its properties appear in the Editor.

Click the Class Info tab in the Editor.

Click the Attributes tab. The Attributes tab contains two sub-tabs.

Click the General tab. Attributes Tab, Type Declaration Fields

Complete the Type Declaration fields on the Attributes tab.

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.

Configuring Attribute Accessing Methods

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

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, 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 Workbench.

Note: If the class exists on both the system classpath and the project classpath, 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 Workbench.

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

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

How to Manage Nondescriptor Classes

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

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

To refresh the classes (for example, if you edited the classes in an IDE), click Refresh.

How to Rename Packages

When you add classes to a project, Workbench shows the classes contained in the package to which they belong (see How to Use the Navigator).

You can use 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 Workbench project.

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

Integrating Workbench with Apache Ant

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

How to Create the mappings.export Task

The mappings.export task is a generation task that you use to generate an EclipseLink deployment XML file for a given Workbench project (.mwp). The mappings.export task executes a Hmappings.validate task before executing. A BuildException is thrown if validation fails.

This task provides the ability to override the Workbench project database login information.

Using Parameters

mappings.export Task Parameters

Attribute

Description

Required

projectfile

Fully qualified Workbench projects file name (.mwp).

Yes

deploymentfile

Fully qualified EclipseLink project deployment file name (.xml).

No – default to the name specified in the Workbench project (.mwp).

ejbjarxmldir

The directory that contains the ejb-jar.xml file (only applicable to Java EE project).

No – default to the directory specified in the Workbench project (.mwp).

classpath

Project classpath.

No

classpathref

Reference to a path defined elsewhere.

No

failonerror

Indicates whether the build will continue even if there are export errors; defaults to true.

No

property

The name of the property to set (true if export completed successfully).

No

Specifying Parameters Specified as Nested Elements

You can specify the following parameters as nested elements of this task:

Specifying Parameters Specified as Nested Elements

Examples

The following example shows a typical ignoreerrorset element. This element instructs a mappings.export task to ignore all of 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.