View source for Using Workbench (ELUG)

[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''

----

<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__
[[Special:Whatlinkshere/Using Workbench (ELUG)|Related Topics]]</div>
This section provides information about understanding, using, and customizing the EclipseLink Workbench.

For information on using Workbench to configure sessions XML, refer to [[EclipseLink/UserGuide/Using EclipseLink Sessions (ELUG)|EclipseLink Sessions]].


==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''.

The Workbench is primarily for developing when using the native EclipseLink API, MOXy, or EIS. When using JPA, other development tools such as Eclipse Dali, or Oracle JDeveloper can be used.

You can use Workbench during the ''development'' phase of the [[Introduction to EclipseLink Application Development (ELUG)|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.

Workbench creates a ''<tt><projectName></tt>''<tt>.mwp</tt> file to store all EclipseLink project information, including object model, descriptor, and session information.

The ''<tt><projectName></tt>''<tt>.mwp</tt> file is used only by Workbench. Typically, the only time you need to modify the ''<tt><projectName></tt>''<tt>.mwp</tt> file is to merge changes during application development by a team of developers ([[Using%20an%20Integrated%20Development%20Environment%20(ELUG)#How to Merge Files|How to Merge Files]]).

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

For more information on using Workbench as the development environment, see [[Introduction%20to%20EclipseLink%20Development%20Tools%20(ELUG)|Introduction to EclipseLink Development Tools]].

==Configuring the Workbench Environment==
Workbench reads its environment variables from the <tt>setenv</tt> script in the ''<tt><ECLIPSELINK_HOME></tt>''<tt>/bin</tt> directory.

Before you launch Workbench, you must configure its environment as follows:
# Use a text editor to open the ''<tt><ECLIPSELINK_HOME></tt>''<tt>/bin/setenv</tt> script.
#* For Windows, open the <tt>setenv.cmd</tt> file.
#* For UNIX, open the <tt>setenv.sh</tt> file.
# Ensure that the <tt>JAVA_HOME</tt> environment variable is set:
#* For Windows: <tt>set JAVA_HOME=C:/j2sdk1.5.0_04</tt>
#* For UNIX: <tt>JAVA_HOME=/usr/local/packages/java; export JAVA_HOME</tt><br>'''Note''': If you have already set JAVA_HOME as a system environment variable, you can skip this step.
# Update the <tt>DRIVER_CLASSPATH</tt> environment variable to add the location of the following (if necessary):<br>'''Note''': Do not include any Java classes for your persistent business objects in the <tt>DRIVER_CLASSPATH</tt> variable. Instead, add these persistent business objects in your [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|Workbench project classpath]].
#* JDBC drivers  –  if you are using [[Introduction%20to%20Relational%20Projects%20(ELUG)#Building Relational Projects|building Relational Projects]].
#* Java EE Connector Architecture (JCA) adapters  –  if you are [[Introduction%20to%20EIS%20Projects%20(ELUG)#EIS Project Concepts|Building EIS projects]].
#* JCA <tt>connector.jar</tt> file  –  if you are using [[Introduction%20to%20EIS%20Projects%20(ELUG)#EIS Project Concepts|EIS Projects]].<br>The <tt>connector.jar</tt> file contains <tt>javax.resource.cci</tt> and <tt>javax.resource.spi</tt> interfaces that EclipseLink EIS uses. Edit the <tt>workbench.cmd</tt> or <tt>workbench.sh</tt> file in <tt><</tt>''<tt>ECLIPSELINK_HOME</tt>''<tt>>/utils/workbench/bin</tt> to change the path to this file.<br>At run time, this <tt>connector.jar</tt> file (or its equivalent) must be on your application or application server classpath.
#* Oracle Database <tt>ORACLE_HOME/rdbms/jlib/xdb.jar</tt> file  –  if you are using  [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-XMLType Mapping|Direct-to-XMLType Mappings]] with an Oracle9i or later database.
#* Custom <tt>Collection</tt> class that you use to override the default <tt>Collection</tt> class that EclipseLink uses with a [[Configuring%20a%20Mapping%20(ELUG)#Configuring Container Policy|mapping container policy]].  <br>The following examples shows how to set the <tt>DRIVER_CLASSPATH</tt> variable for Windows system and  for UNIX.<br><br>'''''Example: Setting DRIVER_CLASSPATH on Windows''''' <br><tt>set DRIVER_CLASSPATH=C:\OraHome\jdbc\lib\ojdbc14.jar;C:\Attunity\Connect\Java\lib\attunityResourceAdapter.jar;C:\OraHome\rdbms\jlib\xdb.jar</tt><br>'''Note''': If the path to your driver(s) contains spaces, you must enclose the path in double-quotes in the <tt>setenv.cmd</tt> file. For example:  <tt>set DRIVER_CLASSPATH="C:\Program Files\some directory\driver.jar"</tt><br><br>'''''Example: Setting DRIVER_CLASSPATH on UNIX'''''<br><tt>DRIVER_CLASSPATH=/OraHome/jdbc/lib/ojdbc14.jar;/attunity/connect/java/lib/attunityResourceAdapter.jar;/OraHome/rdbms/jlib/xdb.jar; export JDBC_CLASSPATH</tt>
# Save and close the <tt>setenv</tt> script.
# Start the Workbench by launching the ''<tt><ECLIPSELINK_HOME></tt>''<tt>\utils\workbench\bin\workbench.cmd</tt> or <tt>workbench.sh</tt> file.

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

<span id="Figure 4-1"></span>
'''''Workbench Window'''''

[[Image:mw_.gif|Workbench Window]]<br><br>

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|How to Use Menus]] for more information.
# Toolbars: The toolbars contain shortcuts to specific functions. See [[#How to Use Toolbars|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|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|How to Use the Editor]] for more information.
# Problems window section: The '''Problems''' window section shows messages and errors for the currently selected object in the Navigator window section (see [[#How to Use the Problems Window|How to Use the Problems Window]]). [[EclipseLink Workbench Error Reference (ELUG)]] contains detailed information on each error message.


===How to Use Menus===
Workbench contains the following two types of menus:
* Menu bar menus (see [[#Using Menu Bar Menus|Using Menu Bar Menus]])
* Context menus (see [[#Using Context Menus|Using Context 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.


<span id="Figure 4-2"></span>
'''''Sample Menu Bar Menu'''''

[[Image:menubar.gif|Sample Menu Bar Menu]]<br><br>


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


<span id="Figure 4-3"></span>
''''' Sample Context Menu'''''

[[Image:popup.gif|Sample Context Menu]]<br><br>


===How to Use Toolbars===
Workbench contains the following toolbars at the top of the window:
* [[#Using Standard Toolbar|Standard Toolbar]]
* [[#Using Context Toolbar|Context Toolbar]]

Toolbars provide tool tips: each toolbar button provides a brief description when you position the mouse pointer over it.


====Using Standard Toolbar====
The standard toolbar furnishes quick access to the standard menu options ('''File''', '''Edit''', '''Selected''', and so on).


<span id="Table 4-1"></span>
''''' Standard Toolbar Buttons'''''

{| class="HRuleFormal" dir="ltr" title="Standard Toolbar Buttons" summary="This table defines each button on the standard toolbar." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t4" align="left" valign="bottom" | '''Button'''
! id="r1c2-t4" align="left" valign="bottom" | '''Description'''
! id="r1c3-t4" align="left" valign="bottom" | '''Available for...'''
|- align="left" valign="top"
| id="r2c1-t4" headers="r1c1-t4" align="left" |
[[Image:newprjt.gif|New Project button.]]<br>
| headers="r2c1-t4 r1c2-t4" align="left" |
New
| headers="r2c1-t4 r1c3-t4" align="left" |
All
|- align="left" valign="top"
| id="r3c1-t4" headers="r1c1-t4" align="left" |
[[Image:openbtn.gif|Open Project button]]<br>
| headers="r3c1-t4 r1c2-t4" align="left" |
Open
| headers="r3c1-t4 r1c3-t4" align="left" |
All
|- align="left" valign="top"
| id="r4c1-t4" headers="r1c1-t4" align="left" |
[[Image:savebtn.gif|Save button]]<br>
| headers="r4c1-t4 r1c2-t4" align="left" |
Save
| headers="r4c1-t4 r1c3-t4" align="left" |
All
|- align="left" valign="top"
| id="r5c1-t4" headers="r1c1-t4" align="left" |
[[Image:saveasbt.gif|Save As button]]<br>
| headers="r5c1-t4 r1c2-t4" align="left" |
Save as
| headers="r5c1-t4 r1c3-t4" align="left" |
All
|- align="left" valign="top"
| id="r6c1-t4" headers="r1c1-t4" align="left" |
[[Image:saveall.gif|Save All button]]<br>
| headers="r6c1-t4 r1c2-t4" align="left" |
Save all
| headers="r6c1-t4 r1c3-t4" align="left" |
All
|- align="left" valign="top"
| id="r7c1-t4" headers="r1c1-t4" align="left" |
[[Image:closbtn.gif|Close Project button]]<br>
| headers="r7c1-t4 r1c2-t4" align="left" |
Close
| headers="r7c1-t4 r1c3-t4" align="left" |
All
|- align="left" valign="top"
| id="r8c1-t4" headers="r1c1-t4" align="left" |
[[Image:clsalbtn.gif|Close All button]]<br>
| headers="r8c1-t4 r1c2-t4" align="left" |
Close all
| headers="r8c1-t4 r1c3-t4" align="left" |
All
|- align="left" valign="top"
| id="r10c1-t4" headers="r1c1-t4" align="left" |
[[Image:expxml.gif|Export Deployment XML button]]<br>
| headers="r10c1-t4 r1c2-t4" align="left" |
Export deployment XML for the selected projects
| headers="r10c1-t4 r1c3-t4" align="left" |
Projects
|- align="left" valign="top"
| id="r11c1-t4" headers="r1c1-t4" align="left" |
[[Image:refclsbt.gif|Refresh Selected Classes button]]<br>
| headers="r11c1-t4 r1c2-t4" align="left" |
Refreshes selected classes
| headers="r11c1-t4 r1c3-t4" align="left" |
Projects
|- align="left" valign="top"
| id="r12c1-t4" headers="r1c1-t4" align="left" |
[[Image:addclbt.gif|Add or Update Classes button]]<br>
| headers="r12c1-t4 r1c2-t4" align="left" |
Add or refresh classes
| headers="r12c1-t4 r1c3-t4" align="left" |
Projects
|- align="left" valign="top"
| id="r13c1-t4" headers="r1c1-t4" align="left" |
[[Image:creatcls.gif|Create New Class button]]<br>
| headers="r13c1-t4 r1c2-t4" align="left" |
Create new class
| headers="r13c1-t4 r1c3-t4" align="left" |
Projects
|}


====Using Context Toolbar====
The context toolbar provides quick access to functions for the currently selected object in the '''[[#How to Use the Navigator|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.


<span id="Table 4-2"></span>
''''' Context Toolbar Buttons'''''

{| class="HRuleFormal" dir="ltr" title="Context Toolbar Buttons" summary="This table identifies each button on the context toolbar." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t5" align="left" valign="bottom" | '''Button'''
! id="r1c2-t5" align="left" valign="bottom" | '''Description'''
! id="r1c3-t5" align="left" valign="bottom" | '''Available for...'''
|- align="left" valign="top"
| id="r2c1-t5" headers="r1c1-t5" align="left" |
[[Image:loginbtn.gif|Login to Database button]]<br>
| headers="r2c1-t5 r1c2-t5" align="left" |
Login to database
| headers="r2c1-t5 r1c3-t5" align="left" |
Databases
|- align="left" valign="top"
| id="r3c1-t5" headers="r1c1-t5" align="left" |
[[Image:logotbtn.gif|Logout of Database button]]<br>
| headers="r3c1-t5 r1c2-t5" align="left" |
Logout of database
| headers="r3c1-t5 r1c3-t5" align="left" |
Databases
|- align="left" valign="top"
| id="r4c1-t5" headers="r1c1-t5" align="left" |
[[Image:addtable.gif|Add Table button]]<br>
| headers="r4c1-t5 r1c2-t5" align="left" |
Add new table
| headers="r4c1-t5 r1c3-t5" align="left" |
Databases
|- align="left" valign="top"
| id="r5c1-t5" headers="r1c1-t5" align="left" |
[[Image:addtbldb.gif|Add or Update Tables from Database button]]<br>
| headers="r5c1-t5 r1c2-t5" align="left" |
Add or update existing tables from database
| headers="r5c1-t5 r1c3-t5" align="left" |
Databases
|- align="left" valign="top"
| id="r6c1-t5" headers="r1c1-t5" align="left" |
[[Image:refclsbt.gif|Refresh from Database button]]<br>
| headers="r6c1-t5 r1c2-t5" align="left" |
Refresh from database
| headers="r6c1-t5 r1c3-t5" align="left" |
Database tables
|- align="left" valign="top"
| id="r7c1-t5" headers="r1c1-t5" align="left" |
[[Image:remtable.gif|Remove Table button]]<br>
| headers="r7c1-t5 r1c2-t5" align="left" |
Remove table or selected item
| headers="r7c1-t5 r1c3-t5" align="left" |
Database tables
|- align="left" valign="top"
| id="r8c1-t5" headers="r1c1-t5" align="left" |
[[Image:renambtn.gif|Rename button]]<br>
| headers="r8c1-t5 r1c2-t5" align="left" |
Rename table or selected item
| headers="r8c1-t5 r1c3-t5" align="left" |
Database tables
|- align="left" valign="top"
| id="r14c1-t5" headers="r1c1-t5" align="left" |
[[Image:adschembtn.gif|Import Schema button]]<br>
| headers="r14c1-t5 r1c2-t5" align="left" |
Import schema
| headers="r14c1-t5 r1c3-t5" align="left" |
Schemas
|- align="left" valign="top"
| id="r15c1-t5" headers="r1c1-t5" align="left" |
[[Image:agdesbtn.gif|Aggregate Descriptor button]]<br>
| headers="r15c1-t5 r1c2-t5" align="left" |
Relational aggregate descriptor
| headers="r15c1-t5 r1c3-t5" align="left" |
Descriptors
|- align="left" valign="top"
| id="r16c1-t5" headers="r1c1-t5" align="left" |
[[Image:cldesbtn.gif|Class Descriptor button]]<br>
| headers="r16c1-t5 r1c2-t5" align="left" |
Relational class descriptor
| headers="r16c1-t5 r1c3-t5" align="left" |
Descriptors
|- align="left" valign="top"
| id="r18c1-t5" headers="r1c1-t5" align="left" |
[[Image:compdsbt.gif|EIS composite descriptor button]]<br>
| headers="r18c1-t5 r1c2-t5" align="left" |
EIS composite descriptor
| headers="r18c1-t5 r1c3-t5" align="left" |
Descriptors
|- align="left" valign="top"
| id="r19c1-t5" headers="r1c1-t5" align="left" |
[[Image:rootdsbt.gif|EIS Root Descriptor button]]<br>
| headers="r19c1-t5 r1c2-t5" align="left" |
EIS root descriptor
| headers="r19c1-t5 r1c3-t5" align="left" |
Descriptors
|- align="left" valign="top"
| id="r21c1-t5" headers="r1c1-t5" align="left" |
[[Image:xdscbtn.gif|XML descriptor button]]<br>
| headers="r21c1-t5 r1c2-t5" align="left" |
XML descriptor
| headers="r21c1-t5 r1c3-t5" align="left" |
Descriptors
|- align="left" valign="top"
| id="r22c1-t5" headers="r1c1-t5" align="left" |
[[Image:dtfmpbtn.gif|Direct to Field Mapping button]]<br>
| headers="r22c1-t5 r1c2-t5" align="left" |
Direct-to-field mapping
| headers="r22c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r26c1-t5" headers="r1c1-t5" align="left" |
[[Image:dxmtbtn.gif|Direct-to-XMLType Mapping button]]<br>
| headers="r26c1-t5 r1c2-t5" align="left" |
Direct-to-XMLType mapping
| headers="r26c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r27c1-t5" headers="r1c1-t5" align="left" |
[[Image:dcmapbtn.gif|Direct Collection Mapping button]]<br>
| headers="r27c1-t5 r1c2-t5" align="left" |
Direct collection mapping
| headers="r27c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r28c1-t5" headers="r1c1-t5" align="left" |
[[Image:drmapbtn.gif|Direct Map Mapping button]]<br>
| headers="r28c1-t5 r1c2-t5" align="left" |
Direct map mapping
| headers="r28c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r29c1-t5" headers="r1c1-t5" align="left" |
[[Image:agmapbtn.gif|Aggregate Mapping button]]<br>
| headers="r29c1-t5 r1c2-t5" align="left" |
Aggregate mapping
| headers="r29c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r30c1-t5" headers="r1c1-t5" align="left" |
[[Image:onetoone_map_btn.gif|One-to-one Mapping button]]<br>
| headers="r30c1-t5 r1c2-t5" align="left" |
One-to-one mapping
| headers="r30c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r31c1-t5" headers="r1c1-t5" align="left" |
[[Image:v11mapbt.gif|Variable One-to-one Mapping button]]<br>
| headers="r31c1-t5 r1c2-t5" align="left" |
Variable one-to-one mapping
| headers="r31c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r32c1-t5" headers="r1c1-t5" align="left" |
[[Image:onetomany_map_btn.gif|One-to-many Mapping button]]<br>
| headers="r32c1-t5 r1c2-t5" align="left" |
One-to-many mapping
| headers="r32c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r33c1-t5" headers="r1c1-t5" align="left" |
[[Image:mmmapbtn.gif|Many-to-many Mapping button]]<br>
| headers="r33c1-t5 r1c2-t5" align="left" |
Many-to-many mapping
| headers="r33c1-t5 r1c3-t5" align="left" |
Attributes in relational descriptors
|- align="left" valign="top"
| id="r34c1-t5" headers="r1c1-t5" align="left" |
[[Image:dxmlmpbt.gif|Direct Mapping button]]<br>
| headers="r34c1-t5 r1c2-t5" align="left" |
Direct mapping
| headers="r34c1-t5 r1c3-t5" align="left" |
Attributes in EIS descriptors
|- align="left" valign="top"
| id="r35c1-t5" headers="r1c1-t5" align="left" |
[[Image:dircobtn.gif|Direct Collection Mapping button]]<br>
| headers="r35c1-t5 r1c2-t5" align="left" |
Direct collection mapping
| headers="r35c1-t5 r1c3-t5" align="left" |
Attributes in EIS descriptors
|- align="left" valign="top"
| id="r36c1-t5" headers="r1c1-t5" align="left" |
[[Image:comobbt.gif|Composite Object Mapping button]]<br>
| headers="r36c1-t5 r1c2-t5" align="left" |
Composite object mapping
| headers="r36c1-t5 r1c3-t5" align="left" |
Attributes in EIS descriptors
|- align="left" valign="top"
| id="r37c1-t5" headers="r1c1-t5" align="left" |
[[Image:comclbt.gif|Composite Collection Mapping button]]<br>
| headers="r37c1-t5 r1c2-t5" align="left" |
Composite collection mapping
| headers="r37c1-t5 r1c3-t5" align="left" |
Attributes in EIS descriptors
|- align="left" valign="top"
| id="r38c1-t5" headers="r1c1-t5" align="left" |
[[Image:onetoone_btn.gif|One-to-one Mapping button]]<br>
| headers="r38c1-t5 r1c2-t5" align="left" |
One-to-one mapping
| headers="r38c1-t5 r1c3-t5" align="left" |
Attributes in EIS descriptors
|- align="left" valign="top"
| id="r39c1-t5" headers="r1c1-t5" align="left" |
[[Image:onetomany_btn.gif|One-to-many Mapping button]]<br>
| headers="r39c1-t5 r1c2-t5" align="left" |
One-to-many mapping
| headers="r39c1-t5 r1c3-t5" align="left" |
Attributes in EIS descriptors
|- align="left" valign="top"
| id="r40c1-t5" headers="r1c1-t5" align="left" |
[[Image:dxmlmpbt.gif|Direct-to-XML Mapping button]]<br>
| headers="r40c1-t5 r1c2-t5" align="left" |
Direct-to-XML mapping
| headers="r40c1-t5 r1c3-t5" align="left" |
Attributes in XML descriptors
|- align="left" valign="top"
| id="r41c1-t5" headers="r1c1-t5" align="left" |
[[Image:dircobtn.gif|Direct Collection Mapping button]]<br>
| headers="r41c1-t5 r1c2-t5" align="left" |
Direct collection mapping
| headers="r41c1-t5 r1c3-t5" align="left" |
Attributes in XML descriptors
|- align="left" valign="top"
| id="r42c1-t5" headers="r1c1-t5" align="left" |
[[Image:comobbt.gif|Composite Object Mapping button]]<br>
| headers="r42c1-t5 r1c2-t5" align="left" |
Composite object mapping
| headers="r42c1-t5 r1c3-t5" align="left" |
Attributes in XML descriptors
|- align="left" valign="top"
| id="r43c1-t5" headers="r1c1-t5" align="left" |
[[Image:comclbt.gif|Composite Collection Mapping button]]<br>
| headers="r43c1-t5 r1c2-t5" align="left" |
Composite collection mapping
| headers="r43c1-t5 r1c3-t5" align="left" |
Attributes in XML descriptors
|- align="left" valign="top"
| id="r44c1-t5" headers="r1c1-t5" align="left" |
[[Image:anyobbtn.gif|Any Object Mapping button]]<br>
| headers="r44c1-t5 r1c2-t5" align="left" |
Any object mapping
| headers="r44c1-t5 r1c3-t5" align="left" |
Attributes in XML descriptors
|- align="left" valign="top"
| id="r45c1-t5" headers="r1c1-t5" align="left" |
[[Image:anycolbtn.gif|Any Collection Mapping button]]<br>
| headers="r45c1-t5 r1c2-t5" align="left" |
Any collection mapping
| headers="r45c1-t5 r1c3-t5" align="left" |
Attributes in XML descriptors
|- align="left" valign="top"
| id="r46c1-t5" headers="r1c1-t5" align="left" |
[[Image:trmapbtn.gif|Transformation Mapping button]]<br>
| headers="r46c1-t5 r1c2-t5" align="left" |
Transformation mapping
| headers="r46c1-t5 r1c3-t5" align="left" |
Attributes in all descriptors
|- align="left" valign="top"
| id="r47c1-t5" headers="r1c1-t5" align="left" |
[[Image:unmapbtn.gif|Unmap button]]<br>
| headers="r47c1-t5 r1c2-t5" align="left" |
Unmap
| headers="r47c1-t5 r1c3-t5" align="left" |
Attributes in all descriptors
|- align="left" valign="top"
| id="r48c1-t5" headers="r1c1-t5" align="left" |
[[Image:newsesbt.gif|Session button]]<br>
| headers="r48c1-t5 r1c2-t5" align="left" |
Session
| headers="r48c1-t5 r1c3-t5" align="left" |
Sessions configurations
|- align="left" valign="top"
| id="r49c1-t5" headers="r1c1-t5" align="left" |
[[Image:sesbkbtn.gif|Session Broker button]]<br>
| headers="r49c1-t5 r1c2-t5" align="left" |
Session Broker
| headers="r49c1-t5 r1c3-t5" align="left" |
Sessions configurations
|- align="left" valign="top"
| id="r50c1-t5" headers="r1c1-t5" align="left" |
[[Image:nmdconpl.gif|Named Connection Pool button]]<br>
| headers="r50c1-t5 r1c2-t5" align="left" |
Named connection pool
| headers="r50c1-t5 r1c3-t5" align="left" |
Server sessions
|- align="left" valign="top"
| id="r51c1-t5" headers="r1c1-t5" align="left" |
[[Image:seqconpl.gif|Sequence Connection Pool button]]<br>
| headers="r51c1-t5 r1c2-t5" align="left" |
Sequence connection pool
| headers="r51c1-t5 r1c3-t5" align="left" |
Server sessions
|- align="left" valign="top"
| id="r52c1-t5" headers="r1c1-t5" align="left" |
[[Image:wrtconpl.gif|Write Connection Pool button]]<br>
| headers="r52c1-t5 r1c2-t5" align="left" |
Write connection pool
| headers="r52c1-t5 r1c3-t5" align="left" |
Server sessions
|- align="left" valign="top"
| id="r53c1-t5" headers="r1c1-t5" align="left" |
[[Image:renambtn.gif|Rename button]]<br>
| headers="r53c1-t5 r1c2-t5" align="left" |
Rename
| headers="r53c1-t5 r1c3-t5" align="left" |
Database sessions, session brokers
|- align="left" valign="top"
| id="r54c1-t5" headers="r1c1-t5" align="left" |
[[Image:delbtn.gif|Delete Session button]]<br>
| headers="r54c1-t5 r1c2-t5" align="left" |
Delete session
| headers="r54c1-t5 r1c3-t5" align="left" |
Database sessions, session brokers
|}

===How to Use the Navigator===
EclipseLink displays the items included in each project (descriptors, mappings, data source, and so on) in the '''Navigator''' on the left side of the Workbench window, as this figure shows.


<span id="Figure 4-4"></span>
'''''Sample Navigator'''''

[[Image:city.gif|Sample Navigator]]<br><br>

The numbered callouts on this figure identify the following user interface components:
# Project (relational project)
# Package
# EclipseLink Descriptor (relational descriptor)
# Attribute/mapping (direct to field mapping)
# Unsaved/changed item
# Database
# Database table

Click the plus (''' + ''') or minus ('''  –  ''') sign next to the item, or double-click the item name to expand or collapse the item.

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 [[#How to Use the Editor|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 [[#Using Context Menus|Using Context Menus]]).
* Choose a function from the '''Selected''' menu (see [[#Using Menu Bar Menus|Using Menu Bar Menus]]).

For information on using the Navigator with a database in relational projects, see [[#How to Use Database Tables in the Navigator Window|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 [[#How to Use XML Schemas in the Navigator|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.


<span id="Figure 4-5"></span>
'''''Sample Active and Inactive Descriptors'''''

[[Image:inactive.gif|Sample Active and Inactive Descriptors]]<br><br>

The numbered callouts show the following user interface components:
# Inactive descriptor
# Active descriptor


'''Errors and Missing Information'''

[[Image:catnicon.gif|Caution / Warning icon]] 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 [[#How to Use the Problems Window|Problems window]].

[[EclipseLink Workbench Error Reference (ELUG)]] contains more information on each Workbench error message.


===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.


<span id="Figure 4-6"></span>
''''' Sample Editor'''''

[[Image:edpane.gif|Sample Editor]]<br><br>

The numbered callouts identify the following user interface components:
# Selected element (from the '''Navigator''')
# Editor property tabs


===How to Use the Problems Window===

[[Image:catnicon.gif|Caution / Warning icon]] 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|How to Use the Navigator]]) and displays a message in the Problems window as [[#Figure 4-7|the Sample Deficient Mapping figure]] shows.

If you select the error, then Workbench displays the complete error message in the '''Problems''' window. [[EclipseLink Workbench Error Reference (ELUG)]] contains detailed information on each error message.

<span id="Figure 4-7"></span>
'''''Sample Deficient Mapping'''''

[[Image:desmaper.gif|Sample Deficient Mapping]]<br><br>

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 [[Creating%20a%20Project%20(ELUG)#How to Generate the Project Status Report|create a status report]] that includes all errors in a selected project.

==Using Workbench Preferences==
To customize Workbench, select '''Tools > Preferences''' from the menu. The '''Preferences''' dialog box appears.

<span id="Figure 4-8"></span>
''''' Preferences Dialog Box'''''

[[Image:pref_gen.gif|Preferences Dialog Box]]<br><br>

Workbench provides the following preferences:
* [[#How to Use General Preferences|General Preferences]]
** [[#How to Use Help Preferences|Help Preferences]]
* [[#How to Use Mappings Preferences|Mappings Preferences]]
** [[#How to Use Class Preferences|Class Preferences]]
** [[#How to Use Database Preferences|Database Preferences]]
* [[#How to Use Sessions Configuration Preferences|Sessions Configuration Preferences]]
** [[#How to Use New Names Preferences|New Names Preferences]]
** [[#How to Use Session Platform Preferences|Session Platform Preferences]]
* [[#How to Use Platforms Preferences|Platforms Preferences]]

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:
# Select '''Tools > Preferences''' from the menu. The '''Preferences''' dialog box appears.
# Select '''General''' in the '''Category''' window.<br><span id="Figure 4-9"></span>''''' Preferences – General Dialog Box'''''<br>[[Image:pref_gen.gif|Preferences – General Dialog Box]]<br><br>
# Complete each field on the '''Preferences – General''' dialog box and click '''OK'''.


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

{| class="HRuleInformal" dir="ltr" title="This table defines each field on the General Preferences." summary="This table defines each field on the General Preferences." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t6" align="left" valign="bottom" | '''Field'''
! id="r1c2-t6" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t6" headers="r1c1-t6" align="left" | '''Display Splash Screen'''
| headers="r2c1-t6 r1c2-t6" align="left" | Specify if Workbench should show the graphical splash screen when starting.
|- align="left" valign="top"
| id="r3c1-t6" headers="r1c1-t6" align="left" | '''Look and Feel'''
| headers="r3c1-t6 r1c2-t6" align="left" | Select the look and feel to use for Workbench.
|- align="left" valign="top"
| id="r4c1-t6" headers="r1c1-t6" align="left" | '''Size of recently opened files list'''
| headers="r4c1-t6 r1c2-t6" align="left" |
Select the number of projects to maintain in the '''File''' > '''Reopen''' option. See [[Creating%20a%20Project%20(ELUG)#How to Open Existing Projects|How to Open Existing Projects]] for more information.
|- align="left" valign="top"
| id="r5c1-t6" headers="r1c1-t6" align="left" | '''HTTP Proxy Host'''
| headers="r5c1-t6 r1c2-t6" align="left" | Specify if your PC requires a proxy server to access the internet.
|- align="left" valign="top"
| id="r6c1-t6" headers="r1c1-t6" align="left" | '''HTTP Proxy Port'''
| headers="r6c1-t6 r1c2-t6" align="left" | Specify the port used by your proxy host.
|- align="left" valign="top"
| id="r7c1-t6" headers="r1c1-t6" align="left" | '''Network Connect Timeout'''
| headers="r7c1-t6 r1c2-t6" align="left" | Specify the timeout (in seconds) to establish a network or internet connection.
|- align="left" valign="top"
| id="r8c1-t6" headers="r1c1-t6" align="left" | '''Network Read Timeout'''
| headers="r8c1-t6 r1c2-t6" align="left" | Specify the timeout (in seconds) when accessing data from a network or internet connection.
|- align="left" valign="top"
| id="r9c1-t6" headers="r1c1-t6" align="left" | '''Reopen Projects on Startup'''
| headers="r9c1-t6 r1c2-t6" align="left" | Select to reopen the projects that were open the last time you exited the Workbench.
|}

<br>

You must restart Workbench to apply the changes.


===How to Use Help Preferences===
The EclipseLink Workbench online help is web-based. Use the Help preferences to define the location of your web browser. 

Follow these steps to customize the Help preferences:
# Select '''Tools > Preferences''' from the menu. The '''Preferences''' dialog box appears.
# Select '''General > Help''' in the '''Category''' window. The '''Help''' dialog box appears.<br>'''''Preferences – Help Dialog Box'''''<br>[[Image:pref_help.gif|Preferences – Help Dialog Box]]<br><br>
# Click '''Browse''' and select your HTML web browser.
# Click '''OK'''.

'''Note''': If your location requires a proxy to browse external web pages, be sure to complete the '''Proxy''' fields on the [[#How to Use General Preferences|General Preferences]] page.

===How to Use Mappings Preferences===
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.<br>'''''Preferences – Mappings Dialog Box'''''<br>[[Image:pref_map.gif|Preferences – Mappings Dialog Box]]<br><br>
# Complete each field on the '''Preferences - Mappings''' dialog box and click '''OK'''.


Use the following information to enter data in each field:

{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Mapping Preferences." summary="This table defines each field on the Mapping Preferences." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t7" align="left" valign="bottom" | '''Field'''
! id="r1c2-t7" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t7" headers="r1c1-t7" align="left" | '''Allow changing query type'''
| headers="r2c1-t7 r1c2-t7" align="left" | Configure whether or not Workbench always allows, never allows, or prompts before allowing you to change the query type associated with a descriptor.
|- align="left" valign="top"
| id="r3c1-t7" headers="r1c1-t7" align="left" | '''Allow changing query format'''
| headers="r3c1-t7 r1c2-t7" align="left" | Configure whether or not Workbench always allows, never allows, or prompts before allowing you to change the configuration of a query associated with a descriptor.
|}


===How to Use Class Preferences===
Use the Class preferences to specify how 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'''.<br><span id="Figure 4-11"></span>'''''Preferences  –  Mappings  –  Class Dialog Box'''''<br>[[Image:pref_map_class.gif|Preferences  –  Mappings  –  Class Dialog Box]]<br><br>
# On the '''Preferences''' – '''Mappings''' – '''Class''' dialog box, specify how Workbench maintains classes when renaming or editing a zero-argument constructor.


===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:

# Select '''Tools > Preferences''' from the menu. The '''Preferences''' dialog box appears.
# Expand '''Mappings''' in the '''Category''' window and select '''Database'''.<br><span id="Figure 4-12"></span>'''''Preferences – Mappings – Database Preferences Dialog Box'''''<br>[[Image:pref_map_db.gif|Preferences – Mappings – Database Preferences Dialog Box]]<br><br>
# 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:


{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Database Preferences." summary="This table defines each field on the Database Preferences." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t8" align="left" valign="bottom" | '''Field'''
! id="r1c2-t8" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t8" headers="r1c1-t8" align="left" | '''Database Driver'''
| headers="r2c1-t8 r1c2-t8" align="left" | Enter the custom database driver class name.
|- align="left" valign="top"
| id="r3c1-t8" headers="r1c1-t8" align="left" | '''Connection URL'''
| headers="r3c1-t8 r1c2-t8" align="left" | 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 [[Creating%20a%20Session%20(ELUG)#Configuring a Sessions Configuration|Sessions Configuration property sheet]]. 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.<br><span id="Figure 4-13"></span>''''' Preferences – Sessions Configuration Dialog Box'''''<br>[[Image:pref_ses.gif|Preferences – Sessions Configuration Dialog Box]]<br><br>

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 EclipseLink 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.


===How to Use New Names Preferences===
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'''.<br><span id="Figure 4-14"></span>''''' Preferences – Sessions Configuration – New Names Dialog Box'''''<br>[[Image:pref_ses_new.gif|Preferences – Sessions Configuration – New Names Dialog Box]]<br><br>
# Complete each field on the '''Preferences – Sessions Configuration – New Names dialog box''' and click '''OK'''.

Use the following information to enter data in each field:

{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Session Configuration  –  New Names Preferences." summary="This table defines each field on the Session Configuration  –  New Names Preferences." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t9" align="left" valign="bottom" | '''Field'''
! id="r1c2-t9" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t9" headers="r1c1-t9" align="left" | '''Sessions Configuration'''
| headers="r2c1-t9 r1c2-t9" align="left" |
Specify the default name for newly created sessions configuration files (default, <tt>sessions.xml</tt>). See [[Creating%20a%20Session%20(ELUG)#Creating a Sessions Configuration|Creating a Sessions Configuration]] for more information.
|- align="left" valign="top"
| id="r3c1-t9" headers="r1c1-t9" align="left" | '''Session'''
| headers="r3c1-t9 r1c2-t9" align="left" |
Specify the default name for newly created sessions (default, <tt>Session</tt>). See [[Creating%20a%20Session%20(ELUG)#Introduction to the Session Creation|Introduction to the Session Creation]] for more information.
|- align="left" valign="top"
| id="r4c1-t9" headers="r1c1-t9" align="left" | '''Broker'''
| headers="r4c1-t9 r1c2-t9" align="left" |
Specify the default name for newly created session brokers (default, <tt>SessionBroker</tt>). See [[Creating%20a%20Session%20(ELUG)#Creating Session Broker and Client Sessions|Creating Session Broker and Client Sessions]] for more information.
|- align="left" valign="top"
| id="r5c1-t9" headers="r1c1-t9" align="left" | '''Connection Pool'''
| headers="r5c1-t9 r1c2-t9" align="left" |
Specify the default name for newly created connection pools (default, <tt>ConnectionPool</tt>). See [[Creating%20an%20Internal%20Connection%20Pool%20(ELUG)#Creating an Internal Connection Pool|Creating an Internal Connection Pool]] for more information.
|}


===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:
# Select '''Tools > Preferences''' from the menu. The '''Preferences''' dialog box appears.
# Expand '''Sessions Configuration''' in the '''Category''' window and select '''Platform'''.<br><span id="Figure 4-15"></span>''''' Preferences – Sessions Configuration – Platform Preferences Dialog Box'''''<Br>[[Image:pref_ses_plat.gif|Preferences – Sessions Configuration – Platform Preferences Dialog Box]]<br><br>
# Complete each field on the '''Preferences – Sessions Configuration – Platform dialog box''' and click '''OK'''.

Use the following information to enter data in each field:

{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Session Configuration  –  Platform Preferences." summary="This table defines each field on the Session Configuration  –  Platform Preferences." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t10" align="left" valign="bottom" | '''Field'''
! id="r1c2-t10" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t10" headers="r1c1-t10" align="left" | '''Use Server Platform'''
| headers="r2c1-t10 r1c2-t10" align="left" |
Specify the default application server platform for newly created sessions configuration files (default, <tt>sessions.xml</tt>). See [[Creating%20a%20Session%20(ELUG)#Creating a Sessions Configuration|Creating a Sessions Configuration]] for more information.
|- align="left" valign="top"
| id="r3c1-t10" headers="r1c1-t10" align="left" | '''Default Data Source Type'''
| headers="r3c1-t10 r1c2-t10" align="left" |
Select the default data source type ('''Database''', '''EIS''', or '''XML''') and platform for newly created sessions. See [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|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.

<span id="Figure 4-17"></span>
'''''Sample Database Tables'''''

[[Image:dbtable.gif|Sample Database Tables]]<br><br>

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'''<nowiki>:</nowiki>
* '''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:
* [[#How to Use Database Tables in the Navigator Window|How to Use Database Tables in the Navigator Window]]
* [[#How to Use Database Tables in the Editor Window|How to Use Database Tables in the Editor Window]]
* [[#How to Generate Data from Database Tables|How to Generate Data from Database Tables]]


===How to Use Database Tables in the Navigator Window===
This section describes the following options:
* [[#Logging In and Out of a Database|Logging In and Out of a Database]]
* [[#Creating New Tables|Creating New Tables]]
* [[#Importing Tables from a Database|Importing Tables from a Database]]
* [[#Removing Tables|Removing Tables]]
* [[#Renaming Tables|Renaming Tables]]
* [[#Refreshing Tables from the Database|Refreshing Tables from the Database]]

See [[#How to Use Database Tables in the Editor Window|How to Use Database Tables in the Editor Window]] for more information.


====Logging In and Out of a Database====
To log in or out of a relational database, do the following:
# Create a database login (see [[Configuring%20a%20Database%20Login%20(ELUG)#Introduction to Database Login Configuration|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.


====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''' [[Image:addtable.gif|Add a New Table button]]. The '''New Table''' dialog box appears.<br>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.<br><span id="Figure4-18"></span>'''''New Table Dialog Box'''''<br>[[Image:newtble.gif|New Table Dialog Box]]<br><br>
# Complete each field on the '''New Table''' dialog box and click '''OK'''.


Use the following information to enter data in each field:

{| class="HRuleInformal" dir="ltr" title="This table defines each field on the New Table dialog." summary="This table defines each field on the New Table dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t11" align="left" valign="bottom" | '''Field'''
! id="r1c2-t11" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t11" headers="r1c1-t11" align="left" | '''Catalog'''
| headers="r2c1-t11 r1c2-t11" align="left" |
Use to identify specific database information for the table. Consult your database administrator for more information.
|- align="left" valign="top"
| id="r3c1-t11" headers="r1c1-t11" align="left" | '''Schema'''
| headers="r3c1-t11 r1c2-t11" align="left" |
Use to identify specific database information for the table. Consult your database administrator for more information.
|- align="left" valign="top"
| id="r4c1-t11" headers="r1c1-t11" align="left" | '''Table Name'''
| headers="r4c1-t11 r1c2-t11" align="left" | 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|Generating Tables on the Database]] for more information on creating the table in the database.

Continue with [[#How to Use Database Tables in the Editor Window|How to Use Database Tables in the Editor Window]] to use these tables in your project.


====Importing Tables from a Database====
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:
* <tt>getTables</tt>
* <tt>getTableTypes</tt>
* <tt>getImportedKeys</tt>
* <tt>getCatalogs</tt>
* <tt>getPrimaryKeys</tt>

The JDBC driver must be on the Workbench classpath (see [[#Configuring the Workbench Environment|Configuring the 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''' [[Image:addtbldb.gif|Add/Update Existing Tables from Database]]. The '''Import Tables from Database''' dialog box appears.<br>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.<br><span id="Figure 4-19"></span>'''''Import Tables from Database Dialog Box'''''<br>[[Image:importdb.gif|Import Tables from Database Dialog Box]]<br><br>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:

{| class="HRuleInformal" dir="ltr" title="This table defines each filter field on the Import Tables from Database dialog." summary="This table defines each filter field on the Import Tables from Database dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t12" align="left" valign="bottom" | '''Field'''
! id="r1c2-t12" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t12" headers="r1c1-t12" align="left" | '''Table Name Pattern'''
| headers="r2c1-t12 r1c2-t12" align="left" | 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.
|- align="left" valign="top"
| id="r3c1-t12" headers="r1c1-t12" align="left" | '''Catalog'''
| headers="r3c1-t12 r1c2-t12" align="left" | Specify the catalog of database table(s) to import.
|- align="left" valign="top"
| id="r4c1-t12" headers="r1c1-t12" align="left" | '''Schema Pattern'''
| headers="r4c1-t12 r1c2-t12" align="left" | Specify the schema of database table(s) to import.
|- align="left" valign="top"
| id="r5c1-t12" headers="r1c1-t12" align="left" | '''Table Type'''
| headers="r5c1-t12 r1c2-t12" align="left" | Specify the type of database table(s) to import.
|- align="left" valign="top"
| id="r6c1-t12" headers="r1c1-t12" align="left" | '''Available Tables'''
| headers="r6c1-t12 r1c2-t12" align="left" | Click '''Get Table Names''' to make EclipseLink display tables that match '''Table Name Pattern''', '''Catalog''', '''Schema Pattern''', and '''Table Type''' settings.
|- align="left" valign="top"
| id="r7c1-t12" headers="r1c1-t12" align="left" | '''Selected Tables'''
| headers="r7c1-t12 r1c2-t12" align="left" |
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.
|- align="left" valign="top"
| id="r8c1-t12" headers="r1c1-t12" align="left" | '''Import Fully Qualified Names'''
| headers="r8c1-t12 r1c2-t12" align="left" | Specify whether or not the tables' names are fully qualified against the schema and catalog.
|}

<br>

Examine each table's properties to verify that the imported tables contain the correct information. See [[#How to Use Database Tables in the Editor Window|How to Use Database Tables in the Editor Window]] for more information.

====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''' [[Image:remtable.gif|Remove Table button]] on the toolbar. Workbench prompts for confirmation.<br>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.<br>
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note''': Although you have removed the table from the Workbench project, the table remains in the database.
|}<br>

====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.<br>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.<br>
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note''': Although you have renamed the table in the Workbench project, the original table name remains in the database.
|}<br>

====Refreshing Tables from the Database====
To refresh (that is, reload) the database tables in the Workbench project, use the following procedure:
# Select the database table in the '''Navigator,''' and click '''Refresh from Database''' on the toolbar.<br>You can also right-click on the database table and choose '''Refresh from Database''' from the context menu or choose '''Selected''' > '''Refresh from Database''' from the menu. 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.<br><span id="Figure 4-20"></span><br>''''' Duplicate Table Dialog Box'''''<br>[[Image:duptable.gif|Duplicate Table Dialog Box]]<br><br>
#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:
* [[#Working with Column Properties|Working with Column Properties]]
* [[#Setting a Primary Key for Database Tables|Setting a Primary Key for Database Tables]]
* [[#Creating Table References|Creating Table References]]
* [[#Creating Field Associations|Creating Field Associations]]


====Working with Column Properties====
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.<br><span id="Figure 4-21"></span>'''''Fields Properties'''''<br>[[Image:fields.gif|Fields Properties]]<br><br>
# 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:
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Columns tab." summary="This table defines each field on the Columns tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t15" align="left" valign="bottom" | '''Field'''
! id="r1c2-t15" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t15" headers="r1c1-t15" align="left" | '''Name'''
| headers="r2c1-t15 r1c2-t15" align="left" | Specify the name of the field.
|- align="left" valign="top"
| id="r3c1-t15" headers="r1c1-t15" align="left" | '''Type'''
| headers="r3c1-t15 r1c2-t15" align="left" |
Use the drop-down list to select the field's type. Note: The valid values will vary, depending on the database.
|- align="left" valign="top"
| id="r4c1-t15" headers="r1c1-t15" align="left" | '''Size'''
| headers="r4c1-t15 r1c2-t15" align="left" | Specify the size of the field.
|- align="left" valign="top"
| id="r5c1-t15" headers="r1c1-t15" align="left" | '''Sub-Size'''
| headers="r5c1-t15 r1c2-t15" align="left" | Specify the sub-size of the field.
|- align="left" valign="top"
| id="r6c1-t15" headers="r1c1-t15" align="left" | '''Allows Null'''
| headers="r6c1-t15 r1c2-t15" align="left" | Specify if this field can be null.
|- align="left" valign="top"
| id="r7c1-t15" headers="r1c1-t15" align="left" | '''Unique'''
| headers="r7c1-t15 r1c2-t15" align="left" | Specify whether the value must be unique within the table.
|- align="left" valign="top"
| id="r8c1-t15" headers="r1c1-t15" align="left" | '''Primary Key'''
| headers="r8c1-t15 r1c2-t15" align="left" |
Specify whether or not this field is a primary key for the table (see [[#Setting a Primary Key for Database Tables|Setting a Primary Key for Database Tables]]).
|- align="left" valign="top"
| id="r9c1-t15" headers="r1c1-t15" align="left" | '''Identity'''
| headers="r9c1-t15 r1c2-t15" align="left" | Use to indicate a Sybase, SQL Server or Informix identity field.
|}
<br>

{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''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'''.


====Setting a Primary Key for Database Tables====
To set a primary key(s) for a database table, use this procedure:


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note''': 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.Click the '''Columns''' tab.<br>'''''Setting Primary Key for a Database Table<br><span id="Figure 4-22"></span>'''''<br>[[Image:fieldspk.gif|Setting Primary Key for a Database Table]]<br><br>
# 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|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.<br><span id="Figure 4-23"></span>'''''References Tab'''''<br>[[Image:reftab.gif|Description of Figure 4-23 follows]]<br>The following 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.<br><span id="Figure 4-24"></span>'''''New Reference Dialog Box'''''<br>[[Image:newref.gif|New Reference Dialog Box]]<br><br>
# Complete each field on the new Reference dialog box and click '''OK.'''


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

{| class="HRuleInformal" dir="ltr" title="This table defines each field on the New Reference dialog." summary="This table defines each field on the New Reference dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t18" align="left" valign="bottom" | '''Field'''
! id="r1c2-t18" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t18" headers="r1c1-t18" align="left" | '''Enter Name of New Reference'''
| headers="r2c1-t18 r1c2-t18" align="left" | Specify the name of the reference table. If you leave this field blank, Workbench automatically creates a name based on the format: SOURCETABLE_TARGETTABLE.
|- align="left" valign="top"
| id="r3c1-t18" headers="r1c1-t18" align="left" | '''Select the Source Table'''
| headers="r3c1-t18 r1c2-t18" align="left" | Specify the name of the source database table (the currently selected table in the Navigator).
|- align="left" valign="top"
| id="r4c1-t18" headers="r1c1-t18" align="left" | '''Select the Target Table'''
| headers="r4c1-t18 r1c2-t18" align="left" | Use the list to specify the target table for this reference.
|- align="left" valign="top"
| id="r5c1-t18" headers="r1c1-t18" align="left" | '''On Database'''
| headers="r5c1-t18 r1c2-t18" align="left" | Specify if you want to create the reference on the database when you create the table. Not all database drivers support this option.
|}


Continue with [[#Creating Field Associations|Creating Field Associations]].


====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 [[#Creating Table References|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.<br><span id="Figure 4-25"></span>''''' References Tab'''''<br>[[Image:reftab.gif|References Tab]]<br><br>The following 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:


{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the Reference tab." summary="This table identifies each field on the Reference tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t19" align="left" valign="bottom" | '''Field'''
! id="r1c2-t19" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t19" headers="r1c1-t19" align="left" | '''Table References Area'''
| headers="r2c1-t19 r1c2-t19" align="left" | <br>
|- align="left" valign="top"
| id="r3c1-t19" headers="r1c1-t19" align="left" | <blockquote>'''Name'''</blockquote>
| headers="r3c1-t19 r1c2-t19" align="left" | Specify the name of this table reference
|- align="left" valign="top"
| id="r4c1-t19" headers="r1c1-t19" align="left" | <blockquote>'''Target Table'''</blockquote>
| headers="r4c1-t19 r1c2-t19" align="left" | Specify the database table that is the ''target'' of this reference.
|- align="left" valign="top"
| id="r5c1-t19" headers="r1c1-t19" align="left" | <blockquote>'''On Database'''</blockquote>
| headers="r5c1-t19 r1c2-t19" align="left" | Specify if the reference exists on the database.
|- align="left" valign="top"
| id="r6c1-t19" headers="r1c1-t19" align="left" | '''Key Pairs Area'''
| headers="r6c1-t19 r1c2-t19" align="left" | <br>
|- align="left" valign="top"
| id="r7c1-t19" headers="r1c1-t19" align="left" | <blockquote>'''Source Column'''</blockquote>
| headers="r7c1-t19 r1c2-t19" align="left" | Select the database field from the source table.
|- align="left" valign="top"
| id="r8c1-t19" headers="r1c1-t19" align="left" | <blockquote>'''Target Column'''</blockquote>
| headers="r8c1-t19 r1c2-t19" align="left" | Select the database field from the target table.
|}

===How to Generate Data from Database Tables===

Workbench can automatically generate a variety of information from the database tables. This section describes the following:
* [[#Generating SQL Creation Scripts|Generating SQL Creation Scripts]]
* [[#Generating Classes and Descriptors from Database Tables|Generating Classes and Descriptors from Database Tables]]
* [[#Generating Tables on the Database|Generating Tables on the Database]]


====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.<br>You can also choose '''Selected''' > '''Generate Creation Script for''' > '''Selected Tables''' or '''All Tables''' from the menu.<br><span id="Figure 4-26"></span>''''' SQL Creation Script Dialog Box'''''<br>[[Image:sqlscrip.gif|Creation Script Dialog Box]]<br><br>

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.


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''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.<br>
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note''': Class and attribute names are generated based on the table and column names. You can edit the class properties to change their names.
|}<br>

'''To generate classes and descriptors from database tables, use the following procedure:'''
<ol>
<li> Select the database table(s) in the '''Navigator'''.</li>
<li> 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. <br>You can also choose '''Selected''' > '''Generate Classes and Descriptors from''' > '''Selected Tables''' or '''All Tables''' from the menu. </li>
<li> Click '''Yes'''. The Generate Classes and Descriptors dialog box appears.<br><span id=
Figure 4-27"></span>'''''Generate Classes and Descriptors Dialog Box'''''<br>[[Image:generateclasses.gif|Generate Classes and Descriptors Dialog Box]]<br><br>Complete each field on the Generate Classes and Descriptors dialog box and click '''OK'''. Use the following information to enter data in each field:
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Generate Classes and Descriptors dialog." summary="This table defines each field on the Generate Classes and Descriptors dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t22" align="left" valign="bottom" | '''Field'''
! id="r1c2-t22" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t22" headers="r1c1-t22" align="left" | '''Package Name'''
| headers="r2c1-t22 r1c2-t22" align="left" | Specify the name of package to generate. The package name must comply with Java naming standards.
|- align="left" valign="top"
| id="r3c1-t22" headers="r1c1-t22" align="left" | '''Generate Accessing Methods'''
| headers="r3c1-t22 r1c2-t22" align="left" | Specify if Workbench generates accessing methods for each class and descriptor.
|}<br>
</li>
<li>If the table contains foreign key fields that may represent relationship mappings, then the Choose Relationships to Generate dialog box appears.

<span id="Figure 4-28"></span>
<br>
''''' Choose Relationships to Generate Dialog Box'''''<br>[[Image:choose.gif|Choose Relationships to Generate Dialog Box]]<br><br>
</li>
<li>
Select an entry from '''Potential Relationships''' and click the '''1:1 Mapping''' [[Image:onetoone_map_btn.gif|One to One mapping button]] or '''1:M Mapping'''  [[Image:onetomany_map_btn.gif|One to Many mapping button]] button, located between the Potential Relationships and Selected Relationships windows. See [[Introduction%20to%20Relational%20Mappings%20(ELUG)#CHDCBEDB|Introduction to Relational Mappings]] for more information on mappings.
<br>
You can also specify whether the relationships are bidirectional. See [[Configuring%20a%20Mapping%20(ELUG)#Configuring Bidirectional Relationship|Configuring Bidirectional Relationship]] for more information.
</li>
<li>Click '''OK''' to automatically create the relationships.</li>
</ol>
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:


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note''': You must log in the database before creating tables. See [[Configuring%20a%20Relational%20Project%20(ELUG)#Logging In to the Database|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 Tables''' or '''All Tables''' from the context menu.<br>You can also create tables by selecting '''Selected''' > '''Create on Database''' > '''Selected Tables''' or '''All Tables''' from the menu.

Workbench creates the tables on the database.

Alternatively, you can generate tables at run time by exporting the information in Workbench to a <tt>TableCreator</tt> class (see [[Using%20the%20Schema%20Manager%20(ELUG)#Introduction to the Schema Manager|Introduction to the Schema Manager]]).

==Using XML Schemas==
For XML and EIS projects, Workbench maps each EclipseLink descriptor to your XML schema.

This section includes information on the following topics:
* [[#How to Use XML Schemas in the Navigator|How to Use XML Schemas in the Navigator]]
* [[#How to Use an XML Schema Structure|How to Use an XML Schema Structure]]
* [[#How to Import an XML Schema|How to Import an XML Schema]]
* [[#How to Configure an XML Schema Reference|How to Configure an XML Schema Reference]]
* [[#How to Configure XML Schema Namespace|How to Configure XML Schema Namespace]]


===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|How to Import an XML Schema]]) and you expand the schema object in the '''Navigator''', Workbench displays the schemas associated with the project.

<span id="Figure 4-29"></span>
''''' Sample XML Schemas'''''

[[Image:navschem.gif|Sample XML Schemas]]<br><br>

The following numbered callouts identify the following schema icons:
# Project
# Schemas object
# Specific schema

For more information, see the following:
* [[#How to Use an XML Schema Structure|How to Use an XML Schema Structure]]
* [[#How to Configure an XML Schema Reference|How to Configure an XML Schema Reference]]
* [[#How to Configure XML Schema Namespace|How to Configure XML Schema Namespace]]


===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.<br><span id="Figure 4-30"></span>''''' Schema Structure Tab'''''<br>[[Image:schstruc.gif|Schema Structure Tab]]<br><br>
# Review the fields on the '''Schema Structure''' tab.

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


{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the Schema Structure dialog." summary="This table identifies each field on the Schema Structure dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t24" align="left" valign="bottom" | '''Field'''
! id="r1c2-t24" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t24" headers="r1c1-t24" align="left" | '''Schema Structure'''
| headers="r2c1-t24 r1c2-t24" align="left" | Displays the elements of the schema, listed in alphabetical order, in an expandable or collapsible tree structure.
|- align="left" valign="top"
| id="r3c1-t24" headers="r1c1-t24" align="left" | '''Details'''
| headers="r3c1-t24 r1c2-t24" align="left" | Displays detailed information (such as name and type) for the currently selected element in the '''Schema Structure''' area.
|}

<br>

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|How to Configure an XML Schema Reference]]) if necessary.

After importing an XML schema, you can configure XML schema namespaces (see [[#How to Configure XML Schema Namespace|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.'''''<br><span id="Figure 4-31"></span> Import Schema Dialog Box'''''<br>[[Image:schema.gif|Import Schema Dialog Box]]<br><br>
# Fill the Import Schema dialog box with data, and then click '''OK'''. Workbench will add the schema to the project.


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

{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the Import Schema dialog." summary="This table identifies each field on the Import Schema dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t25" align="left" valign="bottom" | '''Field'''
! id="r1c2-t25" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t25" headers="r1c1-t25" align="left" | '''Name'''
| headers="r2c1-t25 r1c2-t25" align="left" | Specify the name of this schema. This is the display name that Workbench uses. It can be different than the name you specify when you configure '''Source'''.
|- align="left" valign="top"
| id="r3c1-t25" headers="r1c1-t25" align="left" | '''Source'''
| headers="r3c1-t25 r1c2-t25" align="left" | Select how Workbench should import the schema.
|- align="left" valign="top"
| id="r4c1-t25" headers="r1c1-t25" align="left" | '''File'''
| headers="r4c1-t25 r1c2-t25" align="left" |
Specify that Workbench should import the schema from a file. Enter the fully qualified directory path and filename of the schema file.
|- align="left" valign="top"
| id="r5c1-t25" headers="r1c1-t25" align="left" | '''URL'''
| headers="r5c1-t25 r1c2-t25" align="left" |
Specify that 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 [[#How to Use General Preferences|How to Use General Preferences]] for more information.
|- align="left" valign="top"
| id="r6c1-t25" headers="r1c1-t25" align="left" | '''Classpath'''
| headers="r6c1-t25 r1c2-t25" align="left" | Specify that Workbench should import the schema from the project classpath.
|- align="left" valign="top"
| id="r7c1-t25" headers="r1c1-t25" align="left" | '''Resource Name'''
| headers="r7c1-t25 r1c2-t25" align="left" |
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 <tt>mySchema.xsd</tt> is in <tt>C:\project\config</tt> and you add this directory to your project classpath (see [[Configuring%20a%20Project%20(ELUG)#Table 113-4|Project Support for Project Classpath]]), specify a resource name of <tt>project.config.mySchema.xsd</tt>.
|}

<br>

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.


===How to Configure an XML Schema Reference===
After you import an XML schema (see [[#How to Import an XML Schema|How to Import an XML Schema]]), you can update its source by configuring the schema reference.


====How to Configure an XML Schema Reference Using Workbench====
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.<br><span id="Figure 4-32"></span>''''' Schema Document Info Tab – Source Field'''''<br>[[Image:schsrc.gif|Schema Document Info Tab – Source Field]]<br><br>
# Click '''Edit''' to select a new source for the selected schema. The Schema Properties dialog box appears.<br><span id="Figure 4-33"></span>''''' Schema Properties Dialog Box'''''<br>[[Image:schemapr.gif|Schema Properties Dialog Box]]<br><br>

Complete the '''Schema Properties''' dialog box and click '''OK'''. Workbench adds the schema to the project.

Use the following information to complete each field in the Schema Properties dialog box:


{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the Schema Properties dialog." summary="This table identifies each field on the Schema Properties dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t26" align="left" valign="bottom" | '''Field'''
! id="r1c2-t26" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t26" headers="r1c1-t26" align="left" | '''Name'''
| headers="r2c1-t26 r1c2-t26" align="left" | Specify the name of this schema. This is the display name that Workbench uses. It can be different than the name you specify when you configure '''Source'''.
|- align="left" valign="top"
| id="r3c1-t26" headers="r1c1-t26" align="left" | '''Source'''
| headers="r3c1-t26 r1c2-t26" align="left" | Select how Workbench should import the schema.
|- align="left" valign="top"
| id="r4c1-t26" headers="r1c1-t26" align="left" | '''File'''
| headers="r4c1-t26 r1c2-t26" align="left" |
Specify that Workbench should import the schema from a file. Enter the fully qualified directory path and filename of the schema file.
|- align="left" valign="top"
| id="r5c1-t26" headers="r1c1-t26" align="left" | '''URL'''
| headers="r5c1-t26 r1c2-t26" align="left" |
Specify that Workbench should import the schema using a URL. 

Enter the complete URL of the schema file.

'''Note'''<nowiki>: When importing schemas by URL, ensure you have set your proxy information correctly. See </nowiki>[[#How to Use General Preferences|How to Use General Preferences]] for more information.
|- align="left" valign="top"
| id="r6c1-t26" headers="r1c1-t26" align="left" | '''Classpath'''
| headers="r6c1-t26 r1c2-t26" align="left" | Specify that Workbench should import the schema from the project classpath.
|- align="left" valign="top"
| id="r7c1-t26" headers="r1c1-t26" align="left" | '''Resource Name'''
| headers="r7c1-t26 r1c2-t26" align="left" |
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 <tt>C:\project\config</tt> and you add this directory to your project classpath (see [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|Configuring Project Classpath]], specify a resource name of <tt>project.config.mySchema.xsd</tt>.
|}


====How to Configure an XML Schema Reference Using Java====
Use Java to configure schema reference. Create a descriptor amendment method (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Amendment Methods|Configuring Amendment Methods]]) that instantiates the appropriate type of <tt>XMLSchemaReference</tt> (<tt>XMLSchemaClassPathReference</tt>, <tt>XMLSchemaFileReference</tt>, or <tt>XMLSchemaURLReference</tt>) and configures the descriptor with it, as follows:
* If you are using <tt>EISDescriptors</tt>, the EclipseLink runtime does not use the schema reference; no further configuration is required.
* If you are using <tt>XMLDescriptors</tt>, configure the descriptor with the <tt>XMLSchemaReference</tt> using <tt>XMLDescriptor</tt> method <tt>setSchemaReference</tt>.


===How to Configure XML Schema Namespace===
As defined in <tt>http://www.w3.org/TR/REC-xml-names/</tt>, 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 [[#How to Import an XML Schema|How to Import an XML Schema]]) such as the one that the [[#Example 4-3|XML Schema with Namespace Options example]] shows, Workbench organizes the various namespaces that the XML schema identifies, as [[#Table 4-3|the Workbench XML Schema Categories table]] shows.

<br>
<span id="Example 4-3"></span>
''''' XML Schema with Namespace Options'''''
 <xsd:schema
     xmlns:<prefix>="<URI>"             &lt;! –  Workbench Built-in Namespace  – >
     targetNamespace="<URI>"            &lt;! –  Workbench Target Namespace  – >
 
     elementFormDefault="qualified"
     attributeFormDefault="unqualified"
     version="10.1.3">
     <xsd:import                        &lt;! –  Workbench Imported Namespace  – >
         namespace="http://xmlns.oracle.com/ias/xsds/opm"
         schemaLocation="object-persistence_1_0.xsd"
     />
 ...
 </xsd:schema>


<span id="Table 4-3"></span>
''''' Workbench XML Schema Categories'''''

{| class="HRuleFormalMax" dir="ltr" title="Workbench XML Schema Categories" summary="This table summarizes how the the Workbench categorizes the various types of schema your project can use." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t27" align="left" valign="bottom" | '''Workbench Category'''
! id="r1c2-t27" align="left" valign="bottom" | '''Defined By'''
! id="r1c3-t27" align="left" valign="bottom" | '''Purpose'''
! id="r1c4-t27" align="left" valign="bottom" | '''When Needed'''
|- align="left" valign="top"
| id="r2c1-t27" headers="r1c1-t27" align="left" |
Built-in
| headers="r2c1-t27 r1c2-t27" align="left" |
<tt>xmlns:<prefix>="<URI>"</tt>
| headers="r2c1-t27 r1c3-t27" align="left" |
Provides access to types defined in other XML schemas for use as is.
| headers="r2c1-t27 r1c4-t27" align="left" |
If your project uses more than one XML schema or if you want to use <tt>xsi</tt> or <tt>xsd</tt> types.
|- align="left" valign="top"
| id="r3c1-t27" headers="r1c1-t27" align="left" |
Target
| headers="r3c1-t27 r1c2-t27" align="left" |
<tt>targetNamespace="<URI>"</tt>
| headers="r3c1-t27 r1c3-t27" align="left" |
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.
| headers="r3c1-t27 r1c4-t27" align="left" |
You may need to specify a target namespace depending on how element and attribute form options are set (see [[Introduction%20to%20Projects (ELUG)#Element and Attribute Form Options|Element and Attribute Form Options]]).
|- align="left" valign="top"
| id="r4c1-t27" headers="r1c1-t27" align="left" |
Imported
| headers="r4c1-t27 r1c2-t27" align="left" |
<tt>xsd:import</tt>
| headers="r4c1-t27 r1c3-t27" align="left" |
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.
| headers="r4c1-t27 r1c4-t27" align="left" |
If your project uses more than one XML schema and you want to extend one or more built-in types.
|}

<br>

For more information, see [[Introduction%20to%20Projects (ELUG)#XML Namespaces Overview|XML Namespaces Overview]].


====How to Configure XML Schema Namespace Using Workbench====
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.<br><span id="Figure 4-34"></span>''''' Schema Document Info Tab – Namespaces Field'''''<br>[[Image:schnmsp.gif|Schema Document Info Tab – Namespaces Field]]<br><br>
# Complete the Namespaces fields on the Schema Document Info tab.


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

{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the Schema Document Info dialog." summary="This table identifies each field on the Schema Document Info dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t28" align="left" valign="bottom" | '''Field'''
! id="r1c2-t28" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t28" headers="r1c1-t28" align="left" | '''Built-in Namespaces'''
| headers="r2c1-t28 r1c2-t28" align="left" |
All namespaces defined by <tt>xmlns:<prefix>="<URI>"</tt>. 

Note that when a schema is imported to the Workbench (see [[#How to Import an XML Schema|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 <tt>xsi</tt> prefix. Otherwise, EclipseLink will throw exceptions.
|- align="left" valign="top"
| id="r3c1-t28" headers="r1c1-t28" align="left" | '''Target Namespaces'''
| headers="r3c1-t28 r1c2-t28" align="left" | All namespaces defined by <tt>targetNamespace="<URI>"</tt>.
|- align="left" valign="top"
| id="r4c1-t28" headers="r1c1-t28" align="left" | '''Imported Namespaces'''
| headers="r4c1-t28 r1c2-t28" align="left" | All namespaces defined by <tt>xsd:import</tt>.
|- align="left" valign="top"
| id="r5c1-t28" headers="r1c1-t28" align="left" | '''Prefix'''
| headers="r5c1-t28 r1c2-t28" align="left" |
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 [[Introduction%20to%20Projects (ELUG)#EclipseLink Runtime Namespace Resolution|EclipseLink Runtime Namespace Resolution]].
|- align="left" valign="top"
| id="r6c1-t28" headers="r1c1-t28" align="left" | '''Declare'''
| headers="r6c1-t28 r1c2-t28" align="left" |
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 [[Introduction%20to%20Projects (ELUG)#EclipseLink Runtime Namespace Resolution|EclipseLink Runtime Namespace Resolution]].
|}


====How to Configure XML Schema Namespace Using Java====
Using Java, to configure XML schema namespaces for an EIS descriptor (with XML records) or an XML descriptor, create a descriptor amendment method (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Amendment Methods|Configuring Amendment Methods]]) that uses <tt>EISDescriptor</tt> or <tt>XMLDescriptor</tt> method <tt>getNamespaceResolver</tt> to configure the descriptor's <tt>NamespaceResolver</tt> accordingly, as this example shows.

<br>
<span id="Example 4-4"></span>
''''' Configuring Namespaces'''''
 public void addToDescriptor(ClassDescriptor descriptor) {
     descriptor.getNamespaceResolver.put(
         prefix,
         namespaceURI
     );
 }



==Using Classes==
Using Workbench, you can create Java classes and packages. This section includes information on the following:
* [[#How to Create Classes|How to Create Classes]]
* [[#How to Configure Classes|How to Configure Classes]]
* [[#How to Import and Update Classes|How to Import and Update Classes]]
* [[#How to Manage Nondescriptor Classes|How to Manage Nondescriptor Classes]]
* [[#How to Rename Packages|How to Rename Packages]]


===How to Create Classes===
We recommend that you develop your Java classes using an IDE such as Eclipse and import these existing classes into Workbench (see [[#How to Import and Update Classes|How to Import and Update Classes]])

However, it is sometimes convenient to create and configure classes in Workbench: for example, when generating an object model from a database schema.

This section includes information on using Workbench to create Java classes.

For more information on using Workbench to edit classes, see [[#How to Create Classes|How to Create Classes]].


====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''' [[Image:creatcls.gif|Create New Class button]].<br>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.<br><span id="Figure 4-35"></span>''''' Add Class Dialog Box'''''<br>[[Image:addclass.gif|Add Class Dialog Box]]<br><br>
# 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:
{| class="HRuleInformal" dir="ltr" title="This table describes each field on the Add Class dialog." summary="This table describes each field on the Add Class dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t29" align="left" valign="bottom" | '''Field'''
! id="r1c2-t29" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t29" headers="r1c1-t29" align="left" | '''Package Name'''
| headers="r2c1-t29 r1c2-t29" align="left" | Choose an existing package or enter a new package name. If blank, Workbench uses the default package name.
|- align="left" valign="top"
| id="r3c1-t29" headers="r1c1-t29" align="left" | '''New Class Name'''
| headers="r3c1-t29 r1c2-t29" align="left" | Enter a class name. The '''New Class Name''' must be unique within the package.
|}


For more information on using Workbench to edit classes, see [[#How to Configure Classes|How to Configure Classes]].

===How to Configure Classes===
We recommend that you develop your Java classes using an IDE such as Eclipse and import these existing classes into Workbench (see [[#How to Import and Update Classes|How to Import and Update Classes]])

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

This section describes using Workbench to edit classes, including the following:
* [[#Configuring Class Information|Configuring Class Information]]
* [[#Configuring Class Modifiers|Configuring Class Modifiers]]
* [[#Configuring Class Interfaces|Configuring Class Interfaces]]
* [[#Adding Attributes|Adding Attributes]]
* [[#Configuring Attribute Modifiers|Configuring Attribute Modifiers]]
* [[#Configuring Attribute Type Declaration|Configuring Attribute Type Declaration]]
* [[#Configuring Attribute Accessing Methods|Configuring Attribute Accessing Methods]]
* [[#Adding Methods|Adding Methods]]
* [[#Configuring Method Modifiers|Configuring Method Modifiers]]
* [[#Configuring Method Return Type|Configuring Method Return Type]]
* [[#Configuring Method Parameters|Configuring Method Parameters]]


====Configuring Class Information====
This section includes information on using the workbench to configure class information.


=====Using Workbench=====
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'''.
# Click the '''Class''' tab.<br><span id="Figure 4-36"></span>''''' Class Tab, Class Information Fields'''''<br>[[Image:classinfo.gif|Class Tab, Class Information Fields]]<br><br>
# Complete the class information fields on the Class Info tab.

Use the following information to enter data in each field on the tab:

{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the Class Info tab." summary="This table identifies each field on the Class Info tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t30" align="left" valign="bottom" | '''Field'''
! id="r1c2-t30" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t30" headers="r1c1-t30" align="left" | '''Name'''
| headers="r2c1-t30 r1c2-t30" align="left" | The name of the class. This field is for display only.
|- align="left" valign="top"
| id="r3c1-t30" headers="r1c1-t30" align="left" | '''Superclass'''
| headers="r3c1-t30 r1c2-t30" align="left" | Click '''Browse''' and select a class and package that contains the class (that is, the superclass).
|}


====Configuring Class Modifiers====
This section includes information on using the workbench to configure class modifiers.


=====Using Workbench=====
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'''.
# Click the '''Class''' tab.<span id="Figure 4-37"></span><br>''''' Class Tab, Class Modifiers Fields'''''<br>[[Image:clclmodi.gif|Class Tab, Class Modifiers Fields]]<br><br>
# Complete the Modifiers fields on the Class tab.


Use the following information to enter data in each field on the tab:

{| class="HRuleInformal" dir="ltr" title="This table identifies Modifiers fields on the Class Info tab." summary="This table identifies Modifiers fields on the Class Info tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t31" align="left" valign="bottom" | '''Field'''
! id="r1c2-t31" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t31" headers="r1c1-t31" align="left" | '''Access Modifiers'''
| headers="r2c1-t31 r1c2-t31" align="left" |
Use to specify whether the class is accessible publicly or not. Only public classes are visible to the Workbench.
|- align="left" valign="top"
| id="r3c1-t31" headers="r1c1-t31" align="left" | '''Other Modifiers'''
| headers="r3c1-t31 r1c2-t31" align="left" | 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.
|}


====Configuring Class Interfaces====
This section includes information on using the workbnech to specify the interfaces implemented by a class. You can choose any interface in the Workbench classpath (see [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|Configuring Project Classpath]]).

Although you may add interfaces to a project directly (see [[#How to Import and Update Classes|How to Import and Update Classes]]), you do not need to do so in order to configure a class to implement an interface.


=====Using Workbench=====
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'''.
# Click the '''Class''' tab.<br><span id="Figure 4-38"></span>''''' Class Tab, Interfaces Implemented Fields'''''<br>[[Image:clclintr.gif|Class Tab, Interfaces Implemented Fields]]<br><br>
# Complete the Iterfaces Implemented field on the tab.


Use the following information to enter data in the Interfaces Implemented field on the Class tab:

{| class="HRuleInformal" dir="ltr" title="This table identifies Interfaces Implemented field on the Class tab." summary="This table identifies Interfaces Implemented field on the Class tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t32" align="left" valign="bottom" | '''Field'''
! id="r1c2-t32" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t32" headers="r1c1-t32" align="left" | '''Interfaces Implemented'''
| headers="r2c1-t32 r1c2-t32" align="left" |
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'''.
|}

====Adding Attributes====
This section includes information on using the workbench to add an attribute to a class.


=====Using Workbench=====
* 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

====Configuring Attribute Modifiers====
This section includes information on using the workbench to configure attribute modifiers.


=====Using Workbench=====
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.<br><span id="Figure 4-39"></span>''''' Attributes Tab, Modifiers Fields'''''<br>[[Image:clatgenmod.gif|Attributes Tab, Modifiers Fields]]<br><br>
# Complete the Modifiers fields on the Attributes tab.


Use the following information to enter data in the Modifiers fields on the Attributes tab:
{| class="HRuleInformal" dir="ltr" title="This table identifies Modifiers fields on the Attributes tab." summary="This table identifies Modifiers fields on the Attributes tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t33" align="left" valign="bottom" | '''Field'''
! id="r1c2-t33" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t33" headers="r1c1-t33" align="left" | <br>'''Access Modifiers'''
| headers="r2c1-t33 r1c2-t33" align="left" |
Specify how the attribute is accessible:
* [[Image:attpub.gif|Public icon]]'''Public'''
* [[Image:attpro.gif|Protected icon]]'''Protected – '''only visible within its own package and subclasses.
* [[Image:attpri.gif|Private icon]]'''Private''' – not visible for subclasses
* [[Image:attdef.gif|Default icon]]'''Default''' – only visible within its own package
|- align="left" valign="top"
| id="r3c1-t33" headers="r1c1-t33" align="left" | <br>'''Other Modifiers'''
| headers="r3c1-t33 r1c2-t33" align="left" |
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.<br><span id="Figure 4-40"></span>''''' Attributes Tab, Type Declaration Fields'''''<br>[[Image:clatgentyp.gif|Attributes Tab, Type Declaration Fields]]<br><br>
# Complete the Type Declaration fields on the Attributes tab.


Use the following information to enter data in Type Declaration fields on the Attributes tab:
{| class="HRuleInformal" dir="ltr" title="This table identifies Type Declaration fields on the Attributes tab" summary="This table identifies Type Declaration fields on the Attributes tab" width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t34" align="left" valign="bottom" | '''Field'''
! id="r1c2-t34" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t34" headers="r1c1-t34" align="left" | '''Type'''
| headers="r2c1-t34 r1c2-t34" align="left" | Click '''Browse''' and select a class and package for the attribute.
|- align="left" valign="top"
| id="r3c1-t34" headers="r1c1-t34" align="left" | '''Dimensionality'''
| headers="r3c1-t34 r1c2-t34" align="left" | Specify the length of an array. This field applies only if '''Type''' is an array.
|- align="left" valign="top"
| id="r4c1-t34" headers="r1c1-t34" align="left" | '''Value Type'''
| headers="r4c1-t34 r1c2-t34" align="left" |
Click '''Browse''' and select a class and package for the attribute. This field applies for <tt>ValueHolderInterface</tt> types only.
|- align="left" valign="top"
| id="r5c1-t34" headers="r1c1-t34" align="left" | '''Map Key Type'''
| headers="r5c1-t34 r1c2-t34" align="left" |
Click '''Browse''' and select a class and package for the attribute. This field applies for <tt>Map</tt> types only.
|- align="left" valign="top"
| id="r6c1-t34" headers="r1c1-t34" align="left" | '''Map Value Type'''
| headers="r6c1-t34 r1c2-t34" align="left" |
Click '''Browse''' and select a class and package for the attribute. This field applies for <tt>Map</tt> types only.
|- align="left" valign="top"
| id="r7c1-t34" headers="r1c1-t34" align="left" | '''Element Type'''
| headers="r7c1-t34 r1c2-t34" align="left" |
Click '''Browse''' and select a class and package for the attribute. This field applies for <tt>List</tt> 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.


=====Using Workbench=====
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.<br><span id="Figure 4-41"></span>''''' Attributes Tab, Accessors Fields'''''<br>[[Image:clataccs.gif|Attributes Tab, Accessors Fields]]<br><br>
# Complete the Accessors fields on the Attributes tab. Click '''Generate Methods''' to automatically create the required method.

Use the following information to complete the Accessors fields on the Attributes tab:
{| class="HRuleInformal" dir="ltr" title="This table identifies Accessors fields on the Attributes tab." summary="This table identifies Accessors fields on the Attributes tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t35" align="left" valign="bottom" | '''Field'''
! id="r1c2-t35" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t35" headers="r1c1-t35" align="left" | '''Get Method'''
| headers="r2c1-t35 r1c2-t35" align="left" |
Choose the <tt>get</tt> method for the attribute. This field applies for non-<tt>Collection</tt> types only.
|- align="left" valign="top"
| id="r3c1-t35" headers="r1c1-t35" align="left" | '''Set Method'''
| headers="r3c1-t35 r1c2-t35" align="left" |
Choose the <tt>set</tt> method for the attribute. This field applies for non-<tt>Collection</tt> types only.
|- align="left" valign="top"
| id="r4c1-t35" headers="r1c1-t35" align="left" | '''Add Method'''
| headers="r4c1-t35 r1c2-t35" align="left" |
Choose the <tt>add</tt> method for the attribute. This field applies for <tt>List</tt> and <tt>Map</tt> types only.
|- align="left" valign="top"
| id="r5c1-t35" headers="r1c1-t35" align="left" | '''Remove Method'''
| headers="r5c1-t35 r1c2-t35" align="left" |
Choose the <tt>remove</tt> method for the attribute. This field applies for <tt>List</tt> and <tt>Map</tt> types only.
|- align="left" valign="top"
| id="r6c1-t35" headers="r1c1-t35" align="left" | '''Value Holder Get Method'''
| headers="r6c1-t35 r1c2-t35" align="left" |
Choose the method used to return the <tt>ValueHolderInterface</tt> type. This field applies for <tt>ValueHolderInterface</tt> types only.
|- align="left" valign="top"
| id="r7c1-t35" headers="r1c1-t35" align="left" | '''Value Holder Set Method'''
| headers="r7c1-t35 r1c2-t35" align="left" |
Choose the method used to set the <tt>ValueHolderInterface</tt> type. This field applies for <tt>ValueHolderInterface</tt> types only.
|- align="left" valign="top"
| id="r8c1-t35" headers="r1c1-t35" align="left" | '''Value Get Method'''
| headers="r8c1-t35 r1c2-t35" align="left" |
Choose the method used to return the actual value. This field applies for <tt>ValueHolderInterface</tt> types only.
|- align="left" valign="top"
| id="r9c1-t35" headers="r1c1-t35" align="left" | '''Value Set Method'''
| headers="r9c1-t35 r1c2-t35" align="left" |
Choose the method used to set the actual value. This field applies for <tt>ValueHolderInterface</tt> types only.
|}


====Adding Methods====
This section includes information on the workbench to add a method to a class.


=====Using Workbench=====
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.<span id="Figure 4-42"></span><br>''''' Class Info – Methods Tab'''''<br>[[Image:clmethod.gif|Class Info – Methods Tab]]<br><br>

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'''.


====Configuring Method Modifiers====
This section includes information on using the workbench to configure method modifiers.


=====Using Workbench=====
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.<br><span id="Figure 4-43"></span>''''' Methods Tab, Modifiers Fields'''''<br>[[Image:clmemod.gif|DMethods Tab, Modifiers Fields]]<br><br>
# Complete the Modifiers fields on the Methods tab.

Use the following information to enter data in Modifiers fields on the Methods tab:
{| class="HRuleInformal" dir="ltr" title="This table identifies Modifiers fields on the Methods tab." summary="This table identifies Modifiers fields on the Methods tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t36" align="left" valign="bottom" | '''Field'''
! id="r1c2-t36" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t36" headers="r1c1-t36" align="left" | <br>'''Access Modifiers'''
| headers="r2c1-t36 r1c2-t36" align="left" |
Specify how the method can be accessed:
* [[Image:metpub.gif|Public icon]]'''Public'''
* [[Image:metpro.gif|Protected icon]]'''Protected''' – only visible within its own package and subclasses.
* [[Image:metpri.gif|Private icon]]'''Private''' – not visible for subclasses.
* [[Image:metdef.gif|Default icon]]'''Default''' – only visible within its own package.
|- align="left" valign="top"
| id="r3c1-t36" headers="r1c1-t36" align="left" | <br>'''Other Modifiers'''
| headers="r3c1-t36 r1c2-t36" align="left" |
Specify whether the method is '''Abstract, Final''', '''Synchronized, Static''', or '''Native'''. 

Note: Selecting some modifiers may disable others.
|}


====Configuring Method Return Type====
This section includes information on using the workbench to configure method return type.


=====Using Workbench=====
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.<br><span id="Figure 4-44"></span>''''' Methods Tab, Return Type Fields'''''<br>[[Image:clmetyp.gif|Methods Tab, Return Type Fields]]<br><br>
# Complete the Return Type fields on the Methods tab.


Use the following information to enter data in Return Type fields on the Methods tab:
{| class="HRuleInformal" dir="ltr" title="This table identifies Return Type fields on the Methods tab." summary="This table identifies Return Type fields on the Methods tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t37" align="left" valign="bottom" | '''Field'''
! id="r1c2-t37" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t37" headers="r1c1-t37" align="left" |'''Type'''
| headers="r2c1-t37 r1c2-t37" align="left" | Click '''Browse''' and select a class and package for the method.
|- align="left" valign="top"
| id="r3c1-t37" headers="r1c1-t37" align="left" |'''Dimensionality'''
| headers="r3c1-t37 r1c2-t37" align="left" | Specify the length of an array. This field applies only if '''Type''' is an array.
|}

====Configuring Method Parameters====
This section includes information on using the workbench to configure method parameters.


=====Using Workbench=====
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.<br><span id="Figure 4-45"></span>''''' Methods Tab, Method Parameters Fields'''''<br>[[Image:clmeparm.gif|Methods Tab, Method Parameters Fields]]<br><br>
# Complete the Parameters fields on the Methods tab.


Use the following information to enter data in Parameters fields on the Methods tab:
{| class="HRuleInformal" dir="ltr" title="This table identifies Parameters fields on the Methods tab." summary="This table identifies Parameters fields on the Methods tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t38" align="left" valign="bottom" | '''Field'''
! id="r1c2-t38" align="left" valign="bottom" | '''Description'''
|- align="left" valign="top"
| id="r2c1-t38" headers="r1c1-t38" align="left" | '''Type'''
| headers="r2c1-t38 r1c2-t38" align="left" | Click '''Browse''' and select a class and package for the method.
|- align="left" valign="top"
| id="r3c1-t38" headers="r1c1-t38" align="left" | '''Dimensionality'''
| headers="r3c1-t38 r1c2-t38" align="left" | Specify the length of an array. This field applies only if '''Type''' is an array.
|}

===How to Import and Update Classes===
This section includes information on [[#Importing and Updating Classes Using Workbench|Importing and Updating Classes Using Workbench]] to import and update Java classes.

You can import Java classes and interfaces created in any IDE.


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note'''<nowiki>:</nowiki> You can import interfaces only in relational projects.
|}


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.

For more information, see [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|Configuring Project Classpath]].


====Importing and Updating Classes Using Workbench====
Use this procedure to update or refresh the classes in the Workbench project.

# Define the available classes and packages for the project on the '''General''' tab. See [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|Configuring Project Classpath]] for information on classes and packages.
# Click '''Add or Refresh Class''' [[Image:creatcls.gif|Add or Refresh Class button]]. The Select Classes dialog box appears.<br>You can also update the classes by choosing '''Selected''' > '''Add or Refresh Classes''' from the menu.<br><span id="Figure 4-46"></span>''''' Select Classes Dialog Box'''''<br>[[Image:select.gif|Select Classes Dialog Box]]<br><br>

Select the packages or classes (or both) to import into the project and click '''OK'''. Workbench adds the new classes to your project in the '''Navigator'''.

By default, Workbench creates the following descriptor types for each package and class (depending on your project type):
* [[Creating%20a%20Relational%20Descriptor%20(ELUG)#Creating Relational Class Descriptors|Relational projects  –  Relational class descriptors]]
* [[Creating%20an%20EIS%20Descriptor%20(ELUG)#EIS Composite Descriptors|EIS projects  –  EIS composite descriptors]]
* [[Introduction%20to%20XML%20Descriptors%20(ELUG)#Composite Descriptors in XML Projects|XML projects  –  XML descriptors]]

See [[Creating%20a%20Descriptor%20(ELUG)#Creating a Descriptor|Creating a Descriptor]] for more information.


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''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''' [[Image:remclass.gif|Remove Class button]], 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:

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 EclipseLink project icon in the '''Navigator''' and selecting '''Manage Non-Descriptor Classes''' from the context menu.


<span id="Figure 4-47"></span>
'''''Manage Non-Descriptor Classes Dialog Box'''''

[[Image:nondescriptor.gif|Manage Non-Descriptor Classes Dialog Box]]<br><br>

Select one of the following options:
* To add new classes, click '''Add'''. The Select Classes dialog box appears (see [[#Figure_4-46|the Select Classes Dialog Box]]).<br>Only classes that have been added to the [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|project's classpath]] can be added as nondescriptor classes. 
* 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'''.

===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|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.


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''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. 

For information on the EclipseLink Package Renamer, see [[EclipseLink/Examples/MigratingFromOracleTopLink|"Running the Package Renamer" in the Migration Guide]].
|}


For more information on using Workbench to edit classes, see [[#How to Configure Classes|How to Configure Classes]].


====Renaming Packages Using Workbench====
To change the package of an existing class in Workbench, use this procedure:
# Right-click the package in the '''Navigator''' and select '''Rename'''.<br>You can also select the package and choose '''Selected''' > '''Rename''' from the menu.'''<br>'''''Rename Package Dialog Box'''''<br><span id="Figure 4-48"></span>[[Image:changpkg.gif|Rename Package Dialog Box]]<br><br>
# Enter the package name on the Rename Package dialog box and click '''OK'''. Workbench will change the name of the package in the Navigator.

Enter the package name and click '''OK'''. Workbench changes the name of the package in the Navigator window.

For more information on using Workbench to edit classes, see [[#How to Configure Classes|How to Configure 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.

This section describes the following:
* [[#How to Configure Ant to Use Workbench Tasks|How to Configure Ant to Use Workbench Tasks]]
* [[#What You May Need to Know About Workbench Ant Task API|What You May Need to Know About Workbench Ant Task API]]
* [[#How to Create Workbench Ant Tasks|How to Create Workbench Ant Tasks]]

For more information about Ant, see <tt>http://ant.apache.org/manual/</tt>.


===How to Configure Ant to Use Workbench Tasks===
Before you can use Workbench tasks in your Ant build files, you must consider their library dependencies (see [[#Creating Library Dependencies|Creating Library Dependencies]]).

To declare Workbench tasks in your Ant <tt>build.xml</tt> file, declare them directly (see [[#Declaring Workbench Tasks|Declaring Workbench Tasks]]).


====Creating Library Dependencies====

In addition to the Ant library dependencies (see <tt>http://ant.apache.org/manual/installl#librarydependencies</tt>), the following table lists the EclipseLink-specific JAR files that must be in your Ant classpath.


<span id="table_4_4"></span><span id="Table 4-4"></span>
'''''Workbench Ant Task Library Dependencies'''''
{| class="RuleFormalMax" dir="ltr" title="Workbench Ant Task Library Dependencies" summary="This table lists the additional JARs that must be in your Ant classpath in order to use Workbench tasks." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
|- align="left" valign="top"
! id="r1c1-t41" align="left" valign="bottom" | '''JAR Name'''
! id="r1c2-t41" align="left" valign="bottom" | '''Needed For...'''
! id="r1c3-t41" align="left" valign="bottom" | '''Available At...'''
|- align="left" valign="top"
| id="r2c1-t41" headers="r1c1-t41" align="left" |
<tt>eclipselinkmw.jar</tt>
| headers="r2c1-t41 r1c2-t41" align="left" |
Workbench Ant task and type definitions.
| headers="r2c1-t41 r1c3-t41" align="left" |
<tt><</tt>''<tt>ECLIPSELINK_HOME</tt>''<tt>>/utils/workbench/jlib</tt>
|}

====Declaring Workbench Tasks====
After you declare the Workbench task definitions (see [[#table_4_6|the Workbench Ant Type Definitions]]) table and data definitions (see [[#table_4_4|the Workbench Ant Task Library Dependencies]]) table in the <tt>eclipselink-ant-lib.xml</tt> file (see [[#example_4_5|Declaring Workbench Ant Task and Data Types in an eclipselink-ant-lib.xml File]]) example, you can use a Workbench task in a <tt>build.xml</tt> file, as the [[#example_4_6|Specifying the eclipselink-ant-lib.xml File in the build.xml File]] example shows:

<span id="example4_5"></span>
'''''Declaring Workbench Ant Task and Data Types in an eclipselink-ant-lib.xml File'''''
 <?xml version="1.0"?>
 <antlib>
     <taskdef name="mappings.export"
         classname="org.eclipse.persistence.tools.workbench.ant.taskdefs.ExportDeploymentXMLTask" />
 
     <taskdef name="mappings.validate"
         classname="org.eclipse.persistence.tools.workbench.ant.taskdefs.MappingsValidateTask" />
 
     <taskdef name="session.validate"
         classname="org.eclipse.persistence.tools.workbench.ant.taskdefs.SessionValidateTask" />
 
  
     <typedef name="ignoreerror"
         classname="org.eclipse.persistence.tools.workbench.ant.typedefs.IgnoreError" />
 
     <typedef name="ignoreerrorset"
         classname="org.eclipse.persistence.tools.workbench.ant.typedefs.IgnoreErrorSet" />
 
     <typedef name="loginspec"
         classname="org.eclipse.persistence.tools.workbench.ant.typedefs.LoginSpec" />
 </antlib>



<span id="example_4_6"></span>
'''''Specifying the eclipselink-ant-lib.xml File in the build.xml File'''''
 <project name="MyBuild" default="validate.session" basedir="." xmlns:eclipselink="eclipselinklib">
    <typedef file = "eclipselink-ant-lib.xml" classpathref = "mw.classpath" uri = "eclipselinklib" />
    ...
 </project>


===What You May Need to Know About Workbench Ant Task API===
The following lists the Workbench Ant task definitions that EclipseLink provides.


<span id="table_4_5"><span><span id="Table 4-5"></span>
'''''Workbench Ant Task Definitions'''''
{| class="HRuleFormalMax" dir="ltr" title="Workbench Ant Task Definitions" summary="This table lists the Workbench Ant tasks available." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t42" align="left" valign="bottom" | '''Task Name'''
! id="r1c2-t42" align="left" valign="bottom" | '''EclipseLink Class'''
|- align="left" valign="top"
| id="r2c1-t42" headers="r1c1-t42" align="left" |
[[#How to Create the mappings.validate Task|mappings.validate Task]]<br>
| headers="r2c1-t42 r1c2-t42" align="left" |
<tt>org.eclipse.persistence.tools.workbench.ant.taskdefs.MappingsValidateTask</tt>
|- align="left" valign="top"
| id="r3c1-t42" headers="r1c1-t42" align="left" |
[[#How to Create the session.validate Task|session.validate Task]]<br>
| headers="r3c1-t42 r1c2-t42" align="left" |
<tt>org.eclipse.persistence.tools.workbench.ant.taskdefs.SessionValidateTask</tt>
|- align="left" valign="top"
| id="r4c1-t42" headers="r1c1-t42" align="left" |
[[#How to Create the mappings.export Task|mappings.export Task]]<br>
| headers="r4c1-t42 r1c2-t42" align="left" |
<tt>org.eclipse.persistence.tools.workbench.ant.taskdefs.ExportDeploymentXMLTask</tt>
|}

<br>

The following lists the Workbench Ant type definitions that EclipseLink provides.


<span id="table_4_6"><span><span id="Table 4-6"></span>
'''''Workbench Ant Type Definitions'''''
{| class="HRuleFormalMax" dir="ltr" title="Workbench Ant Type Definitions" summary="This table lists the Workbench Ant data types available." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t43" align="left" valign="bottom" | '''Type Name'''
! id="r1c2-t43" align="left" valign="bottom" | '''EclipseLink Class'''
|- align="left" valign="top"
| id="r2c1-t43" headers="r1c1-t43" align="left" |
[[#How to Create the ignoreerror Task|ignoreerror Task]]<br>
| headers="r2c1-t43 r1c2-t43" align="left" |
<tt>org.eclipse.persistence.tools.workbench.ant.typedefs.IgnoreError</tt>
|- align="left" valign="top"
| id="r3c1-t43" headers="r1c1-t43" align="left" |
[[#How to Create the ignoreerrorset Task|ignoreerrorset Task]]<br>
| headers="r3c1-t43 r1c2-t43" align="left" |
<tt>org.eclipse.persistence.tools.workbench.ant.typedefs.IgnoreErrorSet</tt>
|- align="left" valign="top"
| id="r4c1-t43" headers="r1c1-t43" align="left" |
[[#How to Create the loginspec Task|loginspec Task]]<br>
| headers="r4c1-t43 r1c2-t43" align="left" |
<tt>org.eclipse.persistence.tools.workbench.ant.typedefs.LoginSpec</tt>
|}


===How to Create Workbench Ant Tasks===
The following shows a typical Ant <tt>build.</tt>xml file that declares and uses the Workbench Ant task and type definitions.


<span id="Example 4-7"></span>
'''''Example Ant Build File with Workbench Ant Tasks'''''
 <project name="MyBuild" default="validate.session" basedir="." xmlns:eclipselink="eclipselinklib">
     &lt;! –  =====================================================  – >
     &lt;! –   Properties                                            – >
 
     &lt;! –  =====================================================  – >
     <target name="init">
         <property file="build.properties"/>
 
         <property name = "eclipselink.mwp.dir" value = "${basedir}/mw"/>
         <property name = "eclipselink.sessions.dir" value = "${basedir}/config"/>
         <property name = " myProject.classes" value = "${basedir}/classes "/>
 
         <path id = "database.classpath">
             <pathelement path = "${eclipselink.home}/jlib/dms.jar"/>
             <pathelement path = "${eclipselink.home}/jlib/OracleThinJDBC.jar"/>
         </path>
         <path id = "eclipselink.classpath">
             <pathelement path = "${eclipselink.home}/jlib/eclipselink.jar"/>
             <pathelement path = "${eclipselink.home}/lib/shared/11.1.1.0.0/antlr.jar"/>
         </path>
         <path id = "mw.classpath">
             <pathelement path = "${eclipselink.home}/utils/workbench/jlib/elmwcore.jar"/>
 
             <pathelement path = "${eclipselink.home}/utils/workbench/jlib/eclipselinkmw.jar"/>
         </path>
         <path id = "mwplatforms.classpath">
             <pathelement path = "${eclipselink.home}/utils/workbench/config"/>
         </path>
 
         <typedef file = "eclipselink-ant-lib.xml"
 
                  classpathref = "mw.classpath"
                  uri = "eclipselinklib" />
 
     </target>
     &lt;! –  =====================================================  – >
     &lt;! –   Define task parameter                                 – >
     &lt;! –  =====================================================  – >
     <target name="parameter.definition" depends="init">
         <eclipselink:ignoreerrorset id = "ignoreErrors">
 
         <eclipselink:ignoreerror code = "0233" />
         </eclipselink:ignoreerrorset>
 
         <eclipselink:loginspec id = "loginSpec" 
         url = "jdbc:cloudscape:stagedb;create=true"
         driverclass = "COM.cloudscape.core.JDBCDriver"
         user = "scott" 
         password="tiger" />
     </target>
     &lt;! –  ====================================================  – >
     &lt;! –   Validate the MW Project                               – >
 
     &lt;! –  =====================================================  – >
     <target name="validate.project" depends="parameter.definition">
 
         <eclipselnk:mappings.validate
             projectfile = "${eclipselink.mwp.dir}/myProject.mwp"
             reportfile = "${eclipselink.mwp.dir}/problem-reportl"
             reportformat = l"
             property = "mw-valid"
             classpathref = "mwplatforms.classpath" >
 
             <eclipselink:classpath refid = "mw.classpath" />
             <eclipselink:classpath refid = "eclipselink.classpath" />
 
             <eclipselink:ignoreerrorset refid = "ignoreErrors"/>
 
         </eclipselink:mappings.validate>
     </target>
     &lt;! –  =====================================================  – >
     &lt;! –   EclipseLink deployment descriptor XML generation          – >
 
     &lt;! –  =====================================================  – >
     <target name="export.deployment" depends="validate.project"  if="mw-valid">
 
         <eclipselink:mappings.export 
             projectfile = "${eclipselink.mwp.dir}/myProject.mwp"
             deploymentfile = "${eclipselink.sessions.dir}/sessions.xml"
             property = "export-completed"
             failonerror = "true"
             classpathref = "eclipselink.classpath">
 
             <eclipselink:classpath refid = "mw.classpath" />
             <eclipselink:classpath refid = "mwplatforms.classpath" />
 
             <eclipselink:ignoreerrorset refid = "ignoreErrors"/>
             <eclipselink:loginspec refid = "loginSpec" />
         </eclipselink:mappings.export>
     </target>
     &lt;! –  =====================================================  – >
     &lt;! –   EclipseLink Session Validate                              – >
 
     &lt;! –  =====================================================  – >
     <target name="validate.session"  depends="export.deployment" if="export-completed">
 
         <eclipselink:session.validate
             sessionsfile = "${eclipselink.sessions.dir}/sessions.xml"
             sessionname = "ThreeTierEmployee"
             property = "session-valid"
             classpathref = "eclipselink.classpath"
             classpath = "${ myProject.classes}" >
 
             <eclipselink:classpath refid = "mw.classpath" />
             <eclipselink:classpath refid = " database.classpath" />
 
             <eclipselink:loginspec refid = "loginSpec" />
         </eclipselink:session.validate>
     </target>
 <project>

===How to Create the mappings.validate Task===
The <tt>mapings.validate</tt> task is a testing task that you use to list of all the problems in a Workbench project (<tt>.mwp</tt>) file.

This task lets you do the following:
* log all the problems to a file in text orL format;
* set an Ant property to indicate that the Workbench project is valid (has no errors).


====Using Parameters====

<span id="Table 4-7"></span>
''''' mappings.validate Task Parameters'''''

{| class="HRuleFormalMax" dir="ltr" title="mappings.validate Task Parameters" summary="This table lists the attributes applicable to this task." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t44" align="left" valign="bottom" | '''Attribute'''
! id="r1c2-t44" align="left" valign="bottom" | '''Description'''
! id="r1c3-t44" align="left" valign="bottom" | '''Required'''
|- align="left" valign="top"
| id="r2c1-t44" headers="r1c1-t44" align="left" |
projectfile
| headers="r2c1-t44 r1c2-t44" align="left" |
Fully qualified Workbench projects file name (.mwp).
| headers="r2c1-t44 r1c3-t44" align="left" |
Yes
|- align="left" valign="top"
| id="r3c1-t44" headers="r1c1-t44" align="left" |
reportfile
| headers="r3c1-t44 r1c2-t44" align="left" |
Fully qualified file name to which to write the output.
| headers="r3c1-t44 r1c3-t44" align="left" |
No
|- align="left" valign="top"
| id="r4c1-t44" headers="r1c1-t44" align="left" |
reportformat
| headers="r4c1-t44 r1c2-t44" align="left" |
The format of the generated output. Must be <tt>codel</tt> or <tt>text</tt>.
| headers="r4c1-t44 r1c3-t44" align="left" |
No – default to <tt>text</tt>.
|- align="left" valign="top"
| id="r5c1-t44" headers="r1c1-t44" align="left" |
classpath
| headers="r5c1-t44 r1c2-t44" align="left" |
Project classpath.
| headers="r5c1-t44 r1c3-t44" align="left" |
No
|- align="left" valign="top"
| id="r6c1-t44" headers="r1c1-t44" align="left" |
classpathref
| headers="r6c1-t44 r1c2-t44" align="left" |
Reference to a path defined elsewhere.
| headers="r6c1-t44 r1c3-t44" align="left" |
No
|- align="left" valign="top"
| id="r7c1-t44" headers="r1c1-t44" align="left" |
property
| headers="r7c1-t44 r1c2-t44" align="left" |
The name of the property to set (true if there is no problem).
| headers="r7c1-t44 r1c3-t44" align="left" |
No
|}


====Specifying Parameters Specified as Nested Elements====
You can specify the following parameters as nested elements of this task:
* classpath
* [[#How to Create the ignoreerror Task|ignoreerror]]
* [[#How to Create the ignoreerrorset Task|ignorerrorset]]


====Examples====
The following shows a typical <tt>mappings.validate</tt> task.

<br>
<span id="Example 4-8"></span>
''''' A mappings.validate Task'''''
 <eclipselink:mappings.validate
     projectfile = "${eclipselink.mwp.dir}/myProject.mwp"
     reportfile = "${eclipselink.mwp.dir}/problem-reportl"
     reportformat = l"
     property = "mw-valid"
     classpath = "${mwplatforms.classpath}" >
 
     <eclipselink:classpath refid = "mw.classpath" />
     <eclipselink:classpath refid = "eclipselink.classpath" />
 
     <eclipselink:ignoreerrorset refid = "ignoreErrors"/>
     <eclipselink:ignoreerror code = "0555" />
 
 </eclipselink:mappings.validate>


===How to Create the session.validate Task===
The <tt>session.validate</tt> task is a testing task that you use to test your EclipseLink deployment XML by running EclipseLink.

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 Workbench project is valid (has no errors).


====Using Parameters====

<span id="Table 4-8"></span>
''''' session.validate Task Parameters'''''

{| class="HRuleFormalMax" dir="ltr" title="session.validate Task Parameters" summary="This table lists the attributes applicable to this task." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t45" align="left" valign="bottom" | '''Attribute'''
! id="r1c2-t45" align="left" valign="bottom" | '''Description'''
! id="r1c3-t45" align="left" valign="bottom" | '''Required'''
|- align="left" valign="top"
| id="r2c1-t45" headers="r1c1-t45" align="left" |
sessionsfile
| headers="r2c1-t45 r1c2-t45" align="left" |
Fully qualified <tt>sessions.xml</tt> file.
| headers="r2c1-t45 r1c3-t45" align="left" |
No – default to <tt>sessions.xml</tt> and to classpath.
|- align="left" valign="top"
| id="r3c1-t45" headers="r1c1-t45" align="left" |
sessionname
| headers="r3c1-t45 r1c2-t45" align="left" |
Name of the session to test.
| headers="r3c1-t45 r1c3-t45" align="left" |
Yes
|- align="left" valign="top"
| id="r4c1-t45" headers="r1c1-t45" align="left" |
classpath
| headers="r4c1-t45 r1c2-t45" align="left" |
Project classpath.
| headers="r4c1-t45 r1c3-t45" align="left" |
No
|- align="left" valign="top"
| id="r5c1-t45" headers="r1c1-t45" align="left" |
classpathref
| headers="r5c1-t45 r1c2-t45" align="left" |
Reference to a path defined elsewhere.
| headers="r5c1-t45 r1c3-t45" align="left" |
No
|- align="left" valign="top"
| id="r6c1-t45" headers="r1c1-t45" align="left" |
property
| headers="r6c1-t45 r1c2-t45" align="left" |
The name of the property to set (true if valid).
| headers="r6c1-t45 r1c3-t45" align="left" |
No
|}


====Specifying Parameters Specified as Nested Elements====
You can specify the following parameters as nested elements of this task:
* classpath;
* [[#How to Create the loginspec Task|loginspec]].


====Examples====
The following shows a typical <tt>session.validate</tt> task.


<span id="Example 4-9"></span>
''''' A session.validate Task'''''
 <eclipselink:session.validate      
     sessionsfile = "${eclipselink.sessions.dir}/sessions.xml"
     sessionname = "ThreeTierEmployee"
     property = "session-valid"
     classpathref = "eclipselink.classpath"
     classpath = "${ myProject.classes}" >
 
     <eclipselink:classpath refid = "mw.classpath" />
     <eclipselink:classpath refid = " database.classpath" />
 
     <eclipselink:loginspec refid = "loginSpec" />
 
 </eclipselink:session.validate>


===How to Create the mappings.export Task===
The <tt>mappings.export</tt> task is a generation task that you use to generate an EclipseLink deployment XML file for a given Workbench project (<tt>.mwp</tt>). The <tt>mappings.export</tt> task executes a [[#How to Create the mappings.validate Task|H<tt>mappings.validate</tt> task]] before executing. A <tt>BuildException</tt> is thrown if validation fails.

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


====Using Parameters====

<span id="Table 4-9"></span>
''''' mappings.export Task Parameters'''''

{| class="HRuleFormalMax" dir="ltr" title="mappings.export Task Parameters" summary="This table lists the attributes applicable to this task." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t46" align="left" valign="bottom" | '''Attribute'''
! id="r1c2-t46" align="left" valign="bottom" | '''Description'''
! id="r1c3-t46" align="left" valign="bottom" | '''Required'''
|- align="left" valign="top"
| id="r2c1-t46" headers="r1c1-t46" align="left" |
projectfile
| headers="r2c1-t46 r1c2-t46" align="left" |
Fully qualified Workbench projects file name (<tt>.mwp</tt>).
| headers="r2c1-t46 r1c3-t46" align="left" |
Yes
|- align="left" valign="top"
| id="r3c1-t46" headers="r1c1-t46" align="left" |
deploymentfile
| headers="r3c1-t46 r1c2-t46" align="left" |
Fully qualified EclipseLink project deployment file name (<tt>.xml</tt>).
| headers="r3c1-t46 r1c3-t46" align="left" |
No – default to the name specified in the Workbench project (<tt>.mwp</tt>).
|- align="left" valign="top"
| id="r4c1-t46" headers="r1c1-t46" align="left" |
ejbjarxmldir
| headers="r4c1-t46 r1c2-t46" align="left" |
The directory that contains the <tt>ejb-jar.xml</tt> file (only applicable to Java EE project).
| headers="r4c1-t46 r1c3-t46" align="left" |
No – default to the directory specified in the Workbench project (<tt>.mwp</tt>).
|- align="left" valign="top"
| id="r5c1-t46" headers="r1c1-t46" align="left" |
classpath
| headers="r5c1-t46 r1c2-t46" align="left" |
Project classpath.
| headers="r5c1-t46 r1c3-t46" align="left" |
No
|- align="left" valign="top"
| id="r6c1-t46" headers="r1c1-t46" align="left" |
classpathref
| headers="r6c1-t46 r1c2-t46" align="left" |
Reference to a path defined elsewhere.
| headers="r6c1-t46 r1c3-t46" align="left" |
No
|- align="left" valign="top"
| id="r7c1-t46" headers="r1c1-t46" align="left" |
failonerror
| headers="r7c1-t46 r1c2-t46" align="left" |
Indicates whether the build will continue even if there are export errors; defaults to <tt>true</tt>.
| headers="r7c1-t46 r1c3-t46" align="left" |
No
|- align="left" valign="top"
| id="r8c1-t46" headers="r1c1-t46" align="left" |
property
| headers="r8c1-t46 r1c2-t46" align="left" |
The name of the property to set (<tt>true</tt> if export completed successfully).
| headers="r8c1-t46 r1c3-t46" align="left" |
No
|}


====Specifying Parameters Specified as Nested Elements====

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

* classpath;
* [[#How to Create the loginspec Task|loginspec]];
* [[#How to Create the ignoreerrorTask|ignorerror]];
* [[#How to Create the ignoreerrorset Task|ignorerrorset]].


====Examples====
The following example shows a typical <tt>mappings.export</tt> task.

<br>
<span id="Example 4-10"></span>
''''' A mappings.export Task'''''
 <eclipselink:mappings.export 
     projectfile = "${eclipselink.mwp.dir}/myProject.mwp"
     deploymentfile = "${eclipselink.sessions.dir}/sessions.xml"
     property = "export-completed"
     failonerror = "true"
     classpathref = "eclipselink.classpath">
 
     <eclipselink:classpath refid = "mw.classpath" />
 
     <eclipselink:classpath refid = "mwplatforms.classpath" />
 
     <eclipselink:ignoreerrorset refid = "ignoreErrors"/>
     <eclipselink:ignoreerror code = "0545" />
     <eclipselink:loginspec
             url = "jdbc:cloudscape:stagedb;create=true"
             driverclass = "COM.cloudscape.core.JDBCDriver"
             user = "scott" 
             password="tiger" />
 </eclipselink:mappings.export>


===How to Create the classpath Task===
Use the classpath element to define the Java classpath necessary to run a task. For more information, see <tt>http://ant.apache.org/manual/usingl#path</tt>.


====Using Parameters====

<span id="Table 4-10"></span>
''''' classpath Element Parameters'''''

{| class="HRuleFormalMax" dir="ltr" title="classpath Element Parameters" summary="This table lists the attributes applicable to this task." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t47" align="left" valign="bottom" | '''Attribute'''
! id="r1c2-t47" align="left" valign="bottom" | '''Description'''
! id="r1c3-t47" align="left" valign="bottom" | '''Required'''
|- align="left" valign="top"
| id="r2c1-t47" headers="r1c1-t47" align="left" |
location
| headers="r2c1-t47 r1c2-t47" align="left" |
Specifies a single file or directory relative to the project's base directory (or an absolute filename).
| headers="r2c1-t47 r1c3-t47" align="left" |
No
|- align="left" valign="top"
| id="r3c1-t47" headers="r1c1-t47" align="left" |
path
| headers="r3c1-t47 r1c2-t47" align="left" |
Specifies one or multiple files or directories separated by a colon or semicolon.
| headers="r3c1-t47 r1c3-t47" align="left" |
No
|- align="left" valign="top"
| id="r4c1-t47" headers="r1c1-t47" align="left" |
refid
| headers="r4c1-t47 r1c2-t47" align="left" |
Reference to a path defined elsewhere.
| headers="r4c1-t47 r1c3-t47" align="left" |
No
|}


====Specifying Parameters Specified as Nested Elements====
You can specify the following parameters as nested elements of this task:
* pathelement
* fileset
* dirset
* filelist


====Examples====
The following example shows a typical <tt>classpath</tt> element.

''''' 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>


===How to Create the ignoreerror Task===

Use the <tt>ignoreerror</tt> element to instruct an EclipseLink Ant task to ignore a specific EclipseLink Foundation Library or Workbench (see [[Troubleshooting an EclipseLink Application (ELUG)]]) run-time error code.

To instruct an EclipseLink Ant task to ignore multiple error codes, consider using an [[#How to Create the ignoreerrorset Task|<tt>ignoreerrorset</tt> element]].


====Using Parameters====
<span id="Table 4-11"></span>
''''' ignoreerror Element Parameters'''''

{| class="HRuleFormalMax" dir="ltr" title="ignoreerror Element Parameters" summary="This table lists the attributes applicable to this task." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t48" align="left" valign="bottom" | '''Attribute'''
! id="r1c2-t48" align="left" valign="bottom" | '''Description'''
! id="r1c3-t48" align="left" valign="bottom" | '''Required'''
|- align="left" valign="top"
| id="r2c1-t48" headers="r1c1-t48" align="left" |
code
| headers="r2c1-t48 r1c2-t48" align="left" |
Error code of the problem to ignore.
| headers="r2c1-t48 r1c3-t48" align="left" |
Yes
|}


====Specifying Parameters Specified as Nested Elements====
You cannot specify parameters as nested elements of this element.


====Examples====
The following example shows a typical <tt>ignoreerror</tt> element. This element instructs a <tt>mappings.export</tt> task to ignore Workbench error code 0545.

''''' An ignoreerror Element'''''
 <eclipselink:mappings.export
     projectfile = "${eclipselink.mwp.dir}/myProject.mwp"
    deploymentfile = "${eclipselink.sessions.dir}/sessions.xml"
    classpathref = "eclipselink.classpath">
    <eclipselink:classpath refid = "mw.classpath" />
    <eclipselink:classpath refid = "mwplatforms.classpath" />
    <eclipselink:ignoreerror code = "0545" />
 </eclipselink:mappings.export>


===How to Create the ignoreerrorset Task===
Use the <tt>ignoreerrorset</tt> element to instruct an EclipseLink Ant task to ignore any of multiple EclipseLink Foundation Library or Workbench run-time error codes.


====Using Parameters====
<span id="Table 4-12"></span>
''''' ignoreerrorset Element Parameters'''''

{| class="HRuleFormalMax" dir="ltr" title="ignoreerrorset Element Parameters" summary="This table lists the attributes applicable to this task." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t49" align="left" valign="bottom" | '''Attribute'''
! id="r1c2-t49" align="left" valign="bottom" | '''Description'''
! id="r1c3-t49" align="left" valign="bottom" | '''Required'''
|- align="left" valign="top"
| id="r2c1-t49" headers="r1c1-t49" align="left" |
id
| headers="r2c1-t49 r1c2-t49" align="left" |
Unique identifier for this type instance, can be used to reference this type in scripts.
| headers="r2c1-t49 r1c3-t49" align="left" |
No
|- align="left" valign="top"
| id="r3c1-t49" headers="r1c1-t49" align="left" |
refid
| headers="r3c1-t49 r1c2-t49" align="left" |
Reference to a ignoreerrorset defined elsewhere.
| headers="r3c1-t49 r1c3-t49" align="left" |
No
|}


====Specifying Parameters Specified as Nested Elements====
You can specify the following parameter as nested elements of this element:
* [[#How to Create the ignoreerror Task|ignorerror ]]


====Examples====
The following example shows a typical <tt>ignoreerrorset</tt> element. This element instructs a <tt>mappings.export</tt> task to ignore all of Workbench error codes 0402 and 0570. Note that the <tt>mappings.export</tt> task also uses an explicitly <tt>ignoreerror</tt> element: this means that the <tt>mappings.export</tt> task will ignore all of error codes 0402, 0570, and 0545.

<span id="Example 4-13"></span>
''''' An ignoreerrorset Element'''''
 <eclipselink:ignoreerrorset id = "ignoreErrors">
    <eclipselink:ignoreerror code = "0402" />
    <eclipselink:ignoreerror code = "0570" /></eclipselink:ignoreerrorset>
    ...
    <eclipselink:mappings.export
     projectfile = "${eclipselink.mwp.dir}/myProject.mwp"
     deploymentfile = "${eclipselink.sessions.dir}/sessions.xml"
     classpathref = "eclipselink.classpath">
    <eclipselink:classpath refid = "mw.classpath" />
    <eclipselink:classpath refid = "mwplatforms.classpath" />
    <eclipselink:ignoreerrorset refid = "ignoreErrors"/>
    <eclipselink:ignoreerror code = "0545" />
 </eclipselink:mappings.export>

===How to Create the loginspec Task===
Use the <tt>loginspec</tt> element to instruct an EclipseLink Ant task to override the project database login information in a Workbench project. For more information, see [[Introduction%20to%20Data%20Access%20(ELUG)|Introduction to Data Access]].


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note:''' You can only use this element with [[Introduction%20to%20Relational%20Projects%20(ELUG)|Relational Projects]]. You cannot use this element with a Java EE project.
|}


====Using Parameters====
<span id="Table 4-13"></span>
'''''loginspec Element Parameters'''''

{| class="HRuleFormalMax" dir="ltr" title="loginspec Element Parameters" summary="This table lists the attributes applicable to this task." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t51" align="left" valign="bottom" | '''Attribute'''
! id="r1c2-t51" align="left" valign="bottom" | '''Description'''
! id="r1c3-t51" align="left" valign="bottom" | '''Required'''
|- align="left" valign="top"
| id="r2c1-t51" headers="r1c1-t51" align="left" |
id
| headers="r2c1-t51 r1c2-t51" align="left" |
Unique identifier for this type instance, can be used to reference this type in scripts.
| headers="r2c1-t51 r1c3-t51" align="left" |
No
|- align="left" valign="top"
| id="r3c1-t51" headers="r1c1-t51" align="left" |
refid
| headers="r3c1-t51 r1c2-t51" align="left" |
Reference to a loginspec defined elsewhere.
| headers="r3c1-t51 r1c3-t51" align="left" |
No
|- align="left" valign="top"
| id="r4c1-t51" headers="r1c1-t51" align="left" |
driverclass
| headers="r4c1-t51 r1c2-t51" align="left" |
Fully qualified class of the data source driver (see [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Database Login Connection Options|Configuring Database Login Connection Options]]).
| headers="r4c1-t51 r1c3-t51" align="left" |
No – default to the class that the Workbench project specifies.
|- align="left" valign="top"
| id="r5c1-t51" headers="r1c1-t51" align="left" |
url
| headers="r5c1-t51 r1c2-t51" align="left" |
URL of the driver (see [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring Database Login Connection Options|Configuring Database Login Connection Options]]).
| headers="r5c1-t51 r1c3-t51" align="left" |
Yes
|- align="left" valign="top"
| id="r6c1-t51" headers="r1c1-t51" align="left" |
user
| headers="r6c1-t51 r1c2-t51" align="left" |
Login user name (see [[Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring User Name and Password|Configuring User Name and Password]]).
| headers="r6c1-t51 r1c3-t51" align="left" |
No – default to the value that the Workbench project specifies
|- align="left" valign="top"
| id="r7c1-t51" headers="r1c1-t51" align="left" |
password
| headers="r7c1-t51 r1c2-t51" align="left" |
Login password (see [[Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring User Name and Password|Configuring User Name and Password]]).
| headers="r7c1-t51 r1c3-t51" align="left" |
No – default to the value that the Workbench project specifies
|}


====Specifying Parameters Specified as Nested Elements====
You cannot specify parameters as nested elements of this element.


====Examples====
The following example shows a typical <tt>loginspec</tt> element.

<span id="Example 4-14"></span>
''''' A loginspec Element'''''
 <eclipselink:mappings.export 
     projectfile = "${eclipselink.mwp.dir}/myProject.mwp"
     deploymentfile = "${eclipselink.sessions.dir}/sessions.xml"
     classpathref = "eclipselink.classpath">
 
     <eclipselink:classpath refid = "mw.classpath" />
     <eclipselink:classpath refid = "mwplatforms.classpath" />
 
     <eclipselink:loginspec
         url = "jdbc:cloudscape:stagedb;create=true"
         driverclass = "COM.cloudscape.core.JDBCDriver"
         user = "scott" 
         password="tiger" />
 
 </eclipselink:mappings.export>



----
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''


[[Category: EclipseLink User's Guide]]
[[Category: Release 1]]
[[Category: Concept]]
[[Category: Task]]