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.html7/22/2019 TopLink JPA Annotation Reference
2/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
@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.html7/22/2019 TopLink JPA Annotation Reference
3/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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.html7/22/2019 TopLink JPA Annotation Reference
4/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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-3lists the attributes of this annotation . For more details, see theAPI.
Table 1-3 @AssociationOverrides Attributes
Att rib ute Requir ed Descr ipt ion
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-4lists the attributes of this annotation . For more details, see theAPI.
Table 1-4 @AttributeOverride 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.
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.html7/22/2019 TopLink JPA Annotation Reference
5/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
}
@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-5lists the attributes of this annotation . For more details, see theAPI.
Table 1-5 @AttributeOverrides Attributes
Att rib ute Requir ed Descr ipt ion
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-6lists the attributes of this annotation . For more details, see theAPI.
Table 1-6 @Basic Attributes
Att rib ute Requir ed Descr ipt ion
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-7lists the attributes of this annotation . For more details, see theAPI.
Table 1-7 @Column Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
6/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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/22/2019 TopLink JPA Annotation Reference
7/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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-8lists the attributes of this annotation . For more details, see theAPI.
Table 1-8 @ColumnResult Attributes
Att rib ute Requir ed Descr ipt ion
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-9lists the attributes of this annotation . For more details, see theAPI.
Table 1-9 @DiscriminatorColumn Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
8/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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.
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.
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
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
9/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
@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).
This annotation has no attributes . For more details, see theAPI.
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.html7/22/2019 TopLink JPA Annotation Reference
10/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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 lists the attributes of this annotation . For more details, see theAPI.
Table 1-11 @Entity Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
11/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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 lists the attributes of this annotation . For more details, see theAPI.
Table 1-12 @EntityListeners Attributes
Att rib ute Requir ed Descr ipt ion
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),
scalar values, or a combination of both.
Use the @Ent i t yResul t annotation to return entities.
For more information, see also @ColumnResult,@FieldResult,and @SqlResultSetMapping.
Table 1-13 lists the attributes of this annotation . For more details, see theAPI.
Table 1-13 @EntityResult Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
12/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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
@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") } ) , @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; . . .}
Example 1-23 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-24 Native Query Using an @SqlResultSetMapping With an @EntityResult
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 . 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 lists the attributes of this annotation . For more details, see theAPI.
Table 1-14 @Enumerated Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
13/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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.
This annotation has no attributes . For more details, see theAPI.
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).
This annotation has no attributes . For more details, see theAPI.
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),
scalar values, or a combination of both.
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 lists the attributes of this annotation . For more details, see theAPI.
Table 1-15 @FieldResult Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
14/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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
@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") } ) , @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; . . .}
Example 1-31 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-32 Native Query Using an @SqlResultSetMapping With an @EntityResult
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 . 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 lists the attributes of this annotation . For more details, see theAPI.
Table 1-16 @GeneratedValue Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
15/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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
This annotation has no attributes . For more details, see theAPI.
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 lists the attributes of this annotation . For more details, see theAPI.
Table 1-17 @IdClass Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
16/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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 lists the attributes of this annotation . For more details, see theAPI.
Table 1-18 @Inheritance Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
17/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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 lists the attributes of this annotation . For more details, see theAPI.
Table 1-19 @JoinColumn Attributes
Att rib ute Requir ed Descr ipt ion
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.html7/22/2019 TopLink JPA Annotation Reference
18/87
nk JPA Annotation Reference
/www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]
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
col umnDefi ni t i on Default: empty Str i ng.
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 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 lists the attributes of this annotation . For more details, see theAPI.
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