TopLink JPA Annotation Reference

TopLink JPA Annotation Reference
( Sign In/Register for Account | Help )
United States
Communities
I am a...
I want to...
Secure Search
Products and Services

Oracle Technology Network
Downloads
Middleware
Store
Support
Education
Partners
About
Oracle Technology Network
Application Server
Fusion Middleware Home AIA Foundation Pack Business Intelligence Coherence Developer Tools Event-Driven Architecture Suite GlassFish Server Identity Management JRockit SOA Suite TopLink Tuxedo WebCenter Suite WebLogic Server Complex Event Processing Business Intelligence Foundation Data Integration Application Server Beehive BPEL Process Manager Business Integration Business Process Management Communications Converged Applications 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 Intelligent Collaboration WebCenter Real-Time Collaboration WebLogic Integration WebLogic Portal Business Activity Monitoring BI Publisher Note : Starting with Oracle TopLink 11 g , JPA support is provided through EclipseLink. EclipseLink supports the JPA 1.0 implementation as well as may extensions, including those previously known as TopLink JPA. Please see http://www.eclipse.org/eclipselink for more information.
Popular Downloads Berkeley DB Enterprise Manager Database EE and XE Enterprise Pack for Eclipse Fusion Middleware Java EE & GlassFish Java SE JDeveloper and ADF MySQL NetBeans IDE Pre-built Developer VMs Solaris 10 & 11 Express SQL Developer VM VirtualBox Zend Server

The 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 objectrelational 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 @Entity annotation as follows:
@Entity public class Employee implements Serializable { ... }
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 nonpersistent 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 orm.xml file) before you can use the class with JPA services.
@Entity
Database Schema Attributes
By default, TopLink JPA assumes that an entity's name corresponds to a database table of the same name and that an entity's data member names correspond to database columns with the same names.
@Table @SecondaryTable @SecondaryTables
Use these annotations to override this default behavior and @Column fine-tune the relationship between your object model and data @JoinColumn model. @JoinColumns @PrimaryKeyJoinColumn @PrimaryKeyJoinColumns @JoinTable
http://www.oracle.com/technetwork/middleware/ias/toplink-jpa-annotations-096251.html[12/24/2010 11:59:53 AM]

Crystal Ball Enterprise Performance Management Essbase SOA Governance Business Intelligence Beans
@UniqueConstraint
Identity
By default, TopLink JPA assumes that each entity must have @Id at least one field or property that serves as a primary key. @IdClass Use these annotations to specify one of the following: @EmbeddedId one @Id @GeneratedValue multiple @Id and an @IdClass one @EmbeddedId @SequenceGenerator @TableGenerator
Business Process Analysis Suite Integration Adapters MapViewer Performance Management Performance Scorecard Workforce Planning Financial Management Financial Close Management Strategic Finance Profitability and Cost Management Hyperion Planning Business Intelligence Enterprise Edition Business Intelligence Standard Edition Real-Time Decisions Hyperion Smart View for Office Smart Space Interactive Reporting Business-to-Business Integrations User Productivity Kit Service Bus for Financial Services Business Rules Human Workflow Data Service Integrator Data Integrator GoldenGate Collaboration Suite Oracle Fusion Middleware for Apps
You can also use these annotations to fine-tune how your database maintains the identity of your entities. Direct Mappings By default, TopLink JPA automatically configures a Basic 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 TopLink JPA requires that you map relationships explicitly, but @OneToOne Mappings TopLink allows some defaulting. @ManyToOne Use these annotations to specify the type and characteristics @OneToMany of entity relationships to fine-tune how your database implements these relationships. @ManyToMany @MapKey @OrderBy
Composition Some 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 @Inheritance defined by a single entity class. @DiscriminatorColumn Use these annotations if your entity class inherits some or all persistent fields from one or more superclasses. @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.
@PrePersist
Use these annotations to associate methods with JPA lifecycle @PostPersist
TopLink JPA Annotation Reference 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 EntityManager . 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 @NamedQuery manager to create and execute queries dynamically or you @NamedQueries can pre-define queries and execute them by name at run time. Use these annotations to pre-define queries and manage their result sets. @NamedNativeQuery @NamedNativeQueries @QueryHint @ColumnResult @EntityResult @FieldResult @SqlResultSetMapping @SqlResultSetMappings
@AssociationOverride
By default, TopLink JPA automatically assumes that a subclass inherits both persistent properties and their association mappings as defined in a superclass. Use the @AssociationOverride annotation 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 @AssociationOverride change to make, you must use @AssociationOverrides. To customize a basic mapping to change its @Column, use @AttributeOverride. Table 1-2 lists the attributes of this annotation . For more details, see the API. Table 1-2 @AssociationOverride Attributes
Attribute Required Description
name
The name of the field or property defined in the embedded object or mapped superclass. To specify the join columns that are being mapped to the persistent attribute, set joinColumns to an array of @JoinColumn instances (see @JoinColumn). The mapping type will remain the same as is defined in the embeddable class or mapped superclass.
joinColumns
Example 1-1 shows a @MappedSuperclass that the entity in Example 1-2 extends. Example 1-2 shows how to use @AssociationOverride in the entity subclass to override the @JoinColumn
TopLink JPA Annotation Reference defined (by default) in the @MappedSuperclass Employee for the association to Address . With @AssociationOverride , the PartTimeEmployee table would have the Address relationship mapped to the ADDR_ID column. Other entity subclasses of Employee would inherit the default mapping to the ADDRESS_ID column, assuming that the primary key column of Address is ID . Example 1-1 @MappedSuperclass
@MappedSuperclass public class Employee { @Id protected Integer id; @ManyToOne protected Address address; ... }
Example 1-2 @AssociationOverride

@Entity @AssociationOverride(name="address", joinColumns=@JoinColumn(name="ADDR_ID")) public class PartTimeEmployee extends Employee { ... }
@AssociationOverrides
If you need to specify more than one @AssociationOverride, you must specify all your association overrides using a single @AssociationOverrides annotation. Table 1-3 lists the attributes of this annotation . For more details, see the API. Table 1-3 @AssociationOverrides Attributes
value
To specify two or more association overrides, set value to an array of @AssociationOverride instances (see @AssociationOverride).
Example 1-3 shows how to use this annotation to specify two association overrides. Example 1-3 @AssociationOverrides
@Entity @AssociationOverrides({ @AssociationOverride(name="address", joinColumns=@JoinColumn(name="ADDR_ID")), @AssociationOverride(name="healthPlan", joinColumns=@JoinColumn(name="PLAN_ID")) }) public class PartTimeEmployee extends Employee { ... }
@AttributeOverride
By default, TopLink JPA automatically assumes that a subclass inherits both persistent properties and their basic mappings as defined in a mapped superclass. Use the @AttributeOverride annotation to customize a basic mapping inherited from a @MappedSuperclass or in an @Embeddable to change the @Column associated with the field or property. If you have more than one @AttributeOverride change to make, you must use @AttributeOverrides. To customize an association mapping to change its @JoinColumn, use @AssociationOverride. Table 1-4 lists the attributes of this annotation . For more details, see the API. Table 1-4 @AttributeOverride Attributes
name
The name of the field or property defined in the embedded object or mapped superclass. 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.
column
Example 1-5 shows how to use @AttributeOverride in the entity subclass to override the @Column defined (by default) in the @MappedSuperclass Employee for the basic mapping to id . With the @AttributeOverride annotation, the PartTimeEmployee table would have the id attribute mapped to the PTEMP_ID column. Other entity subclasses of Employee would inherit the default mapping to the ID column. Example 1-4 @MappedSuperclass
@MappedSuperclass public class Employee { @Id protected Integer id; ... }
Example 1-5 @AttributeOverride

@Entity @AttributeOverride(name="id", column=@Column(name="PTEMP_ID")) public class PartTimeEmployee extends Employee { ...

}
@AttributeOverrides
If you need to specify more than one @AttributeOverride, you must specify all your attribute overrides using a single @AttributeOverrides annotation. Table 1-5 lists the attributes of this annotation . For more details, see the API. Table 1-5 @AttributeOverrides Attributes
value
To specify two or more attribute overrides, set value to an array of @AttributeOverride instances (see @AttributeOverride).
Example 1-6 shows how to use this annotation to specify two attribute overrides. Example 1-6 @AttributeOverrides
@Entity @AttributeOverrides({ @AttributeOverride(name="id", column=@Column(name="PTEMP_ID")), @AttributeOverride(name="salary", column=@Column(name="SAL")) }) public class PartTimeEmployee extends Employee { ... }
@Basic
By default, TopLink JPA automatically configures a @Basic mapping for most Java primitive types, wrappers of the primitive types, and enums. Use the @Basic annotation to configure the fetch type to LAZY. Table 1-6 lists the attributes of this annotation . For more details, see the API. Table 1-6 @Basic Attributes
fetch
Default: FetchType.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 FetchType.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-7 shows how to use this annotation to specify a fetch type of LAZY for a basic mapping. Example 1-7 @Basic
@Entity public class Book implements Serializable { ... @Basic(fetch=LAZY) protected String toc; ... }
@Column
By 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 @Column annotation: 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 lists the attributes of this annotation . For more details, see the API. 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 name to the String column name you want.
unique
Default: false . By default, TopLink JPA assumes that all non-primary key columns
are allowed to contain duplicate values. If this column is not allowed to contain duplicate values, set unique to true. When set to true, this is equivalent to using @UniqueConstraint at the table level. nullable 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 nullable to false . insertable Default: true. By default, TopLink JPA assumes that all columns are always included in SQL INSERT statements. If this column should not be included in these statements, set insertable to false . updatable Default: true. By default, TopLink JPA assumes that a column is always included in SQL UPDATE statements. If this column should not be included in these statements, set updatable to false . columnDefinition Default: empty String . By default, TopLink JPA creates a database table column with minimal SQL. If you want the column created with more specialized options, set columnDefinition to the SQL fragment that you want TopLink JPA to use when generating the DDL for the column. table 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 @Table (see @Table). If this column is associated with a secondary table (see @SecondaryTable), set name to the String name of the appropriate secondary table name as Example 1-8 shows. length Default: 255 By default, TopLink JPA assumes that all columns have a maximum length of 255 characters when used to hold a String value. If this column width is inappropriate for your application or database, set the length to the int value appropriate for your database column. precision 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 precision to the appropriate int precision. scale 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 scale to the appropriate int precision. Example 1-8 shows how to use this annotation to make TopLink JPA persist salary to column SAL in secondary table EMP_SAL . By default, TopLink JPA persists salary to column salary in primary table EMPLOYEE . Example 1-8 @Column
@Entity @SecondaryTable(name="EMP_SAL") public class Employee implements Serializable { ... @Column(name="SAL", table="EMP_SAL") private Long salary; ... }
@ColumnResult
TopLink JPA Annotation Reference When you execute a @NamedNativeQuery, it can return entities (including entities of different types), scalar values, or a combination of both. Use the @ColumnResult annotation to return scalar values. The type of the scalar is determined by the type of the column you identify in the @ColumnResult . For more information, see also @EntityResult, @FieldResult, and @SqlResultSetMapping. Table 1-8 lists the attributes of this annotation . For more details, see the API. Table 1-8 @ColumnResult Attributes
name
Set name to the String equivalent of a column name in the SELECT statement of a native SQL query. If you use a column alias ( AS statement) in the SELECT , then set name to the column alias.
Example 1-9 shows how to use this annotation to include Item (see Example 1-10 scalar name in the result list (see Example 1-11). In this case, the result list would be a List of Object arrays like: {[Order, "Shoes"], [Order, "Socks"], ...}. Example 1-9 Order Entity With @ColumnResult
@SqlResultSetMapping( name="OrderResults", entities={ @EntityResult( entityClass=Order.class, fields={ @FieldResult(name="id", column="order_id"), @FieldResult(name="quantity", column="order_quantity"), @FieldResult(name="item", column="order_item") } ) }, columns={ @ColumnResult( name="item_name" ) } ) @Entity public class Order { @Id protected int id; protected long quantity; @ManyToOne(fetch=LAZY) protected Item item; ... }
Example 1-10 Item Entity

@Entity public class Item { @Id protected int id; protected String name; ... }
Example 1-11 Native Query Using an @SqlResultSetMapping With an @ColumnResult

Query q = entityManager.createNativeQuery( "SELECT o.id AS order_id, " + "o.quantity AS order_quantity, " + "o.item AS order_item, " + "i.name AS item_name " + "FROM Order o, Item i " + "WHERE (order_quantity > 25) AND (order_item = i.id)", "OrderResults" ); List resultList = q.getResultList(); // List of Object arrays: {[Order, "Shoes"], [Order, "Socks"], ...}
@DiscriminatorColumn
By default, when @Inheritance attribute strategy is InheritanceType.SINGLE_TABLE or JOINED , TopLink JPA creates a discriminator column named DTYPE to differentiate classes in an inheritance hierarchy. Use the @DiscriminatorColumn annotation: 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 lists the attributes of this annotation . For more details, see the API. Table 1-9 @DiscriminatorColumn Attributes
name
Default: TopLink JPA assumes that the discriminator column is named " DTYPE ". To specify an alternative column name, set name to the String column name you want.
discriminatorType
Default: DiscriminatorType.STRING. By default, TopLink JPA assumes that the discriminator type is a String . If you want to use a different type, set discriminatorType to DiscriminatorType.CHAR or DiscriminatorType.INTEGER . Your @DiscriminatorValue must conform to this type.
columnDefinition
Default: empty String . By default, TopLink JPA creates a database table column with minimal SQL. If you want the column created with more specialized options, set columnDefinition to the SQL fragment that you want TopLink JPA to use when generating the DDL for the column.
length
Default: 31 By default, TopLink JPA assumes that the discriminator column has a maximum length of 31 characters when used to hold a String value. If this column width is inappropriate for your application or database, set the length to the int value appropriate for your database column. Your @DiscriminatorValue must conform to this length.
Example 1-12 shows how to use this annotation to specify a discriminator column named DISC of type STRING and length 20. In this example, the @DiscriminatorValue for this class is specified as CUST. The ValuedCustomer subclass specifies its own @DiscriminatorValue of VIP . In both Customer and ValuedCustomer, the value for @DiscriminatorValue must be convertable to the type specified by @DiscriminatorColumn attribute discriminatorType and must conform to @DiscriminatorColumn attribute length . Example 1-12 @DiscriminatorColumn and @DiscriminatorValue
@Entity @Inheritance(strategy=SINGLE_TABLE) @DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20) @DiscriminatorValue(value-"CUST") public class Customer { ... } @Entity @DiscriminatorValue("VIP") public class ValuedCustomer extends Customer { ... }
@DiscriminatorValue
By default, when @Inheritance attribute strategy is InheritanceType.SINGLE_TABLE or JOINED , TopLink JPA uses the entity name as a @DiscriminatorValue to differentiate classes in the inheritance hierarchy (see @Entity). Use the @DiscriminatorValue annotation 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 the API. Table 1-10 @DiscriminatorValue Attributes
value
Set value to the String equivalent of a discriminator value that conforms to the @DiscriminatorColumn attributes discriminatorType and length .
Example 1-13 shows how to use this annotation to specify a discriminator column named DISC of type STRING and length 20. In this example, the @DiscriminatorValue for this class is specified as CUST. The ValuedCustomer subclass specifies its own @DiscriminatorValue of VIP . In both Customer and ValuedCustomer, the value for @DiscriminatorValue must be convertable to the type specified by @DiscriminatorColumn attribute discriminatorType and must conform to @DiscriminatorColumn attribute length . Example 1-13 @DiscriminatorColumn and @DiscriminatorValue
@Entity @Inheritance(strategy=SINGLE_TABLE) @DiscriminatorColumn(name="DISC", discriminatorType=STRING, length=20) @DiscriminatorValue("CUST") public class Customer { ... }
@Entity @DiscriminatorValue("VIP") public class ValuedCustomer extends Customer { ... }
@Embeddable
By default, TopLink JPA assumes that every entity is persisted to its own database table. Use the @Embeddable annotation 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 the API. Example 1-14 shows how to use this annotation to specify that class EmploymentPeriod may be embedded in an entity when used as the type for a persistent field annotated as @Embedded (see Example 1-15). Example 1-14 @Embeddable
@Embeddable public class EmploymentPeriod { java.sql.Date startDate; java.sql.Date endDate; ... }
@Embedded
By default, TopLink JPA assumes that every entity is persisted to its own database table. Use the @Embedded annotation 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 @Embedded in conjunction with @Embeddable to model a strict ownership relationship so that 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 the API. Example 1-15 shows how to use this annotation to specify that @Embeddable class EmploymentPeriod (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 @Embedded annotation entirely: TopLink JPA will infer that EmploymentPeriod is embedded from its @Embeddable annotation. Example 1-15 @Embedded
@Entity public class Employee implements Serializable { ... @Embedded @AttributeOverrides({ @AttributeOverride(name="startDate", column=@Column(name="EMP_START")), @AttributeOverride(name="endDate", column=@Column(name="EMP_END")) ) public EmploymentPeriod getEmploymentPeriod() { ... } ... }
@EmbeddedId
Use the @EmbeddedId annotation 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 equals and hashCode methods. 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 the API. Example 1-16 shows a typical composite primary key class, annotated as @Embeddable. Example 1-
TopLink JPA Annotation Reference 17 shows how to configure an entity with this embeddable composite primary key class using the @EmbeddedId annotation. Example 1-16 Embeddable Composite Primary Key Class
@Embeddable public class EmployeePK implements Serializable { private String name; private long id; public EmployeePK() { } public String getName() { return name; } public void setName(String name) { this.name = name; } public long getId() { return id; } public void setId(long id) { this.id = id; } public int hashCode() { return (int) name.hashCode() + id; } public boolean equals(Object obj) { if (obj == this) return true; if (obj == null) return false; if (!(obj instanceof EmployeePK)) return false; EmployeePK pk = (EmployeePK) obj; return pk.id == id && pk.name.equals(name); } }
Example 1-17 @EmbeddedId

@Entity public class Employee implements Serializable { EmployeePK primaryKey; public Employee() { } @EmbeddedId public EmployeePK getPrimaryKey() { return primaryKey; } public void setPrimaryKey(EmployeePK pk) { primaryKey = pk; } ... }
@Entity
Use the @Entity annotation 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 the API. 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 name is " Employee ". If the entity class name is awkward, a reserved word, incompatible with a preexisting data model, or invalid as a table name in your database, set name to an alternative String value.
Example 1-18 shows how to use this annotation. Example 1-18 @Entity
@Entity public class Employee implements Serializable { ... }
@EntityListeners
You can use lifecycle annotations (see Lifecycle Event Annotations) to designate methods that execute your logic when specified lifecycle events occur. Use the @EntityListeners annotation to associate one or more entity listener classes with an @Entity or @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.
TopLink JPA Annotation Reference 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: public void <MethodName>(Object) You may specify an argument type of Object 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 @ExcludeDefaultListeners and @ExcludeSuperclassListeners. Table 1-12 lists the attributes of this annotation . For more details, see the API. Table 1-12 @EntityListeners Attributes
value
To specify the list of entity listener classes for an @Entity or @MappedSuperclass, set value to a Class array of entity listener classes.
Example 1-19 shows how to use this annotation to associate entity listener classes EmployeePersistListener (see Example 1-20) and EmployeeRemoveListener (see Example 1-21) with the entity Employee . Example 1-21 shows 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
@Entity @EntityListeners({EmployeePersistListener.class, EmployeeRemoveListener.class}) public class Employee implements Serializable { ... }
Example 1-20 EmployeePersistListener

public class EmployeePersistListener { @PostPersist @PostLoad public void employeePersist(Object employee) { ... } ... }
Example 1-21 EmployeeRemoveListener

public class EmployeeRemoveListener { @PreRemove public void employeePreRemove(Object employee) { ... } ... }
@EntityResult
When you execute a @NamedNativeQuery, it can return entities (including entities of different types), scalar values, or a combination of both. Use the @EntityResult 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 the API. Table 1-13 @EntityResult Attributes
entityClass
Set entityClass to the Class of the entity returned by the query. Default: empty FieldResult array. By default, TopLink JPA assumes that 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). 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 ( AS statements are used), set fields to an array of @FieldResult, one @FieldResult per column in the SELECT statement.
fields
discriminatorColumn
String
TopLink JPA Annotation Reference Default: empty .
By default, TopLink JPA assumes that a discriminator column (see @Inheritance) is not included in the SELECT statement. If you use a discriminator column in your SELECT statement, set discriminatorColumn to the String column name you use. Example 1-22 shows how to use this annotation to include both Order and Item (see Example 1-23) entities in the result list (see Example 1-24). In this case, the result list would be a List of Object arrays like: {[Order, Item], [Order, Item], ...}. Example 1-22 Order Entity With @EntityResult
@SqlResultSetMapping( name="OrderResults", entities={ @EntityResult( entityClass=Order.class, fields={ @FieldResult(name="id", @FieldResult(name="quantity", @FieldResult(name="item", } ), @EntityResult( entityClass=Item.class, fields={ @FieldResult(name="id", @FieldResult(name="name", } ) } ) @Entity public class Order { @Id protected int id; protected long quantity; @ManyToOne protected Item item; ... }
column="order_id"), column="order_quantity"), column="order_item")
column="item_id"), column="item_name")

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

Query q = entityManager.createNativeQuery( "SELECT o.id AS order_id, " + "o.quantity AS order_quantity, " + "o.item AS order_item, " + "i.id AS item_id, " + "i.name AS item_name " + "FROM Order o, Item i " + "WHERE (order_quantity > 25) AND (order_item = i.id)" "OrderResults" ); List resultList = q.getResultList(); // List of Object arrays: {[Order, Item], [Order, Item], ...}
@Enumerated
By default, TopLink JPA persists the ordinal values of enumerated constants. Use the @Enumerated annotation to specify whether TopLink JPA should persist ordinal or String 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 the API. Table 1-14 @Enumerated Attributes
value
Default: EnumType.ORDINAL . 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 EmployeeStatus is written to the database when Employee is persisted. If you want the String value of the enumerated constant persisted, set value to EnumType.STRING .
Given the enumerated constants in Example 1-25, Example 1-26 shows how to use this annotation to specify that the String value of SalaryRate should be written to the database when Employee is persisted. By default, the ordinal value of EmployeeStatus is written to the database. Example 1-25 Enumerated Constants
public enum EmployeeStatus {FULL_TIME, PART_TIME, CONTRACT} public enum SalaryRate {JUNIOR, SENIOR, MANAGER, EXECUTIVE}
TopLink JPA Annotation Reference Example 1-26 @Enumerated

@Entity public class Employee { ... public EmployeeStatus getStatus() { ... } @Enumerated(STRING) public SalaryRate getPayScale() { ... } ... }
@ExcludeDefaultListeners
A default listener is a lifecycle event listener class specified in the orm.xml file that applies to all entities in a persistence unit (see @PersistenceUnit). TopLink JPA first invokes default listeners, if any, in the order defined in the orm.xml file, before any other entity listeners (see @EntityListeners). Use the @ExcludeDefaultListeners annotation to override (and prevent) default listener execution for a given @Entity or @MappedSuperclass if default listener behavior does not apply. This annotation has no attributes . For more details, see the API. Example 1-27 shows how to use this annotation to specify that default listeners should not be executed for the Employee entity. Example 1-27 @ExcludeDefaultListeners
@Entity @ExcludeDefaultListeners public class Employee implements Serializable { ... }
@ExcludeSuperclassListeners
If the @Entity and @MappedSuperclass classes in an inheritance hierarchy define @EntityListeners, by default, TopLink JPA invokes superclass listeners before subclass listeners. Use the @ExcludeSuperclassListeners annotation to override (and prevent) superclass listener execution for a given @Entity or @MappedSuperclass if superclass listener behavior does not apply. The @ExcludeSuperclassListeners annotation does not affect default listeners (see @ExcludeDefaultListeners). This annotation has no attributes . For more details, see the API. Example 1-28 shows how to use this annotation to specify that superclass listener EmployeeListener should not be executed for the PartTimeEmployee entity but default listeners and subclass listeners PartTimeEmployeeListener1 and PartTimeEmployeeListener2 are executed. Example 1-28 Entity Listeners at the Superclass Level
@MappedSuperclass @EntityListeners({EmployeeListener.class}) public class Employee { ... }
Example 1-29 @ExcludeSuperclassListeners at the Subclass Level

@Entity @ExcludeSuperclassListeners @EntityListeners({PartTimeEmployeeListener1.class, PartTimeEmployeeListener2.class}) public class PartTimeEmployee extends Employee { ... }
@FieldResult
When 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 @FieldResult annotation to map columns in the SELECT statement to fields or properties when returning entities with @EntityResult 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 ( AS statements are used). For more information, see also @ColumnResult and @SqlResultSetMapping. Table 1-15 lists the attributes of this annotation . For more details, see the API. Table 1-15 @FieldResult Attributes
name
Set name to the entity's field or property name (as a String ) that corresponds to the column name specified by the column attribute.
TopLink JPA Annotation Reference column Set column to the String name of the column used in the SELECT statement. If you use a column alias ( AS statement) in the SELECT , then set column to the column alias.
Example 1-30 shows how to use this annotation to include both Order and Item (see Example 1-31) entities in the result list (see Example 1-32). In this case, the result list would be a List of Object arrays like: {[Order, Item], [Order, Item], ...}. Example 1-30 Order Entity With @EntityResult and @FieldResult
@SqlResultSetMapping( name="OrderResults", entities={ @EntityResult( entityClass=Order.class, fields={ @FieldResult(name="id", @FieldResult(name="quantity", @FieldResult(name="item", } ), @EntityResult( entityClass=Item.class, fields={ @FieldResult(name="id", @FieldResult(name="name", } ) } ) @Entity public class Order { @Id protected int id; protected long quantity; @ManyToOne protected Item item; ... }
column="item_id"), column="item_name")


Query q = entityManager.createNativeQuery( "SELECT o.id AS order_id, " + "o.quantity AS order_quantity, " + "o.item AS order_item, " + "i.id AS item_id, " + "i.name AS item_name " + "FROM Order o, Item i " + "WHERE (order_quantity > 25) AND (order_item = i.id)", "OrderResults" ); List resultList = q.getResultList(); // List of Object arrays: {[Order, Item], [Order, Item], ...}
@GeneratedValue
By default, the application is responsible for supplying and setting entity identifiers (see @Id). Use the @GeneratedValue annotation if you want TopLink JPA to provide and manage entity identifiers. Table 1-16 lists the attributes of this annotation . For more details, see the API. Table 1-16 @GeneratedValue Attributes
strategy
Default: GenerationType.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 strategy to the GeneratorType you want: IDENTITY - 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)
generator
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 generator to the String generator name you want to use.
TopLink JPA Annotation Reference Example 1-33 shows how to use this annotation to tell TopLink JPA to use a primary key generator of type GeneratorType.SEQUENCE named CUST_SEQ . Example 1-33 @GeneratedValue
@Entity public class Employee implements Serializable { ... @Id @GeneratedValue(strategy=SEQUENCE, generator="CUST_SEQ") @Column(name="CUST_ID") public Long getId() { return id; } ... }
@Id
Use the @Id annotation 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 @Id multiple @Id and an @IdClass (for a composite primary key) one @EmbeddedId This annotation has no attributes . For more details, see the API. Example 1-34 shows how to use this annotation to designate persistent field empID as the primary key of the Employee table. Example 1-34 @Id
@Entity public class Employee implements Serializable { @Id private int empID; ... }
@IdClass
Use the @IdClass 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 equals and hashCode methods. 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 the API. Table 1-17 @IdClass Attributes
value
To specify a composite primary key class, set value to the Class you want.
Example 1-35 shows a non-embedded composite primary key class. In this class, fields empName and birthDay must 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 @IdClass annotation. Because entity class fields empName and birthDay are used in the primary key, you must also annotate them using the @Id annotation. Example 1-35 Non-Embedded Composite Primary Key Class
public class EmployeePK implements Serializable { private String empName; private Date birthDay; public EmployeePK() { } public String getEmpName() {

return empName; } public void setEmpName(String name) { empName = name; } public Date getBirthDay() { return birthDay; } public void setBirthDay(Date date) { birthDay = date; } public int hashCode() { return (int) empName.hashCode(); } public boolean equals(Object obj) { if (obj == this) return true; if (obj == null) return false; if (!(obj instanceof EmployeePK)) return false; EmployeePK pk = (EmployeePK) obj; return pk.birthDay == birthDay && pk.empName.equals(empName); } }
Example 1-36 @IdClass

@IdClass(EmployeePK.class) @Entity public class Employee { @Id String empName; @Id Date birthDay; ... }
@Inheritance
By default, TopLink JPA automatically manages the persistence of entities in an inheritance hierarchy. Use the @Inheritance annotation 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 the API. Table 1-18 @Inheritance Attributes
strategy
Default: InheritanceType.SINGLE_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 strategy to the desired InheritanceType : SINGLE_TABLE Foot 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 the instance that is represented by the row belongs. JOINED - 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-37 shows how to use this annotation to specify that all subclasses of Customer will use InheritanceType.JOINED . The subclass in Example 1-38 will be mapped to its own table that contains a column for each the persistent properties of ValuedCustomer and one foreign key column that contains the primary key to the Customer table. Example 1-37 @Inheritance - Root Class Using JOINED
@Entity@Inheritance(strategy=JOINED)public class Customer { @Id private int customerId; ... }
Example 1-38 @Inheritance - Subclass Using JOINED

@Entity public class ValuedCustomer extends Customer { ... }
In Example 1-39, by default, InheritanceType.SINGLE_TABLE applies to Customer and all its subclasses. In this example, the default discriminator column DTYPE (see @DiscriminatorColumn) is specified as having a discriminator type of INTEGER and the @DiscriminatorValue for Customer is specified as 1 . Example 1-40 shows how to specify the discriminator value for subclass ValuedCustomer as 2 . In this example, all the persistent properties of both Customer and
TopLink JPA Annotation Reference ValuedCustomer will be mapped to a single table. Example 1-39 @Inheritance - Root Class Specifying its Discriminator Column
@Entity @DiscriminatorColumn(discriminatorType=DiscriminatorType.INTEGER) @DiscriminatorValue("1") public class Customer { ... }
Example 1-40 @Inheritance - Subclass Specifying its Discriminator Value

@Entity @DiscriminatorValue("2") public class ValuedCustomer extends Customer { ... }
@JoinColumn
By 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 @JoinColumn annotation 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 the API. 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 name to the String column name you want.
referencedColumnName
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 referencedColumnName to the String column name you want.
unique
Default: false . 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 unique to true.
nullable
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 nullable to false .
insertable
Default: true. By default, TopLink JPA assumes that it can insert into all table
columns. If this column is read-only, set insertable to false . updatable Default: true. By default, TopLink JPA assumes that it can update all table columns. If this column is read-only, set updatable to false columnDefinition Default: empty String. TopLink JPA creates a database table column with minimal SQL. If you want the column created with more specialized options, set columnDefinition to the String SQL fragment that you want TopLink JPA to use when generating the DDL for the column. table 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 name to the String name of the appropriate secondary table name as Example 1-8 shows. Example 1-41 shows how to use this annotation to make TopLink JPA use database table Employee column ADDR_ID as the join column. Example 1-41 @JoinColumn
@Entity public class Employee implements Serializable { ... @ManyToOne @JoinColumn(name="ADDR_ID") public Address getAddress() { return address; } }
@JoinColumns
By default, in an entity association, TopLink JPA assumes that a single join column is used. Use the @JoinColumns 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 the API. Table 1-20 @JoinColumns Attributes
value
To specify two or more join columns, set value to an array of JoinColumn instances (see @JoinColumn).
Example 1-42 shows how to use this annotation to specify the names of two join columns: ADDR_ID in the Employee table which contains foreign key values from Address table column ID and ADDR_ZIP in the Employee table which contains foreign key values from Address table column ZIP . Example 1-42 @JoinColumns
@Entity public class Employee implements Serializable { ... @ManyToOne @JoinColumns({ @JoinColumn(name="ADDR_ID", referencedColumnName="ID"), @JoinColumn(name="ADDR_ZIP", referencedColumnName="ZIP") }) public Address getAddress() { return address; } ... }
@JoinTable
By default, TopLink JPA uses a join table when mapping entity associations on the owning side of a many-to-many association, or in a unidirectional one-to-many association. The join table name and its column names are all specified by defaults and TopLink JPA assumes that there is a join column for the primary key column of each of the entities in the relationship. Use the @JoinTable annotation if you want to: change the name of the join table because the default name is awkward, a reserved word, incompatible with a pre-existing data model, or invalid as a table name in your database change the column names of the join table because the default names are awkward, a reserved word, incompatible with a pre-existing data model, or invalid as a column name in your database
TopLink JPA Annotation Reference configure the join table with a specific catalog or schema configure one or more join table columns with a unique constraint use multiple join columns per entity Table 1-21 lists the attributes of this annotation . For more details, see the API. Table 1-21 @JoinTable Attributes
name
Default: TopLink JPA names the join table by concatenating the table names of the associated primary tables (owning side first) using an underscore. If such a join table name is awkward, a reserved word, or incompatible with a pre-existing data model, set name to the appropriate join table name. In Example 1-43, TopLink JPA uses the join table named PROJ_EMP .
catalog
Default: By default, TopLink JPA uses whatever the default catalog is for your database. If the default catalog is inappropriate for your application, set the catalog to the String catalog name to use.
schema
Default: By default, TopLink JPA uses whatever the default schema is for your database.empty. If the default schema is inappropriate for your application, set the schema to the String schema name to use.
joinColumns
Default: By default, TopLink JPA assumes that there is a single join column for the owning entity's primary key column. TopLink JPA names the column by concatenating the name of the owning entity + "_" + the name of the referenced primary key column. If such a column name is awkward, a reserved word, incompatible with a pre-existing data model, or if you want to specify more than one join column, then set joinColumns to one or more instances of JoinColumn (see @JoinColumn).
inverseJoinColumns
Default: By default, TopLink JPA assumes that there is a single join column on the inverse side of the association. TopLink JPA names this column by concatenating the name of the owned entity + "_" + the name of the referenced primary key column. If such a column name is awkward, a reserved word, incompatible with a pre-existing data model, or if you want to specify more than one join column, then set joinColumns to one or more instances of JoinColumn (see @JoinColumn)
uniqueConstraints
Default: empty array of UniqueConstraint . By default, TopLink JPA assumes that none of the columns in the join table have unique constraints. If unique constraints do apply to one or more columns in this table, set uniqueContraints to an array of one or more UniqueConstraint instances. For more information, see @UniqueConstraint.
Example 1-43 shows how to use this annotation to specify a join table named EMP_PROJ_EMP for a many-to-many relationship between entities Employee and Project . In the join table, there are two columns: EMP_ID and PROJ_ID . The EMP_ID column contains primary key values from the Employee table whose primary key column (referenced column) is named ID . The PROJ_ID column contains primary key values from the Project table whose primary key column (referenced column) is also named ID . Example 1-43 @JoinTable
@Entity public class Employee implements Serializable { ... @ManyToMany @JoinTable( name="PROJ_EMP", joinColumns=@JoinColumn(name="EMP_ID", referencedColumnName="ID"), inverseJoinColumns=@JoinColumn(name="PROJ_ID", referencedColumnName="ID") ) public Collection getProjects() { return projects; } ... }
@Lob
By default, TopLink JPA assumes that all persistent data can be represented as typical database data
TopLink JPA Annotation Reference types. Use the @Lob annotation with a basic mapping to specify that a persistent property or field should be persisted as a large object to a database-supported large object type. A Lob may be either a binary or character type. TopLink JPA infers the Lob type from the type of the persistent field or property. For string and character-based types, the default is Clob. In all other cases, the default is Blob. You can also use the @Column attribute columnDefinition to further refine the Lob type. This annotation has no attributes . For more details, see the API. Example 1-44 shows how to use this annotation to specify that persistent field pic should be persisted as a Blob. Example 1-44 @Lob
@Entity public class Employee implements Serializable { ... @Lob @Basic(fetch=LAZY) @Column(name="EMP_PIC", columnDefinition="BLOB NOT NULL") protected byte[] pic; ... }
@ManyToMany
By default, TopLink JPA automatically defines a @ManyToMany mapping for a many-valued association with many-to-many multiplicity. Use the @ManyToMany annotation to: declare the cardinality of the relationship configure the fetch type to EAGER configure the mapping to forbid null values (for non-primitive types) in case null values are inappropriate for your application configure the associated target entity because the Collection used is not defined using generics configure the operations that must be cascaded to the target of the association; for example, if the owning entity is removed, ensure that the target of the association is also removed Table 1-22 lists the attributes of this annotation . For more details, see the API. Table 1-22 @ManyToMany Attributes
targetEntity
Default: the parameterized type of the Collection when defined using generics. By default, if you are using a Collection defined using generics, then TopLink JPA infers the associated target entity from the type of the object being referenced. If your Collection does not use generics, then you must specify the entity class that is the target of the association: set the targetEntity element on owning side of the association to the Class of the entity that is the target of the relationship.
cascade
Default: empty array of CascadeType . By default, TopLink JPA does not cascade any persistence operations to the target of the association. If you want some or all persistence operations cascaded to the target of the association, set cascade to one or more CascadeType instances, including: ALL - all possible cascading operations performed on the source entity are cascaded to the target of the association. MERGE - if the source entity is merged, the merge is cascaded to the target of the association. PERSIST - if the source entity is persisted, the persist is cascaded to the target of the association. REFRESH - if the source entity is refreshed, the refresh is cascaded to the target of the association. REMOVE - if the source entity is removed, the target of the association is also removed.
fetch
Default: FetchType.LAZY. By default, TopLink JPA uses a fetch type of LAZY: this is a hint to TopLink
JPA 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 . If this is inappropriate for your application or a particular persistent field, set fetch to FetchType.EAGER; this is a requirement on TopLink JPA runtime that data must be eagerly fetched. mappedBy Default: if the relationship is unidirectional, TopLink JPA determines the field that owns the relationship. If the relationship is bidirectional, then set the mappedBy attribute on the inverse (non-owning) side of the association to the name of the field or property that owns the relationship (as Example 1-46 shows). Example 1-45 and Example 1-46 show how to use this annotation to configure a many-to-many mapping between Customer and PhoneNumber using generics. Example 1-45 @ManyToMany - Customer Class With Generics
@Entity public class Customer implements Serializable { ... @ManyToMany @JoinTable( name="CUST_PHONE", joinColumns= @JoinColumn(name="CUST_ID", referencedColumnName="ID"), inverseJoinColumns= @JoinColumn(name="PHONE_ID", referencedColumnName="ID") ) public Set<PhoneNumber> getPhones() { return phones; } ... }
Example 1-46 @ManyToMany - PhoneNumber Class With Generics

@Entity public class PhoneNumber implements Serializable { ... @ManyToMany(mappedBy="phones") public Set<Customer> getCustomers() { return customers; } ... }
@ManyToOne
By default, TopLink JPA automatically defines a ManyToOne mapping for a single-valued association to another entity class that has many-to-one multiplicity. Use the @ManyToOne annotation to: configure the fetch type to LAZY configure the mapping to forbid null values (for non-primitive types) in case null values are inappropriate for your application configure the associated target entity if it cannot be inferred from the type of the object being referenced configure the operations that must be cascaded to the target of the association: for example, if the owning entity is removed, ensure that the target of the association is also removed Table 1-23 lists the attributes of this annotation . For more details, see the API. Table 1-23 @ManyToOne Attributes
targetEntity
Default: TopLink JPA infers the associated target entity from the type of the object being referenced If TopLink JPA cannot infer the type of the target entity, then set the targetEntity element on owning side of the association to the Class of the entity that is the target of the relationship.
cascade
Default: empty array of CascadeType . By default, TopLink JPA does not cascade any persistence operations to the target of the association. If you want some or all persistence operations cascaded to the target of the association, set cascade to one or more CascadeType instances, including: ALL - all possible cascading operations performed on the source entity are cascaded to the target of the association. MERGE - if the source entity is merged, the merge is cascaded to the target of the association.
TopLink JPA Annotation Reference PERSIST - if the source entity is persisted, the persist is cascaded to the target of the association. REFRESH - if the source entity is refreshed, the refresh is cascaded to the target of the association. REMOVE - if the source entity is removed, the target of the association is also removed. fetch Default: FetchType.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 FetchType.LAZY; this is a hint to TopLink JPA 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-47 show how to use this annotation to configure a many-to-one mapping between Customer (the owned side) and Order (the owning side) using generics. Example 1-47 @ManyToOne
@Entity public class Order implements Serializable { ... @ManyToOne @JoinColumn(name="CUST_ID") public Customer getCustomer() { return customer; } ... }
@MapKey
By default, TopLink JPA assumes that the primary key of the associated entity is the Map key for associations of type java.util.Map : If the primary key is a non-composite primary key annotated as @Id, an instance of this field or property's type is used as the Map key. If the primary key is a composite primary key annotated as @IdClass, an instance of the primary key class is used as the Map key. Use the @MapKey annotation to: specify some other field or property as the Map key if the primary key of the associated entity is not appropriate for your application specify an embedded composite primary key class (see @EmbeddedId) The field or property you specify must have a unique constraint (see @UniqueConstraint). Table 1-24 lists the attributes of this annotation . For more details, see the API. Table 1-24 @MapKey Attributes
name
Default: By default, TopLink JPA uses the primary key of the associated entity as the Map key for a property or field mapped to a java.util.Map for non-composite primary keys or composite primary keys annotated as @IdClass. If you want to use some other field or property as the Map key, set name to the associated entity's String field or property name to use.
In Example 1-48, Project owns a one to many relationship to instances of Employee as a Map . Example 1-48 shows how to use the @MapKey annotation to specify that the key for this Map is Employee field empPK , an embedded composite primary key (see Example 1-49) of type EmployeePK (see Example 1-50). Example 1-48 Project Entity Using @MapKey
@Entity public class Project { ... @OneToMany(mappedBy="project") @MapKey(name="empPK") public Map<EmployeePK, Employee> getEmployees() { ... } ... }
Example 1-49 Employee Entity

@Entity public class Employee { @EmbeddedId public EmployeePK empPK; ... @ManyToOne @JoinColumn(name="PROJ_ID") public Project project;

... } ... }
Example 1-50 EmployeePK Composite Primary Key Class

@Embeddable public class EmployeePK { String name; Date birthDate; }
@MappedSuperclass
By default, TopLink JPA assumes that all the persistent fields of an entity are defined in that entity. Use the @MappedSuperclass annotation to designate a superclass from which your entity class inherits persistent fields. This is a convenient pattern when multiple entity classes share common persistent fields or properties. You can annotate this superclass's fields and properties with any of the direct and relationship mapping annotations (such as @Basic and @ManyToMany) as you would for an entity but these mappings apply only to its subclasses since no table exists for the superclass itself. The inherited persistent fields or properties belong to the subclass's table. You can use the @AttributeOverride or @AssociationOverride annotations in the subclass to override the superclass's mapping configuration. This annotation has no attributes. For more details, see the API. Example 1-51 shows how to use this annotation to specify Employee as a mapped superclass. Example 1-52 shows how to extend this superclass in an entity and how to use @AttributeOverride in the entity class to override configuration made in the superclass. Example 1-51 @MappedSuperclass
@MappedSuperclass public class Employee { @Id protected Integer empId; @Version protected Integer version; @ManyToOne @JoinColumn(name="ADDR") protected Address address; ... }
Example 1-52 Extending a @MappedSuperclass

@Entity @AttributeOverride(name="address", column=@Column(name="ADDR_ID")) public class PartTimeEmployee extends Employee { @Column(name="WAGE") protected Float hourlyWage; ... }
@NamedNativeQueries
If you need to specify more than one @NamedNativeQuery, you must specify all your named queries using a single @NamedNativeQueries annotation. Table 1-25 lists the attributes of this annotation . For more details, see the API. Table 1-25 @NamedNativeQueries Attributes
value
To specify two or more attribute overrides, set value to an array of NamedNativeQuery instances (see @NamedNativeQuery).
Example 1-53 shows how to use this annotation to specify two named native queries. Example 1-53 @NamedNativeQueries
@Entity @NamedNativeQueries({ @NamedNativeQuery( name="findAllPartTimeEmployees", query="SELECT * FROM EMPLOYEE WHERE PRT_TIME=1" ), @NamedNativeQuery( name="findAllSeasonalEmployees", query="SELECT * FROM EMPLOYEE WHERE SEASON=1" ) }) public class PartTimeEmployee extends Employee { ... }
@NamedNativeQuery
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 the @NamedNativeQuery annotation to create pre-defined queries associated with an @Entity or @MappedSuperclass that: use SQL native to the underlying database
are frequently used are complex and difficult to create can be shared amongst different entities return entities, scalar values, or a combination of both (see also @ColumnResult, @EntityResult, @FieldResult, and @SqlResultSetMapping) If you have more than one @NamedNativeQuery to define, you must use @NamedNativeQueries. To pre-define portable queries suitable for any database, see @NamedQuery. Table 1-26 lists the attributes of this annotation . For more details, see the API. Table 1-26 @NamedNativeQuery Attributes
name
To specify the name of the query, set name to the String name you want. This is the name by which you invoke the query at runtime (see Example 1-58).
query
To specify the query, set query to the SQL query as a String . For more information on native SQL query language, see your database documentation.
hints
Default: empty QueryHint array. By default TopLink JPA assumes that the SQL query should be executed exactly as given by the query attribute. To fine-tune the execution of the query, you can optionally set hints to a QueryHint array (see @QueryHint).
resultClass
To specify a result class, set resultClass to the Class you want. If not specified, then either there is no return type, or it is specified by a ResultSetMapping . Default: TopLink JPA assumes that the SELECT statement in a native SQL query: returns a single type of entity; includes all the columns that correspond to all the fields or properties of the entity returned; and uses column names that correspond to the field or property names ( AS statements are not used). To control how TopLink JPA maps the JDBC result set to entity fields or properties and scalars, specify a result set mapping by setting resultSetMapping to the String name of the @SqlResultSetMapping you want.
resultSetMapping
Example 1-54 shows how to use the @NamedNativeQuery annotation to define a query using SQL native to the underlying database. Example 1-55 shows how you use the EntityManager to acquire this query and use Query method getResultList to execute it. Example 1-54 Implementing an Oracle Hierarchical Query Using @NamedNativeQuery
@Entity @NamedNativeQuery( name="findAllEmployees", query="SELECT * FROM EMPLOYEE", resultClass=Employee.class ) public class Employee implements Serializable { ... }
Example 1-55 Executing a Named Native Query

Query queryEmployees = em.createNamedQuery("findAllEmployees"); Collection employees = queryEmployees.getResultList();
@NamedQueries
If you need to specify more than one @NamedQuery, you must specify all your named queries using a single @NamedQueries annotation. Table 1-27 lists the attributes of this annotation . For more details, see the API. Table 1-27 @NamedQueries Attributes
value
To specify two or more attribute overrides, set value to an array of NamedQuery instances (see @NamedQuery).
Example 1-56 shows how to use this annotation to specify two named queries. Example 1-56 @NamedQueries
@Entity @NamedQueries({ @NamedQuery( name="findAllEmployeesByFirstName", query="SELECT emp FROM Employee emp WHERE emp.firstName = :firstname" ), @NamedQuery( name="findAllEmployeesByLastName", query="SELECT emp FROM Employee emp WHERE emp.lastName = :lastname" ) }) public class Employee { ... }
@NamedQuery
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 the @NamedQuery annotation to create pre-defined queries associated with an @Entity or @MappedSuperclass that: use the JPA query language (see Enterprise JavaBeans v3.0 specification, Chapter 4) for portable execution on any underlying database are frequently used are complex and difficult to create can be shared amongst different entities If you have more than one @NamedQuery to define, you must use @NamedQueries. To pre-define queries in SQL native to a known, underlying database, see @NamedNativeQuery. Using a native SQL query, you can return entities (including entities of different types), scalar values, or both. Table 1-28 lists the attributes of this annotation . For more details, see the API. Table 1-28 @NamedQuery Attributes
name
To specify the name of the query, set name to the query name as a String . This is the name by which you invoke the query at runtime (see Example 1-58).
query
To specify the query, set query to the JPA query language query as a String . For more information on the JPA query language, see the Enterprise JavaBeans v.3.0 specification, Chapter 4.
hints
Default: empty QueryHint array. By default TopLink JPA assumes that the JPA query should be executed exactly as given by the query attribute regardless of the underlying database. To fine-tune the execution of the query, you can optionally set hints to a QueryHint array (see @QueryHint).
Example 1-57 shows how to use the @NamedQuery annotation to define a JPA query language query that takes a parameter named firstname. Example 1-58 shows how you use the EntityManager to acquire this query and use Query method setParameter to set the firstname parameter. Example 1-57 Implementing a Query with Parameters Using @NamedQuery
@Entity @NamedQuery( name="findAllEmployeesByFirstName", query="SELECT emp FROM Employee emp WHERE emp.firstName = :firstname" ) public class Employee implements Serializable { ... }
Example 1-58 Executing a Named Query

Query queryEmployeesByFirstName = em.createNamedQuery("findAllEmployeesByFirstName"); queryEmployeesByFirstName.setParameter("firstname", "John"); Collection employees = queryEmployeesByFirstName.getResultList();
@OneToMany
By default, TopLink JPA automatically defines a OneToMany mapping for a many-valued association with one-to-many multiplicity. Use the @OneToMany annotation to: configure the fetch type to EAGER configure the associated target entity because the Collection used is not defined using generics configure the operations that must be cascaded to the target of the association: for example, if the owning entity is removed, ensure that the target of the association is also removed configure the details of the join table used by TopLink JPA for uni-directional one-to-many
TopLink JPA Annotation Reference relationships (see @JoinTable) Table 1-29 lists the attributes of this annotation . For more details, see the API. Table 1-29 @OneToMany Attributes
targetEntity
Default: the parameterized type of the Collection when defined using generics. By default, if you are using a Collection defined using generics, then TopLink JPA infers the associated target entity from the type of the object being referenced. If your Collection does not use generics, then you must specify the entity class that is the target of the association; set the targetEntity element on owning side of the association to the Class of the entity that is the target of the relationship.
cascade
Default: empty array of CascadeType . By default, TopLink JPA does not cascade any persistence operations to the target of the association. If you want some or all persistence operations cascaded to the target of the association, set cascade to one or more CascadeType instances, including: ALL - all cascading operations performed on the source entity are cascaded to the target of the association. MERGE - if the source entity is merged, the merge is cascaded to the target of the association. PERSIST - if the source entity is persisted, the persist is cascaded to the target of the association. REFRESH - if the source entity is refreshed, the refresh is cascaded to the target of the association. REMOVE - if the source entity is removed, the target of the association is also removed.
fetch
Default: FetchType.LAZY. By default, TopLink JPA uses a fetch type of LAZY; this is a hint to TopLink JPA 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 . If this is inappropriate for your application or a particular persistent field, set fetch to FetchType.EAGER ; this is a requirement on TopLink JPA runtime that data must be eagerly fetched.
mappedBy
Default: TopLink JPA assumes the relationship is unidirectional. If the relationship is bidirectional, then set the mappedBy element on the inverse (non-owning) side of the association to the name of the field or property that owns the relationship as Example 1-60 shows.
Example 1-59 and Example 1-60 show how to use this annotation to configure a one-to-many mapping between Customer (the inverse side) and Order (the owning side) using generics. Example 1-59 @OneToMany - Customer Class With Generics
@Entity public class Customer implements Serializable { ... @OneToMany(cascade=ALL, mappedBy="customer") public Set<Order> getOrders() { return orders; } ... }
Example 1-60 @ManyToOne - Order Class With Generics

@Entity public class Customer implements Serializable { ... @ManyToOne @JoinColumn(name="CUST_ID", nullable=false) public Customer getCustomer() { return customer; } ... }
@OneToOne
By default, TopLink JPA automatically defines a OneToOne mapping for a single-valued association to another entity that has one-to-one multiplicity and infers the associated target entity from the type of the object being referenced.
Use the @OneToOne annotation to: configure the fetch type to LAZY configure the mapping to forbid null values (for non-primitive types) in case null values are inappropriate for your application configure the associated target entity if it cannot be inferred from the type of the object being referenced configure the operations that must be cascaded to the target of the association. For example, if the owning entity is removed, ensure that the target of the association is also removed Table 1-30 lists the attributes of this annotation . For more details, see the API. Table 1-30 @OneToOne Attributes
targetEntity
Default: TopLink JPA infers the associated target entity from the type of the object being referenced. If TopLink JPA cannot infer the type of the target entity, then set the targetEntity element on owning side of the association to the Class of the entity that is the target of the relationship.
cascade
Default: empty CascadeType array. By default, TopLink JPA does not cascade any persistence operations to the target of the association. If you want some or all persistence operations cascaded to the target of the association, set cascade to one or more CascadeType instances, including: ALL - all cascading operations performed on the source entity are cascaded to the target of the association. MERGE - if the source entity is merged, the merge is cascaded to the target of the association. PERSIST - if the source entity is persisted, the persist is cascaded to the target of the association. REFRESH - if the source entity is refreshed, the refresh is cascaded to the target of the association. REMOVE - if the source entity is removed, the target of the association is also removed.
fetch
Default: FetchType.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 FetchType.LAZY; this is a hint to TopLink JPA 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 .
mappedBy
Default: TopLink JPA assumes the source entity is the owning side of the relationship. If the source entity does not own the relationship, then set the mappedBy element on the inverse (non-owning) side of the association to the String name of the field or property that owns the relationship as Example 1-62 shows.
Example 1-61 and Example 1-62 show how to use this annotation to configure a one-to-one mapping between Customer (the owning side) and CustomerRecord (the owned side). Example 1-61 @OneToOne - Customer Class
@Entity public class Customer implements Serializable { ... @OneToOne @JoinColumn(name="CUSTREC_ID", unique=true, nullable=false, updatable=false) public CustomerRecord getCustomerRecord() { return customerRecord; } ... }
Example 1-62 @OneToOne - CustomerRecord Class

@Entity public class CustomerRecord implements Serializable { ... @OneToOne(mappedBy="customerRecord") public Customer getCustomer() {

return customer; } ... }
@OrderBy
By default, TopLink JPA retrieves the members of a Collection association in ascending order by primary key of the associated entities. Use the @OrderBy annotation with @OneToMany and @ManyToMany to specify: one or more other field or property names to order by different orders (ascending or descending) for each such field or property Table 1-31 lists the attributes of this annotation . For more details, see the API. Table 1-31 @OrderBy Attributes
value
Default: TopLink JPA retrieves the members of a Collection association in ascending order by primary key of the associated entities. If you want to order by some other fields or properties and specify different, set value to a comma separated list of the following string elements: " propertyor-field-name ASC | DESC" (see Example 1-63).
Example 1-63 shows how to use the @OrderBy annotation to specify that Project method getEmployees should return a List of Employee in ascending order by Employee field lastname and in descending order by Employee field seniority. Example 1-64 shows that by default, Employee method getProjects returns a List in ascending order by Employee primary key empId . Example 1-63 Project Entity
@Entity public class Project { ... @ManyToMany @OrderBy("lastname ASC", "seniority DESC") public List<Employee> getEmployees() { ... }; ... }
Example 1-64 Employee Entity

@Entity public class Employee { @Id private int empId; private String lastname; private int seniority; @ManyToMany(mappedBy="employees") // By default, returns a List in ascending order by empId private List<Project> projects; ... }
@PersistenceContext
In an application that uses TopLink JPA, you use an entity manager to perform all persistence operations (create, read, update, and delete). A Java EE application obtains an entity manager using dependency injection or direct lookup of the entity manager in the JNDI namespace. Use the @PersistenceContext annotation in Java EE to obtain an entity manager: using dependency injection by name using JNDI lookup associated with a specific persistence unit (see also @PersistenceUnit) with an extended persistence context customized with specific persistence properties (see @PersistenceProperty) If you have more than one @PersistenceContext to specify, you must use @PersistenceContexts. Table 1-32 lists the attributes of this annotation . For more details, see the API. Table 1-32 @PersistenceContext Attributes
name
Default: TopLink JPA retrieves the default entity manager. If you want to inject or look up a specific entity manager, set name to the String name of the entity manager you want to use. For dependency injection, name is not required. For JNDI look up, name must be set to the name by which the entity manager is to be accessed in the environment referencing context.
unitName
Default: TopLink JPA retrieves an entity manager for the default persistence
TopLink JPA Annotation Reference unit. If you want to inject or look up an entity manager associated with a specific persistence unit, set unitName to the String persistence unit name you want. Alternatively, you can use a @PersistenceUnit if you need to obtain an EntityManagerFactory for the persistence unit. For JNDI look up, if you specify a unitName , then the entity manager accessed by name must be associated with this persistence unit. type Default: PersistenceContextType.TRANSACTION. By default, TopLink JPA assumes that entity managers are container-managed and the lifetime of their persistence context is scoped to a single transaction. That is, the persistence context comes into existence at the time a transaction is started and ceases to exist when that transaction commits. Set type to PersistenceContextType.EXTENDED if: your persistence context is application-managed you want the extended persistence context to exist from the time the EntityManager instance is created until it is closed you want the entity manager to maintain references to entity objects after a transaction has committed you want to invoke EntityManager methods persist , remove , merge , and refresh regardless of whether a transaction is active properties Default: TopLink JPA assumes that the entity manager will use default properties. If you want to configure TopLink JPA properties, including vendor-specific properties, set properties to an array of @PersistenceProperty instances. Example 1-65 shows how to use this annotation to inject an entity manager in a stateless session bean and Example 1-66 shows how to use this annotation to look up an entity manager in JNDI. Example 1-65 Using @PersistenceContext and Dependency Injection
@Stateless public class OrderEntryBean implements OrderEntry { @PersistenceContext EntityManager em; public Customer getCustomer(int custID) { return em.find(Customer.class, custID); } }
Example 1-66 Using @PersistenceContext and JNDI Lookup

@Stateless @PersistenceContext(name="OrderEM") public class OrderEntryBean implements OrderEntry { @Resource EJBContext ctx; EntityManager em; public Customer getCustomer(int custID) { em = (EntityManager)ctx.lookup("OrderEM"); return em.find(Customer.class, custID); } }
@PersistenceContexts
If you need to specify more than one @PersistenceContext, you must specify all your persistence contexts using a single @PersistenceContexts annotation. Table 1-33 lists the attributes of this annotation . For more details, see the API. Table 1-33 @PersistenceContexts Attributes
value
To specify two or more persistence contexts, set value to an array of PersistenceContext instances (see @PersistenceContext).
Example 1-67 shows how to use this annotation to specify two persistence contexts. Example 1-67 @PersistenceContexts
@Stateless @PersistenceContexts({ @PersistenceContext(name="OrderEM"), @PersistenceContext(name="ItemEM") }) public class OrderEntryBean implements OrderEntry { @Resource EJBContext ctx; public Customer getCustomer(int custID) { EntityManager em = (EntityManager)ctx.lookup("OrderEM"); return em.find(Customer.class, custID); } public void enterItem(int orderID, Item newItem) { EntityManager em = (EntityManager)ctx.lookup("ItemEM"); ... } }
@PersistenceProperty
By default, TopLink JPA assumes that the entity manager you obtain using @PersistenceContext will use default properties. Use the @PersistenceProperty annotation to specify properties, including vendor-specific properties, for the container or TopLink JPA to: customize entity manager behavior exploit specific features Properties are passed to TopLink JPA when the entity manager is created. Unrecognized properties are simply ignored. Table 1-34 lists the attributes of this annotation . For more details, see the API. Table 1-34 @PersistenceProperty Attributes
name
To specify the name of the persistence property, set name to the String property name. To specify the value of the persistence property, set value to the String property value you want.
value
Example 1-68 shows how to use the @PersistenceProperty annotation to customize the query to take advantage of a JPA extension provided by TopLink JPA. In this case, the property ensures that a full TopLink cache is used in this persistence context. For more information, see "How to Use the Persistence Unit Properties for Caching" in the Oracle Fusion Middleware Oracle TopLink Developer's Guide . Example 1-68 @PersistenceProperty
@Stateless public class OrderEntryBean implements OrderEntry { @PersistenceContext( properties={ @PersistenceProperty(name="toplink.cache.type.default", value="CacheType.Full") } ) EntityManager em; ... }
@PersistenceUnit
By default, TopLink JPA uses the EntityManagerFactory associated with the default persistence unit. Use the @PersistenceUnit annotation to obtain an EntityManagerFactory by lookup or through injection. If you have more than one @PersistenceUnit to specify, you must use @PersistenceUnits. Table 1-35 lists the attributes of this annotation . For more details, see the API. Table 1-35 @PersistenceUnit Attributes
name
Default: TopLink JPA obtains its EntityManager instances from the default EntityManagerFactory . For dependency injection, name is not required. For JNDI look up, name must be set to the name by which the entity manager is to be accessed in the environment referencing context.
unitName
Default: TopLink JPA retrieves the entity manager factory for the default persistence unit. If you want to inject or look up an entity manager factory associated with a specific persistence unit, set unitName to the String persistence unit name you want. See also @PersistenceContext.
Example 1-69 shows how to use the @PersistenceUnit annotation to specify the JNDI name of the EntityManagerFactory to use and the persistence unit name associated with that factory. Example 1-69 Using @PersistenceUnit to Specify Factory and Unit
@Stateless @PersistenceUnit(name="OrderEMFactory", unitName="OrderEMUnit") public class OrderEntryBean implements OrderEntry { @Resource EJBContext ctx; public Customer getCust(int custID) { EntityManagerFactory emf; EntityManager em; emf = (EntityManagerFactory)ctx.lookup("OrderEMFactory"); em = emf.createEntityManager(); return em.find(Customer.class, custID); }

}
Example 1-70 shows an alternative approach using @PersistenceUnit to inject an EntityManagerFactory . Example 1-70 Using @PersistenceUnit Attribute unitName
@Stateless public class OrderEntryBean implements OrderEntry { @PersistenceUnit(unitName="OrderEMUnit") EntityManagerFactory emf; public Customer getCust(int custID) { EntityManager em = emf.createEntityManager(); return em.find(Customer.class, custID); } }
@PersistenceUnits
If you need to specify more than one @PersistenceUnit, you must specify all your persistence units using a single @PersistenceUnits annotation. Table 1-36 lists the attributes of this annotation . For more details, see the API. Table 1-36 @PersistenceUnits Attributes
value
To specify two or more persistence units, set value to an array of PersistenceUnit instances (see @PersistenceUnit).
Example 1-71 shows how to use this annotation to specify two persistence units. In this case, @PersistenceContext attribute unitName and @PersistenceUnit attribute unitName must correspond in order to associate persistence context and persistence unit. Example 1-71 @PersistenceUnits
@Stateless @PersistenceUnits({ @PersistenceUnit(name="OrderEMFactory", unitName="OrderEMUnit"), @PersistenceUnit(name="ItemEMFactory", unitName="ItemEMUnit") }) public class OrderEntryBean implements OrderEntry { @Resource EJBContext ctx; public Customer getCust(int custID) { EntityManagerFactory emf = (EntityManagerFactory)ctx.lookup("OrderEMUnit"); EntityManager em = emf.createEntityManager(); return em.find(Customer.class, custID); } public void enterItem(int orderID, Item newItem) { ... } }
@PrimaryKeyJoinColumn
By default, when one entity extends another using InheritanceType.JOINED (see @Inheritance), TopLink JPA assumes that the foreign key columns of the subclass have the same names as the primary key columns of the primary table of the superclass. Use the @PrimaryKeyJoinColumn annotation: if the foreign key columns of the subclass do not have the same names as the primary key columns of the primary table of the superclass in this scenario with a @SecondaryTable annotation to join a secondary table to a primary table in a @OneToOne mapping in which the primary key of the referencing entity is used as a foreign key to the referenced entity. to use composite foreign keys (see @PrimaryKeyJoinColumns) Table 1-37 lists the attributes of this annotation . For more details, see the API. Table 1-37 @PrimaryKeyJoinColumn Attributes
name
Default: TopLink JPA assumes one of the following names for the primary key column of the current table (depending on how you are using this annotation): InheritanceType.JOINED (see @Inheritance): the same name as the primary key column of the superclass. @SecondaryTable mapping: the same name as the primary key column of the primary table. @OneToOne mapping: the same name as the primary key column for the table for the referencing entity. If this name is awkward, a reserved word, incompatible with a pre-existing data model, or invalid as a column name in your database, set name to the String column name you want.
referencedColumnName
Default: TopLink JPA assumes one of the following names for
TopLink JPA Annotation Reference the name of the primary key column of the table being joined to (depending on how you are using this annotation): InheritanceType.JOINED (see @Inheritance): the same name as the primary key column of the primary table of the superclass. @SecondaryTable mapping: the same name as the name of the primary key column of the primary table. @OneToOne mapping: the same name as the primary key column of the table for the referenced entity. If this name is awkward, a reserved word, incompatible with a pre-existing data model, or invalid as a column name in your database, set referencedColumnName to the String column name you want. columnDefinition Default: empty String . By default, TopLink JPA creates a database table column with minimal SQL. If you want the column created with more specialized options, set columnDefinition to the String SQL fragment that you want TopLink JPA to use when generating the DDL for the column. Do not use this attribute with a @OneToOne mapping. Example 1-72 shows an entity base class Customer and Example 1-73 shows how to use @PrimaryKeyJoinColumn to specify primary key join column CUST_ID in the primary table of ValuedCustomer, a subclass of Customer . Example 1-72 @PrimaryKeyJoinColumn - InheritanceType.JOINED Superclass
@Entity @Table(name="CUST") @Inheritance(strategy=JOINED) @DiscriminatorValue("CUST") public class Customer { ... }
Example 1-73 @PrimaryKeyJoinColumn - InheritanceType.JOINED Subclass

@Entity @Table(name="VCUST") @DiscriminatorValue("VCUST") @PrimaryKeyJoinColumn(name="CUST_ID") public class ValuedCustomer extends Customer { ... }
@PrimaryKeyJoinColumns
By default, TopLink JPA assumes that each entity has single-column primary key. Use the @PrimaryKeyJoinColumns annotation if you want to specify a primary key composed of two or more columns. Table 1-38 lists the attributes of this annotation . For more details, see the API. Table 1-38 @PrimaryKeyJoinColumns Attributes
value
To specify a composite (multi-column) primary key, set value to an array of PrimaryKeyJoinColumn instances (see @PrimaryKeyJoinColumn).
Example 1-74 shows how to use this annotation to specify a composite primary key composed of columns CUST_ID and CUST_TYPE. Example 1-74 @PrimaryKeyJoinColumns
@Entity @Table(name="VCUST") @DiscriminatorValue("VCUST") @PrimaryKeyJoinColumns({ @PrimaryKeyJoinColumn(name="CUST_ID",referencedColumnName="ID"), @PrimaryKeyJoinColumn(name="CUST_TYPE",referencedColumnName="TYPE") }) public class ValuedCustomer extends Customer { ... }
@QueryHint
By default, TopLink JPA assumes that a @NamedQuery or @NamedNativeQuery should be executed exactly as specified by the query String . Use the @QueryHint annotation to specify TopLink JPA query extensions to: improve query performance exploit specific TopLink JPA features
TopLink JPA Annotation Reference Table 1-39 lists the attributes of this annotation . For more details, see the API. Table 1-39 @QueryHint Attributes
name
To specify the name of the hint, set name to String hint name.
value
To specify the value of the hint, set value to the String hint value you want.
Example 1-75 shows how to use the @QueryHint annotation to customize the query to take advantage of a JPA extension provided by TopLink JPA. In this case, the hint ensures that the TopLink cache is always refreshed when this query is executed. For more information, see "How to Use TopLink JPA Query Hints" in the Oracle Fusion Middleware Oracle TopLink Developer's Guide . Example 1-75 @QueryHint
@Entity @NamedQuery( name="findAllEmployees", query="SELECT e FROM EMPLOYEE e", hints={@QueryHint(name="toplink.refresh", value="true")} ) public class Employee implements Serializable { ... }
@SecondaryTable
By default, TopLink JPA assumes that all the persistent fields of an entity are stored in a single database table whose name is the entity name. This table is known as the primary table (see @Table). Use the @SecondaryTable annotation to associate an entity with an additional database table if you want TopLink JPA to persist some of the entity's persistent fields to the primary table and some to other database tables. In this case, you associate an entity's persistent field with a table using the @Column annotation. If you want to associate two or more secondary tables with an entity, you can use @SecondaryTables. Table 1-40 lists the attributes of this annotation . For more details, see the API. Table 1-40 @SecondaryTable Attributes
name
If your entity uses a secondary table, set name to the String table name. Default: TopLink JPA uses whatever the default catalog is for your database. If the default catalog is inappropriate for your application, set the catalog to the String catalog name to use.
catalog
schema
Default: TopLink JPA uses whatever the default schema is for your database. If the default schema is inappropriate for your application, set the schema to the String schema name to use.
pkJoinColumns
Default: TopLink JPA assumes a primary key join column of the same name as the primary key field in the primary table. If more columns are used for primary key joins in this table, set pkJoinColumns to an array of one or more @PrimaryKeyJoinColumn instances. For more information, see @PrimaryKeyJoinColumn.
uniqueConstraints
Default: TopLink JPA assumes that there are no additional unique constraints. If additional unique constraints are applied to columns in this table, set uniqueContraints to an array of one or more @UniqueConstraint instances. For more information, see @UniqueConstraint.
Example 1-76 shows how to use this annotation to specify a secondary table named EMP_HR . In this example, by default, TopLink JPA persists entity persistent field empId to the primary table named Employee in column empId and persists empSalary to the secondary table EMP_HR in column empSalary. For more information, see @Column. Example 1-76 @SecondaryTable
@Entity @SecondaryTable(name="EMP_HR")

public class Employee implements Serializable { ... @Id private Long empId; @Column(name="EMP_SALARY", table="EMP_HR") private Float empSalary; ... }
@SecondaryTables
If you need to specify more than one @SecondaryTable, you may specify all your secondary tables using a single @SecondaryTables annotation. Table 1-41 lists the attributes of this annotation . For more details, see the API. Table 1-41 @SecondaryTables Attributes
value
To specify two or more secondary tables, set value to an array of SecondaryTable instances (see @SecondaryTable).
Example 1-77 shows how to use this annotation to specify two secondary tables named EMP_HR and EMP_TR . In this example, by default, TopLink JPA persists entity persistent field empId to the primary table named EMPLOYEE in column EMP_ID . TopLink JPA persists empSalary to secondary table EMP_HR in column EMP_SAL and empStatus to secondary table EMP_TR in column EMP_STAT . For more information, see @Column. Example 1-77 @SecondaryTables
@Entity @SecondaryTables({ @SecondaryTable(name="EMP_HR"), @SecondaryTable(name="EMP_TR") }) public class Employee implements Serializable { ... @Id private Long empId; @Column(name="EMP_SAL", table="EMP_HR") private Float empSalary; @Column(name="EMP_STAT", table="EMP_TR") private int empStatus; ... }
@SequenceGenerator
If you use the @GeneratedValue annotation to specify a primary key generator of type SEQUENCE , then you can use the @SequenceGenerator annotation to fine tune this primary key generator to: change the allocation size to match your application requirements or database performance parameters change the initial value to match an existing data model (for example, if you are building on an existing data set for which a range of primary key values has already been assigned or reserved) use a pre-defined sequence in an existing data model Table 1-42 lists the attributes of this annotation . For more details, see the API. Table 1-42 @SequenceGenerator Attributes
name
The name of the SequenceGenerator must match the generator name in a GeneratedValue with its strategy set to SEQUENCE . Default: TopLink JPA assigns a sequence name of its own creation. If you prefer to use an existing or pre-defined sequence or have a specific requirement for the name of the sequence, set sequenceName to the String name you want.
sequenceName
initialValue
Default: 0. By default, TopLink JPA starts all primary key values from 0. If this does not match an existing data model, set initialValue to the int value you want.
allocationSize
Default: 50. By default, TopLink JPA uses an allocation size of 50. If this allocation size does not match your application requirements or database performance parameters, set allocationSize to the int value you want.
Example 1-78 shows how to use this annotation to specify the allocation size for the SEQUENCE
TopLink JPA Annotation Reference primary key generator named CUST_SEQ . Example 1-78 @SequenceGenerator
@Entity public class Employee implements Serializable { ... @Id @SequenceGenerator(name="CUST_SEQ", allocationSize=25) @GeneratedValue(strategy=SEQUENCE, generator="CUST_SEQ") @Column(name="CUST_ID") public Long getId() { return id; } ...
@SqlResultSetMapping
When you execute a @NamedNativeQuery, it can return entities (including entities of different types), scalar values, or a combination of both. By default, as Example 1-79 shows, TopLink JPA assumes that the SELECT statement in a native SQL query: returns a single type of entity corresponding to the class argument passed at query creation includes all the columns that correspond to all the fields or properties of the entity returned uses column names that correspond to the field or property names ( AS statements are not used) Example 1-79 Simple Native SQL Query
Query q = entityManager.createNativeQuery( "SELECT o.id, o.quantity, o.item " + "FROM Order o, Item i " + "WHERE (o.item = i.id) AND (i.name = 'widget')", Order.class ); List resultList = q.getResultList(); // List of Order entity objects: {Order, Order, ...}
Use the @SqlResultSetMapping annotation to control how TopLink JPA maps the JDBC result set to entity fields or properties and scalars if the native SQL query: returns more than one type of entity returns only scalar values or a combination of entities and scalar values uses column aliases ( AS statements) If you have more than one @SqlResultSetMapping , you must use @SqlResultSetMappings. Table 1-43 lists the attributes of this annotation . For more details, see the API. Table 1-43 @SqlResultSetMapping Attributes
name
Set name to the String name of this @SqlResultSetMapping . This is the name you use to associate the @SqlResultSetMapping with a native SQL query (see Example 1-82).
entities
Default: empty EntityResult array. By default, TopLink JPA assumes that the SELECT statement returns a single type of entity. If your SELECT statement returns more than one type of entity, set entities to an array of EntityResult instances, one @EntityResult per entity type returned.
columns
Default: empty ColumnResult array. By default, TopLink JPA assumes that the SELECT statement returns only entities. If your SELECT statement returns scalar values, set columns to an array of ColumnResult instances, one @ColumnResult per scalar result.
Example 1-80 shows how to use this annotation to include both Order and Item (see Example 1-81) entities in the result list (see Example 1-82). In this case, the result list would be a List of Object arrays like: {[Order, Item], [Order, Item], ...}. Example 1-80 Order Entity With @SqlResultSetMapping
@SqlResultSetMapping( name="OrderResults", entities={ @EntityResult( entityClass=Order.class, fields={ @FieldResult(name="id", @FieldResult(name="quantity", @FieldResult(name="item", } ), @EntityResult( entityClass=Item.class, fields={ @FieldResult(name="id", @FieldResult(name="name",
column="item_id"), column="item_name"),

} ) } ) @Entity public class Order { @Id protected int id; protected long quantity; @ManyToOne protected Item item; ... }


Query q = entityManager.createNativeQuery( "SELECT o.id AS order_id, " + "o.quantity AS order_quantity, " + "o.item AS order_item, " + "i.id AS item_id, " + "i.name AS item_name " + "FROM Order o, Item i " + "WHERE (order_quantity > 25) AND (order_item = i.id)", "OrderResults" ); List resultList = q.getResultList(); // List of Object arrays: {[Order, Item, "Shoes"], [Order, Item, "Socks"], ...}
@SqlResultSetMappings
If you need to specify more than one @SqlResultSetMapping, you must specify all your SQL result set mappings using a single @SqlResultSetMappings annotation. Table 1-44 lists the attributes of this annotation . For more details, see the API. Table 1-44 @SqlResultSetMappings Attributes
value
To specify two or more SQL result set mappings, set value to an array of @SqlResultSetMapping instances.
Example 1-83 shows how to use this annotation to specify two @SqlResultSetMapping instances. Example 1-83 @SqlResultSetMappings
SqlResultSetMappings({ @SqlResultSetMapping( name="OrderItemNameResults", entities={ @EntityResult(entityClass=Order.class), @EntityResult(entityClass=Item.class) } columns={ @ColumnResult(name="item_name") } ), @SqlResultSetMapping( name="OrderItemResults", entities={ @EntityResult(entityClass=Order.class), @EntityResult(entityClass=Item.class) } ) }) @Entity public class Order { @Id protected int id; protected long quantity; protected Item item; ... }
@Table
By default, TopLink JPA assumes that all the persistent fields of an entity are stored in a single database table whose name is the entity name (see @Entity). Use the @Table annotation to specify the primary table associated with an entity if: the entity name is awkward, a reserved word, incompatible with a pre-existing data model, or invalid as a table name in your database you need to control what catalog or schema the table belongs to If you want TopLink JPA to persist some fields to the primary table and other fields to one or more secondary tables, see @SecondaryTable. Table 1-45 lists the attributes of this annotation . For more details, see the API. Table 1-45 @Table Attributes
name
Default: TopLink JPA assumes that an entity's database table has the
TopLink JPA Annotation Reference same name as the entity class. In Example 1-84, the default name is Employee . If the entity class name is awkward, a reserved word, or incompatible with a pre-existing data model, set name to the appropriate database table name. In Example 1-84, TopLink JPA persists the entity class Employee in the database table named EMP . catalog Default: TopLink JPA uses whatever the default catalog is for your database. If the default catalog is inappropriate for your application, set the catalog to the String catalog name to use. schema Default: TopLink JPA uses whatever the default schema is for your database. If the default schema is inappropriate for your application, set the schema to the String schema name to use. uniqueConstraints Default: TopLink JPA assumes that no additional columns in the entity's database table have unique constraints. If additional unique constraints are applied to columns in this table, set uniqueContraints to an array of one or more @UniqueConstraint instances. For more information, see @UniqueConstraint. Example 1-84 shows how to use this annotation to specify the primary table name. Example 1-84 @Table
@Entity @Table(name="EMP") public class Employee implements Serializable { ... }
@TableGenerator
If you use the @GeneratedValue annotation to specify a primary key generator of type TABLE , then you can use the @TableGenerator annotation to fine tune this primary key generator to: set the name of the primary key generator's table because the name is awkward, a reserved word, incompatible with a pre-existing data model, or invalid as a table name in your database change the allocation size to match your application requirements or database performance parameters change the initial value to match an existing data model (for example, if you are building on an existing data set for which a range of primary key values has already been assigned or reserved) configure the primary key generator's table with a specific catalog or schema configure a unique constraint on one or more columns of the primary key generator's table Table 1-46 lists the attributes of this annotation . For more details, see the API. Table 1-46 @TableGenerator Attributes
name
The name of the TableGenerator must match the generator name in a GeneratedValue with its strategy set to TABLE . The scope of the generator name is global to the persistence unit (across all generator types). Default: TopLink JPA provides a suitable name for the table that stores the generated ID values. If the default table name is inappropriate for your application, set table to the String table name you want.
table
catalog
Default: TopLink JPA uses whatever the default catalog is for your database. If the default catalog is inappropriate for your application, set the catalog to the String catalog name to use.
schema
Default: TopLink JPA uses whatever the default schema is for your database. If the default schema is inappropriate for your application, set the schema to the String schema name to use.
pkColumnName
Default: TopLink JPA provides a name for the primary key column in the generator table. If this name is inappropriate for your application, set pkColumnName
TopLink JPA Annotation Reference to the String name you want. valueColumnName Default: TopLink JPA provides a suitable name for the column that stores the generated ID values. If the default column name is inappropriate for your application, set valueColumnName to the String column name you want. pkColumnValue Default: TopLink JPA provides a suitable primary key value for the primary key column in the generator table. If this value is inappropriate for your application, set pkColumnValue to the String value you want. initialValue Default: 0. By default, TopLink JPA starts all primary key values from 0. If this does not match an existing data model, set initialValue to the int value you want. allocationSize Default: 50. By default, TopLink JPA uses an allocation size of 50. If this allocation size does not match your application requirements or database performance parameters, set allocationSize to the int value you want. uniqueConstraints Default: TopLink JPA assumes that no additional columns in the primary key generator table have unique constraints. If additional unique constraints are applied to columns in this table, set uniqueContraints to an array of one or more UniqueConstraint instances. For more information, see @UniqueConstraint. Example 1-85 shows how to use this annotation to specify the allocation size for the TABLE primary key generator named empGen . Example 1-85 @TableGenerator
@Entity public class Employee implements Serializable { ... @Id @TableGenerator( name="empGen", table="GEN_TAB", allocationSize=1 ) @GeneratedValue(strategy=TABLE, generator="empGen") @Column(name="CUST_ID") public Long getId() { return id; } ...
@Temporal
Use the @Temporal annotation to specify the database type that TopLink JPA should persist for persistent fields or properties of type java.util.Date and java.util.Calendar only. This annotation can be used with @Basic. Table 1-47 lists the attributes of this annotation . For more details, see the API. Table 1-47 @Temporal Attributes
value
Set value to the TemporalType that corresponds to the database type you want TopLink JPA to use: DATE - equivalent to java.sql.Date TIME - equivalent to java.sql.Time TIMESTAMP - equivalent to java.sql.Timestamp
Example 1-86 shows how to use this annotation to specify that TopLink JPA should persist java.util.Date field startDate as a DATE ( java.sql.Date ) database type. Example 1-86 @Temporal
@Entity public class Employee { ... @Temporal(DATE) protected java.util.Date startDate; ... }
@Transient
TopLink JPA Annotation Reference By default, TopLink JPA assumes that all the fields of an entity are persistent. Use the @Transient annotation to specify a field or property of an entity that is not persistent, for example, a field or property that is used at run time but that is not part of the entity's state. TopLink JPA will not persist (or create database schema) for a property or field annotated as @Transient . This annotation can be used within classes denoted by @Entity, @MappedSuperclass, and @Embeddable. This annotation has no attributes. For more details, see the API. Example 1-87 shows how to use this annotation to specify Employee field currentSession as not persistent. TopLink JPA will not persist this field. Example 1-87 @Transient
@Entitypublic class Employee { currentSession; ...} @Id int id; @Transient Session
@UniqueConstraint
By default, TopLink JPA assumes that only primary key columns are unique and that other columns may contain duplicate values. Use the @UniqueConstraint annotation to specify that a unique constraint is to be included in the generated DDL for a primary or secondary table. Alternatively, you can specify unique constraints at the column level (see @Column). Table 1-48 lists the attributes of this annotation . For more details, see the API. Table 1-48 @UniqueConstraint Attributes
columnNames
If any columns have a unique constraint, set columnNames to the array of String column names.
Example 1-88 shows how to use this annotation to specify a unique constraint on columns EMP_BDAY and EMP_NAME in primary table EMP . Example 1-88 @Table with Unique Constraints
@Entity @Table( name="EMP", uniqueConstraints={@UniqueConstraint(columnNames={"EMP_BDAY", "EMP_NAME"})} ) public class Employee implements Serializable { ... }
@Version
By default, TopLink JPA assumes that the application is responsible for data consistency. It is recommended that you use the @Version annotation to enable TopLink JPA-managed optimistic locking by specifying the version field or property of an entity class that serves as a holder of its optimistic lock value. When choosing a version field or property, ensure that: there is only one version field or property per entity you choose a property or field persisted to the primary table (see @Table) your application does not modify the version property or field This annotation has no attributes . For more details, see the API. Example 1-89 shows how to use this annotation to specify property getVersionNum as the optimistic lock. In this example, the column name for this property is set to OPTLOCK (see @Column) instead of the default column name for the property. Example 1-89 @Version
@Entity public class Employee implements Serializable { ... @Version @Column(name="OPTLOCK") protected int getVersionNum() { return versionNum; } ... }
Lifecycle Event Annotations

Use the following lifecycle event annotations to associate a lifecycle event with a callback method if you need to execute custom logic during a lifecycle event: @PostLoad @PostPersist
@PostRemove @PostUpdate @PrePersist @PreRemove @PreUpdate Figure 1-1 illustrates the relationship amongst the entity lifecycle events that TopLink JPA supports. You can annotate an entity method directly or you can specify one or more entity listener classes (see @EntityListeners). If you annotate an entity method directly, then that entity method must meet the following requirements: The entity method must have the following signature: public void <MethodName>() The entity method can have any method name as long as it does not begin with ejb . Figure 1-1 JPA Entity LIfecycle Callback Event Annotations
Description of "Figure 1-1 JPA Entity LIfecycle Callback Event Annotations"
@PostLoad
The @PostLoad method for an entity is invoked after the entity has been loaded into the current persistence context from the database or after the refresh operation has been applied to it. This method is invoked before a query result is returned or accessed or before an association is traversed. Use the @PostLoad annotation if you need to invoke custom logic at this point during the entity lifecycle. This annotation has no attributes . For more details, see the API.
@PostPersist
The @PostPersist callback method is invoked for an entity after the entity has been persisted. This method is invoked on all entities to which this operation is cascaded. This method is invoked after the database insert operation, which will typically occur during a flush or transaction commit. Generated primary key values are available in the PostPersist method. Use the @PostPersist annotation to notify any dependent objects or to update information not accessible until the object has been inserted. This annotation has no attributes . For more details, see the API.
@PostRemove
The @PostRemove callback method is invoked for an entity after the entity has been removed. This method is invoked on all entities to which this operation is cascaded. This method is invoked after the database delete operation, which will typically occur during a flush or transaction commit.
Use the @PostRemove annotation to notify any dependent objects. This annotation has no attributes . For more details, see the API.
@PostUpdate
The @PostUpdate callback method is invoked for an entity after the database update operation to entity data, which will typically occur during a flush or transaction commit. Use the @PostUpdate annotation if you need to invoke custom logic at this point during the entity lifecycle. This annotation has no attributes . For more details, see the API.
@PrePersist
The @PrePersist callback method is invoked for a given entity at the time the respective EntityManager persist method on that entity is invoked. It is also invoked during a merge operation if it causes the creation of newly managed instances. In this case, it is invoked for the managed instance after the entity state has been copied to it. This method is invoked on all entities to which this operation is cascaded. Use the @PrePersist annotation if you need to invoke custom logic at this point during the entity lifecycle. This annotation has no attributes . For more details, see the API.
@PreRemove
The @PreRemove callback method is invoked for a given entity at the time the EntityManager remove method on that entity is invoked. This method is invoked on all entities to which this operation is cascaded. Use the @PreRemove annotation if you need to invoke custom logic at this point during the entity lifecycle. This annotation has no attributes . For more details, see the API.
@PreUpdate
The @PreUpdate callback method is invoked for an entity before the database update operation to entity data, which will typically occur during a flush or transaction commit. Use the @PreUpdate annotation if you need to invoke custom logic at this point during the entity lifecycle. This annotation has no attributes . For more details, see the API.
Index of Annotations
A @AssociationOverride @AssociationOverrides @AttributeOverride @AttributeOverrides B @Basic C @Column @ColumnResult D @DiscriminatorColumn @DiscriminatorValue E @Embeddable @Embedded @EmbeddedId @Entity @EntityListeners @EntityResult @Enumerated @ExcludeDefaultListeners
TopLink JPA Annotation Reference @ExcludeSuperclassListeners F @FieldResult G @GeneratedValue I @Id @IdClass @Inheritance J @JoinColumn @JoinColumns @JoinTable L @Lob M @ManyToMany @ManyToOne @MapKey @MappedSuperclass N @NamedNativeQueries @NamedNativeQuery @NamedQueries @NamedQuery O @OneToMany @OneToOne @OrderBy P @PersistenceContext @PersistenceContexts @PersistenceProperty @PersistenceUnit @PersistenceUnits @PrimaryKeyJoinColumn @PrimaryKeyJoinColumns Q @QueryHint S @SecondaryTable @SecondaryTables @SequenceGenerator @SqlResultSetMapping @SqlResultSetMappings T @Table @TableGenerator
TopLink JPA Annotation Reference @Temporal @Transient U @UniqueConstraint V @Version
About Oracle
| Oracle and Sun |
| Subscribe | Careers | Contact Us | Site Maps | Legal Notices | Terms of Use | Your Privacy Rights

TopLink JPA Annotation Reference

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

TopLink JPA Annotation Reference

Загружено:

Авторское право:

Доступные форматы

TopLink JPA Annotation Reference

( Sign In/Register for Account | Help )

Products and Services

Oracle Technology Network