Oracle Dali Java Persistence Tools User Guide

Dali Java Persistence Tools
User Guide
Release 2.3 for Eclipse
June 2010
Dali Java Persistence Tools User Guide
Copyright © 2006, 2010 Oracle. All rights reserved.
The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise indicated
below, the Content is provided to you under the terms and conditions of the Eclipse Public License Version
1.0 ("EPL"). A copy of the EPL is available at http://www.eclipse.org/legal/epl-v10.html. For purposes of
the EPL, "Program" will mean the Content.
If you did not receive this Content directly from the Eclipse Foundation, the Content is being redistributed
by another party ("Redistributor") and different terms and conditions may apply to your use of any object
code in the Content. Check the Redistributor's license that was provided with the Content. If no such license
exists, contact the Redistributor. Unless otherwise indicated below, the terms and conditions of the EPL still
apply to any source code in the Content.
Contents
1
Getting started
1.1
1.2
1.2.1
1.2.2
2
1-1
1-2
1-2
1-3
Concepts
2.1
2.2
2.3
2.3.1
2.3.2
3
Requirements and installation ..................................................................................................
Dali quick start ............................................................................................................................
Creating a new JPA project ................................................................................................
Creating a Java persistent entity with persistent fields..................................................
Understanding Java persistence ..............................................................................................
Understanding OR mappings ...................................................................................................
Understanding EJB 3.0 Java Persistence API ..........................................................................
The persistence.xml file.......................................................................................................
The orm.xml file ...................................................................................................................
2-1
2-1
2-2
2-2
2-2
Tasks
3.1
3.2
3.3
3.4
3.4.1
3.4.2
3.5
3.5.1
3.5.2
3.6
3.6.1
3.6.2
3.6.3
3.7
Creating a new JPA project........................................................................................................ 3-1
Converting a Java Project to a JPA Project .............................................................................. 3-5
Creating a JPA Entity ................................................................................................................. 3-7
Managing the persistence.xml file......................................................................................... 3-10
Synchronizing classes....................................................................................................... 3-12
Upgrading document version......................................................................................... 3-12
Managing the orm.xml file ..................................................................................................... 3-13
Creating an orm.xml file .................................................................................................. 3-13
Working with orm.xml file.............................................................................................. 3-14
Adding persistence to a class ................................................................................................ 3-15
Entity .................................................................................................................................. 3-15
Embeddable ....................................................................................................................... 3-16
Mapped superclass ........................................................................................................... 3-17
Specifying additional tables ................................................................................................... 3-18
3.8
Specifying entity inheritance..................................................................................................
3.9
Creating Named Queries ........................................................................................................
3.10
Mapping an entity ...................................................................................................................
3.10.1
Basic mapping ...................................................................................................................
3.10.2
Embedded mapping.........................................................................................................
3.10.3
Embedded ID mapping ...................................................................................................
3.10.4
ID mapping........................................................................................................................
3.10.5
Many-to-many mapping..................................................................................................
3.10.6
Many-to-one mapping .....................................................................................................
3.10.7
One-to-many mapping.....................................................................................................
3.10.8
One-to-one mapping ........................................................................................................
3.10.9
Transient mapping ...........................................................................................................
3.10.10
Version mapping ..............................................................................................................
3.10.11
Element Collection mapping...........................................................................................
3.11
Generating entities from tables .............................................................................................
3.12
Generating tables from entities ..............................................................................................
3.13
Validating mappings and reporting problems ....................................................................
3.13.1
Error messages ..................................................................................................................
3.13.2
Warning messages ............................................................................................................
3.14
Modifying persistent project properties ...............................................................................
3.15
Generating Schema from Classes ..........................................................................................
3.16
Generating JAXB Classes from a Schema.............................................................................
4
3-19
3-21
3-22
3-22
3-24
3-24
3-24
3-26
3-27
3-28
3-29
3-30
3-30
3-31
3-31
3-36
3-36
3-36
3-38
3-38
3-39
3-41
Reference
4.1
Wizards......................................................................................................................................... 4-1
4.1.1
Create New JPA Project wizard......................................................................................... 4-1
4.1.1.1
New JPA Project page .................................................................................................. 4-1
4.1.1.2
Java Page ........................................................................................................................ 4-2
4.1.1.3
JPA Facet page .............................................................................................................. 4-2
4.1.2
Create JPA Entity wizard.................................................................................................... 4-3
4.1.2.1
Entity Class page .......................................................................................................... 4-4
4.1.2.2
Entity Properties page.................................................................................................. 4-4
4.1.3
Mapping File Wizard .......................................................................................................... 4-5
4.1.3.1
Mapping File ................................................................................................................. 4-5
4.1.4
Generate Tables from Entities Wizard.............................................................................. 4-6
4.1.5
Generate Entities from Tables Wizard.............................................................................. 4-6
4.1.5.1
Select Tables .................................................................................................................. 4-6
4.1.5.2
Table Associations ........................................................................................................ 4-7
4.1.5.3
Customize Default Entity Generation ....................................................................... 4-7
4.1.5.4
Customize Individual Entities .................................................................................... 4-8
4.1.6
Create New Association...................................................................................................... 4-8
4.1.6.1
Association Tables ........................................................................................................ 4-8
4.1.6.2
Join Columns ................................................................................................................. 4-8
4.1.6.3
Association Cardinality ............................................................................................... 4-9
4.1.7
Generate Schema from JAXB Classes Wizard ................................................................. 4-9
4.1.7.1
Generate Schema from Classes................................................................................... 4-9
4.2
Property pages............................................................................................................................. 4-9
4.2.1
4.2.1.1
4.2.1.2
4.2.1.3
4.2.1.4
4.2.1.5
4.2.2
4.2.2.1
4.2.2.2
4.2.2.3
4.2.2.4
4.2.3
4.2.3.1
4.2.3.2
4.2.3.3
4.2.3.4
4.2.3.5
4.2.4
4.2.5
4.2.5.1
4.2.5.2
4.2.5.3
4.2.5.4
4.2.5.5
4.2.5.6
4.2.5.7
4.2.5.8
4.2.5.9
4.3
4.3.1
4.3.2
4.4
4.4.1
4.4.2
4.4.3
4.4.4
4.4.5
4.5
4.6
4.6.1
4.6.2
4.7
JPA Details view (for entities)............................................................................................ 4-9
General information .................................................................................................. 4-10
Attribute overrides .................................................................................................... 4-10
Secondary table information.................................................................................... 4-11
Inheritance information ............................................................................................ 4-11
Queries ........................................................................................................................ 4-12
JPA Details view (for attributes)..................................................................................... 4-12
General information .................................................................................................. 4-12
Join Table Information .............................................................................................. 4-14
Join Columns Information........................................................................................ 4-15
Primary Key Generation information..................................................................... 4-15
JPA Details view (for orm.xml)....................................................................................... 4-16
General information .................................................................................................. 4-16
Persistence Unit information ................................................................................... 4-17
Generators................................................................................................................... 4-17
Queries ........................................................................................................................ 4-18
Converters .................................................................................................................. 4-18
JPA Structure view ........................................................................................................... 4-19
persistence.xml Editor...................................................................................................... 4-19
General ........................................................................................................................ 4-19
Connection.................................................................................................................. 4-20
Customization ............................................................................................................ 4-21
Caching ....................................................................................................................... 4-23
Logging ....................................................................................................................... 4-25
Options........................................................................................................................ 4-28
Schema Generation.................................................................................................... 4-30
Properties .................................................................................................................... 4-31
Source .......................................................................................................................... 4-31
Preferences ................................................................................................................................ 4-31
Project Properties page – Java Persistence Options ..................................................... 4-31
Project Properties page – Validation Preferences ........................................................ 4-31
Dialogs ....................................................................................................................................... 4-32
Edit Join Columns Dialog ................................................................................................ 4-32
Select Cascade dialog ....................................................................................................... 4-33
New EclipseLink Mapping File dialog .......................................................................... 4-33
Add Converter dialog ...................................................................................................... 4-33
Configure JAXB Class Generation dialog ..................................................................... 4-34
JPA Development perspective .............................................................................................. 4-34
Icons and buttons ..................................................................................................................... 4-34
Icons .................................................................................................................................... 4-34
Buttons................................................................................................................................ 4-35
Dali Developer Documentation ............................................................................................. 4-35
5
Tips and tricks
6
What’s new
6.1
Improved Internationalization and Localization ................................................................... 6-1
6.2
6.3
6.4
6.5
6.6
7
Multiple Improvements to the Dali Perspective ....................................................................
Support for JPA 2.0 and EclipseLink........................................................................................
Conversion of Java Projects to JPA Projects ............................................................................
EclipseLink 2.x Support .............................................................................................................
Table-per-Concrete-Class Inheritance......................................................................................
6-1
6-1
6-2
6-2
6-2
Legal
7.1
Index
About this content....................................................................................................................... 7-1
1
Getting started
This section provides information on getting started with the Java Persistence Tools.
■
Requirements and installation
■
Dali quick start
For additional information, please visit the Dali home page at:
http://www.eclipse.org/webtools/dali/main.php.
1.1 Requirements and installation
Before installing Dali, ensure that your environment meets the following minimum
requirements:
■
Eclipse 3.6 (http://www.eclipse.org/downloads)
■
Java Runtime Environment (JRE) 1.5 (http://java.com)
■
Eclipse Web Tools Platform (WTP) 3.2 (http://www.eclipse.org/webtools)
■
Java Persistence API (JPA) for Java EE 5. For example, the EclipseLink
implementation for JPA can be obtained from:
http://www.eclipse.org/eclipselink/
Refer to http://www.eclipse.org/webtools/dali/gettingstarted_
main.html for additional installation information.
Dali is included as part of WTP 3.2. No additional installation or configuration is
required.
Accessibility Features
Dali supports the standard accessibility features in Eclipse, including the following:
■
Navigating the user interface using the keyboard.
■
Specifying general accessibility preferences for the editor.
See Accessibility Features in Eclipse in the Workbench User Guide for details.
Help Accessibility
The documentation and help contains markup to facilitate access by the disabled
community. See Help Accessibility in the Workbench User Guide for details.
When using the help, be aware of the following:
Getting started 1-1
Dali quick start
■
■
Screen readers may not always correctly read the code examples in this document.
The conventions for writing code require that closing braces should appear on an
otherwise empty line; however, some screen readers may not always read a line of
text that consists solely of a bracket or brace.
This documentation may contain links to Web sites of other companies or
organizations that we do not control. We neither evaluate nor make any
representations regarding the accessibility of these Web sites.
1.2 Dali quick start
This section includes information to help you quickly start using Dali to create
relational mappings between Java persistent entities and database tables.
■
Creating a new JPA project
■
Creating a Java persistent entity with persistent fields
1.2.1 Creating a new JPA project
This quick start shows how to create a new JPA project.
1.
Select File > New > Project. The Select a Wizard dialog appears.
Tip: You can also select the JPA perspective and then select File >
New > JPA Project.
2.
Select JPA Project and then click Next. The New JPA Project page appears.
3.
Enter a Project name (such as QuickStart).
4.
If needed, select the Target Runtime (such as Apache Tomcat) and
configuration, such as Utility JPA Project with Java 5.0 and then click Next. The
Java source page appears.
Note:
The Target Runtime is not required for Java SE development.
5.
If you have existing Java source files, add them to your classpath and then click
Next. The JPA Facet page appears.
6.
On the JPA Facet dialog, select your vendor-specific JPA platform (or select
Generic), database connection (or create a new connection), JPA implementation
library (such as EclipseLink), define how Dali should manage persistent classes,
and then click Finish.
Tip: Select Override the Default Schema for Connection if you
require a schema other than the one that Dali derives from the
connection information, which may be incorrect in some cases. Using
this option, you can select a development time schema for defaults
and validation.
Eclipse adds the project to the workbench and opens the JPA perspective.
1-2 Dali Java Persistence Tools User Guide
Dali quick start
Figure 1–1 JPA Project in Project Explorer
Now that you have created a project with persistence, you can continue with Creating
a Java persistent entity with persistent fields.
1.2.2 Creating a Java persistent entity with persistent fields
This quick start shows how to create a new persistent Java entity. We will create an
entity to associate with a database table. You will also need to add the ADDRESS table
to your database.
1.
Select the JPA project in the Navigator or Project Explorer and then click New >
Other. The Select a Wizard dialog appears.
2.
Select JPA > Entity and then click Next. The Entity Class page appears.
3.
Enter the package name (such as quickstart.demo.model), the class name
(such as Address) and then click Next. The Entity Properties page appears, which
enables you to define the persistence fields, which you will map to the columns of
a database table.
4.
Use the Entity Fields dialog (invoked by clicking Add) to add persistence fields to
the Address class:
private
private
private
private
private
private
Long id;
String city;
String country;
String stateOrProvince;
String postalCode;
String street;
You will also need to add the following columns to the
ADDRESS database table:
Note:
NUMBER(10,0)
VARCHAR2(80)
VARCHAR2(80)
VARCHAR2(20)
VARCHAR2(80)
VARCHAR2(80)
5.
ADDRESS_ID (primary key)
PROVINCE
COUNTRY
P_CODE
STREET
CITY
Click Finish. With the Create JPA Entity completed, Eclipse displays the Address
entity in the JPA Structure view.
Getting started 1-3
Dali quick start
Address.java includes the @Entity annotation, the persistence fields, as well as
getter and setter methods for each of the fields.
Figure 1–2 Address Entity in Address.java
Eclipse also displays the Address entity in the JPA Structure view:
Figure 1–3 Address Entity in the JPA Structure View
1.
Select the Address class in the Project Explorer view.
2.
In the JPA Details view, notice that Dali has automatically associated the
ADDRESS database table with the entity because they are named identically.
Depending on your database connection type, you may need
to specify the Schema.
Note:
Figure 1–4 JPA Details View for Address Entity
1-4 Dali Java Persistence Tools User Guide
Dali quick start
Tip: After associating the entity with the database table, you should
update the persistence.xml file to include this JPA entity.
Right-click the persistence.xml file in the Project Explorer and
select JPA Tools > Synchronize Class List. Dali adds the following to
the persistence.xml file:
<class>quickstart.demo.model.Address</class>
Now we are ready to map each fields in the Address class to a column in the database
table.
1.
Select the id field in the JPA Details view.
2.
Right click id and then select Map As > id.
3.
In the JPA Details view, select ADDRESS_ID in the Name field:
Figure 1–5 JPA Details View for the addressId Field
Eclipse adds the following annotations to the Address entity:
@Id
@Column(name="ADDRESS_ID")
4.
Map each of the following fields (as Basic mappings) to the appropriate database
column:
Field
Map As
Database Column
city
Basic
CITY
country
Basic
COUNTRY
Getting started 1-5
Dali quick start
Field
Map As
Database Column
postalCode
Basic
P_CODE
provinceOrState
Basic
PROVINCE
street
Basic
STREET
Dali automatically maps some fields to the correct database column (such as the city
field to the City column) if the names are identical.
1-6 Dali Java Persistence Tools User Guide
Dali quick start
Getting started 1-7
Dali quick start
1-8 Dali Java Persistence Tools User Guide
2
Concepts
This section contains an overview of concepts you should be familiar with when using
Dali to create mappings for Java persistent entities.
■
Understanding Java persistence
■
Understanding OR mappings
■
Understanding EJB 3.0 Java Persistence API
In addition to these sections, you should review the following resources for additional
information:
■
Eclipse Dali project: http://www.eclipse.org/webtools/dali
■
Eclipse Web Tools Platform project: http://www.eclipse.org/webtools
■
JSR 220 EJB 3.0 specification: http://www.jcp.org/en/jsr/detail?id=220
■
EclipseLink project: http://www.eclipse.org/eclipselink
2.1 Understanding Java persistence
Persistence refers to the ability to store objects in a database and use those objects with
transactional integrity. In a J2EE application, data is typically stored and persisted in
the data tier, in a relational database.
Entity beans are enterprise beans that contain persistent data and that can be saved in
various persistent data stores. The entity beans represent data from a database; each
entity bean carries its own identity. Entity beans can be deployed using
application-managed persistence or container-managed persistence.
2.2 Understanding OR mappings
The Dali OR (object-relational) Mapping Tool allows you to describe how your entity
objects map to the data source (or other objects). This approach isolates persistence
information from the object model–developers are free to design their ideal object
model, and DBAs are free to design their ideal schema.
These mappings transform an object data member type to a corresponding relational
database data source representation. These OR mappings can also transform object
data members that reference other domain objects stored in other tables in the
database and are related through foreign keys.
You can use these mappings to map simple data types including primitives (such as
int), JDK classes (such as String), and large object (LOB) values. You can also use
them to transform object data members that reference other domain objects by way of
Concepts 2-1
Understanding EJB 3.0 Java Persistence API
association where data source representations require object identity maintenance
(such as sequencing and back references) and possess various types of multiplicity and
navigability. The appropriate mapping class is chosen primarily by the cardinality of
the relationship.
2.3 Understanding EJB 3.0 Java Persistence API
The Java 2 Enterprise Edition(J2EE) Enterprise JavaBeans (EJB) are a component
architecture that you use to develop and deploy object-oriented, distributed,
enterprise-scale applications. An application written according to the Enterprise
JavaBeans architecture is scalable, transactional, and secure.
The EJB 3.0 Java Persistence API (JPA) improves the EJB architecture by reducing its
complexity through the use of metadata (annotations) and specifying programmatic
defaults of that metadata.
2.3.1 The persistence.xml file
The JPA specification requires the use of a persistence.xml file for deployment.
This file defines the database and entity manager options, and may contain more than
one persistence unit. To enable you to easily edit this information, Dali provides the
persistence.xml Editor. Alternatively, you can use the Eclipse XML Editor to create and
maintain this information. See "Managing the persistence.xml file" on page 3-10 for
more information.
2.3.2 The orm.xml file
Although the JPA specification emphasizes the use of annotations to specify
persistence, you can also use the orm.xml file to store this metadata. Dali enables you
to create a stub orm.xml file for a JPA project using the Mapping File Wizard. See
"Managing the orm.xml file" on page 3-13 for more information.
The metadata must match the XSD specification of your
selected JPA implementation.
Note:
Dali provides comprehensive support for configuring XML mapping files through the
JPA Details view (for orm.xml) that is nearly identical to the annotation-based
configuration in the Java source. Alternatively, you can also use the Eclipse XML
Editor to create and maintain the metadata information in orm.xml.
2-2 Dali Java Persistence Tools User Guide
3
Tasks
This section includes detailed step-by-step procedures for accessing the Dali OR
mapping tool functionality.
■
Creating a new JPA project
■
Converting a Java Project to a JPA Project
■
Creating a JPA Entity
■
Managing the persistence.xml file
■
Managing the orm.xml file
■
Adding persistence to a class
■
Specifying additional tables
■
Specifying entity inheritance
■
Mapping an entity
■
Generating entities from tables
■
Validating mappings and reporting problems
■
Modifying persistent project properties
■
Generating Schema from Classes
■
Generating JAXB Classes from a Schema
3.1 Creating a new JPA project
Use this procedure to create a new JPA project.
1.
From the Navigator or Project Explorer, select File > New > Project. The Select a
wizard dialog appears.
Tip: You can also select the JPA perspective and then select File >
New > JPA Project.
Tasks 3-1
Creating a new JPA project
Figure 3–1 Selecting the Create a JPA Project wizard
2.
Select JPA Project and then click Next. The New JPA Project page appears.
Figure 3–2 The JPA Project Page
3-2 Dali Java Persistence Tools User Guide
Creating a new JPA project
3.
Complete the fields on the New JPA Project page to specify the project name and
location, target runtime, and pre-defined configuration.
Note:
4.
The Target Runtime is not required for Java SE development.
Click Next. The Java source page appears.
Figure 3–3 The Java Source Page
5.
Click Add Folder to add existing Java source files to the project.
6.
Click Next. JPA Facet page appears.
Tasks 3-3
Creating a new JPA project
Figure 3–4 The JPA Facet Page
7.
Complete the fields on the JPA Facet page to specify your vender-specific
platform, JPA implementation library, and database connection.
Click Manage libraries to create or update your JPA user libraries. Click
Download libraries to obtain additional JPA implementation libraries.
If Dali derives the incorrect schema, select Override the Default Schema for
Connection. Using this option, you can select a development time schema for
defaults and validation.
If you clear the Create orm.xml option (which is selected by default), you can later
add a mapping file to the project using the Mapping File Wizard.
3-4 Dali Java Persistence Tools User Guide
Converting a Java Project to a JPA Project
If the server runtime does not provide a JPA implementation,
you must explicitly select a JPA implementation library.
Note:
To insure the portability of your application, you must explicitly list
the managed persistence classes that are included in the persistence
unit. If the server supports EJB 3.0, the persistent classes will be
discovered automatically.
Depending on your JPA implementation (for example, Generic or
EclipseLink), different options may be available when creating JPA
projects.
8.
Click Finish. You should now open the JPA Development perspective.
3.2 Converting a Java Project to a JPA Project
Use this procedure to convert an existing Java project to a JPA project.
1.
From the Navigator or Project explorer, right-click the Java project and then select
Configure > Convert to JPA Project. The Project Facets page of the Modify
Faceted Project wizard appears.
Figure 3–5 Modify Faceted Project Page
2.
Change the Configuration to Default JPA Configuration.
3.
Click Next. JPA Facet page appears.
Tasks 3-5
Converting a Java Project to a JPA Project
Figure 3–6 JPA Facet Page
4.
Complete the fields on the JPA Facet page to specify your vender-specific
platform, JPA implementation library, and database connection.
Click Manage libraries to create or update your JPA user libraries. Click
Download libraries to obtain additional JPA implementation libraries.
If Dali derives the incorrect schema, select Override the Default Schema for
Connection. Using this option, you can select a development time schema for
defaults and validation.
If you clear the Create orm.xml option (which is selected by default), you can later
add a mapping file to the project using the Mapping File Wizard.
5.
Click Finish.
The Dali OR Mapping Tool adds the JPA implementation libraries to your project and
creates the necessary orm.xml and perisistence.xml files.
3-6 Dali Java Persistence Tools User Guide
Creating a JPA Entity
3.3 Creating a JPA Entity
Use this procedure to create a JPA entity:
1.
From the Navigator or Project Explorer, select the JPA project and then File > New
> Other. The Select a Wizard dialog appears.
Figure 3–7 Selecting the Create a JPA Entity Wizard
2.
Select JPA > Entity and then click Next. The Entity Class page appears.
Tasks 3-7
Creating a JPA Entity
Figure 3–8 The Entity Class Page
Complete this page as follows:
■
■
■
In the Source Folder field, select, or enter, the location of the JPA project’s src
folder.
Select, or enter, the name of the class package for this entity in the Java
Package field.
■
Enter the name of the Java class in the Class name field.
■
If needed, enter, or select a superclass.
■
3.
Select the JPA project in the Project field.
If needed, complete the Inheritance section as follows (these properties are
optional):
–
Accept the Entity option (the default) to create a Java class with the
@Entity option.
–
Alternatively, select Mapped superclass (if you defined a super class).
–
Select Inheritance and then select one of the JSR 220 inheritance mapping
strategies (SINGLE_TABLE, TABLE_PER_CLASS, JOINED).
–
Select Add to entity mappings in XML to create XML mappings in
orm.xml, rather than annotations.
Click Next to proceed to the Entity Properties page where you define the
persistent fields for the entity.
3-8 Dali Java Persistence Tools User Guide
Creating a JPA Entity
Figure 3–9 The Entity Properties Page
Alternatively, click Finish to complete the entity.
4.
Complete the page as follows:
1.
If needed, enter a new name for the entity. Doing so results in adding a name
attribute to the @Entity notation (@Entity(name="EntityName")).
2.
Accept Use default (the default setting) to use the default value for the name
of the mapped table. Entering a different name results in adding the @Table
notation with its name attribute defined as the new table
(@Table(name="TableName")).
The Entity Name-related options are not available if you
selected Mapped superclass on the Entity Class page
Note:
3.
Add persistence fields to the entity by clicking Add. The Entity Fields dialog
appears.
Figure 3–10 The Entity Fields Dialog
4.
Select a persistence type from the Type list. You can retrieve additional types
using the Browse function.
5.
Enter the field name and then click OK. Repeat this procedure for each field.
Tasks 3-9
Managing the persistence.xml file
5.
6.
If needed, select Key to designate the field as a primary key.
7.
Select either the Field-based access type (the default) or Property-based access
type.
Click Finish. Eclipse adds the entity to your project.
3.4 Managing the persistence.xml file
When you create a project, Eclipse creates the META-INF\persistence.xml file in
the project’s directory.
You can create a stub persistence.xml file in the META-INF directory when you
create a JPA project (see "Creating a new JPA project"). You can manage this file either
through the XML editor (see "Using the XML Editor to edit the persistence.xml file") or
through the persistence.xml Editor.
Depending on your JPA implementation (for example,
EclipseLink), the following additional pages may be available in the
persistence.xml Editor:
Note:
■
Customization
Use this page to define change-tracking and session customizer-related
properties.
■
Caching
Use this page to define caching properties.
■
Logging
Use this page to define logging properties.
■
Options
Use this page to define session and target database properties.
■
Schema Generation
Use this page to define DDL-related properties.
For projects using the EclipseLink JPA implementation, the
Connections page also includes JDBC connection pool properties.
If the project uses the Generic platform, then only the General,
Connection, Properties and Source pages are available.
To use the persistence.xml Editor:
1.
Open the peristence.xml file. The General page of the editor appears.
2.
Use the General page to define the persistence.xml files
<persistent-unit>-related attributes as well as the <provider>, and
<class> elements (described in the following table).
Tip: The persistence.xml Editor’s Source page enables you to view
and edit the raw XML file.
Property
Description
Element Defined
Name
Enter the name of the
persistence unit.
<persistence-unit name =
"<Name>">
3-10 Dali Java Persistence Tools User Guide
Managing the persistence.xml file
Property
Description
Element Defined
Persistence Provider
Enter the name of the
persistence provider.
<provider>
Description
<description>
Enter a description for
this persistence unit. This
is an optional property.
Managed Classes
Add or remove the
classes managed through
the persistence unit.
Exclude Unlisted Classes Select to include all
annotated entity classes
in the root of the
persistence unit.
XML Mapping Files
Add or remove the
object/relational
mapping XML files
define the classes
managed through the
persistence unit.
JAR Files
Add or remove additional
JAR files and libraries
3.
<class>
<exclude-unlisted-classes>
<mapping-file>
Use the Connection page to define the <jta-data-source> and
<non-jta-data-source> elements as follows:
To configure the JTA (Java Transaction API) source used by the persistence
provider:
1.
Select JTA from the Transaction Type list.
2.
Enter the global JNDI name of the data source.
To configure a non-JTA data source:
1.
Select Resource Local from the Transaction Type list.
2.
Enter the global JNDI name of the data source.
Note: Select Default() to use the data source provided by the
container.
For projects using the Generic platform, you can also define the EclipseLink
connection pool driver, connection pool driver, URL, user name and password.
4.
Use the table in the Properties page to set the vendor-specific <properties>
element.
To add <property> elements:
1.
Click Add.
2.
Enter the <name> and <value> attributes for the <property> element using
the table’s Name and Value fields.
To remove a <property> element, select a defined property in the table and then
click Remove.
Tasks 3-11
Managing the persistence.xml file
If the project uses the EclipseLink platform, the connection
page also includes parameters for JDBC connection pooling.
Note:
3.4.1 Synchronizing classes
As you work with the classes in your Java project, you will need to update the
persistence.xml file to reflect the changes.
Use this procedure to synchronize the persistence.xml file:
1.
Right-click the persistence.xml file in the Project Explorer and select JPA
Tools > Synchronize Class List.
Note: Use this function if you selected Annotated classes must be
listed in the persistence.xml option in the JPA Facet page. In general,
you do not have to use this function within the container.
Figure 3–11 Synchronizing the persistence.xml File
Dali adds the necessary <class> elements to the persistence.xml file.
2.
Use the Persistence XML Editor to continue editing the persistence.xml file.
3.4.2 Upgrading document version
Use this procedure to migrate your project from JPA 1.0 to JPA 2.0. You must complete
this upgrade to use the current JPA 2.0 features in Dali.
Figure 3–12 Upgrading the persistence.xml File
3-12 Dali Java Persistence Tools User Guide
Managing the orm.xml file
3.5 Managing the orm.xml file
When creating a JPA project, (see "Creating a new JPA project") you can also create the
orm.xml file that defines the mapping metadata and defaults.
Eclipse creates the META-INF\orm.xml file in your project’s directory:
<?xml version="1.0" encoding="UTF-8"?>
<persistence version="<PERSISTENCE_VERSION>"
xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
<persistence-unit name="<PERSISTENCE_UNIT_NAME>">
<provider="<PERSISTENCE_PROVIDER>" />
</persistence-unit>
</persistence>
3.5.1 Creating an orm.xml file
If you opt not to create an orm.xml file when you create a JPA project, you can create
one using the Mapping File Wizard.
Use this procedure to create an orm.xml file:
1.
From the Navigator or Project Explorer, select File > New > Other. The Select a
Wizard dialog appears.
Figure 3–13 The Select a Wizard Dialog
2.
Select Mapping File and then click Next. The Mapping File page appears.
If you are using EclipseLink, you can select EclipseLink > EclipseLink Mapping
File.
Tasks 3-13
Managing the orm.xml file
Figure 3–14 The Mapping File Page
3.
Define the properties in the page and click Finish. The orm.xml file appears in
the src directory of the selected JPA project. You can manage the orm.xml file using
the JPA Details view or through the XML Editor. See also JPA Details view (for
orm.xml).
3.5.2 Working with orm.xml file
You can work with the orm.xml by using the JPA Details view.
Use this procedure to work with the orm.xml file:
1.
Right-click the orm.xml file in the Project Explorer and select Open.
2.
In the JPA Structure view, select EntityMappings.
3.
Use the JPA Details view to configure the entity mapping and persistence unit
defaults.
3-14 Dali Java Persistence Tools User Guide
Adding persistence to a class
Figure 3–15 JPA Details view for EntityMappings (orm.xml)
3.6 Adding persistence to a class
You can make a Java class into one of the following persistent types:
■
Entity
■
Embeddable
■
Mapped superclass
3.6.1 Entity
An Entity is a persistent domain object.
An entity can be:
■
Abstract or concrete classes. Entities may also extend non-entity classes as well as
entity classes, and non-entity classes may extend entity classes.
An entity must have:
■
A no-arg constructor (public or protected); the entity class may have other
constructors as well.
Each persistent entity must be mapped to a database table and contain a primary key.
Persistent entities are identified by the @Entity annotation.
Use this procedure to add persistence to an existing entity:
1.
Open the Java class in the Project Explorer.
2.
Select the class in the JPA Structure view.
3.
In the JPA Details view, click the mapping type hyperlink to access the Mapping
Type Selection dialog. In the following figure, clicking entity invokes the dialog
from the JPA Details View.
Tasks 3-15
Adding persistence to a class
Figure 3–16 The Mapping Type Hyperlink
Tip: You can also change (or add) persistence for an entity by
right-clicking the class in the JPA Structure View and then clicking
Map As > Entity.
4.
Select Entity from the Mapping Type Selection dialog and then click OK.
Figure 3–17 The Mapping Type Selection Dialog
5.
Complete the remaining JPA Details view (for entities).
3.6.2 Embeddable
An Embedded class is a class whose instances are stored as part of an owning entity; it
shares the identity of the owning entity. Each field of the embedded class is mapped to
the database table associated with the owning entity.
3-16 Dali Java Persistence Tools User Guide
Adding persistence to a class
To override the mapping information for a specific subclass, use the
@AttributeOverride annotation for that specific class.
An embeddable entity is identified by the @Embeddable annotation.
Use this procedure to add embeddable persistence to an existing entity:
1.
Open the Java class in the Project Explorer.
2.
Select the class in the JPA Structure view.
3.
Click the mapping type hyperlink to open the Mapping Type Selection dialog.
4.
Select Embeddable and then click OK.
Figure 3–18 Mapping Type Selection Dialog (Embeddable)
5.
Complete the remaining JPA Details view (for entities).
3.6.3 Mapped superclass
An entity that extends a Mapped Superclass class inherits the persistent state and
mapping information from a superclass. You should use a mapped superclass to define
mapping information that is common to multiple entity classes.
A mapped superclass can be:
■
Abstract or concrete classes
A mapped superclass cannot be:
■
Be queried or passed as an argument to Entity-Manager or Query operations
■
Be the target of a persistent relationship
A mapped superclass does not have a defined database table. Instead, its mapping
information is derived from its superclass. To override the mapping information for a
specific subclass, use the @AttributeOverride annotation for that specific class.
A mapped superclass is identified by the @MappedSuperclass annotation.
Use this procedure to add Mapped Superclass persistence to an existing entity:
1.
Open the Java class in the Project Explorer.
Tasks 3-17
Specifying additional tables
2.
Select the class in the JPA Structure view.
3.
In the JPA Details view, click the mapping type hyperlink to open the Mapping
Type Selection dialog.
4.
Select Mapped Superclass and then OK.
Figure 3–19 Mapping Type Selection Dialog (Mapped Superclass)
5.
Complete the remaining JPA Details view (for entities).
3.7 Specifying additional tables
Add a secondary table annotation to an entity if its data is split across more than one
table.
To add a secondary table to the entity,
1.
Select the entity in the Project Explorer.
2.
In the JPA Details view, select the Secondary Tables information.
Figure 3–20 Specifying Secondary Tables
3.
Click Add to associate an additional table with the entity. The Edit Secondary
Table dialog appears
3-18 Dali Java Persistence Tools User Guide
Specifying entity inheritance
4.
Select the Name, Catalog, and Schema of the additional table to associate with the
entity.
Eclipse adds the following annotations the entity:
@SecondaryTable(name="NAME", catalog = "CATALOG", schema = "SCHEMA")
To override the default primary key:
1.
Enable the Overwrite default option, then click Add to specify a new primary key
join column. The Create New Primary Key Join Column appears.
2.
Select the Name, Referenced column name, Table, and Column definition of the
primary key for the entity.
Eclipse adds the following annotations the entity:
@SecondaryTable(name="NAME", catalog = "CATALOG", schema = "SCHEMA",
pkJoinColumns = {@PrimaryKeyJoinColumn(name="id", referencedColumnName =
"id"),@PrimaryKeyJoinColumn(name="NAME", referencedColumnName = "REFERENCED
COLUMN NAME", columnDefinition = "COLUMN DEFINITION")})
3.8 Specifying entity inheritance
An entity may inherit properties from other entities. You can specify a specific strategy
to use for inheritance.
Use this procedure to specify inheritance (@Inheritance) for an existing entity
(@Entity):
1.
Select the entity in the Project Explorer.
2.
In the JPA Details view, select the Inheritance information.
Figure 3–21 Specifying Inheritance
3.
In the Strategy list, select one of the following the inheritance strategies:
■
A single table (default)
■
Joined table
■
One table per class
Tasks 3-19
Specifying entity inheritance
4.
Use the following table to complete the remaining fields on the tab. See
"Inheritance information" on page 4-11 for additional details.
Property
Description
Discriminator
Column
Name of the discriminator column when using a
Single or Joined inheritance strategy.
Default
This field corresponds to the
@DiscriminatorColumn annotation.
Discriminator Type
Set the discriminator type to Char or Integer
(instead of its default: String). The
Discriminator Value must conform to this type.
Discriminator Value
Specify the discriminator value used to
differentiate an entity in this inheritance
hierarchy. The value must conform to the
specified Discriminator Type.
This field corresponds to the
@DiscriminatorValue annotation.
Override Default
Use this field to specify custom primary key join
columns.
This field corresponds to the
@PrimaryKeyJoinClumn annotation.
Eclipse adds the following annotations the entity field:
@Inheritance(strategy=InheritanceType.<INHERITANCE_STRATEGY>)
@DiscriminatorColumn(name="<DISCRIMINATOR_COLUMN>",
discriminatorType=<DISCRIMINATOR_TYPE>)
@DiscriminatorValue(value-"<DISCRIMINATOR_VALUE>")
@PrimaryKeyJoinColumn(name="<JOIN_COLUMN_NAME>",
referencedColumnName = "<REFERENCED_COLUMN_NAME>")
The following figures illustrates the different inheritance strategies.
Figure 3–22 Single Table Inheritance
3-20 Dali Java Persistence Tools User Guide
String
Creating Named Queries
Figure 3–23 Joined Table Inheritance
3.9 Creating Named Queries
Named queries improve application performance because they are prepared once and
they (and all of their associated supporting objects) can be efficiently reused thereafter,
making them well suited for complex and frequently executed operations. Named
queries use the JPA query language for portable execution on any underlying
database; named native queries use the SQL language native to the underlying
database.
Use this procedure to add @NamedQuery and @NamedNativeQuery annotations to
the entity.
To create a named query:
1.
Select the entity in the Project Explorer.
2.
In the JPA Details view, expand Queries.
3.
Click Add for a named query, or Add Native for a native query.
4.
In the dialog that appears, enter the name of the query in the Name field and then
click OK.
5.
Enter the query in the Query field.
6.
To add a Query hint, click Add.
Tasks 3-21
Mapping an entity
Figure 3–24 Entering a Named Query
3.10 Mapping an entity
Dali supports the following mapping types for Java persistent entities:
■
Basic mapping
■
Embedded mapping
■
Embedded ID mapping
■
ID mapping
■
Many-to-many mapping
■
Many-to-one mapping
■
One-to-many mapping
■
One-to-one mapping
■
Transient mapping
■
Version mapping
■
Element Collection mapping
Additional mapping types (such as Basic Collection mappings) may be available when
using Dali with EclipseLink.
3.10.1 Basic mapping
Use a Basic Mapping to map an attribute directly to a database column. Basic
mappings may be used only with the following attribute types:
■
Java primitive types and wrappers of the primitive types
■
java.lang.String, java.math.BigInteger
■
java.math.BigDecimal
■
java.util.Date
■
java.util.Calendar, java.sql.Date
3-22 Dali Java Persistence Tools User Guide
Mapping an entity
■
java.sql.Time
■
java.sql.Timestamp
■
byte[]
■
Byte[]
■
char[]
■
Character[]
■
enums
■
any other type that implements Serializable
To create a basic mapping:
1.
In the JPA Structure view, right-click the field to map. Select Map As > Basic. The
JPA Details view (for attributes) displays the properties for the selected field.
2.
Use this table to complete the remaining fields on the JPA Details view.
Property
Description
Default
Entity Map
Hyperlink
Defines this mapping as a Basic
Mapping.
Basic
This corresponds to the @Basic
annotation.
Column
The database column mapped to the
entity attribute. See "Column" on
page 4-12 for details.
Table
Name of the database table.
Fetch
Defines how data is loaded from the
database. See "Fetch Type" on
page 4-13 for details.
■
Eager
■
Lazy
Optional
Specifies if this field is can be null.
Type
Specifies the type of data:
■
■
■
■
By default, the Column is assumed
to be named identically to the
attribute and always included in the
INSERT and UPDATE statements.
Eager
Yes
Default
LOB – Specifies if this is a large
objects (BLOB or CLOB). See
"Lob" on page 4-13 for details.
Temporal – Specify if this is a
Date, Time, or Timestamp
object. See "Temporal" on
page 4-13 for details.
Enumerated – Specify how to
persist enumerated constraints
as ordinal or string, in order to
match an existing database
schema.
Eclipse adds the following annotations to the field:
@Column(name="<COLUMN_NAME>", table="<COLUMN_TABLE>",
insertable=<INSERTABLE>, updatable=<UPDATABLE>)
@Basic(fetch=FetchType.<FETCH_TYPE>, optional = <OPTIONAL>)
Tasks 3-23
Mapping an entity
@Temporal(TemporalType.<TEMPORAL>)
3.10.2 Embedded mapping
Use an Embedded Mapping to specify a persistent field or property of an entity
whose value is an instance of an embeddable class.
1.
In the JPA Structure view, right-click the field to map.
2.
Select Map as > Embedded. The JPA Details view (for attributes) displays the
properties for the selected field.
3.
Use this table to complete the remaining fields on the JPA Details view.
Property
Description
Default
Entity Mapping
Hyperlink
Defines this mapping as a Embedded.
Embedded
Attribute
Overrides
Specify to override the default
mapping of an entity’s attribute. Select
Override Default.
This corresponds to the @Embedded
annotation.
Eclipse adds the following annotations to the field:
@Embedded
@AttributeOverride(column=@Column(table="<COLUMN_TABLE>", name = "<COLUMN_NAME>"))
3.10.3 Embedded ID mapping
Use an Embedded ID Mapping to specify the primary key of an embedded ID. These
mappings may be used with a Embeddable entities.
1.
In the JPA Structure view, select the field to map.
2.
Right-click the field and then select Map As > Embedded Id. The JPA Details view
(for attributes) displays the properties for the selected field.
3.
Use this table to complete the remaining fields on the JPA Details view.
Property
Description
Default
Entity Mapping
Hyperlink
Defines this mapping as a Embedded
Id.
Embedded Id
This corresponds to the @EmbeddedId
annotation.
Eclipse adds the following annotations to the field:
@EmbeddedId
3.10.4 ID mapping
Use an ID Mapping to specify the primary key of an entity. ID mappings may be used
with a Entity or Mapped superclass. Each Entity must have an ID mapping.
3-24 Dali Java Persistence Tools User Guide
Mapping an entity
1.
In the JPA Structure view, select the field to map.
2.
Right click the filed and then select Map as > ID. The JPA Details view (for
attributes) displays the properties for the selected.
3.
Use this table to complete the General information fields in the JPA Details view.
Property
Description
Default
Entity Mapping
Hyperlink
Defines this mapping as an ID
Mapping.
ID
This field corresponds to the @Id
annotation.
Column
The database column mapped to the
entity attribute. See "Column" on
page 4-12 for details.
By default, the Column is
assumed to be named
identically to the attribute.
Table
The database table mapped to the
entity attribute.
By default, the Table is assumed
to be identical to the table
associated with the entity.
Temporal
Specifies the type of data. See
"Temporal" on page 4-13 for details.
4.
■
Date
■
Time
■
Timestamp
Use this table to complete the fields in Primary Key Generation information area
in the JPA Details view.
Property
Description
Primary Key
Generation
These fields define how the primary
key is generated.
Strategy
Generator Name
See "Primary Key Generation" on
page 4-15 for details.
■
Auto
■
Sequence
■
Identity
■
Table
Default
Auto
Name of the primary key generator
specified in the Strategy
Additional fields will appear in the Primary Key Generation information area,
depending on the selected Strategy. See "JPA Details view (for attributes)" on page 4-12
for additional information.
Eclipse adds the following annotations to the field:
@Id
@Column(name="<COLUMN_NAME>", table="<TABLE_NAME>", insertable=<INSERTABLE>,
updatable=<UPDATABLE>)
@Temporal(<TEMPORAL>)
@GeneratedValue(strategy=GeneratorType.<STRATEGY>, generator="<GENERATOR_NAME>")
@TableGenerator(name="<TABLE_GENERATOR_NAME>", table = "<TABLE_GENERATOR_TABLE>",
pkColumnName = "<TABLE_GENERATOR_PK>",
valueColumnName = "<TABLE_GENERATOR_VALUE_COLUMN>",
Tasks 3-25
Mapping an entity
pkColumnValue = "<TABLE_GENERATOR_PK_COLUMN_VALUE>")
@SequenceGenerator(name="<SEQUENCE_GENERATOR_NAME>",
sequenceName="<SEQUENCE_GENERATOR_SEQUENCE>")
3.10.5 Many-to-many mapping
Use a Many-to-Many Mapping to define a many-valued association with
many-to-many multiplicity. A many-to-many mapping has two sides: the owning side
and non-owning side. You must specify the join table on the owning side. For
bidirectional mappings, either side may be the owning side.
1.
In the JPA Structure view, select the field to map.
2.
Right-click the field and then select Map As > Many-to-Many. The JPA Details
view (for attributes) displays the properties for the selected field.
3.
Use this table to complete the General information fields of the JPA Details view.
Property
Description
Default
Mapping Entity
Hyperlink
Defines this mapping as a Many to
Many Mapping.
Many to Many
This field corresponds to the
@ManyToMany annotation.
Target Entity
Fetch
The entity to which this attribute is
mapped.
null
Defines how data is loaded from the
database. See "Fetch Type" on
page 4-13 for details.
Lazy
■
Eager
■
Lazy
Mapped By
The database field that owns the
relationship.
Order By
Specify the default order for objects
returned from a query. See "Order
By" on page 4-14 for details.
4.
■
No ordering
■
Primary key
■
Custom
You do not need to explicitly specify
the target entity, since it can be
inferred from the type of object being
referenced.
No ordering
Use this table to complete the fields in the Join Table Information area in the JPA
Details view.
Property
Description
Default
Name
Name of the join table that contains the
foreign key column.
You must specify the join table on
the owning side.
By default, the name is assumed to
be the primary tables associated
with the entities concatenated with
an underscore.
3-26 Dali Java Persistence Tools User Guide
Mapping an entity
Property
Description
Default
Join Columns
Select Override Default, then Add,
Edit, or Remove the join columns.
By default, the name is assumed to
be the primary tables associated
with the entities concatenated with
an underscore.
Inverse Join
Columns
Select Override Default, then Add,
Edit, or Remove the join columns.
By default, the mapping is
assumed to have a single join.
5.
To add a new Join or Inverse Join Column, click Add.
To edit an existing Join or Inverse Join Column, select the field to and click Edit.
Eclipse adds the following annotations to the field:
@JoinTable(joinColumns=@JoinColumn(name="<JOIN_COLUMN>"),
name = "<JOIN_TABLE_NAME>")
@ManyToMany(cascade=CascadeType.<CASCADE_TYPE>, fetch=FetchType.<FETCH_TYPE>,
targetEntity=<TARGET_ENTITY>, mappedBy = "<MAPPED_BY>")
@OrderBy("<ORDER_BY>")
3.10.6 Many-to-one mapping
Use a Many-to-One mapping to defines a single-valued association to another entity
class that has many-to-one multiplicity.
1.
In the JPA Structure view, select the field to map.
2.
Right click the field and then select Map As > Many-to-One. The JPA Details view
(for attributes) displays the properties for the selected.
3.
Use this table to complete the General information fields JPA Details view.
Property
Description
Default
Mapping Entity
Hyperlink
Defines mapping as Many-to-One.
This corresponds to the
@ManyToOne annotation.
Many-to-One
Target Entity
The entity to which this attribute is
mapped.
null
Defines how data is loaded from the
database. See "Fetch Type" on
page 4-13 for details.
Eager
Fetch
Cascade
■
Eager
■
Lazy
See "Cascade Type" on page 4-14 for
details.
■
Default
■
All
■
Persist
■
Merge
■
Remove
You do not need to explicitly specify
the target entity, since it can be
inferred from the type of object being
referenced.
Default
Tasks 3-27
Mapping an entity
Property
Description
Default
Optional
Specifies if this field is can be null.
Yes
4.
Use this table to complete the fields on the Join Columns Information tab in the
JPA Details view.
Property
Description
Default
Join Column
Specify a mapped column for joining
an entity association. This field
corresponds to the @JoinColum
attribute.
By default, the mapping is assumed
to have a single join.
Select Override Default, then Add,
Edit, or Remove the join columns.
Eclipse adds the following annotations to the field:
@JoinTable(joinColumns=@JoinColumn(name="<JOIN_COLUMN>"),
name = "<JOIN_TABLE_NAME>")
@ManyToOne(targetEntity=<TARGET_ENTITY>, fetch=<FETCH_TYPE>,
cascade=<CASCADE_TYPE>)
3.10.7 One-to-many mapping
Use a One-to-Many Mapping to define a relationship with one-to-many multiplicity.
1.
In the JPA Structure view, select the field to map.
2.
Right-click the field and then select Map As > One-to-many. The JPA Details view
(for attributes) displays the properties for the selected.
3.
Use this table to complete the General information fields JPA Details view.
Property
Description
Default
Mapping Entity
Type Hyperlink
Defines mapping as One-to-Many.
This corresponds to the @OneToMany
annotation.
One-to-Many
Target Entity
The entity to which this attribute is
mapped.
Cascade
See "Cascade Type" on page 4-14 for
details.
Fetch
■
Default
■
All
■
Persist
■
Merge
■
Remove
Defines how data is loaded from the
database. See "Fetch Type" on
page 4-13 for details.
■
Eager
■
Lazy
3-28 Dali Java Persistence Tools User Guide
Eager
Mapping an entity
Property
Description
Mapped By
The database field that owns the
relationship.
Order By
Specify the default order for objects
returned from a query. See "Order By"
on page 4-14 for details.
4.
■
No ordering
■
Primary key
■
Custom
Default
No ordering
Use this table to complete the Join Table Information fields in the JPA Details view.
Property
Description
Default
Name
Name of the join table
By default, the name is assumed to
be the primary tables associated
with the entities concatenated with
an underscore.
Join Columns
Specify two or more join columns (that
is, a primary key).
Inverse Join
Columns
The join column on the owned (or
inverse) side of the association: the
owned entity’s primary key column.
Eclipse adds the following annotations to the field:
@OneToMany(targetEntity=<TARGET_ENTITY>)
@Column(name="<COLUMN>")
@OneToMany(targetEntity=<TARGET_ENTITY>.class, cascade=CascadeType.<CASCADE_TYPE>,
fetch = FetchType.<FETCH_TYPE>, mappedBy = "<MAPPED_BY>")
@OrderBy("<ORDER_BY>")
@JoinTable(name="<JOIN_TABLE_NAME>", joinColumns=@JoinColumn(name=
"<JOIN_COLUMN_NAME>", referencedColumnName="<JOIN_COLUMN_REFERENCED_COLUMN>"),
inverseJoinColumns=@JoinColumn(name="<INVERSE_JOIN_COLUMN_NAME>",
referencedColumnName="<INVERSE_JOIN_COLUMN_REFERENCED_COLUMN>"))
3.10.8 One-to-one mapping
Use a One-to-One Mapping to define a relationship with one-to-many multiplicity.
1.
In the JPA Structure view, select the field to map.
2.
Right-click the field and then select Map As > One-to-One. The JPA Details view
(for attributes) displays the properties for the selected.
3.
Use this table to complete the General information fields in the JPA Details view.
Property
Description
Default
Mapped Entity
Hyperlink
Defines mapping as One-to-One.
This corresponds to the @OneToOne
annotation.
One-to-One
Tasks 3-29
Mapping an entity
Property
Description
Default
Target Entity
The entity to which this attribute is
mapped.
null
Defines how data is loaded from the
database. See "Fetch Type" on
page 4-13 for details.
Eager
Fetch Type
Mapped By
4.
■
Eager
■
Lazy
You do not need to explicitly specify
the target entity, since it can be
inferred from the type of object being
referenced.
The database field that owns the
relationship.
Use this table to complete the Join Columns Information fields in the JPA Details
view.
Property
Description
Default
Join Column
Specify a mapped column for joining
an entity association. This field
corresponds to the @JoinColum
attribute.
By default, the mapping is assumed
to have a single join.
Select Override Default, then Add,
Edit, or Remove the join columns.
Eclipse adds the following annotations to the field:
@OneToOne(targetEntity=<TARGET_ENTITY>, cascade=CascadeType.<CASCADE_TYPE>,
fetch = FetchType.<FETCH_TYPE>, mappedBy = "<MAPPED_BY>")
@JoinColumn(name="<JOIN_COLUMN_NAME>", referencedColumnName=
"<JOIN_COLUMN_REFERENCED_COLUMN>", insertable = <INSERTABLE>,
updatable = <UPDATABLE>)
3.10.9 Transient mapping
Use the Transient Mapping to specify a field of the entity class that is not persistent.
To create a transient mapping:
1.
In the JPA Structure view, select the field to map.
2.
Right-click the field and then select Map As Transient. The JPA Details view (for
attributes) displays the properties for the selected.
Eclipse adds the following annotation to the field:
@Transient
3.10.10 Version mapping
Use a Version Mapping to specify the field used for optimistic locking. If the entity is
associated with multiple tables, you should use a version mapping only with the
3-30 Dali Java Persistence Tools User Guide
Generating entities from tables
primary table. You should have only a single version mapping per persistent entity.
Version mappings may be used only with the following attribute types:
■
int
■
Integer
■
short, Short
■
long, Long
■
Timestamp
To create a version mapping:
1.
In the JPA Structure view, select the field to map.
2.
Right-click the field and then select Map As > Version. The JPA Details view (for
attributes) displays the properties for the selected.
3.
Use this table to complete the remaining fields in the JPA Details view.
Property
Description
Default
Mapped Entity
Hyperlink
Defines the mapping as Version. This
corresponds to the @Version
annotation.
Version
Column
The database column mapped to the
entity attribute. See "Column" on
page 4-12 for details.
By default, the Column is assumed
to be named identically to the
attribute and always included in
the INSERT and UPDATE
statements.
Table
Name of the database table. This must
be the primary table associated with
the attribute’s entity.
Temporal
Specifies the type of data. See
"Temporal" on page 4-13 for details.
■
Date
■
Time
■
Timestamp
Eclipse adds the following annotations to the field:
@Version
@Column(table="<COLUMN_TABLE>", name="<COLUMN_NAME>")
3.10.11 Element Collection mapping
3.11 Generating entities from tables
Use this procedure to generate Java persistent entities from database tables. You must
create a JPA project and establish a database connection before generating persistent
entities. See "Creating a new JPA project" on page 3-1 for more information.
1.
Right-click the JPA project in the Project Explorer and select JPA Tools > Generate
Entities from Tables.
Tasks 3-31
Generating entities from tables
Figure 3–25 Generating Entities
2.
On the Select Tables page, select your database connection and schema.
To create a new database connection, click Add connection.
If you are not currently connected to the database, the Database Connection page
appears. Select your database connection and schema, and click Reconnect.
Figure 3–26 Select Tables
3.
After selecting a schema, select the tables from which to generate Java persistent
entities and click Next.
4.
On the Table Associations page, select the associations to generate. You can specify
to generate specific references for each association.
To create a new association, click Add Association. Use the Create New
Association wizard to define the association.
3-32 Dali Java Persistence Tools User Guide
Generating entities from tables
Figure 3–27 Table Associations
5.
After editing the table associations, click Next.
6.
On the Customize Default Entity Generation page, customize the mapping and
class information for each generated entity.
Tasks 3-33
Generating entities from tables
Figure 3–28 Customize Default Entity Generation
7.
After customizing the mappings, click Next.
8.
On the Customize Individual Entities page, review the mapping and class
information for each entity that will be generated, then click Finish.
3-34 Dali Java Persistence Tools User Guide
Generating entities from tables
Figure 3–29 Customize Individual Entities
Eclipse creates a Java persistent entity for each database table. Each entity contains
fields based on the table’s columns. Eclipse will also generate entity relationships
(such as one-to-one) based on the table constraints. Figure 3–30 illustrates how Eclipse
generates entities from tables.
Figure 3–30 Generating Entities from Tables
Tasks 3-35
Generating tables from entities
3.12 Generating tables from entities
When using a vendor-specific platform, you can create a DDL script from your
persistent entities.
Note: The DDL script with DROP existing tables on the database and
CREATE new tables, based on the entities in your project.
To generate a DDL script:
Right-click the JPA project in the Project Explorer and select JPA Tools > Generate
Tables from Entities.
3.13 Validating mappings and reporting problems
Errors and warnings on persistent entities and mappings are indicated with a red error
or yellow warning next to the resource with the error, as well as the parent containers
up to the project.
Figure 3–31 Sample Errors and Warnings
This section contains information on the following:
■
Error messages
■
Warning messages
3.13.1 Error messages
This section contains information on error messages (including how to resolve the
issue) you may encounter while working with Dali.
Attribute "<ATTRIBUTE__NAME>" has invalid mapping type in this context
The mapped attribute is invalid. Either change the mapping type or change the entity
type.
See "Mapping an entity" on page 3-22 for more information.
3-36 Dali Java Persistence Tools User Guide
Validating mappings and reporting problems
Attribute "<ATTRIBUTE_NAME>" cannot be resolved.
Dali cannot map the attribute to a database table and column. Verify that you database
connection information is correct.
See "Creating a new JPA project" on page 3-1 for more information.
Class "<CLASS_NAME>" is not annotated as a persistent class.
The class has not been identified as a persistent class. Configure the class as an Entity,
Mapped Superclass, or Embeddable persistent entity.
See "Adding persistence to a class" on page 3-15.
Column "<COLUMN_NAME>" cannot be resolved.
You mapped an entity’s field to an incorrect or invalid column in the database table.
By default, Dali will attempt to map each field in the entity with an identically named
row in the database table. If the field’s name differs from the row’s name, you must
explicitly create the mapping.
Map the field to a valid row in the database table as shown in "Mapping an entity" on
page 3-22.
Duplicate class "<CLASS_NAME>".
You created to persistence classes with the same name. Each Java class must have a
unique name. See "Adding persistence to a class" on page 3-15 for more information.
Entity does not have an Id or Embedded Id.
You created a persistent entity without identifying its primary key. A persistent entity
must have a primary key field designated with an @Id or @EmbeddedId annotation.
Add an ID mapping to the entity as shown in "ID mapping" on page 3-24 or
"Embedded ID mapping" on page 3-24.
Multiple persistence.xml files in project.
You created a JPA project with more than one persistence.xml file. Each JPA
project must contain a single persistence.xml file.
See "Managing the persistence.xml file" on page 3-10 for more information.
No persistence unit defined.
There is no persistence unit defined in the persistence.xml file. Use the
<persistence-unit name="<PERSISTENCE_UNIT_NAME>" tag to define the persistent
unit.
See "Managing the orm.xml file" on page 3-13 for more information.
No persistence.xml file in project.
You created a JPA project without a persistence.xml file. Each JPA project must
contain a single persistence.xml file.
See "Managing the persistence.xml file" on page 3-10 for more information.
Referenced column "<COLUMN_NAME>" in join column "<COLUMN_NAME>"
cannot be resolved.
The column that you selected to join a relationship mapping does not exist on the
database table. Either select a different column on the Join Table Information or create
the necessary column on the database table.
Tasks 3-37
Modifying persistent project properties
See "JPA Details view (for attributes)" on page 4-12 for more information.
Schema "<SCHEMA_NAME>" cannot be resolved for table/join table "<TABLE_
NAME>".
Define the default database schema information in the persistence unit.
See "Managing the orm.xml file" on page 3-13 for more information.
Table "<TABLE_NAME>" cannot be resolved.
You associated a persistent entity to an incorrect or invalid database table. By default,
Dali will attempt to associate each persistent entity with an identically named
database table. If the entity’s name differs from the table’s name, you must explicitly
create the association.
Associate the entity with a valid database table as shown in "Adding persistence to a
class" on page 3-15.
Unresolved generator "<GENERATOR_NAME>" is defined in persistence unit.
You created a persistence entity that uses sequencing or a table generator, but did not
define the generator in the persistence unit. Either define the generator by using an
annotation or including it in the XML mapping file.
3.13.2 Warning messages
This section contains information on warning messages (including how to resolve the
issue) you may encounter while working with Dali.
Connection "<CONNECTION_NAME>" is not active. No validation will be done
against the data source.
The database connection you specified to use with the JPA project is not active. The
JPA project requires an active connection.
No connection specified for the project. No data-specific validation will be
performed.
You created a JPA project without specifying a database connection. The JPA project
requires an active connection.
See "Creating a new JPA project" on page 3-1 or "Modifying persistent project
properties" on page 3-38 for information on specifying a database connection.
3.14 Modifying persistent project properties
Each persistent project must be associated with a database connection. To create a new
database connection, click Database Connection use the New Connection wizard.
Use this procedure to modify the vender-specific platform and database connection
associated with your JPA project.
3-38 Dali Java Persistence Tools User Guide
Generating Schema from Classes
1.
Right-click the project in the Explorer view and select Properties. The Properties
page appears.
Figure 3–32 The Properties Page
2.
Complete each field on the Project Properties page – Java Persistence Options click
OK.
See "Project Properties page – Java Persistence Options" on page 4-31 for more
information.
3.15 Generating Schema from Classes
Use the Generate Schema from JAXB Classes wizard create an XML schema ( .xsd) for
a set of JAXB mapped classes.
1.
From the Navigator or Project Explorer, select File > New > Other. The Select a
wizard dialog appears.
Tip: You can also access the Generate Schema from JAXB Classes
wizard from a specific project or package.
Tasks 3-39
Generating Schema from Classes
Figure 3–33 Selecting the Schema from JAXB Classes wizard
2.
Select JAXB > Schema from JAXB Classes and then click Next. The Generate
Schema from Classes page of the Generate Schema from JAXB Classes Wizard
appears.
Figure 3–34 The Generate Schema from Classes Page
3.
Select the project, package, or classes from which to generate the schema and click
Finish.
3-40 Dali Java Persistence Tools User Guide
Generating JAXB Classes from a Schema
3.16 Generating JAXB Classes from a Schema
Use the Generate Classes from XSD dialog to generate JAXB classes from an XML
schema ( .xsd).
1.
From the Navigator or Project Explorer, right-click a schema ( .xsd file) and select
Generate > JAXB Classes. The Generate Classes from Schema dialog appears.
Figure 3–35 Configure JAXB Class Generation dialog
2.
Enter the JAXB settings information and click Finish.
Tasks 3-41
Generating JAXB Classes from a Schema
3-42 Dali Java Persistence Tools User Guide
4
Reference
This section includes detailed help information for each of the following elements in
the Dali OR Mapping Tool:
■
Wizards
■
Property pages
■
Preferences
■
Dialogs
■
JPA Development perspective
■
Icons and buttons
■
Dali Developer Documentation
4.1 Wizards
This section includes information on the following wizards:
■
Create New JPA Project wizard
■
Create JPA Entity wizard
■
Generate Tables from Entities Wizard
■
Generate Entities from Tables Wizard
■
Create New Association
■
Generate Schema from JAXB Classes Wizard
4.1.1 Create New JPA Project wizard
The Create New JPA Project wizard allows you to create a new Java project using JPA.
The wizard consists of the following pages:
■
New JPA Project page
■
Java Page
■
JPA Facet page
4.1.1.1 New JPA Project page
This table lists the properties available on the New JPA Project page of the Create New
JPA Project wizard.
Reference 4-1
Wizards
Property
Description
Project name
Name of the Eclipse JPA project.
Project contents
Location of the workspace in which to save the
project.
Default
Current workspace
Unselect The Use Default option and click
Browse to select a new location.
Target runtime
Select a pre-defined target for the project.
Click New to create a new environment with
the New Server Runtime wizard.
Configurations
Select a project configuration with pre-defined
facets.
Utility JPA project
with Java 5.0
Select <custom> to manually select the facets
for this project.
EAR membership
Specify if this project should be included in an
EAR file for deployment.
Select the EAR Project Name, or click New to
create a new EAR project.
Working sets
Specify if this project should be included in an
existing working set. The drop down field
shows a list of previous selected working sets.
Select Add project to working sets, then select
a working set in which to add this project.
4.1.1.2 Java Page
This table lists the properties available on the Java page of the Create New JPA Project
wizard.
Property
Description
Default
Source folders on
build path
Click Add Folder to select an existing Java
source folder to add to this project.
EclipseLink
Default output
folder
Specify the location of the .class files.
build\classes
4.1.1.3 JPA Facet page
This table lists the properties available on the JPA Facet page of the Create New JPA
Project wizard.
Property
Description
Default
Platform
Vendor-specific JPA implementation.
EclipseLink
JPA Implementation
Select a specific JPA library configuration.
Click Manage libraries to create or update a
user library.
Click Download libraries to download a
specific library configuration.
4-2 Dali Java Persistence Tools User Guide
Wizards
Property
Type
Description
Default
Select User Library to select from the available
user-defined or downloaded libraries.
User Library
If you select Disable, you must manually
include the JPA implementation library on the
project classpath.
Include libraries
Specify if the selected libraries are included
with this application when deploying the application.
Connection
Selected
Select the database connection to use with the
project. Dali requires an active database
connection to use and validate the persistent
entities and mappings.
Click Add connection to create a new database
connection.
Override default
schema from
connection
Select a schema other than the default one that
is derived from the connection information.
Use this option if the default schema cannot be
used. For example, use this option when the
deployment login differs from the design-time
login.
The value calculated
by Dali.
JPA Implementation
Select to use the JPA implementation provided
by the server at runtime, or select a specific
implementation library that contain the Java
Persistence API (JPA) and entities to be added
to the project’s Java Build Path.
Determined by
server.
Click Configure default JPA implementation
library to create a default library for the project
or click Configure user libraries to define
additional libraries.
Depending on your JPA implementation (for
example, Generic or EclipseLink), different
options may be available when working with
JPA projects.
Persistent class
management
Specify if Dali will discover annotated classes
automatically, or if the annotated classes must
be listed in the persistence.xml file.
Determined by
server.
Note: To insure application portability, you
should explicitly list the managed persistence
classes that are included in the persistence unit.
Create orm.xml
Specify if Dali should create a default orm.xml
file for your entity mappings and persistence
unit defaults.
Selected
4.1.2 Create JPA Entity wizard
The Create JPA wizard enables you to quickly add an entity and also add persistence
fields to that entity. In addition, this wizard adds the accessor methods (getter and
setter) in the class file. The wizard consists of the following pages:
■
Entity Class page
■
Entity Properties page
Reference 4-3
Wizards
4.1.2.1 Entity Class page
This table lists the properties of the Entity Class page of the Create JPA Entity wizard.
Property
Description
Default
Project
The name of the JPA project.
Source Folder
The location of the JPA project’s src folder.
Java Package
The name of the class package.
Class name
The name of the Java class.
Superclass
Select the superclass.
Inheritance
Because the wizard creates a Java class with an
@Entity notation, the Entity option is selected by
default.
Entity
Select Mapped Superclass if you defined a superclass.
To add an @Inheritance notation to the entity, select
Inheritance and then select one of the inheritance
mapping strategies (described in JSR 220):
SINGLE_TABLE -- All classes in a hierarchy as
mapped to a single table. This annotation is without
an attribute for the inheritance strategy.
■
TABLE_PER_CLASS -- Each class is mapped to a
separate table.
■
JOINED -- The root of the class hierarchy is
represented by a single table. Each subclass is
represented by a separate table that contains those
fields that are specific to the subclass (not inherited
from its superclass), as well as the column(s) that
represent its primary key. The primary key
column(s) of the subclass table serves as a foreign
key to the primary key of the superclass table.
■
XML Entity
Mappings
Select Add to entity mappings in XML to create XML
mappings in orm.xml, rather than annotations.
Use the Mapping file field to specify the file to use. By
default, mappings are stored in the
META-INF/orm.xml file.
4.1.2.2 Entity Properties page
This table lists the properties of the Entity Properties page of the Create JPA Entity
wizard.
Table 4–1
Property
Description
Entity Name
The name of the entity. By default, this value is Determined by
the same as the one entered as the class name. If server.
the entity name differs from the class name,
then the entity name is added as an attribute.
For example:
@Entity(name="EntityName").
4-4 Dali Java Persistence Tools User Guide
Default
Wizards
Table 4–1 (Cont.)
Property
Description
Default
Table Name
Select Use default to match the name of the
mapped table name to the entity name.
Otherwise, clear the Use default option and
enter the name in the Table Name field. These
options result in the addition of the @Table
option to the Java class file.
Use default.
Entity Fields
Click the Add button to add persistence fields
using the Entity Fields dialog. This dialog
enable you to build a field by entering a field
name and selecting among persistence types.
The Key option enables you to mark a field as a
primary key. The dialog’s Browse function
enables you to add other persistence types
described in the JPA specification. The Edit
button enables you to change the name or type
set for a persistent field.
Access Type
Select whether the entity’s access to instance
variables is field-based or property-based, as
defined in the JPA specification.
■
■
Field
Field – Instance variables are accessed
directly. All non-transient instance
variables are persistent.
Property – Persistent state accessed
through the property accessor methods.
The property accessor methods must be
public or private.
4.1.3 Mapping File Wizard
The Mapping File wizard enables you to add an orm.xml file to a JPA project if no
object map exists at the location specified. For example, if you cleared the Create
orm.xml option on the JPA Facet page, you can later add the orm.xml file to the src
file of the project using this wizard.
The Mapping File Wizard consists of the Mapping File page.
4.1.3.1 Mapping File
This table lists the properties of the Mapping File Wizard.
Table 4–2
Mapping File Wizard Properties
Property
Description
Default
Project
The name of the JPA project.
Selected.
Source folder
The location of the project’s src folder. If
Selected.
needed, click Browse to point the wizard to the
src file’s location.
File Path
The location for the new orm.xml file.
Selected.
Reference 4-5
Wizards
Table 4–2 (Cont.) Mapping File Wizard Properties
Property
Description
Default Access
Select whether the access to the entity is
None
field-based or property-based, as defined in JPA
specification.
■
■
■
Add to persistence
unit
Default
None – No access type specified.
Property-based – Persistent state accessed
through the property accessor methods.
The property accessor methods must be
public or private.
Field-based – Instance variables are
accessed directly. All non-transient
instance variables are persistent.
Designates the persistence unit for this object
map file.
Selected.
4.1.4 Generate Tables from Entities Wizard
Use the Generate DDL from Entities Wizard to quickly create DDL scripts from your
persistent entities. Dali automatically creates the necessary primary and foreign keys,
based on the entity mappings.
4.1.5 Generate Entities from Tables Wizard
Use the Generate Custom Entities Wizard to create entities from your database tables.
The wizard consists of the following pages:
■
Select Tables
■
Table Associations
■
Customize Default Entity Generation
■
Customize Individual Entities
4.1.5.1 Select Tables
Use the Select Tables dialog to specify the database connection and tables from which
to create entities.
Property
Description
Connection
Select a database connection or click Add Connection to create
a new connection.
Schema
Select the database schema from which to select tables.
Tables
Select the tables from which to create Java persistent entities.
The tables shown are determined by the database connection
and schema selections.
4-6 Dali Java Persistence Tools User Guide
Wizards
Property
Description
Synchronize Classes listed
in persistence.xml
Specify if Dali should update the persistence.xml file to
include the generated classes.
4.1.5.2 Table Associations
Use this page to create or edit the association between the database table and entity.
Property
Description
Table associations
Select an association to modify or click to create a new table
association with the Create New Association wizard.
Generate this association
Specify if Dali should create the selected association. If enabled,
you can specify the Cardinality and Join table for the table
association.
Generate a reference to
<ROW> in <TABLE>
Specify if the entity should contain a reference to the specified
table.
If enabled, you can also enter the Property name and select the
Cascade method (all, persist, merge, remove, or refresh) for the
reference.
4.1.5.3 Customize Default Entity Generation
Use this page to specify the default information Dali will use when generating the
entities from the database tables. You will be able to override this information for
specific entities.
Property
Description
Table Mapping
Use these options to define the table mapping information for
the entity.
Key generator
Sequence name
Select the generator used for this mapping.
Enter a name for the sequence.
You can use $table and $pk as variables in the name. These will
be replaced by the table name and primary key column name
(respectively) when Dali generates a table mapping.
Entity access
Specify the default entity access method: Field (default) or
Property.
Associations fetch
Specify the default fetch mode for associations: Default, as
defined by the application (default), or Lazy.
Collection type
Specify if the collection properties are a Set or List.
Enable the Always generate optional JPA annotations and
DDL parameters option to have Dali include this information
in the entity.
Domain Java Class
Use these options to define the class information (Package,
Superclass, and Interfaces) for the entity.
Reference 4-7
Wizards
4.1.5.4 Customize Individual Entities
Use this page to customize each generated entity. Select an item in the Table and
columns area, then complete the following fields for each item.
Property
Description
Table Mapping
Use these options to define the table mapping information for
the entity.
Key generator
Sequence name
Select the generator used for this mapping.
Enter a name for the sequence.
You can use $table and $pk as variables in the name. These will
be replaced by the table name and primary key column name
(respectively) when Dali generates a table mapping.
Entity access
Domain Java Class
Specify the default entity access method: Field (default) or
Property.
Use these options to define the class information (Superclass
and Interfaces) for the entity.
4.1.6 Create New Association
Use the Create New Association wizard to specify association tables when generating
an entity.
The wizard consists of the following pages:
■
Association Tables
■
Join Columns
■
Association Cardinality
4.1.6.1 Association Tables
Use this page to specify the association tables for an entity.
Property
Description
Association kind
Specify if the association is Simple (1:M) or Many to Many
(M:M).
Association tables
Click Table Selection, then select the two tables to associate.
When creating a Many to Many association, you can select a
Join Table for the association.
4.1.6.2 Join Columns
Use this dialog to specify the join columns of an association table.
4-8 Dali Java Persistence Tools User Guide
Property pages
Click Add to specify the join columns between the two tables.
4.1.6.3 Association Cardinality
Use this dialog to specify cardinality of an association table. Depending on the
Association Kind and Join Columns that you selected previously, some associations
may not be available.
■
Many to one
■
One to many
■
One to one
■
Many to many
4.1.7 Generate Schema from JAXB Classes Wizard
Use the Generate Schema from JAXB Classes wizard create an XML schema ( .xsd) for
a set of JAXB mapped classes.
The wizard consists of the following pages:
■
Generate Schema from Classes
4.1.7.1 Generate Schema from Classes
Use this dialog to select the classes from which to generate a schema. You can select an
entire project, a package, or specific classes.
4.2 Property pages
This section includes information on the following:
■
JPA Details view (for entities)
■
JPA Details view (for attributes)
■
JPA Details view (for orm.xml)
■
JPA Structure view
4.2.1 JPA Details view (for entities)
The JPA Details view displays the persistence information for the currently selected
entity and contains the following tabs:
■
General information
■
Attribute overrides
Reference 4-9
Property pages
■
Secondary table information
■
Inheritance information
4.2.1.1 General information
This table lists the General information fields available in the JPA Details view for each
entity type.
Property
Description
Default
Available for Entity Type
Mapping Type
Hyperlink
Clicking the name of the mapping type, which
is represented as a hyperlink, invokes the
Mapping Type Selection dialog. Use this dialog
to specify the type of entity: Mapped
Superclass, Embeddable or the default
mapping type.
Entity
Entity, Embeddable, and
Mapped superclass
Table
The default database table information for this
entity. These fields can be overridden by the
information in the Attribute overrides area.
Entity
Name
The name of the primary database table
associated with the entity.
Entity
Catalog
The database catalog that contains the Table.
As defined in
orm.xml.
Entity
Schema
The database schema that contains the Table.
As defined in
orm.xml.
Entity
Name
The name of this entity. By default, the class
name is used as the entity name.
Access
The access method for this entity.
Primary key cla
ss
Click Browse and select the primary key for the
entity. Clicking the field name, which is
represented as a hyperlink, allows you to create
a new class.
Cachable
Specifies if the entity is cachable.
Entity
Field
Entity
@Cachable(false)
Entity
This field corresponds to the @Cachable
annotation.
4.2.1.2 Attribute overrides
Use the Attribute Overrides area in the JPA Details view to override the default
settings specified in the General information area of an attribute. Attribute overrides
generally override/configure attributes that are inherited or embedded.
This table lists the Attribute override fields available in the JPA Details view for each
entity type.
Property
Description
Attribute
Overrides
Specify a property or field to be overridden
(from the default mappings). Select Override
Default.
Join Columns
Specify the joining strategy. Select Override
Default to add a different joining strategy.
4-10 Dali Java Persistence Tools User Guide
Default
Available for Entity Type
Entity
Join columns
Entity
Property pages
4.2.1.3 Secondary table information
Use the Secondary Tables area in the JPA Details view to associate additional tables
with an entity. Use this area if the data associated with an entity is spread across
multiple tables.
Refer to "Specifying additional tables" on page 3-19 for additional information.
4.2.1.4 Inheritance information
This table lists the fields available on the Inheritance area in the JPA Details view for
each entity type.
Property
Description
Default
Strategy
Specify the strategy to use when mapping a
class or class hierarchy:
Single table
■
■
■
Single table – All classes in the hierarchy
are mapped to a single table.
Joined – The root of the hierarchy is
mapped to a single table; each child maps
to its own table.
Table per class – Each class is mapped to a
separate table.
This field corresponds to the @Inheritance
annotation.
Discriminator Value
Specify the discriminator value used to
differentiate an entity in this inheritance
hierarchy. The value must conform to the
specified Discriminator Type.
Discriminator
Column
These fields are available when using a Single
or Joined inheritance strategy.
This field corresponds to the
@DiscriminatorColumn annotation.
Use the Details area to define the Length and
Column definition of this Discriminator
Column.
Name
Name of the discriminator column
Type
Set this field to set the discriminator type to
Char or Integer (instead of its default:
String). The Discriminator Value must
conform to this type.
Primary Key Join
Columns
String
Use to override the default primary key join
columns. Select Override Default, then click
Add to select new Join Column.
This field corresponds with
@PrimaryKeyJoinColumn annotation.
Refer to "Specifying entity inheritance" on page 3-19 for additional information.
Reference 4-11
Property pages
4.2.1.5 Queries
Use the queries area of the JPA Details view to create named queries and named native
queries. Refer to "Creating Named Queries" on page 3-21 for additional information.
4.2.2 JPA Details view (for attributes)
The JPA Details view displays the persistence information for the currently selected
mapped attribute and contains the following areas:
■
General information
■
Join Table Information
■
Join Columns Information
■
Primary Key Generation information
See "Mapping an entity" on page 3-22 for more information.
4.2.2.1 General information
This table lists the General properties available in the Java Details view for each
mapping type.
Property
Description
Default
Available for
Mapping Type
Mapping Type
Hyperlink
Clicking the name of the mapping
type, which is represented as a
hyperlink, invokes the Mapping
Type Selection dialog. Use this
dialog to specify the type of
attribute.
Basic
All mapping types
Column
The database column that
contains the value for the
attribute. This field corresponds
to the @Column annotation.
By default, the Column is
assumed to be named
identically to the attribute.
Basic mapping,
Embedded mapping,
ID mapping, Version
mapping
Name
Name of the database column.
Basic mapping,
Embedded mapping,
ID mapping
This field corresponds to the
@Column annotation.
Table
Name of the database table that
contains the selected column.
Insertable
Specifies if the column is always
included in SQL INSERT
statements.
True
Basic mapping,
Embedded mapping,
ID mapping
Updatable
Specifies if this column is always
included in SQL UPDATE
statements.
True
Basic mapping,
Embedded mapping,
ID mapping
Unique
Sets the UNIQUE constraint for the
column.
False
Basic mapping,
Embedded mapping,
ID mapping
Nullable
Specifies if the column allows null
values.
True
Basic mapping,
Embedded mapping,
ID mapping
Length
Sets the column length.
255
Basic mapping,
Embedded mapping,
ID mapping
4-12 Dali Java Persistence Tools User Guide
Basic mapping,
Embedded mapping,
ID mapping
Property pages
Property
Available for
Mapping Type
Description
Default
Precision
Sets the precision for the column
values.
0
Basic mapping,
Embedded mapping,
ID mapping
Scale
Sets the number of digits that
appear to the right of the decimal
point.
0
Basic mapping,
Embedded mapping,
ID mapping
Column Definition
Define the DDL for a column.
This is used when a table is being
generated.
Fetch Type
Defines how data is loaded from
the database:
■
■
Basic mapping,
Embedded mapping,
ID mapping
Eager
Basic mapping,
One-to-one mapping,
Many-to-many
mapping,
Many-to-one mapping
Yes
Basic mapping,
One-to-one mapping,
Many-to-one mapping
Eager – Data is loaded in
before it is actually needed.
Lazy – Data is loaded only
when required by the
transaction.
Optional
Specifies if this field is can be
null.
Lob
Specify if the field is mapped to
java.sql.Clob or
java.sql.Blob.
Basic mapping
This field corresponds to the
@Lob annotation.
Temporal
Specifies if this field is one of the
following:
■
Date – java.sql.Date
■
Time – java.sql.Time
■
Basic mapping, ID
mapping
Timestamp –
java.sql.Timestamp
This field corresponds to the
@Temporal annotation.
Enumerated
Specify how to persist
enumerated constraints if the
String value suits your
application requirements or to
match an existing database
schema.
■
ordinal
■
String
Ordinal
This field corresponds to the
@Enumerated annotation.
Target Entity
The persistent entity to which the
attribute is mapped.
ID
Specify if the entity’s ID is
derived from the identity of
another entity.
One-to-one mapping,
One-to-many
mapping
Many-to-many
mapping,
Many-to-one mapping
Reference 4-13
Property pages
Property
Description
Cascade Type
Specify which operations are
propagated throughout the entity.
Available for
Mapping Type
Default
■
All – All operations
■
Persist
■
Merge
■
Move
■
Remove
■
Refresh
Mapped By
The field in the database table
that "owns" the relationship. This
field is required only on the
non-owning side of the
relationship.
Order By
Specify the default order for
objects returned from a query:
■
No ordering
■
Primary key
■
Custom ordering
One-to-one mapping,
One-to-many
mapping,
Many-to-many
mapping,
Many-to-one mapping
One-to-one mapping,
One-to-many
mapping
Primary key
One-to-many
mapping.
Many-to-many
mapping,
Many-to-one mapping
This field corresponds to the
@OrderBy annotation.
Attribute Overrides
Overrides Basic mappings of a
mapped superclass (for example,
if the inherited column name is
incompatible with a pre-existing
data model, or invalid as a
column name in your database).
Embedded mapping
Embedded mapping
4.2.2.2 Join Table Information
Use area to specify a mapped column for joining an entity association. By default, the
mapping is assumed to have a single join.
This table lists the fields available on the Join Table area in the JPA Details view for
One-to-many mapping and Many-to-many mapping mapping types.
Property
Description
Default
Name
Name of the join table that contains
the foreign key column.
By default, the name is
assumed to be the primary
tables associated with the
entities concatenated with an
underscore.
Join Columns
Specify a mapped column for
joining an entity association. This
field corresponds to the
@JoinColum attribute.
By default, the mapping is
assumed to have a single join.
Select Override Default, then Add,
Edit, or Remove the join columns.
Inverse Join Columns
Select Override Default, then Add,
Edit, or Remove the join columns.
4-14 Dali Java Persistence Tools User Guide
Property pages
4.2.2.3 Join Columns Information
This table lists the fields available in the Join Table area in JPA Details view for
Many-to-one mapping and One-to-one mapping mapping types.
Property
Description
Default
Join Column
Specify a mapped column for
joining an entity association. This
field corresponds to the
@JoinColum attribute.
By default, the mapping is
assumed to have a single join.
Select Override Default, then Add,
Edit, or Remove the join columns.
4.2.2.4 Primary Key Generation information
This table lists the fields available in the Primary Key Generation area in JPA Details
view for ID mapping types.
Property
Description
Default
Primary Key
Generation
These fields define how the
primary key is generated. These
fields correspond to the
@GeneratedValue annotation.
Generated Value
Strategy
■
■
■
■
Generator Name
Table Generator
Auto
Auto
Identity – Values are assigned
by the database’s Identity
column.
Sequence – Values are assigned
by a sequence table (see
Sequence Generator).
Table – Values are assigned by
a database table (see Table
Generator).
Unique name of the generated
value.
These fields define the database
table used for generating the
primary key and correspond to the
@TableGenerator annotation.
These fields apply only when
Strategy = Table.
Name
Unique name of the generator.
Table
Database table that stores the
generated ID values.
Primary Key Column
The column in the table generator’s
Table that contains the primary key.
Value Column
The column that stores the
generated ID values.
Primary Key Column
Value
The value for the Primary Key
Column in the generator table.
Reference 4-15
Property pages
Property
Description
Sequence Generator
These fields define the specific
sequence used for generating the
primary key and correspond to the
@SequenceGenerator
annotation.
Default
These fields apply only when
Strategy = Sequence.
Name
Name of the sequence table to use
for defining primary key values.
Sequence
Unique name of the sequence.
4.2.3 JPA Details view (for orm.xml)
The JPA Details view displays the default mapping and persistence information for the
project and contains the following areas:
■
General information
■
Persistence Unit information
■
Generators
■
Queries
■
Converters (when using EclipseLink)
These defaults can be overridden by the settings on a specific entity or mapping.
4.2.3.1 General information
This table lists the General information fields available in the JPA Details view for each
entity type.
Property
Description
Package
The Java package that contains the persistent
entities. Click Browse and select the package
Schema
The database schema that contains the Table.
This field corresponds to the <schema> element in
the orm.xml file.
Catalog
The database catalog that contains the Table.
This field corresponds to the <catalog> element in
the orm.xml file.
Access
Specify the default access method for the variables in
the project:
■
Property
■
Field
This field corresponds to the <access> element in
the orm.xml file.
4-16 Dali Java Persistence Tools User Guide
Default
Property pages
4.2.3.2 Persistence Unit information
This table lists the Persistence Unit information fields available in the JPA Details view
for each entity type. These fields are contained in the
<persistence-unit-metadata> element in the orm.xml file.
Property
Description
XML Mapping
Data Complete
Specifies that the Java classes in this persistence unit
are fully specified by their metadata. Any
annotations will be ignored.
Default
This field corresponds to the
<xml-mapping-metadata-complete> element
in the orm.xml file.
Cascade Persist
Adds cascade-persist to the set of cascade options in
entity relationships of the persistence unit.
This field corresponds to the <cascade-persist>
element in the orm.xml file.
Schema
The database schema that contains the Table.
This field corresponds to the <schema> element in
the orm.xml file.
Catalog
The database catalog that contains the Table.
This field corresponds to the <catalog> element in
the orm.xml file.
Access
Specify how the entity its access instance variables.
■
■
Property
Property – Persistent state accessed through the
property accessor methods. The property
accessor methods must be public or private.
Field – Instance variables are accessed directly.
All non-transient instance variables are
persistent.
4.2.3.3 Generators
This table lists the Generator information fields available in the JPA Details view for
the orm.xml file.
Reference 4-17
Property pages
Property
Description
Generator
Displays the existing Sequence and Table generators.
Click Add Sequence or Add Table to add a new generator.
For sequence generators, you must complete the following fields:
■
Name
■
Sequence
■
Schema
■
Catalog
■
Allocation size
■
Initial value
For table generators, you must complete the following fields:
■
Name
■
Table
■
Schema
■
Catalog
■
Primary key column
■
Value column
■
Primary key column value
■
Allocation size
4.2.3.4 Queries
This table lists the Query information fields available in the JPA Details view for the
orm.xml file.
Property
Description
Queries
Displays the existing Named and Native queries.
Click Add to add a named query, or Add Native for a native query.
For named queries, enter the query in the Query field.
For native queries, select a result class, then enter the query in the Query
field.
Query Hints
Displays the existing query hints (Name and Value).
Click Add to add a new query hint.
4.2.3.5 Converters
The Converters information in the JPA Details view applies only when using
EclipseLink
Click Add to create a new converter, using the Add Converter dialog.
4-18 Dali Java Persistence Tools User Guide
Property pages
4.2.4 JPA Structure view
The JPA Structure view displays an outline of the structure (its attributes and
mappings) of the entity that is currently selected or opened in the editor. The
structural elements shown in the outline are the entity and its fields.
Figure 4–1 Sample JPA Structure View
4.2.5 persistence.xml Editor
The persistence.xml Editor provides an interface that enables you to update the
persistence.xml file. For projects using the EclipseLink platform, the perisistence.xml
Editor consists of the following pages:
■
General
■
Connection
■
Customization
■
Caching
■
Logging
■
Options
■
Schema Generation
■
Properties
■
Source
For projects using the Generic platform, the following subset of these pages is
available:
■
General
■
Connection
■
Properties
■
Source
4.2.5.1 General
The following table lists properties available in the General page of the persistence.xml
Editor.
Table 4–3
Properties of the General Page
Property
Description
Default
Name
Enter the name of the persistence unit.
The project name.
Reference 4-19
Property pages
Table 4–3 (Cont.) Properties of the General Page
Property
Description
Default
Persistence Provider
Enter the name of the persistence provider.
Determined by the
server.
Description
Enter a description for this persistence unit.
This is an optional property.
Managed Classes
Add or remove the classes managed through
the persistence unit.
Exclude Unlisted
Classes
Select to include all annotated entity classes in
the root of the persistence unit.
XML Mapping Files
Add or remove the object/relational mapping
Meta-INF\orm.xml
XML files that define the classes to be managed
by the persistence unit.
False
JAR Files
4.2.5.2 Connection
The following table lists the properties available in the Connection page of the
persistence.xml Editor.
Table 4–4
Properties of the Connection Page
Property
Description
Transaction Type
Specify if the connection for this persistence
unit uses one of the following transaction types:
■
■
■
Batch Writing
Default
Default -- Select to use the container used
by the container.
JTA (Java Transaction API) -- Transactions
of the Java EE server.
Resource Local -- Native actions of a JDBC
driver that are referenced by a persistence
unit.
Specify the use of batch writing to optimize
transactions with multiple write operations.
None
Set the value of this property into the session at
deployment time.
Note: This property applies when used both in
a Java SE and Java EE environment.
The following are the valid values for
oracle.toplink.config.BatchWriting:
■
■
■
■
JDBC–Use JDBC batch writing.
Buffered–Do not use either JDBC batch
writing nor native platform batch writing.
OracleJDBC–Use both JDBC batch writing
and Oracle native platform batch writing.
None–Do not use batch writing (turn it
off).
Statement caching
Native SQL
4-20 Dali Java Persistence Tools User Guide
False
Property pages
Table 4–4 (Cont.) Properties of the Connection Page
Property
Description
JTA Data Source
Name
If you selected JTA as the transaction type, then
enter the name of the default JTA data source
for the persistence unit.
Default
Non-JTA Data Source If you selected Resource Local as the
Name
transaction type, then enter the name of the
non-JTA data source.
This property is not available for projects using
the Generic platform.
Bind Parameters
Control whether or not the query uses
parameter binding.
Note: This property applies when used in a
Java SE environment.
This property is not available for projects using
the Generic platform.
EclipseLink
Connection Pool
Define the connection pool driver, URL, user
name and password.
These properties are note available for projects
using the Generic platform.
Read Connection
The maximum and minimum number of
connections allowed in the JDBC read
connection pool.
Note: These property apply when used in a
Java SE environment.
These properties are not available for projects
using the Generic platform
Write Connection
The maximum and minimum number of
connections allowed in the JDBC read
connection pool.
Note: These property apply when used in a
Java SE environment.
These properties are not available for projects
using the Generic platform
4.2.5.3 Customization
The following table lists the properties available in the Customization page of the
persistence.xml Editor.
Reference 4-21
Property pages
Table 4–5
Properties of the Customization Page
Property
Description
Weaving
Weave Dynamically
Specifies if weaving of the entity classes is
performed. The EclipseLink JPA persistence
provider uses weaving to enhance JPA entities for
such properties as lazy loading, change tracking,
fetch groups, and internal optimizations. Select
from the following options:
■
No Weaving
■
Weave Dynamically
■
Weaving Lazy
Weave Statically -- Use this option if you
plan to execute your application outside of a
Java EE 5 container in an environment that
does not permit the use of
-javaagent:eclipselink.jar on the
JVM command line. This assumes that
classes have already been statically woven.
Run the static weaver on the classes before
deploying them.
Select this option to enable lazy weaving.
Weaving Fetch Grou Select this option to enable fetch groups through
ps
weaving. Set this option to false if:
■
■
Default
True
True
There is no weaving.
Classes should not be changed during
weaving (for example, when debugging).
Set this property to false for platforms where it is
not supported.
Weaving internal
True
Weaving eager
False
Weaving Change Tr
acking
Select this option to use weaving to detect which
fields or properties of the object change.
True
Throw Exceptions
Select this option to set EclipseLink to throw an
exception or log a warning when it encounters a
problem with any of the files listed in a
persistence.xml file <mapping-file> element.
True
Exception handler
Select (or create) a Java class to handle
exceptions.
Session Customizer
Select a session customizer class: a Java class that
implements the
eclipselink.tools.sessionconfigurati
on.SessionCustomizer interface and
provides a default (zero-argument) constructor.
Use this class’ customize method, which takes
an eclipselink.sessions.Session, to
programmatically access advanced EclipseLink
session API.
4-22 Dali Java Persistence Tools User Guide
Property pages
Table 4–5 (Cont.) Properties of the Customization Page
Property
Description
Descriptor
Customizer
Select an EclipseLink descriptor customizer
class–a Java class that implements the
eclipselink.tools.sessionconfigurati
on.DescriptorCustomizer interface and
provides a default (zero-argument) constructor.
Use this class’s customize method, which takes
an
eclipselink.descriptors.ClassDescrip
tor, to programmatically access advanced
EclipseLink descriptor and mapping API for the
descriptor associated with the JPA entity named
<ENTITY>.
Default
Validation only
True
Profiler
NoProfiler
■
No Profiler
■
Performance Profiler
■
Query Monitor
Note: This page is not available for projects using the Generic
platform.
4.2.5.4 Caching
This table lists the properties of the Caching page of the persistence.xml Editor.
Reference 4-23
Property pages
Table 4–6
Properties of the Caching Page
Property
Description
Default Cache Type
Select one of the following as the Default Cache Weak with soft
subcache
Type:
■
Default
Soft with Weak Subcache–This option is
similar to Weak with Hard Subcache
except that it maintains a most frequently
used subcache that uses soft references.
The size of the subcache is proportional to
the size of the identity map. The subcache
uses soft references to ensure that these
objects are garbage-collected only if the
system is low on memory.
Use this identity map in most
circumstances as a means to control
memory used by the cache.
■
■
Week with Hard Subcache–This option is
similar to Soft with Weak subcache except
that it maintains a most frequently used
subcache that uses hard references. Use
this identity map if soft references are not
suitable for your platform.
Weak–This option is similar to Full, except
that objects are referenced using weak
references. This option uses less memory
than Full, allows complete garbage
collection and provides full caching and
guaranteed identity.
Use this identity map for transactions that,
once started, stay on the server side.
■
■
Soft–This option is similar to Weak except
that the map holds the objects using soft
references. This identity map enables full
garbage collection when memory is low. It
provides full caching and guaranteed
identity.
Full–This option provides full caching and
guaranteed identity: all objects are cached
and not removed.
Note: This process may be
memory-intensive when many objects are
read.
■
Default Cache Size
None–This option does not preserve object
identity and does not cache objects.This
option is not recommended.
Set the size (maximum number of objects) of
the cache.
Default Shared Cache Specifies if cached instances should be in the
shared cache or in a client isolated cache.
Entity Caching
Specify the entity-specific caching information.
Cache Type
See Default Cache Type.
Cache Size
See Default Cache Size.
Shared Cache
See Default Shared Cache.
4-24 Dali Java Persistence Tools User Guide
100
True
Property pages
Table 4–6 (Cont.) Properties of the Caching Page
Property
Description
Flush clear cache
Select one of the following as the Default Cache Drop Invalidate
Type:
■
■
■
Default
Drop – This mode is the fastest and uses
the least memory. However, after commit
the shared cache might potentially contain
stale data.
Drop Invalidate – Classes that have at
least one object updated or deleted are
invalidated in the shared cache at commit
time. This mode is slower than Drop, but
as efficient memory usage-wise, and
prevents stale data.
Merge – Drop classes from the
EntityManager’s cache of objects that have
not been flushed. This mode leaves the
shared cache in a perfect state after
commit. However, it is the least
memory-efficient mode; the memory might
even run out in a very large transaction.
Note: This page is not available for projects using the Generic
platform.
4.2.5.5 Logging
This table lists the properties of the Logging page of the persistence.xml Editor.
Note: This page is not available for projects using the Generic
platform.
Reference 4-25
Property pages
Table 4–7
Properties of the Logging Page
Property
Description
Default
Logging Level
Specifies the amount and detail of log output
by selecting the log level (in ascending order of
information):
Info
The following are the valid values for the
java.util.logging.Level:
■
■
■
■
■
■
■
■
OFF–disables logging
SEVERE–logs exceptions indicating
TopLink cannot continue, as well as any
exceptions generated during login. This
includes a stack trace.
WARNING–logs exceptions that do not
force TopLink to stop, including all
exceptions not logged with severe level.
This does not include a stack trace.
INFO–logs the login/logout per sever
session, including the user name. After
acquiring the session, detailed information
is logged.
CONFIG–logs only login, JDBC
connection, and database information.
FINE–logs SQL.
FINER–similar to warning. Includes stack
trace.
FINEST–includes additional low level
information.
Example: persistence.xml file
<property
name="eclipselink.logging.level"
value="INFO"/>
Timestamp
Control whether the timestamp is logged in
each log entry.
true
The following are the valid values:
■
true–log a timestamp.
■
false–do not log a timestamp.
Example: persistence.xml file
<property
name="eclipselink.logging.timestamp"
value="false"/>
Thread
Control whether a thread identifier is logged in true
each log entry.
The following are the valid values:
■
true–log a thread identifier.
■
false–do not log a thread identifier.
4-26 Dali Java Persistence Tools User Guide
Property pages
Table 4–7 (Cont.) Properties of the Logging Page
Property
Session
Description
Default
Control whether an EclipseLink session
identifier is logged in each log entry.
true
The following are the valid values:
■
■
true–log a EclipseLink session identifier.
false–do not log a EclipseLink session
identifier.
Example: persistence.xml file
<property
name="eclipselink.logging.session"
value="false"/>
Exceptions
Control whether the exceptions thrown from
within the EclipseLink code are logged prior to
returning the exception to the calling
application. Ensures that all exceptions are
logged and not masked by the application
code.
false
The following are the valid values:
■
true–log all exceptions.
■
false–do not log exceptions.
Example: persistence.xml file
<property
name="eclipselink.logging.exceptions"
value="true"/>
Log file
Specify a file location for the log output
(instead of the standard out).
Example: persistence.xml file
<property name="eclipselink.logging.file"
value="C:\myout\" />
Reference 4-27
Property pages
Table 4–7 (Cont.) Properties of the Logging Page
Property
Logger
Description
Default
Select the type of logger to use:
DefaultLogger
The following are the valid values:
■
■
■
■
DefaultLogger–the EclipseLink native
logger
eclipselink.logging.DefaultSess
ionLog.
JavaLogger–the java.util.logging
logger
eclipselink.logging.JavaLog.
ServerLogger–the java.util.logging
logger
eclipselink.platform.server.Ser
verLog. Integrates with the application
server's logging as define in the
eclipselink.platform.server.Ser
verPlatform.
Fully qualified class name of a custom
logger. The custom logger must implement
the
eclipselink.logging.SessionLog
interface.
Example: persistence.xml file
<property
name="eclipselink.logging.logger"
value="acme.loggers.MyCustomLogger" />
4.2.5.6 Options
This table lists the properties of the Options page of the persistence.xml Editor.
Note: This page is not available for projects using the Generic
platform.
Table 4–8
Properties of the Options Page
Property
Description
Session Name
Specify the name by which the EclipseLink
session is stored in the static session manager.
Use this option if you need to access the
EclipseLink shared session outside of the
context of the JPA or to use a pre-existing
EclipseLink session configured through a
EclipseLink sessions.xml file
Valid values: a valid EclipseLink session name
that is unique in a server deployment.
Example: persistence.xml file
<property name="eclipselink.session-name"
value="MySession"/>
4-28 Dali Java Persistence Tools User Guide
Default
Property pages
Table 4–8 (Cont.) Properties of the Options Page
Property
Description
Sessions XML
Specify persistence information loaded from
the EclipseLink session configuration file
(sessions.xml).
Default
You can use this option as an alternative to
annotations and deployment XML. If you
specify this property, EclipseLink will override
all class annotation and the object relational
mapping from the persistence.xml, as well
as ORM.xml and other mapping files, if present.
Indicate the session by setting the
eclipselink.session-name property.
Note: If you do not specify the value for this
property, sessions.xml file will not be used.
Valid values: the resource name of the sessions
XML file.
Example: persistence.xml file
<property name="toplink.session-xml"
value="mysession.xml"/>
Target Database
Select the target database. You can also set the
Auto
value to the fully qualified class name of a
subclass of the
org.eclipse.persistence.platform.Da
tabasePlatform class.
Example: persistence.xml file
<property
name="eclipselink.target-database"
value="Oracle"/>
Target Server
Select the target server for your JPA
application.
None
Example: persistence.xml file
<property
name="eclipselink.target-server"
value="OC4J_10_1_3"/>
Event Listener
Specify a descriptor event listener to be added
during bootstrapping.
Valid values: qualified class name for a class
that implements the
eclipselink.sessions.SessionEventLi
stener interface.
Example: persistence.xml file
<property
name="eclipselink.session-event-listener"
value="mypackage.MyClass.class"/>
Include Descriptor
Queries
Enable or disable the default copying of all
named queries from the descriptors to the
session. These queries include the ones defined
using EclipseLink API, descriptor amendment
methods, and so on.
Miscellaneous
Options
Reference 4-29
Property pages
Table 4–8 (Cont.) Properties of the Options Page
Property
Temporal mutable
Description
Default
Specify if all Date and Calendar persistent
fields should be handled as mutable objects.
False
Example: persistence.xml file
<property
name="eclipselink.temporal.mutable"
value="true"/>
4.2.5.7 Schema Generation
This table lists the properties of the Schema Generation page of the persistence.xml
Editor.
Note: This page is not available for projects using the Generic
platform.
Table 4–9
Property
Description
Default
DDL Generation
Type
Select the type of DDL generation:
None
■
■
■
Output Mode
None -- Do not generate DDL; no schema
is generated.
Create Tables -- Create DDL for
non-existent tables; leave existing tables
unchanged.
Drop and Create Tables -- Create DDL for
all tables; drop all existing tables.
Select the DDL generation target:
■
■
■
Both -- Generate SQL files and execute
them on the database.
Database -- Execute SQL on the database
only (do not generate SQL files).
SQL Script -- Generate SQL files only (do
not execute them on the database).
DDL Generation
Location
Specify where EclipseLink writes DDL output.
Specify a file specification to a directory in
which you have write access. The file
specification may be relative to your current
working directory or absolute. If it does not end
in a file separator, then EclipseLink appends
one that is valid for your operating system.
Create DDL File
Name
Specify the file name of the DDL file that
EclipseLink generates that contains SQL
statements for creating tables for JPA entities.
Specify a file name valid for your operating
system.
Drop DDL File Name Specify the file name of the DDL file that
EclipseLink generates that contains SQL
statements for dropping tables for JPA entities.
4-30 Dali Java Persistence Tools User Guide
createDDL.jdbc
dropDDL.jdbc
Preferences
4.2.5.8 Properties
This page enables you to add or remove the vendor-specific <properties> elements
of persistence.xml.
To add a property, click Add then enter the property Name and Value.
4.2.5.9 Source
Using this page, you can manually edit the persistence.xml file.
See "Managing the persistence.xml file" on page 3-10 for additional information.
4.3 Preferences
This section includes information on the following preference pages:
■
Project Properties page – Java Persistence Options
■
Project Properties page – Validation Preferences
4.3.1 Project Properties page – Java Persistence Options
Use the Errors/Warnings options on the Properties page to specify the validation
options to use with the project.
Property
Description
Enable project specific
settings
Select the to override the general settings for this project.
Project level
Select the warning level to report.
Persistent unit level
Select the warning level to report.
Type level
Select the warning level to report.
Attribute level
Select the warning level to report.
Schema mapping
Select the warning level to report.
Implied attributes
Select the warning level to report.
Implied associations
Select the warning level to report.
Inheritance
Select the warning level to report.
Queries and generators
Select the warning level to report.
See "Modifying persistent project properties" on page 3-38 for additional information.
4.3.2 Project Properties page – Validation Preferences
Use the Java Persistence options on the Properties page to select the database
connection to use with the project.
This table lists the properties available in the JPA Details page.
Property
Description
Platform
Select the vendor-specific platform.
Reference 4-31
Dialogs
Property
Description
Library
Select a specific JPA library configuration.
Click Manage libraries to create or update a user library.
Click Download libraries to download a specific library
configuration.
Type
Select User Library to select from the available user-defined or
downloaded libraries.
If you select Disable, you must manually include the JPA
implementation library on the project classpath.
Include libraries with this
application
Specify if the selected libraries are included when deploying
the application.
Connection
The database connection used to map the persistent entities.
■
To create a new connection, click Add Connections.
■
To reconnect to an existing connection, click Reconnect.
Override default catalog fr
om connection
Select a catalog other than the default one derived from the
connection information. Use this option if the default catalog is
incorrect or cannot be used.
Override default schema fr
om connection
Select a schema other than the default one derived from the
connection information. Use this option if the default schema is
incorrect or cannot be used. For example, use this option when
the deployment login differs from the design-time login.
Persistent Class
Management
Specify if Dali will discover annotated classes automatically,
or if the annotated classes must be listed in the
persistence.xml file.
Note: To insure application portability, you should explicitly list
the managed persistence classes that are included in the
persistence unit.
Canonical Metamodel
4.4 Dialogs
This section includes information on the following preference pages:
■
Edit Join Columns Dialog
■
Select Cascade dialog
■
New EclipseLink Mapping File dialog
■
Add Converter dialog
■
Configure JAXB Class Generation dialog
4.4.1 Edit Join Columns Dialog
Use the Join Columns dialog to create or modify the join tables and columns in
relationship mappings.
This table lists the properties available in the Join Columns dialog.
4-32 Dali Java Persistence Tools User Guide
Dialogs
Property
Description
Name
Name of the joint table column that contains the foreign key
column.
Referenced Column Name
Name of the database column that contains the foreign key
reference for the entity relationship.
4.4.2 Select Cascade dialog
Specify which operations are propagated throughout the association: All, Persist,
Merge, Remove, or Refresh.
4.4.3 New EclipseLink Mapping File dialog
Specify the location and properties of the EclipseLink mapping file
(eclispelink-orm.xml).
Property
Description
Project
Select the project in which to add the mapping file.
Source folder
Click Browse and select the source file in which to add the mapping file. The
default is ../<PROJECT>/src.
File path
Enter the filename and path of the mapping file. The default is
META-INF/eclipselink-orm.xml.
Default access
Select whether the entity’s access to instance variables is field-based or
property-based, as defined in the JPA specification.
Add to persistence unit
Specify if this mapping file should be added to the persistence unit
(persistence.xml).
Persistence Unit
Select the persistence unit in which to add the mapping file.
4.4.4 Add Converter dialog
Use this dialog to create a new EclipseLink converter.
Property
Description
Name
Enter the name for this converter
Type
Select the converter type:
■
Custom
■
Object type
■
Struct
■
Type
Reference 4-33
JPA Development perspective
4.4.5 Configure JAXB Class Generation dialog
Use this dialog to generate JAXB classes from a schema.
Property
Description
Source folder
Location in which to generate the classes. Click Browse to select a location.
Package
Name of the package. Click Browse to select an existing package.
Catalog
Name of the catalog file to use to resolve external entity references.
Bindings files
Click Add to select the external bindings files
4.5 JPA Development perspective
The JPA Development perspective defines the initial set and layout of views in the
Workbench window when using Dali. By default, the JPA Development perspective
includes the following views:
■
JPA Structure view
■
JPA Details view (for entities)
■
JPA Details view (for attributes)
■
JPA Details view (for orm.xml)
4.6 Icons and buttons
This section includes information on each of the icons and buttons used in the Dali OR
Mapping Tool.
■
Icons
■
Buttons
4.6.1 Icons
The following icons are used throughout the Dali OR Mapping Tool.
Icon
Description
Entity
Embeddable entity
Mapped superclass
Basic mapping
Basic collection mapping
Basic map mapping
Embedded mapping
4-34 Dali Java Persistence Tools User Guide
Dali Developer Documentation
Icon
Description
Embedded ID mapping
ID mapping
Many-to-many mapping
Many-to-one mapping
One-to-many mapping
One-to-one mapping
Transformation mappings
Transient mapping
Variable one-to-one mappings
Version mapping
4.6.2 Buttons
The following buttons are used throughout the Dali OR Mapping Tool.
Icon
Description
JPA Development perspective
4.7 Dali Developer Documentation
Additional Dali documentation is available online at:
http://wiki.eclipse.org/index.php/Dali_Developer_Documentation
This developer documentation includes information about:
■
Dali architecture
■
Plugins that comprise the Dali JPA Eclipse feature
■
Extension points
Reference 4-35
Dali Developer Documentation
Reference 4-36
Dali Developer Documentation
Reference 4-37
Dali Developer Documentation
Reference 4-38
Dali Developer Documentation
Reference 4-39
Dali Developer Documentation
Reference 4-40
Dali Developer Documentation
Reference 4-41
Dali Developer Documentation
Reference 4-42
Dali Developer Documentation
Reference 4-43
Dali Developer Documentation
Reference 4-44
Dali Developer Documentation
Reference 4-45
Dali Developer Documentation
4-46 Dali Java Persistence Tools User Guide
5
Tips and tricks
The following tips and tricks give some helpful ideas for increasing your productivity.
■
Database Connections
■
Schema-based persistence.xml
Tip
Description
Database Connections
When starting a new workbench session, be sure to reconnect to
your database (if you are working online). This allows Dali to
provide database-related mapping assistance and validation.
Schema-based
persistence.xml
If you are behind a firewall, you may need to configure your Eclipse
workspace proxy in the Preferences dialog (Preferences > Internet >
Proxy Settings) to properly validate a schema-based
persistence.xml file.
Tips and tricks 5-1
5-2 Dali Java Persistence Tools User Guide
6
What’s new
This section contains descriptions of the following new features and significant
changes made to the Dali OR Mapping Tool for Release 2.3:
■
Multiple Improvements to the Dali Perspective
■
Support for JPA 2.0 and EclipseLink
■
Conversion of Java Projects to JPA Projects
■
EclipseLink 2.x Support
6.1 Improved Internationalization and Localization
This release of the Dali OR Mapping Tool provides improved internationalization
(i18n) and localization support. Dali projects can support different locales and
processing of international data (such as dates and strings).
6.2 Multiple Improvements to the Dali Perspective
There have been multiple improvements to the Dali perspectives to improve its
ease-of-use:
■
The Create JPA Entity wizard now accepts short names as attribute types.
■
Dali will perform validation after refreshing database information.
■
Dali allows project-level customization for validation (error and warning reports)
6.3 Support for JPA 2.0 and EclipseLink
This release of the Dali OR Mapping Tool supports generic JPA 2.0 as well as specific
items for EclispeLink 1.2.
■
Derived IDs
■
Caching (Shared Cache and Cachable)
■
Canonical metamodel generation
■
Order Column configuration
■
ElementCollection mapping type
■
Cascade detach
■
Dali will upgrade your persistence.xml from JPA 1.0 to 2.0.
What’s new 6-1
Conversion of Java Projects to JPA Projects
6.4 Conversion of Java Projects to JPA Projects
The Dali OR Mapping Tool now uses the Eclipse Configure menu to convert existing
Java projects to JPA projects.
See "Converting a Java Project to a JPA Project" for more information.
6.5 EclipseLink 2.x Support
Release 2.3 provides support for EclipseLink 2.x features.
EclipseLink (the Eclipse Persistence Services Project) is a complete persistence frame
work. Refer to http://www.eclipse.org/eclipselink/ for more information.
6.6 Table-per-Concrete-Class Inheritance
The Dali OR Mapping Tool now supports the JPA 1.0-optional table-per-concrete-class
inheritance option. This functionality may be required in JPA 2.0.
6-2 Dali Java Persistence Tools User Guide
Table-per-Concrete-Class Inheritance
What’s new 6-3
Table-per-Concrete-Class Inheritance
What’s new 6-4
Table-per-Concrete-Class Inheritance
What’s new 6-5
Table-per-Concrete-Class Inheritance
What’s new 6-6
Table-per-Concrete-Class Inheritance
What’s new 6-7
Table-per-Concrete-Class Inheritance
What’s new 6-8
7
Legal
Copyright © 2006, 2010, Oracle. All rights reserved.
This program and the accompanying materials are made available under the terms of
the Eclipse Public License v1.0 which accompanies this distribution, and is available
at:
http://www.eclipse.org/legal/epl-v10.html
7.1 About this content
Terms and conditions regarding the use of this guide.
June 2010
License
The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless
otherwise indicated below, the Content is provided to you under the terms and
conditions of the Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is
available at http://www.eclipse.org/legal/epl-v10.html. For purposes of
the EPL, "Program" will mean the Content.
If you did not receive this Content directly from the Eclipse Foundation, the Content is
being redistributed by another party ("Redistributor") and different terms and
conditions may apply to your use of any object code in the Content. Check the
Redistributor’s license that was provided with the Content. If no such license exists,
contact the Redistributor. Unless otherwise indicated below, the terms and conditions
of the EPL still apply to any source code in the Content and such source code may be
obtained at http://www.eclipse.org.
Legal 7-1
About this content
7-2 Dali Java Persistence Tools User Guide
Index
Annotations
@Basic, 3-22
@Column, 4-12
@DiscriminatorColumn, 3-20, 4-11
@DiscriminatorValue, 3-20, 4-11
@Embeddable, 3-17
@Embedded, 3-24
@EmbeddedId, 3-24
@Entity, 3-15
@Enumerated, 4-13
@GeneratedValue, 4-15
@Id, 3-24
@Inheritance, 3-19
@JoinColumn, 3-28, 3-30, 4-14, 4-15
@Lob, 4-13
@ManyToMany, 3-26
@ManyToOne, 3-27
@MappedSuperclass, 3-17
@NamedQuery, 3-21
@OneToMany, 3-28
@OneToOne, 3-29
@OrderBy, 4-14
@SequenceGenerator, 4-16
@Temporal, 4-13
@Transient, 3-30
@Version, 3-30
A
annotations. See specific annotation.
architecture of Dali feature, 4-35
association tables, 4-8
attribute overrides, 4-10
Attribute Overrides, in Java Details view, 4-10
attributes
JPA Details view, 4-12
mapping, 2-1
B
basic mapping
@Basic, 3-22
about, 3-22
See also mappings
C
caching, 4-23
canonical metamodel, 4-32
cardinality, association tables, 4-9
classes
adding persistence to, 3-15
embeddable, 3-16
entity, 3-15
generating schema from, 3-39, 3-41
managed, 3-11
managing persistent classes, 4-3
mapped superclass, 3-17
synchronizing, 3-12
columns
discriminator, 3-20, 4-11
join, 3-28, 3-30, 4-14, 4-15
mapping to, 4-12
value, 3-20, 4-11
connection pool, 3-11
converting Java project to JPA, 3-5
Create a JPA Project Wizard, 3-2, 3-40, 3-41
Create New JPA Project wizard, 4-1
D
database tables
generating entities from, 3-31
database, persistence
connection, 4-31
schema, 4-32
derived ID, 4-13
developer documentation, Dali, 4-35
E
eager fetch, 4-13
EJB. see persistent entities
embeddable class
@Embeddable, 3-17
about, 3-16
embedded ID mapping
@EmbeddedId, 3-24
about, 3-24
embedded mapping
@Embedded, 3-24
about, 3-24
entities
@Entity annotation, 3-15
about, 2-1
creating, 3-7
customizing, 4-8
embeddable, 3-17
from tables, 3-31, 4-6
generating, 4-7
JPA Details view, 4-9
mapped superclass, 3-17
mapping, 1-3
persistence, 1-3
persistent, 3-15
secondary tables, 4-11
Entity Class page, 3-8
Entity Properties page, 3-9
@Enumerated, 4-13
enumerated, 4-13
error messages, Dali, 3-36
extension points, Dali feature, 4-35
F
fetch type,
4-13
G
Generate Entities from Tables dialog, 3-31, 4-6
Generate Schema from Classes wizard, 3-39, 3-41
generated values
ID mappings, 4-15
sequence, 4-16
H
hints, query,
3-21
I
ID mapping
@Id, 3-24
about, 3-24
inheritance
entity, 3-19, 4-4, 4-11
joined tables, 3-21
single table, 3-20
Inheritance, in Java Details view, 4-11
installation, Dali, 1-1
J
Java project, converting to JPA, 3-5
JAXB, 3-39, 3-41
join columns, 4-8, 4-15
joined tables, inheritance, 3-21
JPA Details view
attributes, 4-12
entities, 4-9
JPA Development perspective, 4-34
JPA Facet page, 3-4
JPA project
converting from Java, 3-5
creating new, 3-1
implementation, 4-2
page, 3-2, 3-40
platform, 4-31
JPA Structure view, 4-19
L
lazy fetch, 4-13
library, JPA, 4-2
M
many-to-many mapping
@ManyToMany, 3-26
about, 3-26
many-to-one mapping
@ManyToOne, 3-27
about, 3-27
mapped superclass
@MappedSuperclass, 3-17
about, 3-17
mapping entities, 1-3
mapping file, 3-13, 4-4
mappings
about, 2-1
basic, 3-22
embedded, 3-24
embedded ID, 3-24
ID, 3-24
many-to-many, 3-26
many-to-one, 3-27
one-to-many, 3-28
one-to-one, 3-29
problems, 3-36
transient, 3-30
version, 3-30
metamodel, canonical, 4-32
N
named queries
entity, 3-21
hints, 3-21
native queries, 3-21
nonpersistent
classes, 3-15
fields. See transient
O
one-to-many mapping
@OneToMany, 3-28
about, 3-28
one-to-one mapping
@OneToOne, 3-29
about, 3-29
OR (object-relational) mappings. See mappings
ordering, 4-14
orm.xml file
about, 2-2
creating, 4-3
managing, 3-13
sample, 3-13
outline, persistence. See JPA Structure view
overrides, JPA attributes, 4-10
P
persistence
about, 2-1
database connection, 4-31
database schema, 4-32
entity class, 3-15
options, 4-31
provider, 3-11
persistence.xml file
about, 2-2
managing, 3-10, 3-14
sample, 3-10
synchronizing with classes, 3-12
persistent entity, 3-15
perspective, JPA Development, 4-34
platform, JPA, 4-31
problems, 3-36
projects, JPA
creating new, 1-2, 3-1
options, 4-31
validation preferences, 4-31
Q
query hints, 3-21
quick start, Dali, 1-2
R
requirements
Dali Java Persistence Tools, 1-1
persistent entities, 3-15
S
schema
from classes, 3-39, 3-41
schema, database, 4-32
secondary tables, 4-11
Secondary Tables, in Java Details view, 4-11
single table inheritance, 3-20
superclass, 3-17
synchronizing classes with persistence.xml file, 3-12
T
tables
associations, 4-7, 4-8
creating entities from, 3-31, 4-6
inheritance, 3-20
secondary, 4-11
@Temporal, 4-13
temporal, 4-13
transient mapping
@Transient, 3-30
about, 3-30
V
version mapping
@Version, 3-30
about, 3-30
views
JPA Details view, 4-9, 4-12
JPA Structure view, 4-19
W
warning messages, Dali, 3-36
Web Tools Platform (WTP), 1-1
X
XML editor, 3-14
">