TopLink JPA Annotation Reference

7/22/2019 TopLink JPA Annotation Reference

1/87

nk JPA Annotation Reference

/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]

( Sign In/Register for Account | Help) United States Communities I am a... I want to...

Note: Starting with Oracle TopLink 11g, JPA support is provided through EclipseLink.EclipseLink supports theJPA 1.0 implementation as well as may extensions, including those previously known as TopLink JPA. Please

see http://www.eclipse.org/eclipselinkfor more information.

TopLink JPA Annotation ReferenceThe Java Persistence API (JPA), part of the Java Enterprise Edition 5 (Java EE 5) Enterprise

JavaBeans (EJB) 3.0 specification, greatly simplifies Java persistence and provides an object-

relational mapping approach that allows you to declaratively define how to map Java objects to

relational database tables in a standard, portable way that works both inside a Java EE 5 application

server and outside an EJB container in a Java Standard Edition (Java SE) 5 application.

When using TopLink JPA, you can configure the JPA behavior of your entities using annotations. An

annotation is a simple, expressive means of decorating Java source code with metadata that is

compiled into the corresponding Java class files for interpretation at runtime by TopLink JPA to

manage JPA behavior.

For example, to designate a Java class as a JPA entity, use the @Entityannotation as follows:

@Ent i t ypubl i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { . . .}

You can selectively decorate your entity classes with annotations to override defaults. This is known

as configuration by exception.

This reference quotes extensively from the JSR-220 Enterprise JavaBeans v.3.0 Java Persistence API

specification to summarize annotation information by category (see Table 1-1) and explains when and

how you use these annotations to customize JPA behavior to meet your application requirements.

For more information, see:

Index of Annotations

Complete JPA annotation Javadoc

Table 1-1 JPA Annotations by Category

Category Description Annotations

Entity By default, TopLink JPA assumes that a Java class is non-

persistent and not eligible for JPA services unless it is

decorated with this annotation.

Use this annotation to designate a plain old Java object

(POJO) class as an entity so that you can use it with JPA

services.

You must designate a class as a JPA entity (either using this

annotation or the or m. xml file) before you can use the class

with JPA services.

@Entity

Database

SchemaAttributes

By default, TopLink JPA assumes that an entity's name

corresponds to a database table of the same name and thatan entity's data member names correspond to database

columns with the same names.

Use these annotations to override this default behavior and

fine-tune the relationship between your object model and data

model.

@Table

@SecondaryTable

@SecondaryTables

@Column

@JoinColumn

@JoinColumns

@PrimaryKeyJoinColumn

@PrimaryKeyJoinColumns

@JoinTable

Popular Downloads

Berkeley DB

Enterprise Manager

Database EE and XE

Enterprise Pack for Ecli

Fusion Middleware

Java EE & GlassFish

Java SE

JDeveloper and ADF

MySQL

NetBeans IDE

Pre-built Developer VM

Solaris 10 & 11 Expres

SQL Developer

VM VirtualBox

Zend Server

Fusion Middleware Home

AIA Foundation Pack

Business Intelligence

Coherence

Developer Tools

Event-Driven ArchitectureSuite

GlassFish Server

Identity Management

JRockit

SOA Suite

TopLink

Tuxedo

WebCenter Suite

WebLogic Server

Complex Event Processing

Business IntelligenceFoundation

Data Integration

Application Server

Beehive

BPEL Process Manager

Business Integration

Business ProcessManagement

Communications ConvergedApplications Server

Communications Presence

Content Management

Enterprise Repository

Entitlements Server

Portal

Reports

Service Bus

Service Registry

Virtual Assembly Builder

Web Services Manager

WebCenter Interaction

WebCenter Services

WebCenter IntelligentCollaboration

WebCenter Real-TimeCollaboration

WebLogic Integration

WebLogic Portal

Business Activity Monitoring

BI Publisher

OracleTechnology Network Middleware Application Server

Products and Services Downloads Store Support Education Partners About Oracle Technology Netwo

ecure earc
http://www.oracle.com/webapps/redirect/signon?nexturl=http://www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.htmlhttp://www.oracle.com/corporate/contact/accounthelp.htmlhttp://www.oracle.com/us/community/index.htmlhttp://www.eclipse.org/eclipselinkhttp://www.eclipse.org/eclipselinkhttp://jcp.org/aboutJava/communityprocess/pfd/jsr220/index.htmlhttp://java.sun.com/javaee/5/docs/api/index.html?javax/persistence/package-summary.htmlhttp://www.oracle.com/technetwork/database/berkeleydb/downloads/index.htmlhttp://www.oracle.com/technetwork/oem/grid-control/downloads/index.htmlhttp://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.htmlhttp://www.oracle.com/technetwork/developer-tools/eclipse/downloads/index.htmlhttp://www.oracle.com/technetwork/middleware/downloads/index-087510.htmlhttp://www.oracle.com/technetwork/java/javaee/downloads/index-jsp-140710.htmlhttp://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.htmlhttp://www.oracle.com/technetwork/developer-tools/jdev/downloads/index.htmlhttp://mysql.com/downloadshttp://netbeans.org/downloads/index.htmlhttp://www.oracle.com/technetwork/community/developer-vm/index.htmlhttp://www.oracle.com/technetwork/indexes/downloads/index.html#servershttp://www.oracle.com/technetwork/developer-tools/sql-developer/downloads/index.htmlhttp://dlc.sun.com/virtualbox/vboxdownload.htmlhttp://www.oracle.com/technetwork/topics/php/zend-server-096314.htmlhttp://www.oracle.com/technetwork/middleware/fusion-middleware/index.htmlhttp://www.oracle.com/technetwork/middleware/foundation-pack/index.htmlhttp://www.oracle.com/technetwork/middleware/bi/index.htmlhttp://www.oracle.com/technetwork/middleware/coherence/index.htmlhttp://www.oracle.com/technetwork/middleware/dev-tools/index.htmlhttp://www.oracle.com/technetwork/middleware/event-driven-architecture/index.htmlhttp://www.oracle.com/technetwork/middleware/event-driven-architecture/index.htmlhttp://www.oracle.com/technetwork/middleware/glassfish/index.htmlhttp://www.oracle.com/technetwork/middleware/id-mgmt/index.htmlhttp://www.oracle.com/technetwork/middleware/jrockit/index.htmlhttp://www.oracle.com/technetwork/middleware/soasuite/index.htmlhttp://www.oracle.com/technetwork/middleware/toplink/index.htmlhttp://www.oracle.com/technetwork/middleware/tuxedo/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic/index.htmlhttp://www.oracle.com/technetwork/middleware/complex-event-processing/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-foundation/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-foundation/index.htmlhttp://www.oracle.com/technetwork/middleware/data-integration/index.htmlhttp://www.oracle.com/technetwork/middleware/ias/index.htmlhttp://www.oracle.com/technetwork/middleware/beehive/index.htmlhttp://www.oracle.com/technetwork/middleware/bpel/index.htmlhttp://www.oracle.com/technetwork/middleware/integration/index.htmlhttp://www.oracle.com/technetwork/middleware/bpm/index.htmlhttp://www.oracle.com/technetwork/middleware/bpm/index.htmlhttp://www.oracle.com/technetwork/middleware/ccas/index.htmlhttp://www.oracle.com/technetwork/middleware/ccas/index.htmlhttp://www.oracle.com/technetwork/middleware/ocp/index.htmlhttp://www.oracle.com/technetwork/middleware/content-management/index.htmlhttp://www.oracle.com/technetwork/middleware/repository/index.htmlhttp://www.oracle.com/technetwork/middleware/oes/index.htmlhttp://www.oracle.com/technetwork/middleware/portal/index.htmlhttp://www.oracle.com/technetwork/middleware/reports/index.htmlhttp://www.oracle.com/technetwork/middleware/service-bus/index.htmlhttp://www.oracle.com/technetwork/middleware/registry/index.htmlhttp://www.oracle.com/technetwork/middleware/ovab/index.htmlhttp://www.oracle.com/technetwork/middleware/webservices-manager/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter-interaction/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter-services/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-intelligent-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-intelligent-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-real-time-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-real-time-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic-integration/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic-portal/index.htmlhttp://www.oracle.com/technetwork/middleware/bam/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-publisher/index.htmlhttp://www.oracle.com/technetwork/index.htmlhttp://www.oracle.com/technetwork/index.htmlhttp://www.oracle.com/technetwork/middleware/index.htmlhttp://www.oracle.com/us/products/index.htmlhttp://www.oracle.com/technetwork/indexes/downloads/index.htmlhttps://shop.oracle.com/http://www.oracle.com/us/support/index.htmlhttp://education.oracle.com/http://www.oracle.com/partners/index.htmlhttp://www.oracle.com/us/corporate/index.htmlhttp://www.oracle.com/technetwork/index.htmlhttp://www.oracle.com/technetwork/index.htmlhttp://www.oracle.com/us/corporate/index.htmlhttp://www.oracle.com/us/corporate/index.htmlhttp://www.oracle.com/partners/index.htmlhttp://www.oracle.com/partners/index.htmlhttp://education.oracle.com/http://education.oracle.com/http://www.oracle.com/us/support/index.htmlhttp://www.oracle.com/us/support/index.htmlhttps://shop.oracle.com/https://shop.oracle.com/http://www.oracle.com/technetwork/indexes/downloads/index.htmlhttp://www.oracle.com/technetwork/indexes/downloads/index.htmlhttp://www.oracle.com/us/products/index.htmlhttp://www.oracle.com/us/products/index.htmlhttp://www.oracle.com/technetwork/middleware/index.htmlhttp://www.oracle.com/technetwork/index.htmlhttp://www.oracle.com/technetwork/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-publisher/index.htmlhttp://www.oracle.com/technetwork/middleware/bam/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic-portal/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic-integration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-real-time-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-real-time-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-intelligent-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-intelligent-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter-services/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter-interaction/index.htmlhttp://www.oracle.com/technetwork/middleware/webservices-manager/index.htmlhttp://www.oracle.com/technetwork/middleware/ovab/index.htmlhttp://www.oracle.com/technetwork/middleware/registry/index.htmlhttp://www.oracle.com/technetwork/middleware/service-bus/index.htmlhttp://www.oracle.com/technetwork/middleware/reports/index.htmlhttp://www.oracle.com/technetwork/middleware/portal/index.htmlhttp://www.oracle.com/technetwork/middleware/oes/index.htmlhttp://www.oracle.com/technetwork/middleware/repository/index.htmlhttp://www.oracle.com/technetwork/middleware/content-management/index.htmlhttp://www.oracle.com/technetwork/middleware/ocp/index.htmlhttp://www.oracle.com/technetwork/middleware/ccas/index.htmlhttp://www.oracle.com/technetwork/middleware/ccas/index.htmlhttp://www.oracle.com/technetwork/middleware/bpm/index.htmlhttp://www.oracle.com/technetwork/middleware/bpm/index.htmlhttp://www.oracle.com/technetwork/middleware/integration/index.htmlhttp://www.oracle.com/technetwork/middleware/bpel/index.htmlhttp://www.oracle.com/technetwork/middleware/beehive/index.htmlhttp://www.oracle.com/technetwork/middleware/ias/index.htmlhttp://www.oracle.com/technetwork/middleware/data-integration/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-foundation/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-foundation/index.htmlhttp://www.oracle.com/technetwork/middleware/complex-event-processing/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter/index.htmlhttp://www.oracle.com/technetwork/middleware/tuxedo/index.htmlhttp://www.oracle.com/technetwork/middleware/toplink/index.htmlhttp://www.oracle.com/technetwork/middleware/soasuite/index.htmlhttp://www.oracle.com/technetwork/middleware/jrockit/index.htmlhttp://www.oracle.com/technetwork/middleware/id-mgmt/index.htmlhttp://www.oracle.com/technetwork/middleware/glassfish/index.htmlhttp://www.oracle.com/technetwork/middleware/event-driven-architecture/index.htmlhttp://www.oracle.com/technetwork/middleware/event-driven-architecture/index.htmlhttp://www.oracle.com/technetwork/middleware/dev-tools/index.htmlhttp://www.oracle.com/technetwork/middleware/coherence/index.htmlhttp://www.oracle.com/technetwork/middleware/bi/index.htmlhttp://www.oracle.com/technetwork/middleware/foundation-pack/index.htmlhttp://www.oracle.com/technetwork/middleware/fusion-middleware/index.htmlhttp://www.oracle.com/technetwork/middleware/crystalball/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-publisher/index.htmlhttp://www.oracle.com/technetwork/middleware/bam/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic-portal/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic-integration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-real-time-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/wc-intelligent-collaboration/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter-services/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter-interaction/index.htmlhttp://www.oracle.com/technetwork/middleware/webservices-manager/index.htmlhttp://www.oracle.com/technetwork/middleware/ovab/index.htmlhttp://www.oracle.com/technetwork/middleware/registry/index.htmlhttp://www.oracle.com/technetwork/middleware/service-bus/index.htmlhttp://www.oracle.com/technetwork/middleware/reports/index.htmlhttp://www.oracle.com/technetwork/middleware/portal/index.htmlhttp://www.oracle.com/technetwork/middleware/oes/index.htmlhttp://www.oracle.com/technetwork/middleware/repository/index.htmlhttp://www.oracle.com/technetwork/middleware/content-management/index.htmlhttp://www.oracle.com/technetwork/middleware/ocp/index.htmlhttp://www.oracle.com/technetwork/middleware/ccas/index.htmlhttp://www.oracle.com/technetwork/middleware/bpm/index.htmlhttp://www.oracle.com/technetwork/middleware/integration/index.htmlhttp://www.oracle.com/technetwork/middleware/bpel/index.htmlhttp://www.oracle.com/technetwork/middleware/beehive/index.htmlhttp://www.oracle.com/technetwork/middleware/ias/index.htmlhttp://www.oracle.com/technetwork/middleware/data-integration/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-foundation/index.htmlhttp://www.oracle.com/technetwork/middleware/complex-event-processing/index.htmlhttp://www.oracle.com/technetwork/middleware/weblogic/index.htmlhttp://www.oracle.com/technetwork/middleware/webcenter/index.htmlhttp://www.oracle.com/technetwork/middleware/tuxedo/index.htmlhttp://www.oracle.com/technetwork/middleware/toplink/index.htmlhttp://www.oracle.com/technetwork/middleware/soasuite/index.htmlhttp://www.oracle.com/technetwork/middleware/jrockit/index.htmlhttp://www.oracle.com/technetwork/middleware/id-mgmt/index.htmlhttp://www.oracle.com/technetwork/middleware/glassfish/index.htmlhttp://www.oracle.com/technetwork/middleware/event-driven-architecture/index.htmlhttp://www.oracle.com/technetwork/middleware/dev-tools/index.htmlhttp://www.oracle.com/technetwork/middleware/coherence/index.htmlhttp://www.oracle.com/technetwork/middleware/bi/index.htmlhttp://www.oracle.com/technetwork/middleware/foundation-pack/index.htmlhttp://www.oracle.com/technetwork/middleware/fusion-middleware/index.htmlhttp://www.oracle.com/technetwork/topics/php/zend-server-096314.htmlhttp://dlc.sun.com/virtualbox/vboxdownload.htmlhttp://www.oracle.com/technetwork/developer-tools/sql-developer/downloads/index.htmlhttp://www.oracle.com/technetwork/indexes/downloads/index.html#servershttp://www.oracle.com/technetwork/community/developer-vm/index.htmlhttp://netbeans.org/downloads/index.htmlhttp://mysql.com/downloadshttp://www.oracle.com/technetwork/developer-tools/jdev/downloads/index.htmlhttp://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.htmlhttp://www.oracle.com/technetwork/java/javaee/downloads/index-jsp-140710.htmlhttp://www.oracle.com/technetwork/middleware/downloads/index-087510.htmlhttp://www.oracle.com/technetwork/developer-tools/eclipse/downloads/index.htmlhttp://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.htmlhttp://www.oracle.com/technetwork/oem/grid-control/downloads/index.htmlhttp://www.oracle.com/technetwork/database/berkeleydb/downloads/index.htmlhttp://java.sun.com/javaee/5/docs/api/index.html?javax/persistence/package-summary.htmlhttp://jcp.org/aboutJava/communityprocess/pfd/jsr220/index.htmlhttp://www.eclipse.org/eclipselinkhttp://www.eclipse.org/eclipselinkhttp://www.oracle.com/us/community/index.htmlhttp://www.oracle.com/us/community/index.htmlhttp://www.oracle.com/corporate/contact/accounthelp.htmlhttp://www.oracle.com/webapps/redirect/signon?nexturl=http://www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.htmlhttp://www.oracle.com/http://www.oracle.com/sun/index.html


2/87



@UniqueConstraint

Identity By default, TopLink JPA assumes that each entity must have

at least one field or property that serves as a primary key.

Use these annotations to specify one of the following:

one @I d

multiple @I dand an @I dCl ass

one @EmbeddedI d

You can also use these annotations to fine-tune how your

database maintains the identity of your entities.

@Id

@IdClass

@EmbeddedId

@GeneratedValue

@SequenceGenerator

@TableGenerator

Direct

Mappings

By default, TopLink JPA automatically configures a Basi c

mapping for most Java primitive types, wrappers of the

primitive types, and enums .

Use these annotations to fine-tune how your database

implements these mappings.

@Basic

@Enumerated

@Temporal

@Lob

@Transient

Relationship

Mappings

TopLink JPA requires that you map relationships explicitly, but

TopLink allows some defaulting.

Use these annotations to specify the type and characteristics

of entity relationships to fine-tune how your database

implements these relationships.

@OneToOne

@ManyToOne

@OneToMany

@ManyToMany

@MapKey

@OrderBy

CompositionSome objects cannot exist on their own, but can only be

embedded within owning entities.

Use these annotations to specify objects that are embedded

and to override how they are mapped in the owning entity's

table.

@Embeddable

@Embedded

@AttributeOverride

@AttributeOverrides

@AssociationOverride

@AssociationOverrides

Inheritance By default, TopLink JPA assumes that all persistent fields are

defined by a single entity class.

Use these annotations if your entity class inherits some or all

persistent fields from one or more superclasses.

@Inheritance

@DiscriminatorColumn

@DiscriminatorValue

@MappedSuperclass

@AssociationOverride

@AssociationOverrides

@AttributeOverride

@AttributeOverrides

Locking By default, TopLink JPA assumes that the application is

responsible for data consistency.

It is recommended that you use this annotation to enable

TopLink JPA-managed optimistic locking.

@Version

Lifecycle

Callback

Events

By default, TopLink JPA handles all persistence operations.

Use these annotations to associate methods with JPA lifecycle

@PrePersist

@PostPersist

Crystal Ball

Enterprise PerformanceManagement

Essbase

SOA Governance

Business Intelligence Beans

Business Process AnalysisSuite

Integration Adapters

MapViewerPerformance Management

Performance Scorecard

Workforce Planning

Financial Management

Financial Close Management

Strategic Finance

Profitability and CostManagement

Hyperion Planning

Business IntelligenceEnterprise Edition

Business Intelligence StandardEdition

Real-Time Decisions

Hyperion Smart View for Office

Smart Space

Interactive Reporting

Business-to-Business

Integrations

User Productivity Kit

Service Bus for FinancialServices

Business Rules

Human Workflow

Data Service Integrator

Data Integrator

GoldenGate

Collaboration Suite

Oracle Fusion Middleware forApps
http://www.oracle.com/technetwork/middleware/crystalball/index.htmlhttp://www.oracle.com/technetwork/middleware/epm/index.htmlhttp://www.oracle.com/technetwork/middleware/epm/index.htmlhttp://www.oracle.com/technetwork/middleware/essbase/index.htmlhttp://www.oracle.com/technetwork/middleware/governance/index.htmlhttp://www.oracle.com/technetwork/middleware/bbi-beans/index.htmlhttp://www.oracle.com/technetwork/middleware/bpa/index.htmlhttp://www.oracle.com/technetwork/middleware/bpa/index.htmlhttp://www.oracle.com/technetwork/middleware/adapters/index.htmlhttp://www.oracle.com/technetwork/middleware/mapviewer/index.htmlhttp://www.oracle.com/technetwork/middleware/performance-management/index.htmlhttp://www.oracle.com/technetwork/middleware/performance-scorecard/index.htmlhttp://www.oracle.com/technetwork/middleware/workforce-planning/index.htmlhttp://www.oracle.com/technetwork/middleware/financial-management/index.htmlhttp://www.oracle.com/technetwork/middleware/close-management/index.htmlhttp://www.oracle.com/technetwork/middleware/strategic-finance/index.htmlhttp://www.oracle.com/technetwork/middleware/profit-cost-management/index.htmlhttp://www.oracle.com/technetwork/middleware/profit-cost-management/index.htmlhttp://www.oracle.com/technetwork/middleware/planning/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-enterprise-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-enterprise-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-standard-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-standard-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/real-time-decisions/index.htmlhttp://www.oracle.com/technetwork/middleware/smart-view-for-office/index.htmlhttp://www.oracle.com/technetwork/middleware/smart-space/index.htmlhttp://www.oracle.com/technetwork/middleware/interactive-reporting/index.htmlhttp://www.oracle.com/technetwork/middleware/b2b-integrations/index.htmlhttp://www.oracle.com/technetwork/middleware/b2b-integrations/index.htmlhttp://www.oracle.com/technetwork/middleware/upk/index.htmlhttp://www.oracle.com/technetwork/middleware/service-bus-fs/index.htmlhttp://www.oracle.com/technetwork/middleware/service-bus-fs/index.htmlhttp://www.oracle.com/technetwork/middleware/business-rules/index.htmlhttp://www.oracle.com/technetwork/middleware/human-workflow/index.htmlhttp://www.oracle.com/technetwork/middleware/data-service-integrator/index.htmlhttp://www.oracle.com/technetwork/middleware/data-integrator/index.htmlhttp://www.oracle.com/technetwork/middleware/goldengate/index.htmlhttp://www.oracle.com/technetwork/middleware/collaboration-suite/index.htmlhttp://www.oracle.com/technetwork/middleware/fmw4apps/index.htmlhttp://www.oracle.com/technetwork/middleware/fmw4apps/index.htmlhttp://www.oracle.com/technetwork/middleware/fmw4apps/index.htmlhttp://www.oracle.com/technetwork/middleware/fmw4apps/index.htmlhttp://www.oracle.com/technetwork/middleware/collaboration-suite/index.htmlhttp://www.oracle.com/technetwork/middleware/goldengate/index.htmlhttp://www.oracle.com/technetwork/middleware/data-integrator/index.htmlhttp://www.oracle.com/technetwork/middleware/data-service-integrator/index.htmlhttp://www.oracle.com/technetwork/middleware/human-workflow/index.htmlhttp://www.oracle.com/technetwork/middleware/business-rules/index.htmlhttp://www.oracle.com/technetwork/middleware/service-bus-fs/index.htmlhttp://www.oracle.com/technetwork/middleware/service-bus-fs/index.htmlhttp://www.oracle.com/technetwork/middleware/upk/index.htmlhttp://www.oracle.com/technetwork/middleware/b2b-integrations/index.htmlhttp://www.oracle.com/technetwork/middleware/b2b-integrations/index.htmlhttp://www.oracle.com/technetwork/middleware/interactive-reporting/index.htmlhttp://www.oracle.com/technetwork/middleware/smart-space/index.htmlhttp://www.oracle.com/technetwork/middleware/smart-view-for-office/index.htmlhttp://www.oracle.com/technetwork/middleware/real-time-decisions/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-standard-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-standard-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-enterprise-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-enterprise-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/planning/index.htmlhttp://www.oracle.com/technetwork/middleware/profit-cost-management/index.htmlhttp://www.oracle.com/technetwork/middleware/profit-cost-management/index.htmlhttp://www.oracle.com/technetwork/middleware/strategic-finance/index.htmlhttp://www.oracle.com/technetwork/middleware/close-management/index.htmlhttp://www.oracle.com/technetwork/middleware/financial-management/index.htmlhttp://www.oracle.com/technetwork/middleware/workforce-planning/index.htmlhttp://www.oracle.com/technetwork/middleware/performance-scorecard/index.htmlhttp://www.oracle.com/technetwork/middleware/performance-management/index.htmlhttp://www.oracle.com/technetwork/middleware/mapviewer/index.htmlhttp://www.oracle.com/technetwork/middleware/adapters/index.htmlhttp://www.oracle.com/technetwork/middleware/bpa/index.htmlhttp://www.oracle.com/technetwork/middleware/bpa/index.htmlhttp://www.oracle.com/technetwork/middleware/bbi-beans/index.htmlhttp://www.oracle.com/technetwork/middleware/governance/index.htmlhttp://www.oracle.com/technetwork/middleware/essbase/index.htmlhttp://www.oracle.com/technetwork/middleware/epm/index.htmlhttp://www.oracle.com/technetwork/middleware/epm/index.htmlhttp://www.oracle.com/technetwork/middleware/crystalball/index.htmlhttp://www.oracle.com/technetwork/middleware/fmw4apps/index.htmlhttp://www.oracle.com/technetwork/middleware/collaboration-suite/index.htmlhttp://www.oracle.com/technetwork/middleware/goldengate/index.htmlhttp://www.oracle.com/technetwork/middleware/data-integrator/index.htmlhttp://www.oracle.com/technetwork/middleware/data-service-integrator/index.htmlhttp://www.oracle.com/technetwork/middleware/human-workflow/index.htmlhttp://www.oracle.com/technetwork/middleware/business-rules/index.htmlhttp://www.oracle.com/technetwork/middleware/service-bus-fs/index.htmlhttp://www.oracle.com/technetwork/middleware/upk/index.htmlhttp://www.oracle.com/technetwork/middleware/b2b-integrations/index.htmlhttp://www.oracle.com/technetwork/middleware/interactive-reporting/index.htmlhttp://www.oracle.com/technetwork/middleware/smart-space/index.htmlhttp://www.oracle.com/technetwork/middleware/smart-view-for-office/index.htmlhttp://www.oracle.com/technetwork/middleware/real-time-decisions/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-standard-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/bi-enterprise-edition/index.htmlhttp://www.oracle.com/technetwork/middleware/planning/index.htmlhttp://www.oracle.com/technetwork/middleware/profit-cost-management/index.htmlhttp://www.oracle.com/technetwork/middleware/strategic-finance/index.htmlhttp://www.oracle.com/technetwork/middleware/close-management/index.htmlhttp://www.oracle.com/technetwork/middleware/financial-management/index.htmlhttp://www.oracle.com/technetwork/middleware/workforce-planning/index.htmlhttp://www.oracle.com/technetwork/middleware/performance-scorecard/index.htmlhttp://www.oracle.com/technetwork/middleware/performance-management/index.htmlhttp://www.oracle.com/technetwork/middleware/mapviewer/index.htmlhttp://www.oracle.com/technetwork/middleware/adapters/index.htmlhttp://www.oracle.com/technetwork/middleware/bpa/index.htmlhttp://www.oracle.com/technetwork/middleware/bbi-beans/index.htmlhttp://www.oracle.com/technetwork/middleware/governance/index.htmlhttp://www.oracle.com/technetwork/middleware/essbase/index.htmlhttp://www.oracle.com/technetwork/middleware/epm/index.htmlhttp://www.oracle.com/technetwork/middleware/crystalball/index.html


3/87



events if you need to invoke custom logic at any point during

the entity lifecycle. Figure 1-1 illustrates the relationship

amongst these lifecycle events.

@PreRemove

@PostRemove

@PreUpdate

@PostUpdate

@PostLoad

@EntityListeners

@ExcludeDefaultListeners

@ExcludeSuperclassListeners

Entity

Manager

In an application that uses TopLink JPA, you perform all

persistence operations (create, read, update, and delete)

using an instance of Ent i t yManager .

Use these annotations to declare or inject an entity manager

or entity manager factory.

@PersistenceUnit

@PersistenceUnits

@PersistenceContext

@PersistenceContexts

@PersistenceProperty

Queries In an application that uses TopLink JPA, you can use an entity

manager to create and execute queries dynamically or you

can pre-define queries and execute them by name at run time.

Use these annotations to pre-define queries and manage their

result sets.

@NamedQuery

@NamedQueries

@NamedNativeQuery

@NamedNativeQueries

@QueryHint

@ColumnResult

@EntityResult

@FieldResult

@SqlResultSetMapping

@SqlResultSetMappings

@AssociationOverrideBy default, TopLink JPA automatically assumes that a subclass inherits both persistent properties and

their association mappings as defined in a superclass.

Use the @Associ ati onOver r i deannotation to customize an @OneToOne or @ManyToOne

mapping inherited from a @MappedSuperclass or in an @Embeddable to change the @JoinColumn

associated with the existing field or property.

If you have more than one @Associ ati onOver r i dechange to make, you must use

@AssociationOverrides.

To customize a basic mapping to change its @Column,use @AttributeOverride.

Table 1-2lists the attributes of this annotation . For more details, see theAPI.

Table 1-2 @AssociationOverride Attributes

Att rib ute Requir ed Descr ipt ion

name The name of the field or property defined in the embedded object or mapped

superclass.

j oi nCol umns To specify the join columns that are being mapped to the persistent attribute,

setj oi nCol umns to an array of @J oi nCol umninstances (see

@JoinColumn).

The mapping type will remain the same as is defined in the embeddable class

or mapped superclass.

Example 1-1shows a @MappedSuperclassthat the entity in Example 1-2extends. Example 1-2

shows how to use @Associ ati onOver r i dein the entity subclass to override the @JoinColumn
http://java.sun.com/javaee/5/docs/api/javax/persistence/AssociationOverride.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/AssociationOverride.html


4/87



defined (by default) in the @MappedSuperclassEmpl oyeefor the association to Addr ess .

With @Associ ati onOver r i de, the Par t Ti meEmpl oyeetable would have the Addr ess relationship

mapped to the ADDR_I Dcolumn. Other entity subclasses of Empl oyeewould inherit the default

mapping to the ADDRESS_I Dcolumn, assuming that the primary key column of Addr ess is I D.

Example 1-1 @MappedSuperclass

@MappedSuperc l asspubl i c cl ass Empl oyee { @I d protected I nteger i d; @ManyToOne prot ect ed Address addr ess; . . .}Example 1-2 @AssociationOverride

@Ent i t y

@Associ at i onOver r i de(name="addr ess", j oi nCol umns=@J oi nCol umn(name="ADDR_I D" ) )publ i c cl ass Par t Ti meEmpl oyee ext ends Empl oyee { . . .}

@AssociationOverridesIf you need to specify more than one @AssociationOverride,you must specify all your association

overrides using a single @Associ at i onOverr i des annotation.


Table 1-3 @AssociationOverrides Attributes


val ue To specify two or more association overrides, set val ueto an array of

@Associ ati onOver r i deinstances (see @AssociationOverride).

Example 1-3shows how to use this annotation to specify two association overrides.

Example 1-3 @AssociationOverrides

@Ent i t y@Associ ati onOver r i des( { @Associ at i onOver r i de(name="addr ess", j oi nCol umns=@J oi nCol umn(name="ADDR_I D") ) , @Associ ati onOver r i de( name="heal t hPl an",j oi nCol umns=@J oi nCol umn(name="PLAN_I D" ) )})publ i c cl ass Par t Ti meEmpl oyee ext ends Empl oyee { . . .}

@AttributeOverrideBy default, TopLink JPA automatically assumes that a subclass inherits both persistent properties and

their basic mappings as defined in a mapped superclass.

Use the @At t r i but eOver r i deannotation to customize a basic mapping inherited from a

@MappedSuperclassor in an @Embeddableto change the @Column associated with the field or

property.

If you have more than one @At t r i but eOver r i dechange to make, you must use

@AttributeOverrides.

To customize an association mapping to change its @JoinColumn,use @AssociationOverride.


Table 1-4 @AttributeOverride Attributes


name The name of the field or property defined in the embedded object or mapped

superclass.

col umn The @Column that is being mapped to the persistent attribute. The mapping type

will remain the same as is defined in the embeddable class or mapped superclass.

Example 1-5shows how to use @At t r i but eOver r i dein the entity subclass to override the

@Column defined (by default) in the @MappedSuperclassEmpl oyeefor the basic mapping to i d.

With the @At t r i but eOver r i deannotation, the Par t Ti meEmpl oyeetable would have the i d

attribute mapped to the PTEMP_ID column. Other entity subclasses of Empl oyeewould inherit the

default mapping to the I Dcolumn.

Example 1-4 @MappedSuperclass

@MappedSuperc l asspubl i c cl ass Empl oyee { @I d protected I nteger i d; . . .}Example 1-5 @AttributeOverride

@Ent i t y@Att r i buteOver r i de(name="i d", col umn=@Col umn(name="PTEMP_I D") )publ i c cl ass Par t Ti meEmpl oyee ext ends Empl oyee { . . .
http://java.sun.com/javaee/5/docs/api/javax/persistence/AssociationOverrides.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/AttributeOverride.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/AttributeOverride.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/AssociationOverrides.html


5/87



}

@AttributeOverridesIf you need to specify more than one @AttributeOverride,you must specify all your attribute overrides

using a single @At t r i but eOver r i des annotation.


Table 1-5 @AttributeOverrides Attributes


val ue To specify two or more attribute overrides, set val ueto an array of

@At t r i but eOver r i deinstances (see @AttributeOverride).

Example 1-6shows how to use this annotation to specify two attribute overrides.

Example 1-6 @AttributeOverrides

@Ent i t y@At t ri buteOver ri des({ @Att r i buteOver r i de(name="i d", col umn=@Col umn(name="PTEMP_I D" ) ) , @Att r i buteOver r i de(name="sal ary", col umn=@Col umn(name="SAL" ) )})publ i c cl ass Par t Ti meEmpl oyee ext ends Empl oyee { . . .}

@BasicBy default, TopLink JPA automatically configures a @Basi c mapping for most Java primitive types,

wrappers of the primitive types, and enums.

Use the @Basi c annotation to configure the fetch type to LAZY.


Table 1-6 @Basic Attributes


fe tch Default: Fet chType. EAGER.

By default, TopLink JPA uses a fetch type of EAGER: this is a requirement on

TopLink JPA runtime that data must be eagerly fetched.

If this is inappropriate for your application or a particular persistent field, set fetch

to Fet chType. LAZY: this is a hint that data should be fetched lazily when it is first

accessed (if possible). For more information, see "TopLink JPA Lazy Loading" in the

Oracle Fusion Middleware Oracle TopLink Developer's Guide .

Example 1-7shows how to use this annotation to specify a fetch type of LAZYfor a basic mapping.

Example 1-7 @Basic

@Ent i t ypubl i c cl ass Book i mpl ement s Ser i al i zabl e { . . . @Basi c( f et ch=LAZY) prot ected Str i ng toc;

. . .}

@ColumnBy default, TopLink JPA assumes that each of an entity's persistent attributes is stored in a database

table column whose name matches that of the persistent field or property.

Use the @Col umnannotation:

to associate a persistent attribute with a different name if the default column name is awkward,

incompatible with a pre-existing data model, or invalid as a column name in your database

to associate a persistent attribute with a column in a secondary table (see @SecondaryTable)

to fine-tune the characteristics of a column in your database


Table 1-7 @Column Attributes


name Default: TopLink JPA assumes that each of an entity's persistent

attributes is stored in a database table column whose name matches

that of the persistent field or property.

To specify an alternative column name, set nameto the Str i ng

column name you want.

uni que Default: f a l se.

By default, TopLink JPA assumes that all non-primary key columns
http://java.sun.com/javaee/5/docs/api/javax/persistence/AttributeOverrides.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Basic.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Column.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Column.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Basic.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/AttributeOverrides.html


6/87



are allowed to contain duplicate values.

If this column is not allowed to contain duplicate values, set uni queto

true. When set to true, this is equivalent to using @UniqueConstraint

at the table level.

nul l abl e Default: true.

By default, TopLink JPA assumes that all columns are allowed to

contain a null value.

If this column is not allowed to contain a null value, set nul l abl eto

f a l se .

i nsert abl e Default: true.

By default, TopLink JPA assumes that all columns are always included

in SQL I NSERTstatements.

If this column should not be included in these statements, set

i nsert abl eto f a l se.

updat abl e Default: true.

By default, TopLink JPA assumes that a column is always included in

SQL UPDATEstatements.

If this column should not be included in these statements, set

updat abl eto f a l se .

col umnDefi ni t i on Default: empty Str i ng.

By default, TopLink JPA creates a database table column with minimal

SQL.

If you want the column created with more specialized options, set

col umnDefi ni t i onto the SQL fragment that you want TopLink JPA

to use when generating the DDL for the column.

tabl e Default: TopLink JPA assumes that all the persistent attributes of an

entity are stored in a single database table whose name is the entity

name or is specified by @Tabl e(see @Table).

If this column is associated with a secondary table (see

@SecondaryTable), set nameto the Str i ngname of the appropriate

secondary table name as Example 1-8 shows.

l engt h Default: 255

By default, TopLink JPA assumes that all columns have a maximum

length of 255 characters when used to hold a Str i ngvalue.

If this column width is inappropriate for your application or database,

set the l engt hto the i nt value appropriate for your database

column.

preci si on Default: 0.

By default, TopLink JPA assumes that all columns have a precision of

0 when used to hold a decimal (exact numeric) value.

If this precision is inappropriate for your application or database, set

preci si onto the appropriate i nt precision.

scal e Default: 0.

By default, TopLink JPA assumes that all columns have a scale of 0

when used to hold a decimal (exact numeric) value.

If this scale is inappropriate for your application or database, set

scal eto the appropriate i nt precision.

Example 1-8shows how to use this annotation to make TopLink JPA persist sal ary to column SAL

in secondary table EMP_SAL. By default, TopLink JPA persists sal ary to column sal ary in primary

table EMPLOYEE.

Example 1-8 @Column

@Ent i t y@SecondaryTabl e( name="EMP_SAL")publ i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { . . . @Col umn( name="SAL", t abl e="EMP_SAL") pr i vat e Long sal ary; . . .}

@ColumnResult


7/87



When you execute a @NamedNativeQuery, it can return entities (including entities of different types),

scalar values, or a combination of both.

Use the @Col umnResul t annotation to return scalar values. The type of the scalar is determined by

the type of the column you identify in the @Col umnResul t .

For more information, see also @EntityResult, @FieldResult, and @SqlResultSetMapping.


Table 1-8 @ColumnResult Attributes


name Set nameto the Str i ngequivalent of a column name in the SELECTstatement of a

native SQL query. If you use a column alias ( ASstatement) in the SELECT, then setnameto the column alias.

Example 1-9shows how to use this annotation to include I t em(see Example 1-10 scalar namein the

result list (see Example 1-11). In this case, the result list would be a Li s t of Obj ect arrays like:

{[ Order , "Shoes"] , [ Order, "Socks"] , . . . }.

Example 1-9 Order Entity With @ColumnResult

@Sql Resul t SetMappi ng( name="Or derResul t s" , enti ti es={ @Ent i t yResul t ( ent i t yCl ass=Order. cl ass,

f i el ds={ @Fi el dResul t ( name="i d", col umn="or der _i d") , @Fi el dResul t ( name="quanti t y", col umn="or der _quant i t y") , @Fi el dResul t ( name=" i t em", col umn="order _i t em") } ) },

col umns={ @Col umnResul t ( name="i t em_name" ) })@Ent i t ypubl i c cl ass Order { @I d prot ected i nt i d; pr otected l ong quanti t y; @ManyToOne(f et ch=LAZY) prot ected I tem i t em; . . .}

Example 1-10 Item Entity

@Ent i t ypubl i c cl ass I tem{ @I d prot ected i nt i d; prot ect ed Str i ng name; . . .}Example 1-11 Native Query Using an @SqlResultSetMapping With an @ColumnResult

Quer y q = ent i t yManager. cr eateNat i veQuer y( "SELECT o. i d AS order_ i d, " + "o. quanti ty AS order_quant i t y, " + "o. i t em AS order_i t em, " +

" i . name AS i t em_name " + "FROM Order o, I tem i " + "WHERE ( order _quant i t y > 25) AND ( order_ i t em = i . i d)", "OrderResul t s") ;

L ist resul tL i st = q. getResul tL i st ( ) ;/ / Li st of Obj ect arrays: {[Order, "Shoes"], [Order, "Socks"] , . . . }

@DiscriminatorColumnBy default, when @Inheritance attribute strategy is I nheri t anceType. SI NGLE_TABLEorJ OI NED,

TopLink JPA creates a discriminator column named DTYPEto differentiate classes in an inheritance

hierarchy.

Use the @Di scr i mi nator Col umnannotation:

to specify a discriminator column name if the column name in your data model is not the default

column name DTYPE.

to specify a discriminator column length that is appropriate for your application or a pre-existing data

model

to fine-tune the characteristics of the discriminator column in your database


Table 1-9 @DiscriminatorColumn Attributes


name Default: TopLink JPA assumes that the discriminator column is

named " DTYPE".

To specify an alternative column name, set nameto the Str i ng

column name you want.
http://java.sun.com/javaee/5/docs/api/javax/persistence/ColumnResult.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/DiscriminatorColumn.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/DiscriminatorColumn.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/ColumnResult.html


8/87



di scri mi natorType Default: Di scr i mi nat orType. STRI NG.

By default, TopLink JPA assumes that the discriminator type is a

Str i ng.

If you want to use a different type, set di scri mi nat orTypeto

Di scr i mi nat orType. CHARor Di scr i mi nat orType. I NTEGER.

Your @DiscriminatorValuemust conform to this type.


By default, TopLink JPA creates a database table column with

minimal SQL.


col umnDefi ni t i onto the SQL fragment that you want TopLink

JPA to use when generating the DDL for the column.

l engt h Default: 31

By default, TopLink JPA assumes that the discriminator column has a

maximum length of 31 characters when used to hold a Str i ng

value.

If this column width is inappropriate for your application or database,

set the l engt hto the i nt value appropriate for your database

column.

Your @DiscriminatorValuemust conform to this length.

Example 1-12shows how to use this annotation to specify a discriminator column named DI SCof type

STRI NGand length 20. In this example, the @DiscriminatorValuefor this class is specified as CUST.

The ValuedCustomer subclass specifies its own @DiscriminatorValue of VI P. In both Cust omer and

Val uedCust omer , the value for @DiscriminatorValue must be convertable to the type specified by

@DiscriminatorColumn attribute di scri mi natorTypeand must conform to @DiscriminatorColumn

attribute l engt h.

Example 1-12 @DiscriminatorColumn and @DiscriminatorValue

@Ent i t y@I nheri t ance( st r ategy=SI NGLE_TABLE)@Di scr i mi nat orCol umn(name="DI SC" , di scr i mi nat orType=STRI NG, l ength=20)@Di scr i mi nat orVal ue( val ue- "CUST")publ i c cl ass Cust omer { . . .}@Ent i t y@Di scr i mi nat orVal ue( "VI P")publ i c cl ass Val uedCust omer ext ends Cust omer {

. . .}

@DiscriminatorValueBy default, when @Inheritance attribute strategy is I nheri t anceType. SI NGLE_TABLEorJ OI NED,

TopLink JPA uses the entity name as a @DiscriminatorValueto differentiate classes in the inheritance

hierarchy (see @Entity).

Use the @Di scr i mi nat orVal ueannotation to specify the discriminator value used to differentiate an

entity in this inheritance hierarchy:

if the entity name is inappropriate for this application

to match an existing database schema

Table 1-10 lists the attributes of this annotation . For more details, see theAPI.

Table 1-10 @DiscriminatorValue Attributes


val ue Set val ueto the Str i ngequivalent of a discriminator value that conforms to the

@DiscriminatorColumn attributes di scri mi natorTypeand l engt h.

Example 1-13shows how to use this annotation to specify a discriminator column named DI SCof type

STRI NGand length 20. In this example, the @DiscriminatorValuefor this class is specified as CUST.

The Val uedCust omer subclass specifies its own @DiscriminatorValueof VI P. In both Cust omer

and Val uedCust omer , the value for @DiscriminatorValue must be convertable to the type specified

by @DiscriminatorColumn attribute di scri mi natorTypeand must conform to

@DiscriminatorColumn attribute l engt h.

Example 1-13 @DiscriminatorColumn and @DiscriminatorValue

@Ent i t y@I nheri t ance( st r ategy=SI NGLE_TABLE)@Di scr i mi nat orCol umn(name="DI SC" , di scr i mi nat orType=STRI NG, l ength=20)@Di scr i mi nat orVal ue( "CUST")publ i c cl ass Cust omer { . . .}
http://java.sun.com/javaee/5/docs/api/javax/persistence/DiscriminatorValue.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/DiscriminatorValue.html


9/87



@Ent i t y@Di scr i mi nat orVal ue( "VI P")publ i c cl ass Val uedCust omer ext ends Cust omer {

. . .}

@EmbeddableBy default, TopLink JPA assumes that every entity is persisted to its own database table.

Use the @Embeddabl eannotation to specify a class whose instances are stored as an intrinsic part of

an owning entity and share the identity of the entity. Each of the persistent properties or fields of the

embedded object is mapped to the database table for the entity.

This annotation has no attributes . For more details, see theAPI.

Example 1-14shows how to use this annotation to specify that class Empl oyment Per i odmay beembedded in an entity when used as the type for a persistent field annotated as @Embedded (see

Example 1-15).

Example 1-14 @Embeddable

@Embeddabl epubl i c cl ass Empl oyment Per i od { j ava.sql . Dat e start Date; j ava. sql . Date endDate; . . .}

@EmbeddedBy default, TopLink JPA assumes that every entity is persisted to its own database table.

Use the @Embeddedannotation to specify a persistent field whose @Embeddable type can be stored

as an intrinsic part of the owning entity and share the identity of the entity. Each of the persistent

properties or fields of the embedded object is mapped to the database table for the owning entity.

You can use @Embeddedin conjunction with @Embeddable to model a strict ownership relationship sothat if the owning object is removed, the owned object is also removed.

Embedded objects should not be mapped across more than one table.

By default, column definitions (see @Column)specified in the @Embeddable class apply to the table

of the owning entity. If you want to override these column definitions, use @AttributeOverride.

This annotation has no attributes. For more details, see theAPI.

Example 1-15shows how to use this annotation to specify that @Embeddable class

Empl oymentPer i od(see Example 1-14) may be embedded in the entity class using the specified

attribute overrides (see @AttributeOverride). If you do not need attribute overrides, you can omit the

@Embeddedannotation entirely: TopLink JPA will infer that Empl oymentPer i odis embedded from its

@Embeddableannotation.

Example 1-15 @Embedded

@Ent i t y

publ i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { . . . @Embedded @At t ri buteOver ri des({ @Att r i buteOver r i de(name="st ar t Dat e", col umn=@Col umn(name="EMP_START") ) , @Att r i buteOver r i de(name="endDat e", col umn=@Col umn( name="EMP_END") ) ) publ i c Empl oyment Peri od get Empl oyment Peri od() {

. . .}

. . .}

@EmbeddedIdUse the @EmbeddedI dannotation to specify an embeddable composite primary key class (usually

made up of two or more primitive or JDK object types) owned by the entity. Composite primary keys

typically arise when mapping from legacy databases when the database key is comprised of several

columns.

A composite primary key class has the following characteristics:

It is a plain old Java object (POJO) class.

It must be public and must have a public no-argument constructor.

If you use property-based access, the properties of the primary key class must be public or

protected.

It must be serializable.

It must define equal s and hashCodemethods.

The semantics of value equality for these methods must be consistent with the database equality for

the database types to which the key is mapped.

Alternatively, you can make the composite primary key class a non-embedded class (see @IdClass).


Example 1-16shows a typical composite primary key class, annotated as @Embeddable.Example 1-
http://java.sun.com/javaee/5/docs/api/javax/persistence/Embeddable.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Embedded.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/EmbeddedId.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/EmbeddedId.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Embedded.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Embeddable.html


10/87



17shows how to configure an entity with this embeddable composite primary key class using the

@EmbeddedI dannotation.

Example 1-16 Embeddable Composite Primary Key Class

@Embeddabl epubl i c cl ass Empl oyeePK i mpl ement s Seri al i zabl e { pri vat e Str i ng name; pri vat e l ong i d;

publ i c Empl oyeePK() { }

publ i c Str i ng get Name() { r et urn name; }

publ i c voi d set Name(St r i ng name) { t hi s. name = name; }

publ i c l ong getI d() { return i d; }

publ i c void setI d(l ong i d) { th is . i d = i d; }

publ i c i nt hashCode() { r etur n ( i nt) name. hashCode() + i d; }

publ i c bool ean equal s( Obj ect obj ) { i f (obj == thi s) return tr ue; i f (obj == nul l ) return f al se; i f ( !( obj i nstanceof Empl oyeePK)) return f al se; Empl oyeePK pk = ( Empl oyeePK) obj ; r eturn pk. i d == i d && pk. name. equal s( name) ; }}

Example 1-17 @EmbeddedId

@Ent i t ypubl i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { Empl oyeePK pr i maryKey;

publ i c Empl oyee() { }

@EmbeddedI d publ i c Empl oyeePK get Pri maryKey() { r etur n pri maryKey; }

publ i c voi d set Pri maryKey(Empl oyeePK pk) { pr i maryKey = pk; }

. . .}

@EntityUse the @Ent i t yannotation to designate a plain old Java object (POJO) class as an entity and make

it eligible for JPA services. You must designate a POJO class as an entity before you can use any

other JPA annotations.


Table 1-11 @Entity Attributes


name Default: TopLink JPA assumes that the name of the entity is the unqualified name

of the entity class. In Example 1-18,the default nameis " Empl oyee".

If the entity class name is awkward, a reserved word, incompatible with a pre-

existing data model, or invalid as a table name in your database, set nameto an

alternative Str i ngvalue.

Example 1-18shows how to use this annotation.

Example 1-18 @Entity

@Ent i t ypubl i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { . . .}

@EntityListenersYou can use lifecycle annotations (see Lifecycle Event Annotations) to designate methods that

execute your logic when specified lifecycle events occur.

Use the @Enti t yLi st eners annotation to associate one or more entity listener classes with an

@Entityor @MappedSuperclass if you need to execute logic when specified lifecycle events occur

and:

You do not want to expose lifecycle listener methods in your entity API.

You want to share lifecycle listener logic between different entity types.

When a lifecycle event occurs on the entity or subclass, TopLink JPA notifies each entity listener class

in the order in which listeners are defined, and invokes the entity listener method (if any) annotated

with the corresponding lifecycle event type.
http://java.sun.com/javaee/5/docs/api/javax/persistence/Entity.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Entity.html


11/87



An entity listener class has the following characteristics:

It is a plain old Java object (POJO) class

It has one or more callback methods with the following signature:

publ i c voi d ( Obj ect )You may specify an argument type of Obj ect or the type of the entity class you will associate the

entity listener with.

It has each callback method annotated with one or more lifecycle event annotations.

You may associate a lifecycle event with one and only one callback listener method but you may

associate a given callback listener method with more than one lifecycle event.

If you use entity listeners, you can manage what entity listeners are invoked using

@ExcludeDefaultListenersand @ExcludeSuperclassListeners.


Table 1-12 @EntityListeners Attributes


val ue To specify the list of entity listener classes for an @Entity or @MappedSuperclass,

set val ueto a Cl assarray of entity listener classes.

Example 1-19shows how to use this annotation to associate entity listener classes

Empl oyeePer si st Li st ener (see Example 1-20) and Empl oyeeRemoveLi st ener (see Example

1-21) with the entity Empl oyee. Example 1-21shows that you can associate more than one lifecycle

event with a given entity listener class method but any given lifecycle event may appear in an entity

listener class only once.

Example 1-19 @EntityListeners

@Ent i t y@Ent i t yLi st eners( {Empl oyeePers i st Li st ener. cl ass, Empl oyeeRemoveLi st ener. cl ass})publ i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { . . .}

Example 1-20 EmployeePersistListener

publ i c cl ass Empl oyeePers i st Li st ener { @PostPers i st @Post Load publ i c voi d empl oyeePersi st ( Obj ect empl oyee) { . . . } . . .}Example 1-21 EmployeeRemoveListener

publ i c cl ass Empl oyeeRemoveLi st ener { @Pr eRemove publ i c voi d empl oyeePreRemove(Obj ect empl oyee) { . . . }

. . .}

@EntityResultWhen you execute a @NamedNativeQuery, it can return entities (including entities of different types),


Use the @Ent i t yResul t annotation to return entities.

For more information, see also @ColumnResult,@FieldResult,and @SqlResultSetMapping.


Table 1-13 @EntityResult Attributes


ent i t yCl ass Set ent i t yCl ass to the Cl assof the entity returned by the

query.

f i el ds Default: empty Fi el dResul t array.

By default, TopLink JPA assumes that the SELECTstatement

includes all the columns that correspond to all the fields or

properties of the entity returned and the column names in the

SELECTstatement correspond to the field or property names ( AS

statements are not used).

If your SELECT statement includes only some of the columns that

correspond to the fields or properties of the entity returned or the

column names in the SELECT statement do not correspond to the

field or property names ( ASstatements are used), set f i el ds to

an array of @FieldResult,one @FieldResult per column in the

SELECTstatement.

di scr i mi nat or Col umn St r i ng
http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityListeners.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/EntityResult.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/EntityResult.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/EntityListeners.html


12/87



Default: empty .

By default, TopLink JPA assumes that a discriminator column (see

@Inheritance)is not included in the SELECTstatement.

If you use a discriminator column in your SELECTstatement, set

di scr i mi nat orCol umnto the Str i ngcolumn name you use.

Example 1-22shows how to use this annotation to include both Or der and I t em(see Example 1-23)

entities in the result list (see Example 1-24). In this case, the result list would be a Li s t of Obj ect

arrays like: {[Order, I tem], [ Order, I tem], . . . }.

Example 1-22 Order Entity With @EntityResult


f i el ds={ @Fi el dResul t ( name="i d", col umn="or der _i d") , @Fi el dResul t ( name="quanti t y", col umn="or der _quant i t y") , @Fi el dResul t ( name=" i t em", col umn="order _i t em") } ) , @Ent i t yResul t ( ent i t yCl ass=I t em. cl ass, fi el ds={ @Fi el dResul t ( name="i d", col umn="i t em_i d") , @Fi el dResul t ( name="name", col umn=" i t em_name") } ) })@Ent i t ypubl i c cl ass Order { @I d prot ected i nt i d; pr otected l ong quanti t y; @ManyToOne

prot ected I tem i t em; . . .}


@Ent i t ypubl i c cl ass I tem{ @I d prot ected i nt i d; prot ect ed Str i ng name; . . .}

Example 1-24 Native Query Using an @SqlResultSetMapping With an @EntityResult


"i . i d AS i tem_i d, " + " i . name AS i t em_name " + "FROM Order o, I tem i " + "WHERE ( order_quanti t y > 25) AND ( order_i t em = i . i d)" "OrderResul t s") ;

L ist resul tL i st = q. getResul tL i st ( ) ;/ / Li st of Obj ect arrays: {[Order, I tem], [Order, I tem], . . . }

@EnumeratedBy default, TopLink JPA persists the ordinal values of enumerated constants.

Use the @Enumer at edannotation to specify whether TopLink JPA should persist ordinal or Str i ng

values of enumerated constants if the String value suits your application requirements or to match an

existing database schema.

This annotation can be used with @Basic.


Table 1-14 @Enumerated Attributes


val ue Default: EnumType. ORDI NAL .

By default, TopLink JPA assumes that for a property or field mapped to an

enumerated constant, the ordinal value should be persisted. In Example 1-26, the

ordinal value of Empl oyeeStat usis written to the database when Empl oyeeis

persisted.

If you want the String value of the enumerated constant persisted, set val ueto

EnumType. STRI NG.

Given the enumerated constants in Example 1-25, Example 1-26shows how to use this annotation to

specify that the Str i ngvalue of Sal aryRate should be written to the database when Empl oyeeis

persisted. By default, the ordinal value of Empl oyeeStat usis written to the database.

Example 1-25 Enumerated Constants

publ i c enum Empl oyeeSt atus {FULL_TI ME, PART_TI ME, CONTRACT}publ i c enum Sal aryRate {J UNI OR, SENI OR, MANAGER, EXECUTI VE}
http://java.sun.com/javaee/5/docs/api/javax/persistence/Enumerated.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Enumerated.html


13/87



Example 1-26 @Enumerated

@Ent i t ypubl i c cl ass Empl oyee { . . . publ i c Empl oyeeSt atus get Stat us() { . . . }

@Enumer at ed( STRI NG) publ i c Sal aryRate get PayScal e() { . . . } . . .}

@ExcludeDefaultListenersA default listener is a lifecycle event listener class specified in the or m. xml file that applies to all

entities in a persistence unit (see @PersistenceUnit). TopLink JPA first invokes default listeners, ifany, in the order defined in the or m. xml file, before any other entity listeners (see @EntityListeners).

Use the @Excl udeDef aul t Li st eners annotation to override (and prevent) default listener

execution for a given @Entity or @MappedSuperclassif default listener behavior does not apply.


Example 1-27shows how to use this annotation to specify that default listeners should not be

executed for the Empl oyeeentity.

Example 1-27 @ExcludeDefaultListeners

@Ent i t y@Excl udeDef aul t Li st enerspubl i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { . . .}

@ExcludeSuperclassListeners

If the @Entityand @MappedSuperclassclasses in an inheritance hierarchy define @EntityListeners,by default, TopLink JPA invokes superclass listeners before subclass listeners.

Use the @Excl udeSupercl assLi st eners annotation to override (and prevent) superclass listener

execution for a given @Entity or @MappedSuperclassif superclass listener behavior does not apply.

The @Excl udeSupercl assLi st eners annotation does not affect default listeners (see

@ExcludeDefaultListeners).


Example 1-28shows how to use this annotation to specify that superclass listener

Empl oyeeLi st ener should not be executed for the Par t Ti meEmpl oyeeentity but default listeners

and subclass listeners Part Ti meEmpl oyeeLi st ener1 and Part Ti meEmpl oyeeLi st ener2 are

executed.

Example 1-28 Entity Listeners at the Superclass Level

@MappedSuperc l ass

@Ent i t yLi st eners( {Empl oyeeLi st ener. cl ass})publ i c cl ass Empl oyee { . . .}

Example 1-29 @ExcludeSuperclassListeners at the Subclass Level

@Ent i t y@Excl udeSupercl assLi st eners@Ent i t yLi st eners( {Part Ti meEmpl oyeeLi st ener1. cl ass,Par t Ti meEmpl oyeeLi st ener2. cl ass})publ i c cl ass Par t Ti meEmpl oyee ext ends Empl oyee { . . .}

@FieldResultWhen you execute a @NamedNativeQuery, it can return entities (including entities of different types),


By default, TopLink JPA assumes that when returning entities with @EntityResult, the SELECT

statement includes all the columns that correspond to all the fields or properties of the entity returned

and the column names in the SELECT statement correspond to the field or property names (AS

statements are not used).

Use the @Fi el dResul t annotation to map columns in the SELECTstatement to fields or properties

when returning entities with @EntityResultif your SELECTstatement includes only some of the

columns that correspond to the fields or properties of the entity returned or the column names in the

SELECTstatement do not correspond to the field or property names ( ASstatements are used).

For more information, see also @ColumnResult and @SqlResultSetMapping.


Table 1-15 @FieldResult Attributes


name Set nameto the entity's field or property name (as a Str i ng) that corresponds to

the column name specified by the col umnattribute.
http://java.sun.com/javaee/5/docs/api/javax/persistence/ExcludeDefaultListeners.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/ExcludeSuperclassListeners.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/FieldResult.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/FieldResult.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/ExcludeSuperclassListeners.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/ExcludeDefaultListeners.html


14/87



col umn Set col umnto the Str i ngname of the column used in the SELECTstatement. If

you use a column alias ( ASstatement) in the SELECT, then set col umnto the

column alias.

Example 1-30shows how to use this annotation to include both Or der and I t em(see Example 1-31)

entities in the result list (see Example 1-32). In this case, the result list would be a Li s t of Obj ect

arrays like: {[Order, I tem], [ Order, I tem], . . . }.

Example 1-30 Order Entity With @EntityResult and @FieldResult


f i el ds={ @Fi el dResul t ( name="i d", col umn="or der _i d") , @Fi el dResul t ( name="quanti t y", col umn="or der _quant i t y") , @Fi el dResul t ( name=" i t em", col umn="order _i t em") } ) , @Ent i t yResul t ( ent i t yCl ass=I t em. cl ass, fi el ds={ @Fi el dResul t ( name="i d", col umn="i t em_i d") , @Fi el dResul t ( name="name", col umn=" i t em_name") } ) })@Ent i t ypubl i c cl ass Order { @I d prot ected i nt i d; pr otected l ong quanti t y; @ManyToOne prot ected I tem i t em; . . .}


@Ent i t ypubl i c cl ass I tem{ @I d prot ected i nt i d; prot ect ed Str i ng name; . . .}

Example 1-32 Native Query Using an @SqlResultSetMapping With an @EntityResult


"i . i d AS i tem_i d, " + " i . name AS i t em_name " + "FROM Order o, I tem i " + "WHERE ( order _quant i t y > 25) AND ( order_ i t em = i . i d)", "OrderResul t s") ;

L ist resul tL i st = q. getResul tL i st ( ) ;/ / Li st of Obj ect arrays: {[Order, I tem], [Order, I tem], . . . }

@GeneratedValueBy default, the application is responsible for supplying and setting entity identifiers (see @Id).

Use the @Generat edVal ueannotation if you want TopLink JPA to provide and manage entity

identifiers.


Table 1-16 @GeneratedValue Attributes


strategy Default: Gener at i onType. AUTO.

By default, TopLink JPA chooses the type of primary key generator that is most

appropriate for the underlying database.

If you feel that another generator type is more appropriate for your database or

application, set strategyto the Gener at orTypeyou want:

I DENTI TY- specify that TopLink JPA use a database identity column

AUTO- specify that TopLink JPA should choose a primary key generator that is

most appropriate for the underlying database.

SEQUENCE- specify that TopLink JPA use a database sequence (see

@SequenceGenerator)

TABLE- specify that TopLink JPA assign primary keys for the entity using an

underlying database table to ensure uniqueness (see @TableGenerator)

gener ator Default: TopLink JPA assigns a name to the primary key generator it selects.

If this name is awkward, a reserved word, incompatible with a pre-existing data

model, or invalid as a primary key generator name in your database, set

gener ator to the Str i nggenerator name you want to use.
http://java.sun.com/javaee/5/docs/api/javax/persistence/GeneratedValue.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/GeneratedValue.html


15/87



Example 1-33shows how to use this annotation to tell TopLink JPA to use a primary key generator of

type Generat or Type. SEQUENCEnamed CUST_SEQ.

Example 1-33 @GeneratedValue

@Ent i t ypubl i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { . . . @I d @Gener at edVal ue(st r at egy=SEQUENCE, generat or ="CUST_SEQ") @Col umn( name="CUST_I D" ) publ i c Long get I d() {

return id;}

. . .}

@IdUse the @I dannotation to designate one or more persistent fields or properties as the entity's primary

key.

For each entity, you must designate at least one of the following:

one @I d

multiple @I dand an @IdClass(for a composite primary key)

one @EmbeddedId


Example 1-34shows how to use this annotation to designate persistent field empI Das the primary

key of the Empl oyeetable.

Example 1-34 @Id

@Ent i t ypubl i c cl ass Empl oyee i mpl ement s Ser i al i zabl e {

@I d pr i vat e i nt empI D; . . .}

@IdClassUse the @I dCl ass annotation to specify a composite primary key class (usually made up of two or

more primitive or JDK object types) for an entity. Composite primary keys typically arise when

mapping from legacy databases when the database key is comprised of several columns.

A composite primary key class has the following characteristics:

It is a plain old Java object (POJO) class.

It must be public and must have a public no-argument constructor.

If you use property-based access, the properties of the primary key class must be public or

protected.

It must be serializable.

It must define equal s and hashCodemethods.

The semantics of value equality for these methods must be consistent with the database equality for

the database types to which the key is mapped.

Its fields or properties must correspond in type and name to the entity primary key fields or

properties annotated with @Id.

Alternatively, you can make the composite primary key class an embedded class owned by the entity

(see @EmbeddedId).


Table 1-17 @IdClass Attributes


val ue To specify a composite primary key class, set val ueto the Cl assyou want.

Example 1-35shows a non-embedded composite primary key class. In this class, fields empNameand

bi r t hDaymust correspond in name and type to properties in the entity class. Example 1-36 shows

how to configure a JPA entity with this non-embedded composite primary key class using the

@I dCl ass annotation. Because entity class fields empNameand bi r t hDayare used in the primary

key, you must also annotate them using the @Idannotation.

Example 1-35 Non-Embedded Composite Primary Key Class

publ i c cl ass Empl oyeePK i mpl ement s Seri al i zabl e{ pr i vat e St r i ng empName; pr i vat e Date bi rt hDay;

publ i c Empl oyeePK() { }

publ i c Str i ng get EmpName( ) {
http://java.sun.com/javaee/5/docs/api/javax/persistence/Id.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/IdClass.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/IdClass.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Id.html


16/87



r et ur n empName; }

publ i c voi d set EmpName(Str i ng name) { empName = name; }

publ i c Date get Bi rt hDay( ) { ret urn bi rt hDay; }

publ i c voi d setBi rt hDay( Date dat e) { bi r t hDay = dat e; }

publ i c i nt hashCode() { r eturn ( i nt) empName. hashCode( ) ; }

publ i c bool ean equal s( Obj ect obj ) { i f (obj == thi s) return tr ue;

i f (obj == nul l ) return f al se; i f ( !( obj i nstanceof Empl oyeePK)) return f al se; Empl oyeePK pk = ( Empl oyeePK) obj ; r et urn pk. bi r t hDay == bi r t hDay && pk. empName. equal s( empName) ; }}Example 1-36 @IdClass

@I dCl ass( Empl oyeePK. cl ass)@Ent i t ypubl i c cl ass Empl oyee { @I d St r i ng empName; @I d Date bi r t hDay;. . .}

@InheritanceBy default, TopLink JPA automatically manages the persistence of entities in an inheritance hierarchy.

Use the @I nheri t anceannotation to customize the TopLink JPA inheritance hierarchy support to

improve application performance or to match an existing data model.


Table 1-18 @Inheritance Attributes


strategy Default: I nher i t anceType. SI NGLE_TABLE.

By default, TopLink JPA assumes that all the classes in a hierarchy are mapped

to a single table differentiated by the discriminator value (see

@DiscriminatorValue) in the table's discriminator column (see

@DiscriminatorColumn).

If this is not appropriate for your application or if you must match an existing data

model, set strategyto the desired I nheri t anceType:

SI NGLE_TABLEFoot 1 - all the classes in a hierarchy are mapped to a single

table. The table has a discriminator column (see @DiscriminatorColumn)whose

value (see @DiscriminatorValue) identifies the specific subclass to which theinstance that is represented by the row belongs.

J OI NED- the root of the class hierarchy is represented by a single table and

each subclass is represented by a separate table. The table has a discriminator

column (see @DiscriminatorColumn). Each subclass table additionally contains

fields that are specific to the subclass (not inherited from its superclass) and

primary key columns that serve as foreign keys to the primary keys of the

superclass table.

Footnote 1 This option provides the best support for both polymorphic relationships between entities and

queries that range over the class hierarchy. The disadvantages of this option include the need to make

nullable columns that should be NOT NULL .

Example 1-37shows how to use this annotation to specify that all subclasses of Cust omer will use

I nheri t anceType. J OI NED. The subclass in Example 1-38 will be mapped to its own table that

contains a column for each the persistent properties of Val uedCust omer and one foreign key column

that contains the primary key to the Cust omer table.

Example 1-37 @Inheritance - Root Class Using JOINED

@Ent i t y@I nheri t ance(s t r ategy=J OI NED) publ i c cl ass Cust omer {@I d

pr i vat e i nt cust omerI d; . . .}

Example 1-38 @Inheritance - Subclass Using JOINED

@Ent i t ypubl i c cl ass Val uedCust omer ext ends Cust omer {

. . .}

In Example 1-39,by default, I nher i t anceType. SI NGLE_TABLEapplies to Cust omer and all its

subclasses. In this example, the default discriminator column DTYPE(see @DiscriminatorColumn)is

specified as having a discriminator type of I NTEGERand the @DiscriminatorValuefor Cust omer is

specified as 1. Example 1-40shows how to specify the discriminator value for subclass

Val uedCust omer as 2. In this example, all the persistent properties of both Cust omer and
http://java.sun.com/javaee/5/docs/api/javax/persistence/Inheritance.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/Inheritance.html


17/87



Val uedCust omer will be mapped to a single table.

Example 1-39 @Inheritance - Root Class Specifying its Discriminator Column

@Ent i t y@Di scr i mi nat orCol umn(di scr i mi nat orType=Di scr i mi nat orType. I NTEGER)@Di scr i mi nat orVal ue( "1")publ i c cl ass Customer {

. . .}

Example 1-40 @Inheritance - Subclass Specifying its Discriminator Value

@Ent i t y@Di scr i mi nat orVal ue( "2")publ i c cl ass Val uedCust omer ext ends Cust omer {

. . .}

@JoinColumnBy default, in an entity association, TopLink JPA assumes a database schema based on existing

names (such as field or property names) so that it can automatically determine the single join column

(the column that contains the foreign key) to use.

Use the @J oi nCol umnannotation if:

the default join column name is awkward, a reserved word, incompatible with a pre-existing data

model, or invalid as a column name in your database

you want to join using a column in the foreign table other than the primary key column

you want to use two or more join columns (see @JoinColumns)

you want to use a join table (see @JoinTable)


Table 1-19 @JoinColumn Attributes


name Default: if you are using a single join column, TopLink JPA

assumes that the name of the foreign key column is the name of

the referencing relationship field or property + "_" + the name of

the referenced primary key column.

If join columns are being used in a join table (see @JoinTable),

the join column name is formed as the concatenation of the name

of the entity + "_" + the name of the referenced primary key

column.

If the join is for a one-to-one or many-to-one entity relationship,

this column is in the table of the source entity. If the join is for a

many-to-many entity relationship, this column is in a join table

(see @JoinTable).

If the join column name is awkward, a reserved word,incompatible with a pre-existing data model, or invalid as a

column name in your database, set nameto the Str i ngcolumn

name you want.

r ef er encedCol umnName Default: if you are using a single join column, TopLink JPA

assumes that in an entity relationship, the referenced column

name is the name of the referenced primary key column.

If used in a join table (see @JoinTable), the referenced key

column is in the entity table of the owning entity, or inverse entity

if the join is part of the inverse join definition.

To specify an alternative column name, set

r ef er encedCol umnNameto the Str i ngcolumn name you

want.

uni que Default: f a l se .

By default, TopLink JPA assumes that join columns are allowed

to contain duplicate values.

If this column is not allowed to contain duplicate values, set

uni queto true.

nul l abl e Default: true.

By default, TopLink JPA assumes that all columns are allowed to

contain a null value.

If this column is not allowed to contain a null value, set nul l abl e

to f a l se.

i nsert abl e Default: true.

By default, TopLink JPA assumes that it can insert into all table
http://java.sun.com/javaee/5/docs/api/javax/persistence/JoinColumn.htmlhttp://java.sun.com/javaee/5/docs/api/javax/persistence/JoinColumn.html


18/87



columns.

If this column is read-only, set i nsert abl eto f a l se .

updat abl e Default: true.

By default, TopLink JPA assumes that it can update all table

columns.

If this column is read-only, set updat abl eto f a l s e


TopLink JPA creates a database table column with minimal SQL.


col umnDefi ni t i onto the Str i ngSQL fragment that you want

TopLink JPA to use when generating the DDL for the column.

tabl e Default: TopLink JPA assumes that join columns of one-to-one

and many-to-one relationships are stored in a single database

table whose name is the entity class name (see @Table).

If this column is associated with a secondary table (see

@SecondaryTable), set nameto the Str i ngname of the

appropriate secondary table name as Example 1-8 shows.

Example 1-41shows how to use this annotation to make TopLink JPA use database table Empl oyee

column ADDR_I Das the join column.

Example 1-41 @JoinColumn

@Ent i t ypubl i c cl ass Empl oyee i mpl ement s Ser i al i zabl e { . . . @ManyToOne @J oi nCol umn( name="ADDR_I D" ) publ i c Addr ess getAddress() { r etur n address; }}

@JoinColumnsBy default, in an entity association, TopLink JPA assumes that a single join column is used.

Use the @J oi nCol umns annotation if you want to specify two or more join columns (that is, a

composite primary key).


Table 1-20 @JoinColumns Attributes

Att rib ute Requir ed Descr ipt ionval ue To specify two or more join columns, set val ueto an array ofJ oi nCol umn

instances (see @JoinColumn).

Example 1-42shows how to use this annotation to specify the names of two join columns: ADDR_I D

in the Empl oyeetable which contains foreign key values f

Documents

TopLink JPA Annotation Reference