This chapter provides information about understanding, using, and customizing TopLink Workbench.
This chapter includes the following sections:
For information on using TopLink Workbench to configure sessions XML, refer to Part XXI, "TopLink Sessions".
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.
You can use TopLink Workbench during the development phase of the development process (see Section 2.1, "Introduction to TopLink Application Development"). Typically, this phase includes the following:
Defining an object model (a set of Java classes) to describe and solve your problem.
Creating a TopLink 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 a TopLink session and registering your descriptors. In your application, use the session to retrieve and store objects from and to the data source.
TopLink Workbench creates a <projectName>
.mwp
file to store all TopLink project information, including object model, descriptor, and session information.
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.
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 theDRIVER_CLASSPATH
variable. Instead, add these persistent business objects in your TopLink Workbench project classpath (see Section 117.3, "Configuring Project Classpath").JDBC drivers–if you are using relational projects (see Section 18.1, "Building Relational Projects").
Java EE Connector Architecture (JCA) adapters–if you are using EIS projects (see Section 71.1, "EIS Project Concepts").
JCA connector.jar
file–if you are using EIS projects (see Section 71.1, "EIS Project Concepts").
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.n connector.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.
Oracle Database ORACLE_HOME/rdbms/jlib/xdb.jar
file–if you are using direct-to-XMLType
mappings with an Oracle9i Database or later (see Section 27.4, "Direct-to-XMLType Mapping").
Custom Collection
class that you use to override the default Collection
class that TopLink uses with a mapping container policy (see Section 121.14, "Configuring Container Policy").
Example 5-1 shows how to set the DRIVER_CLASSPATH
variable for Windows system, and Example 5-2–for UNIX.
Example 5-1 Setting DRIVER_CLASSPATH on Windows
set DRIVER_CLASSPATH=C:\OraHome2\jdbc\lib\ojdbc14.jar;C:\Attunity\Connect\Java\lib\attunityResourceAdapter.jar;C:\OraHome2\rdbms\jlib\xdb.jar
Note:
If the path to your driver(s) contains spaces, you must enclose the path in double-quotes in thesetenv.cmd
file. For example:
set DRIVER_CLASSPATH="C:\Program Files\some directory\driver.jar"
Save and close the setenv
script.
To launch TopLink Workbench, double-click the workbench.cmd
file located in <
TOPLINK_HOME
>/utils/workbench
directory.
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:
JVM_ARGS="
-Duser.language=en -Duser.country=en_US
"
Figure 5-1 shows the primary parts of TopLink Workbench window.
The numbered callouts in Figure 5-1 identify the following user interface components:
The menu bar contains menus for each TopLink Workbench function. Some objects also contain context-sensitive menus. See Section 5.3.1, "How to Use Menus" for more information.
The toolbars contain shortcuts to specific functions. See Section 5.3.2, "How to Use Toolbars" for more information.
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.
The Editor window section contains specific property sheets and option tabs for the currently selected object. See Section 5.3.4, "How to Use the Editor" for more information.
The Problems window section shows messages and errors for the currently selected object in the Navigator window section (see Section 5.3.5, "How to Use the Problems Window"). Section A.3, "TopLink Workbench Error Reference" contains detailed information on each error message.
TopLink Workbench contains the following two types of menus:
Menu bar menus (see Section 5.3.1.1, "Using Menu Bar Menus")
Context menus (see Section 5.3.1.2, "Using Context 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.
TopLink Workbench contains the following toolbars at the top of the window:
Standard toolbar (see Section 5.3.2.1, "Using Standard Toolbar")
Context toolbar (see Section 5.3.2.2, "Using Context Toolbar")
Toolbars provide tool tips: each toolbar button provides a brief description when you position the mouse pointer over it.
The standard toolbar furnishes quick access to the standard menu options (File, Edit, Selected, and so on).
Table 5-1 Standard Toolbar Buttons
Button | Description | Available for... |
---|---|---|
![]() |
New |
All |
![]() |
Open |
All |
![]() |
Save |
All |
![]() |
Save as |
All |
![]() |
Save all |
All |
![]() |
Close |
All |
![]() |
Close all |
All |
![]() |
Help topics |
All |
![]() |
Export deployment XML for the selected projects |
Projects |
![]() |
Refreshes selected classes |
Projects |
![]() |
Add or refresh classes |
Projects |
![]() |
Create new class |
Projects |
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.
Table 5-2 Context Toolbar Buttons
Button | Description | Available for... |
---|---|---|
![]() |
Login to database |
Databases |
![]() |
Logout of database |
Databases |
![]() |
Add new table |
Databases |
![]() |
Add or update existing tables from database |
Databases |
![]() |
Refresh from database |
Database tables |
![]() |
Remove table or selected item |
Database tables |
![]() |
Rename table or selected item |
Database tables |
![]() |
Import schema |
Schemas |
![]() |
Relational aggregate descriptor |
Descriptors |
![]() |
Relational class descriptor |
Descriptors |
![]() |
Relational EJB descriptor |
Descriptors |
![]() |
EIS composite descriptor |
Descriptors |
![]() |
EIS root descriptor |
Descriptors |
![]() |
EIS EJB descriptor |
Descriptors |
![]() |
XML descriptor |
Descriptors |
![]() |
Direct-to-field mapping |
Attributes in relational descriptors |
![]() |
Object type mappingFoot 1 |
Attributes in relational descriptors |
![]() |
Type conversion mappingFootref 1 |
Attributes in relational descriptors |
![]() |
Serialized object mappingFootref 1 |
Attributes in relational descriptors |
![]() |
Direct-to-XMLType mapping |
Attributes in relational descriptors |
![]() |
Direct collection mapping |
Attributes in relational descriptors |
![]() |
Direct map mapping |
Attributes in relational descriptors |
![]() |
Aggregate mapping |
Attributes in relational descriptors |
![]() |
One-to-one mapping |
Attributes in relational descriptors |
![]() |
Variable one-to-one mapping |
Attributes in relational descriptors |
![]() |
One-to-many mapping |
Attributes in relational descriptors |
![]() |
Many-to-many mapping |
Attributes in relational descriptors |
![]() |
Direct mapping |
Attributes in EIS descriptors |
![]() |
Direct collection mapping |
Attributes in EIS descriptors |
![]() |
Composite object mapping |
Attributes in EIS descriptors |
![]() |
Composite collection mapping |
Attributes in EIS descriptors |
![]() |
One-to-one mapping |
Attributes in EIS descriptors |
![]() |
One-to-many mapping |
Attributes in EIS descriptors |
![]() |
Direct-to-XML mapping |
Attributes in XML descriptors |
![]() |
Direct collection mapping |
Attributes in XML descriptors |
![]() |
Composite object mapping |
Attributes in XML descriptors |
![]() |
Composite collection mapping |
Attributes in XML descriptors |
![]() |
Any object mapping |
Attributes in XML descriptors |
![]() |
Any collection mapping |
Attributes in XML descriptors |
![]() |
Transformation mapping |
Attributes in all descriptors |
![]() |
Unmap |
Attributes in all descriptors |
![]() |
Session |
Sessions configurations |
![]() |
Session Broker |
Sessions configurations |
![]() |
Named connection pool |
Server sessions |
![]() |
Sequence connection pool |
Server sessions |
![]() |
Write connection pool |
Server sessions |
![]() |
Rename |
Database sessions, session brokers |
![]() |
Delete session |
Database sessions, session brokers |
Footnote 1 Deprecated. For more information, see Section 27.2.2.2, "Using a Converter Mapping"
TopLink displays the items included in each project (descriptors, mappings, data source, and so on) in the Navigator on the left side of the TopLink Workbench window, as Figure 5-4 shows.
The numbered callouts on Figure 5-4 identify the following user interface components:
Click the plus ( + ) or minus ( – ) sign next to the item, or double-click the item name to expand or collapse the item.
TopLink Workbench identifies items that have been changed but not yet saved by adding an asterisk ( * ) in front of the item name.
When you select an item in the Navigator, its properties appear in the Editor (see Section 5.3.4, "How to Use the Editor").
To perform specific functions for an item, select the item in the Navigator and do one of the following:
Right-click on the object and select the function from the context menu (see Section 5.3.1.2, "Using Context Menus").
Choose a function from the Selected menu (see Section 5.3.1.1, "Using Menu Bar Menus").
For information on using the Navigator with a database in relational projects, see Section 5.5.1, "How to Use Database Tables in the Navigator Window".
For information on using the Navigator with an XML schema in EIS projects (using XML records) and XML projects, see Section 5.6.1, "How to Use XML Schemas in the Navigator".
Active and Inactive Descriptors
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 Sample Active and Inactive Descriptors
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").
Section A.3, "TopLink Workbench Error Reference" contains more information on each TopLink Workbench error message.
The Editor, on the right side of the TopLink Workbench window, displays the property sheet associated with the currently selected item in the Navigator, as Figure 5-6 shows.
Figure 5-6 numbered callouts identify the following user interface components:
Selected element (from the Navigator)
Editor property tabs
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.
If you select the error, then TopLink Workbench displays the complete error message in the Problems window. Section A.3, "TopLink Workbench Error Reference" contains detailed information on each error message.
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.
You can also create a status report (see Section 116.2.3, "How to Generate the Project Status Report") that includes all errors in a selected project.
TopLink Workbench contains an extensive online Help system to assist you in developing TopLink applications.
To receive help on any field, tab, or element in TopLink Workbench, right-click the element and select Help from the context menu or press F1.
To review the complete TopLink documentation and Quick Start, click Help.
To customize TopLink Workbench, select Tools > Preferences from the menu. The Preferences dialog box appears.
TopLink Workbench provides the following preferences:
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.
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:
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Select General in the Category window.
Figure 5-9 Preferences–General Dialog Box
Use the following information to enter data in each field of the dialog box:
Field | Description |
---|---|
Display Splash Screen | Specify if TopLink Workbench should show the graphical splash screen when starting. |
Look and Feel | Select the look and feel to use for TopLink Workbench. |
Size of recently opened files list | Select the number of projects to maintain in the File menu. See Section 116.2.1, "How to Open Existing Projects" for more information. |
HTTP Proxy Host | Specify if your PC requires a proxy server to access the internet. |
HTTP Proxy Port | Specify the port used by your proxy host. |
Network Connect Timeout | Specify the timeout (in seconds) to establish a network or internet connection. |
Network Read Timeout | Specify the timeout (in seconds) when accessing data from a network or internet connection. |
Reopen Projects on Startup | Select to reopen the projects that were open the last time you exited the TopLink Workbench. |
You must restart TopLink Workbench to apply the changes.
Use the Help preferences to select the Help system preferences.
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Expand General in the Category window and select Help. The Preferences–Help dialog box appears.
Figure 5-10 Preferences–General–Help Dialog Box
Use the following information to enter data in each field:
Field | Description |
---|---|
Display Welcome at Startup | Specify if TopLink should show the Welcome screen each time you start TopLink Workbench. |
External HTML Browser | Click Browse and select the location of your default Web browser. You must specify a Web browser to access the Quick Tour, Javadoc (API), and other Web-based material. |
Help Jar | Specify the location of the JAR file that contains help topics.
Click Browse and select the help JAR file location. The default filename is To use the help content in a language other than the default language for your local, specify a different help JAR file. Note: You must restart TopLink Workbench to apply changes to this option. |
Use the Mappings preferences to specify general mapping preferences. Follow these steps to set the Mapping preferences:
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Select Mappings in the Category window. The Mappings dialog box appears.
Figure 5-11 Preferences–Mappings Dialog Box
Use the following information to enter data in each field:
Field | Description |
---|---|
Allow changing query type | Configure whether or not TopLink Workbench always allows, never allows, or prompts before allowing you to change the query type associated with a descriptor. |
Allow changing query format | Configure whether or not TopLink Workbench always allows, never allows, or prompts before allowing you to change the configuration of a query associated with a descriptor. |
Use the Class preferences to specify how TopLink Workbench maintains classes when renaming or editing a zero-argument constructor. Follow these steps to set the Class preferences:
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Expand Mappings in the Category window and select Class.
Figure 5-12 Preferences – Mappings – Class Dialog Box
On the Preferences–Mappings–Class dialog box, specify how TopLink Workbench maintains classes when renaming or editing a zero-argument constructor.
Use the EJB preferences to specify how TopLink Workbench updates the ejb-jar.xml
file when saving EJB projects. Follow these steps to set the EJB preferences:
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Expand Mappings in the Category window and select EJB.
Figure 5-13 Preferences–Mappings–EJB Preferences Dialog Box
Use the following information to select how TopLink Workbench will update the ejb-jar.xml
file:
Field | Description |
---|---|
Write ejb-jar.xml on project save | Configure whether or not TopLink Workbench always updates, never updates, or prompts before updating the ejb-jar.xml file each time you save the project. |
Allow removing EJB info | Configure whether or not TopLink Workbench always allows, never allows, or prompts before allowing you to remove the EJB information associated with a descriptor. See Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information" for more information. |
Allow removing EJB 2.x info | Configure whether or not TopLink Workbench always allows, never allows, or prompts before allowing you to remove the EJB 2.0 or 2.1 information associated with a descriptor. See Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information" for more information. |
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:
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Expand Mappings in the Category window and select Database.
Figure 5-14 Preferences–Mappings–Database Preferences Dialog Box
Use the following information to enter data in each field:
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:
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Select Sessions Configuration in the Category window.
Figure 5-15 Preferences–Sessions Configuration Dialog Box
To add a JAR or ZIP file, click Add Entry or Browse and add the JAR or ZIP files that contain the default compiled Java classes for this sessions configuration.
To remove a JAR or ZIP file, select the file and click Remove.
To change the order in which TopLink searches these JAR or ZIP files, select a file and click Up to move it up, or click Down to move it down in the list.
Use the New Names preferences to specify the default values and names of newly created sessions, session brokers, and connection pools. Follow these steps to set the New Names preferences:
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Expand Sessions Configuration in the Category window and select New Names.
Figure 5-16 Preferences–Sessions Configuration–New Names Dialog Box
Use the following information to enter data in each field:
Field | Description |
---|---|
Sessions Configuration | Specify the default name for newly created sessions configuration files (default, sessions.xml ). See Section 88.2, "Creating a Sessions Configuration" for more information. |
Session | Specify the default name for newly created sessions (default, Session ). See Section 88.1, "Introduction to the Session Creation" for more information. |
Broker | Specify the default name for newly created session brokers (default, SessionBroker ). See Section 88.5, "Creating Session Broker and Client Sessions" for more information. |
Connection Pool | Specify the default name for newly created connection pools (default, ConnectionPool ). See Chapter 100, "Creating an Internal Connection Pool" for more information. |
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:
Select Tools > Preferences from the menu. The Preferences dialog box appears.
Expand Sessions Configuration in the Category window and select Platform.
Figure 5-17 Preferences–Sessions Configuration–Platform Preferences Dialog Box
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 Section 88.2, "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 Section 89.9, "Configuring the Server Platform" for more information. |
Configure whether or not TopLink Workbench allows platforms to be visible in production.
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.
Figure 5-18 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.
References–Specify references between tables.
This section includes information on the following topics:
This section describes the following options:
See Section 5.5.2, "How to Use Database Tables in the Editor Window" for more information.
To log in or out of a relational database, do the following:
Create a database login (see Section 98.1, "Introduction to Database Login Configuration").
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.
To create a new database table within TopLink 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.
Use the following information to enter data in each field:
Field | Description |
---|---|
Catalog |
|
Schema |
|
Table Name | Specify the name of this database table. |
TopLink 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 Section 5.5.3.4, "Generating Tables on the Database" for more information on creating the table in the database.
Continue with Section 5.5.2, "How to Use Database Tables in the Editor Window" to use these tables in your project.
TopLink Workbench can automatically read the schema for a relational database and import the table data into the project as long as your JDBC driver supports the following JDBC methods:
The JDBC driver must be on the TopLink Workbench classpath (see Section 5.2, "Configuring the TopLink Workbench Environment").
To import tables from the database, use the following procedure:
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.
Figure 5-20 Import Tables from Database Dialog Box
Figure 5-20 numbered callouts identify the following user interface components:
Filters
Database tables that match the filters
Use the following information to enter data in each field of the dialog box:
Examine each table's properties to verify that the imported tables contain the correct information. See Section 5.5.2, "How to Use Database Tables in the Editor Window" for more information.
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. TopLink 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. TopLink Workbench removes the table from the project.
Note:
Although you have removed the table from the TopLink Workbench project, the table remains in the database.To rename a database table in the TopLink 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. TopLink Workbench renames the table.
Note:
Although you have renamed the table in the TopLink Workbench project, the original table name remains in the database.To refresh (that is, reload) the database tables in the TopLink Workbench project, use this procedure:
Select a database table in the Navigator, and click Refresh from Database on the toolbar.
You can also right-click on the table and choose Refresh from Database from the context menu or choose Selected > Refresh from Database from the menu. TopLink 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.
Select the specific database table to update, and then click OK.
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:
Use the database table's Column tab to specify properties for the database table's fields.
To specify a table's column properties, use this procedure:
Select a database table in the Navigator. The table's property sheet displays in the Editor.
Click the Columns tab.
Enter data in each field on the Columns tab. Use the scroll bar to display the additional field.
Use the following information to fill each column on the Columns tab:
Field | Description |
---|---|
Name | Specify the name of the field. |
Type | Use the drop-down list to select the field's type.
Note: The valid values will vary, depending on the database. |
Size | Specify the size of the field. |
Sub-Size | Specify the sub-size of the field. |
Allows Null | Specify if this field can be null. |
Unique | Specify whether the value must be unique within the table. |
Primary Key | Specify whether or not this field is a primary key for the table (see Section 5.5.2.2, "Setting a Primary Key for Database Tables"). |
Identity | Use to indicate a Sybase, SQL Server or Informix identity field. |
Note:
Some properties may be unavailable, depending on your database type.To add a new field, click Add.
To remove a field, select the field and click Remove.
To rename a field, select the field and click Rename.
To set a primary key(s) for a database table, use this procedure:
Note:
TopLink Workbench can automatically import primary key information if supported by the JDBC driver.Select a database table in the Navigator. Its property sheet appears in the Editor.
Click the Columns tab.
Figure 5-23 Setting Primary Key for a Database Table
Select the Primary Key field(s) for the table.
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.
When importing tables from the database, TopLink Workbench can automatically create references (if the driver supports this), or you can define references from the workbench. See Section 5.5.1.3, "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.
Click the References tab.
Figure 5-26 numbered callouts identify the following user interface components:
Table References area
Key Pairs area
In the References area, click Add. The New Reference dialog box appears.
Use the following information to enter data in each field of the dialog box:
Continue with Section 5.5.2.4, "Creating Field Associations".
For each table reference, you can specify one or more field associations that define how fields in the source table relate to fields in the target table. See Section 5.5.2.3, "Creating Table References".
To create new field references, use this procedure:
Select a database table in the Navigator. The table's properties display in the Editor.
Click the References tab.
Figure 5-26 numbered callouts identify the following user interface components:
Table references area
Key pairs area
Select a table reference from the references area.
To create a new key pair, click Add in the key pairs area and complete each field in the key pairs area using the following information:
To create a new key pair, click Add in the key pairs area and complete each field in the key pairs area using the following information.
Field | Description |
---|---|
Table References Area | |
Name | Specify the name of this table reference |
Target Table | Specify the database table that is the target of this reference. |
On Database | Specify if the reference exists on the database. |
Key Pairs Area | |
Source Column | Select the database field from the source table. |
Target Column | Select the database field from the target table. |
TopLink Workbench can automatically generate a variety of information from the database tables. This section describes the following:
Using the TopLink 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.
Figure 5-27 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 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.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.
Click Yes. The Generate Classes and Descriptors dialog box appears.
Figure 5-28 Generate Classes and Descriptors Dialog Box
Use the following information to enter data in each field:
If the table contains foreign key fields that may represent relationship mappings, then the Choose Relationships to Generate dialog box appears.
Figure 5-29 Choose Relationships to Generate Dialog Box
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.
You can also specify whether the relationships are bidirectional. See Section 121.18, "Configuring Bidirectional Relationship" for more information.
Click OK to automatically create the relationships.
The newly created descriptors appear in the Navigator of TopLink Workbench.
Using TopLink Workbench, you can automatically generate EJB entity beans and descriptors for each database table, including the following:
One EJB descriptor that implements the <javax.ejb.EntityBean>
and entity bean classes
Bean relation attributes (CMP or BMP)
Java source for each class
EJB-compliant method stubs
Note:
This option is available only for projects with container-managed or bean-managed persistence. See Section 117.5, "Configuring Persistence Type" for more information.To automatically generate EJB entity beans and descriptors for each database table, use this procedure:
Select the database table(s) in the Navigator.
Right-click the table(s) and choose Generate EJB Entities and Descriptors from > Selected Table or All Tables from the context menu. TopLink Workbench prompts you to save your project.
You can also choose Selected > Generate EJB Entities and Descriptors from > Selected Table or All Tables from the menu.
Click Yes to save your project before generating EJB entities. The Generate EJB Entity Classes and Descriptors dialog box appears.
Figure 5-30 Generate EJB Entity Classes and Descriptors Dialog Box
Use the following information to enter data in each field on the Generate EJB Entity Classes and Descriptors dialog box:
Field | Description |
---|---|
Package Name | Name of the package to contain the generated entity beans and descriptors. |
Generate Local InterfacesFoot 1 | Specify if TopLink creates local interfaces for the EJB entity beans. |
Generate Remote InterfacesFootref 1 | Specify if TopLink creates remote interfaces for the EJB entity beans. |
Footnote 1 For CMP and BMP projects only. See Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information" for more information.
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.
You can also specify if the relationships are bidirectional (see Section 121.18, "Configuring Bidirectional Relationship").
Repeat for all appropriate sets of tables.
Click OK to generate the relationship mappings.
The system creates the remote primary key, home, and bean classes for each bean and adds this information to the project.
To create a table in the database, based on the information in TopLink Workbench, use this procedure:
Note:
You must log in the database before creating tables. See Section 20.6, "Logging In to the Database" for more information.Select the database table(s) in the Navigator.
Right-click the table(s) and choose Create on Database > Selected Table or All Tables from the context menu.
You can also create tables by selecting Selected > Create on Database > Selected Table or All Tables from the menu.
TopLink Workbench creates the tables on the database.
Alternatively, you can generate tables at run time by exporting the information in TopLink Workbench to a TableCreator
class (see Section 6.1, "Introduction to the Schema Manager").
For XML and EIS projects, TopLink Workbench maps each TopLink descriptor to your XML schema.
This section includes information on the following topics:
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.
Figure 5-31 numbered callouts identify the following schema icons:
Project
Schemas object
Specific schema
For more information, see the following:
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.
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 TopLink Workbench.
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 TopLink the information it needs to locate the schema itself. Anytime after you import an XML schema, you can update the schema reference (see Section 5.6.4, "How to Configure an XML Schema Reference") if necessary.
After importing an XML schema, you can configure XML schema namespaces (see Section 5.6.5, "How to Configure XML Schema Namespace").
To import an XML schema into an EIS project (using XML records) or an EIS project, use this procedure:
Right-click the schemas element in the Navigator and select Import Schema from the context menu. The Import Schema dialog box appears.
Use the following information to enter data in each field in the Import Schema dialog box:
Field | Description |
---|---|
Name | Specify the name of this schema. This is the display name that TopLink Workbench uses. It can be different than the name you specify when you configure Source. |
Source | Select how TopLink Workbench should import the schema. |
File | Specify that TopLink Workbench should import the schema from a file.
Enter the fully qualified directory path and filename of the schema file. |
URL | Specify that TopLink Workbench should import the schema using a URL.
Enter the complete URL of the schema file. Note: When importing schemas by URL, ensure you have set your proxy information correctly. See Section 5.4.1, "How to Use General Preferences" for more information. |
Classpath | 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.
After you import an XML schema (see Section 5.6.3, "How to Import an XML Schema"), you can update its source by configuring the schema reference.
To specify the source of a schema, use this procedure:
Select a schema element in the Navigator. Its properties appear in the Editor.
Click the Schema Document Info tab. The Schema Document Info tab appears.
Figure 5-34 Schema Document Info Tab–Source Field
Click Edit to select a new source for the selected schema. The Schema Properties dialog box appears.
Use the following information to complete each field in the Schema Properties dialog box:
Field | Description |
---|---|
Name | Specify the name of this schema. This is the display name that TopLink Workbench uses. It can be different than the name you specify when you configure Source. |
Source | Select how TopLink Workbench should import the schema. |
File | Specify that TopLink Workbench should import the schema from a file.
Enter the fully qualified directory path and filename of the schema file. |
URL | Specify that TopLink Workbench should import the schema using a URL.
Enter the complete URL of the schema file. Note: When importing schemas by URL, ensure you have set your proxy information correctly. See Section 5.4.1, "How to Use General Preferences" for more information. |
Classpath | 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 . |
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
.
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.
When you import an XML schema (see Section 5.6.3, "How to Import an XML Schema") such as the one that Example 5-3 shows, TopLink Workbench organizes the various namespaces that the XML schema identifies, as Table 5-3 shows.
Example 5-3 XML Schema with Namespace Options
<xsd:schema xmlns:<prefix>="<URI>" <!-- TopLink Workbench Built-in Namespace --> targetNamespace="<URI>" <!-- TopLink Workbench Target Namespace --> elementFormDefault="qualified" attributeFormDefault="unqualified" version="10.1.3"> <xsd:import <!-- TopLink Workbench Imported Namespace --> namespace="http://xmlns.oracle.com/ias/xsds/opm" schemaLocation="object-persistence_1_0.xsd" /> ... </xsd:schema>
Table 5-3 TopLink Workbench XML Schema Categories
TopLink Workbench Category | Defined By | Purpose | When Needed |
---|---|---|---|
Built-in |
|
Provides access to types defined in other XML schemas for use as is. |
If your project uses more than one XML schema or if you want to use |
Target |
|
The namespace you use to qualify the types you define for your application. If set, all XML documents that use these types must use this namespace qualifier. |
You may need to specify a target namespace depending on how element and attribute form options are set (see Section 15.4.2, "Element and Attribute Form Options"). |
Imported |
|
Provides access to types defined in the corresponding built-in XML schema so that you can extend the built-in types. Extended types must be qualified by the target namespace. |
If your project uses more than one XML schema and you want to extend one or more built-in types. |
For more information, see Section 15.4, "XML Namespaces Overview".
To specify the namespaces of a schema, use this procedure:
Select a schema element in the Navigator. Its properties appear in the Editor.
Click the Schema Document Info tab. The Schema Document Info tab appears.
Figure 5-36 Schema Document Info Tab–Namespaces Field
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 |
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 the TopLink 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 Section 15.4.3, "TopLink 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 Section 15.4.3, "TopLink Runtime Namespace Resolution". |
Using Java, to configure XML schema namespaces for an EIS descriptor (with XML records) or an XML descriptor, create a descriptor amendment method (see Section 119.35, "Configuring Amendment Methods") that uses EISDescriptor
or XMLDescriptor
method getNamespaceResolver
to configure the descriptor's NamespaceResolver
accordingly, as Example 5-4 shows.
Using TopLink Workbench, you can create Java classes and packages. This section includes information on the following:
Oracle recommends that you develop your Java classes using an IDE, such as Oracle Oracle JDeveloper, and import these existing classes into TopLink Workbench (see Section 5.7.3, "How to Import and Update Classes")
However, it is sometimes convenient to create and configure classes in TopLink Workbench: for example, when generating an object model from a database schema.
This section includes information on using TopLink Workbench to create Java classes.
For more information on using TopLink Workbench to edit classes, see Section 5.7.1, "How to Create Classes".
To create new classes and packages from within TopLink 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.
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, TopLink Workbench uses the default package name. |
New Class Name | Enter a class name. The New Class Name must be unique within the package. |
For more information on using TopLink Workbench to edit classes, see Section 5.7.2, "How to Configure Classes".
Oracle recommends that you develop your Java classes using an IDE, such as Oracle Oracle JDeveloper, and import these existing classes into TopLink Workbench (see Section 5.7.3, "How to Import and Update Classes")
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:
This section includes information on Using TopLink Workbench to configure class information.
To configure class and superclass information, use this procedure:
Select a class in the Navigator. Its properties appear in the Editor.
Click the Class Info tab in the Editor.
Figure 5-38 Class Tab, Class Information Fields
Use the following information to enter data in each field on the tab:
Field | Description |
---|---|
Name | The name of the class. This field is for display only. |
Superclass | Click Browse and select a class and package that contains the class (that is, the superclass). |
This section includes information on Using TopLink Workbench to configure class modifiers.
To configure class modifiers, use this procedure:
Select a class in the Navigator. Its properties appear in the Editor.
Click the Class Info tab in the Editor.
Figure 5-39 Class Tab, Class Modifiers Fields
Use the following information to enter data in each field on the tab:
Field | Description |
---|---|
Access Modifiers | Use to specify whether the class is accessible publicly or not.
Only public classes are visible to the Oracle TopLink Workbench. |
Other Modifiers | Specify if the class is Final or Abstract, or both. Final classes are not included in the superclass selection lists for other classes to extend. |
This section includes information on Using TopLink Workbench to specify the interfaces implemented by a class. You can choose any interface in the TopLink Workbench classpath (see Section 117.3, "Configuring Project Classpath").
Although you may add interfaces to a project directly (see Section 5.7.3, "How to Import and Update Classes"), you do not need to do so in order to configure a class to implement an interface.
To implement interfaces, use this procedure:
Select a class in the Navigator. Its properties appear in the Editor.
Click the Class Info tab in the Editor.
Figure 5-40 Class Tab, Interfaces Implemented Fields
Use the following information to enter data in the Interfaces Implemented field on the Class tab:
Field | Description |
---|---|
Interfaces Implemented | To add an interface, click Add. The Choose Class dialog box appears. In the dialog box, select the interface and package.
To remove an interface, select the interface and click Remove |
This section includes information on Using TopLink Workbench to add an attribute to a class.
To add a new attribute (field) to the descriptor, click Add.
To delete an existing attribute, select the attribute and click Remove.
To rename an existing attribute, select the attribute and click Rename.
The Attributes tab contains the following tabs:
General
Accessors
This section includes information on Using TopLink Workbench to configure attribute modifiers.
To specify access modifiers, 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.
Figure 5-41 Attributes Tab, Modifiers Fields
Use the following information to enter data in the Modifiers fields on the Attributes tab:
This section includes information on Using TopLink Workbench to configure attribute type declaration.
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.
Figure 5-42 Attributes Tab, Type Declaration Fields
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 |
Map Key Type | Click Browse and select a class and package for the attribute.
This field applies for |
Map Value Type | Click Browse and select a class and package for the attribute.
This field applies for |
Element Type | Click Browse and select a class and package for the attribute.
This field applies for |
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.
To specify attribute accessing methods, 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 Accessors tab.
Figure 5-43 Attributes Tab, Accessors Fields
Use the following information to complete the Accessors fields on the Attributes tab:
Field | Description |
---|---|
Get Method | Choose the get method for the attribute.
This field applies for non- |
Set Method | Choose the set method for the attribute.
This field applies for non- |
Add Method | Choose the add method for the attribute.
This field applies for |
Remove Method | Choose the remove method for the attribute.
This field applies for |
Value Holder Get Method | Choose the method used to return the ValueHolderInterface type.
This field applies for |
Value Holder Set Method | Choose the method used to set the ValueHolderInterface type.
This field applies for |
Value Get Method | Choose the method used to return the actual value.
This field applies for |
Value Set Method | Choose the method used to set the actual value.
This field applies for |
This section includes information on Using TopLink Workbench to add a method to a class.
To add or remove methods, 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 Methods tab.
To add a new method to the descriptor, click Add.
To delete an existing method, select the method and click Remove.
To rename an existing method, select the method and click Rename.
This section includes information on Using TopLink Workbench to configure method modifiers.
To specify access modifiers, 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 Methods tab.
Figure 5-45 Methods Tab, Modifiers Fields
Use the following information to enter data in Modifiers fields on the Methods tab:
This section includes information on Using TopLink Workbench to configure method return type.
To specify method return type, 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 Methods tab.
Figure 5-46 Methods Tab, Return Type Fields
Use the following information to enter data in Return Type fields on the Methods tab:
Field | Description |
---|---|
Type |
Click Browse and select a class and package for the method. |
Dimensionality |
Specify the length of an array. This field applies only if Type is an array. |
This section includes information on Using TopLink Workbench to configure method parameters.
To specify additional method parameters, 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 Methods tab.
Figure 5-47 Methods Tab, Method Parameters Fields
Use the following information to enter data in Parameters fields on the Methods tab:
Field | Description |
---|---|
Type | Click Browse and select a class and package for the method. |
Dimensionality | Specify the length of an array. This field applies only if Type is an array. |
This section includes information on Importing and Updating Classes Using TopLink Workbench to import and update Java classes.
You can import Java classes and interfaces created in any IDE.
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.
For more information, see Section 117.3, "Configuring Project Classpath".
Use this procedure to update or refresh the classes in the TopLink Workbench project.
Define the available classes and packages for the project on the General tab. See Section 117.3, "Configuring Project Classpath" for information on classes and packages.
Click Add or Refresh Class. The Select Classes dialog box appears.
You can also update the classes by choosing Selected > Add or Refresh Classes from the menu.
Select the packages or classes (or both) to import into the project and click OK. TopLink Workbench adds the new classes to your project in the Navigator.
By default, TopLink Workbench creates the following descriptor types for each package and class (depending on your project type):
Relational projects–Relational class descriptors (see Section 22.2.1.1, "Creating Relational Class Descriptors")
EIS projects–EIS composite descriptors (see Section 75.2.1.2, "EIS Composite Descriptors")
XML projects–XML descriptors (see Section 50.1.1.1, "Composite Descriptors in XML Projects")
See Chapter 118, "Creating a Descriptor" for more information.
Note:
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.
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:
From the menu, select Workbench > Manage Non-Descriptor Classes. The Manage Non-Descriptor Classes dialog box appears.
You can access the dialog box by right-clicking the TopLink project icon in the Navigator and selecting Manage Non-Descriptor Classes from the context menu.
Figure 5-49 Manage Non-Descriptor Classes Dialog Box
Select one of the following options:
To add new classes, click Add. The Select Classes dialog box appears.
To add new classes, click Add. The Select Classes dialog box appears (see Figure 5-48, "Select Classes Dialog Box".
Only classes that have been added to the project's class path can be added as nondescriptor classes. See Section 117.3, "Configuring Project Classpath" for more information.
To delete an existing class, select the class and click Remove.
To refresh the classes (for example, if you edited the classes in an IDE), click Refresh.
When you add classes to a project, TopLink Workbench shows the classes contained in the package to which they belong (see Section 5.3.3, "How to Use the Navigator").
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.
For more information on using TopLink Workbench to edit classes, see Section 5.7.2, "How to Configure Classes".
To change the package of an existing class in TopLink Workbench, use this procedure:
Right-click the package in the Navigator and select Rename.
You can also select the package and choose Selected > Rename from the menu.
Enter the package name and click OK. TopLink Workbench changes the name of the package in the Navigator window.
For more information on using TopLink Workbench to edit classes, see Section 5.7.2, "How to Configure Classes".
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.
This section describes the following:
For more information about Ant, see http://ant.apache.org/manual/
.
Before you can use TopLink Workbench tasks in your Ant build files, you must consider their library dependencies (see Section 5.8.1.1, "Creating Library Dependencies").
To declare TopLink Workbench tasks in your Ant build.xml
file, declare them directly (see Section 5.8.1.2, "Declaring TopLink Workbench Tasks").
In addition to the Ant library dependencies (see http://ant.apache.org/manual/install.html#librarydependencies
), Table 5-4 lists the TopLink-specific JAR files that must be in your Ant classpath.
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:
Example 5-5 Declaring TopLink Workbench Ant Task and Data Types in a toplink-ant-lib.xml File
<?xml version="1.0"?> <antlib> <taskdef name="mappings.export" classname="oracle.toplink.workbench.ant.taskdefs.ExportDeploymentXMLTask" /> <taskdef name="mappings.validate" classname="oracle.toplink.workbench.ant.taskdefs.MappingsValidateTask" /> <taskdef name="session.validate" classname="oracle.toplink.workbench.ant.taskdefs.SessionValidateTask" /> <typedef name="ignoreerror" classname="oracle.toplink.workbench.ant.typedefs.IgnoreError" /> <typedef name="ignoreerrorset" classname="oracle.toplink.workbench.ant.typedefs.IgnoreErrorSet" /> <typedef name="loginspec" classname="oracle.toplink.workbench.ant.typedefs.LoginSpec" /> </antlib>
Table 5-5 lists the TopLink Workbench Ant task definitions that TopLink provides.
Table 5-5 TopLink Workbench Ant Task Definitions
Task Name | TopLink Class |
---|---|
|
|
|
|
|
Table 5-6 lists the TopLink Workbench Ant type definitions that TopLink provides.
Example 5-7 shows a typical Ant build.
xml file that declares and uses the TopLink Workbench Ant task and type definitions.
Example 5-7 Example Ant Build File with TopLink Workbench Ant Tasks
<project name="MyBuild" default="validate.session" basedir="." xmlns:toplink="toplinklib"> <!-- ===================================================== --> <!-- Properties --> <!-- ===================================================== --> <target name="init"> <property file="build.properties"/> <property name = "toplink.mwp.dir" value = "${basedir}/mw"/> <property name = "toplink.sessions.dir" value = "${basedir}/config"/> <property name = " myProject.classes" value = "${basedir}/classes "/> <path id = "database.classpath"> <pathelement path = "${toplink.home}/mdoules/oracle.toplink_11.1.1jlib/OracleThinJDBC.jar"/> </path> <path id = "toplink.classpath"> <pathelement path = "${toplink.home}/modules/oracle.toplink_11.1.1/toplink.jar"/> <pathelement path = "${toplink.home}/modules/oracle.toplink_11.1.1lib/java/api/ejb.jar"/> <pathelement path = "${toplink.home}/modules/xmlparserv2.jar"/> <pathelement path = "${toplink.home}/modules/oracle.toplink_11.1.1/jlib/antlr.jar"/> </path> <path id = "mw.classpath"> <pathelement path = "${toplink.home}/modules/oracle.toplink_11.1.1/jlib/tlmwcore.jar"/> <pathelement path = "${toplink.home}/modules/oracle.toplink_11.1.1/jlib/toplinkmw.jar"/> </path> <path id = "mwplatforms.classpath"> <pathelement path = "${toplink.home}/config"/> </path> <typedef file = "toplink-ant-lib.xml" classpathref = "mw.classpath" uri = "toplinklib" /> </target> <!-- ===================================================== --> <!-- Define task parameter --> <!-- ===================================================== --> <target name="parameter.definition" depends="init"> <toplink:ignoreerrorset id = "ignoreErrors"> <toplink:ignoreerror code = "0233" /> </toplink:ignoreerrorset> <toplink:loginspec id = "loginSpec" url = "jdbc:cloudscape:stagedb;create=true" driverclass = "COM.cloudscape.core.JDBCDriver" user = "scott" password="tiger" /> </target> <!-- ==================================================== --> <!-- Validate the MW Project --> <!-- ===================================================== --> <target name="validate.project" depends="parameter.definition"> <toplink:mappings.validate projectfile = "${toplink.mwp.dir}/myProject.mwp" reportfile = "${toplink.mwp.dir}/problem-report.html" reportformat = "html" property = "mw-valid" classpathref = "mwplatforms.classpath" > <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = "toplink.classpath" /> <toplink:ignoreerrorset refid = "ignoreErrors"/> </toplink:mappings.validate> </target> <!-- ===================================================== --> <!-- TopLink deployment descriptor XML generation --> <!-- ===================================================== --> <target name="export.deployment" depends="validate.project" if="mw-valid"> <toplink:mappings.export projectfile = "${toplink.mwp.dir}/myProject.mwp" deploymentfile = "${toplink.sessions.dir}/sessions.xml" property = "export-completed" failonerror = "true" classpathref = "toplink.classpath"> <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = "mwplatforms.classpath" /> <toplink:ignoreerrorset refid = "ignoreErrors"/> <toplink:loginspec refid = "loginSpec" /> </toplink:mappings.export> </target> <!-- ===================================================== --> <!-- TopLink Session Validate --> <!-- ===================================================== --> <target name="validate.session" depends="export.deployment" if="export-completed"> <toplink:session.validate sessionsfile = "${toplink.sessions.dir}/sessions.xml" sessionname = "ThreeTierEmployee" property = "session-valid" classpathref = "toplink.classpath" classpath = "${ myProject.classes}" > <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = " database.classpath" /> <toplink:loginspec refid = "loginSpec" /> </toplink:session.validate> </target> <project>
The mapings.validate
task is a testing task that you use to list of all the problems in a TopLink Workbench project (.mwp
) file.
This task lets you do the following:
log all the problems to a file in text or HTML format;
set an Ant property to indicate that the TopLink Workbench project is valid (has no errors).
Table 5-7 mappings.validate Task Parameters
Attribute | Description | Required |
---|---|---|
projectfile |
Fully qualified TopLink Workbench projects file name (.mwp). |
Yes |
reportfile |
Fully qualified file name to which to write the output. |
No |
reportformat |
The format of the generated output. Must be |
No–default to |
classpath |
Project classpath. |
No |
classpathref |
Reference to a path defined elsewhere. |
No |
property |
The name of the property to set (true if there is no problem). |
No |
You can specify the following parameters as nested elements of this task:
classpath
ignoreerror (see Section 5.8.8, "How to Create the ignoreerror Task")
ignorerrorset (see Section 5.8.9, "How to Create the ignoreerrorset Task")
Example 5-8 shows a typical mappings.validate
task.
Example 5-8 A mappings.validate Task
<toplink:mappings.validate projectfile = "${toplink.mwp.dir}/myProject.mwp" reportfile = "${toplink.mwp.dir}/problem-report.html" reportformat = "html" property = "mw-valid" classpath = "${mwplatforms.classpath}" > <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = "toplink.classpath" /> <toplink:ignoreerrorset refid = "ignoreErrors"/> <toplink:ignoreerror code = "0555" /> </toplink:mappings.validate>
The session.validate
task is a testing task that you use to test your TopLink deployment XML by running TopLink.
This task provides the ability to do the following:
specify the test type using a nested element;
set an Ant property to indicate that the TopLink Workbench project is valid (has no errors).
Table 5-8 session.validate Task Parameters
Attribute | Description | Required |
---|---|---|
sessionsfile |
Fully qualified |
No–default to |
sessionname |
Name of the session to test. |
Yes |
classpath |
Project classpath. |
No |
classpathref |
Reference to a path defined elsewhere. |
No |
property |
The name of the property to set (true if valid). |
No |
You can specify the following parameters as nested elements of this task:
classpath;
loginspec (see Section 5.8.10, "How to Create the loginspec Task").
Example 5-9 shows a typical session.validate
task.
Example 5-9 A session.validate Task
<toplink:session.validate sessionsfile = "${toplink.sessions.dir}/sessions.xml" sessionname = "ThreeTierEmployee" property = "session-valid" classpathref = "toplink.classpath" classpath = "${ myProject.classes}" > <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = " database.classpath" /> <toplink:loginspec refid = "loginSpec" /> </toplink:session.validate>
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.
This task provides the ability to override the TopLink Workbench project database login information.
Table 5-9 mappings.export Task Parameters
Attribute | Description | Required |
---|---|---|
projectfile |
Fully qualified TopLink Workbench projects file name ( |
Yes |
deploymentfile |
Fully qualified TopLink project deployment file name ( |
No–default to the name specified in the TopLink Workbench project ( |
ejbjarxmldir |
The directory that contains the |
No–default to the directory specified in the TopLink Workbench project ( |
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 |
No |
property |
The name of the property to set ( |
No |
You can specify the following parameters as nested elements of this task:
classpath;
loginspec (see Section 5.8.10, "How to Create the loginspec Task");
ignorerror (see Section 5.8.8, "How to Create the ignoreerror Task");
ignorerrorset (see Section 5.8.9, "How to Create the ignoreerrorset Task").
Example 5-10 shows a typical mappings.export
task.
Example 5-10 A mappings.export Task
<toplink:mappings.export projectfile = "${toplink.mwp.dir}/myProject.mwp" deploymentfile = "${toplink.sessions.dir}/sessions.xml" property = "export-completed" failonerror = "true" classpathref = "toplink.classpath"> <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = "mwplatforms.classpath" /> <toplink:ignoreerrorset refid = "ignoreErrors"/> <toplink:ignoreerror code = "0545" /> <toplink:loginspec url = "jdbc:cloudscape:stagedb;create=true" driverclass = "COM.cloudscape.core.JDBCDriver" user = "scott" password="tiger" /> </toplink:mappings.export>
Use the classpath element to define the Java classpath necessary to run a task. For more information, see http://ant.apache.org/manual/using.html#path
.
Table 5-10 classpath Element Parameters
Attribute | Description | Required |
---|---|---|
location |
Specifies a single file or directory relative to the project's base directory (or an absolute filename). |
No |
path |
Specifies one or multiple files or directories separated by a colon or semicolon. |
No |
refid |
Reference to a path defined elsewhere. |
No |
You can specify the following parameters as nested elements of this task:
pathelement
fileset
dirset
filelist
Example 5-11 shows a typical classpath
element.
Example 5-11 A classpath Element
<classpath> <pathelement path="${classpath}"/> <fileset dir="lib"> <include name="**/*.jar"/> </fileset> <pathelement location="classes"/> <dirset dir="${build.dir}"> <include name="apps/**/classes"/> <exclude name="apps/**/*Test*"/> </dirset> <filelist refid="third-party_jars"/> </classpath>
Use the ignoreerror
element to instruct a TopLink Ant task to ignore a specific TopLink Foundation Library or TopLink Workbench (see Section A.3, "TopLink Workbench Error Reference") run-time error code.
To instruct a TopLink Ant task to ignore multiple error codes, consider using an ignoreerrorset
element (see Section 5.8.9, "How to Create the ignoreerrorset Task").
You cannot specify parameters as nested elements of this element.
Example 5-12 shows a typical ignoreerror
element. This element instructs a mappings.export
task to ignore TopLink Workbench error code 0545.
Example 5-12 An ignoreerror Element
<toplink:mappings.export projectfile = "${toplink.mwp.dir}/myProject.mwp" deploymentfile = "${toplink.sessions.dir}/sessions.xml" classpathref = "toplink.classpath"> <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = "mwplatforms.classpath" /> <toplink:ignoreerror code = "0545" /> </toplink:mappings.export>
Use the ignoreerrorset
element to instruct a TopLink Ant task to ignore any of multiple TopLink Foundation Library or TopLink Workbench (see Section A.3, "TopLink Workbench Error Reference") run-time error codes.
You can specify the following parameter as nested elements of this element:
ignorerror (see Section 5.8.8, "How to Create the ignoreerror Task")
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.
Example 5-13 An ignoreerrorset Element
<toplink:ignoreerrorset id = "ignoreErrors"> <toplink:ignoreerror code = "0402" /> <toplink:ignoreerror code = "0570" /> </toplink:ignoreerrorset> ... <toplink:mappings.export projectfile = "${toplink.mwp.dir}/myProject.mwp" deploymentfile = "${toplink.sessions.dir}/sessions.xml" classpathref = "toplink.classpath"> <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = "mwplatforms.classpath" /> <toplink:ignoreerrorset refid = "ignoreErrors"/> <toplink:ignoreerror code = "0545" /> </toplink:mappings.export>
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".
Note:
You can only use this element with a relational project (see Chapter 18, "Introduction to Relational Projects").You cannot use this element with a Java EE project.
Table 5-13 loginspec Element Parameters
Attribute | Description | Required |
---|---|---|
id |
Unique identifier for this type instance, can be used to reference this type in scripts. |
No |
refid |
Reference to a loginspec defined elsewhere. |
No |
driverclass |
Fully qualified class of the data source driver (see Section 98.3, "Configuring Database Login Connection Options"). |
No–default to the class that the TopLink Workbench project specifies. |
url |
URL of the driver see Section 98.3, "Configuring Database Login Connection Options"). |
Yes |
user |
Login user name (see Section 97.2, "Configuring User Name and Password"). |
No–default to the value that the TopLink Workbench project specifies |
password |
Login password (see Section 97.2, "Configuring User Name and Password"). |
No–default to the value that the TopLink Workbench project specifies |
You cannot specify parameters as nested elements of this element.
Example 5-14 shows a typical loginspec
element.
Example 5-14 A loginspec Element
<toplink:mappings.export projectfile = "${toplink.mwp.dir}/myProject.mwp" deploymentfile = "${toplink.sessions.dir}/sessions.xml" classpathref = "toplink.classpath"> <toplink:classpath refid = "mw.classpath" /> <toplink:classpath refid = "mwplatforms.classpath" /> <toplink:loginspec url = "jdbc:cloudscape:stagedb;create=true" driverclass = "COM.cloudscape.core.JDBCDriver" user = "scott" password="tiger" /> </toplink:mappings.export>