Note: Starting with Oracle TopLink 11g, 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.

TopLink JPA Annotation Reference

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 object-relational mapping approach that allows you to declaratively define how to map Java objects to relational database tables in a standard, portable way that works both inside a Java EE 5 application server and outside an EJB container in a Java Standard Edition (Java SE) 5 application.

When using TopLink JPA, you can configure the JPA behavior of your entities using annotations. An annotation is a simple, expressive means of decorating Java source code with metadata that is compiled into the corresponding Java class files for interpretation at runtime by TopLink JPA to manage JPA behavior.

For example, to designate a Java class as a JPA entity, use the @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:

Table 1-1 JPA Annotations by Category

Category Description Annotations

Category	Description	Annotations
Entity	By default, TopLink JPA assumes that a Java class is non-persistent and not eligible for JPA services unless it is decorated with this annotation. Use this annotation to designate a plain old Java object (POJO) class as an entity so that you can use it with JPA services. You must designate a class as a JPA entity (either using this annotation or the `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. Use these annotations to override this default behavior and fine-tune the relationship between your object model and data model.	@Table @SecondaryTable @SecondaryTables @Column @JoinColumn @JoinColumns @PrimaryKeyJoinColumn @PrimaryKeyJoinColumns @JoinTable @UniqueConstraint
Identity	By default, TopLink JPA assumes that each entity must have at least one field or property that serves as a primary key. Use these annotations to specify one of the following: one `@Id` multiple `@Id` and an `@IdClass` one `@EmbeddedId` You can also use these annotations to fine-tune how your database maintains the identity of your entities.	@Id @IdClass @EmbeddedId @GeneratedValue @SequenceGenerator @TableGenerator
Direct Mappings	By default, TopLink JPA automatically configures a `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 Mappings	TopLink JPA requires that you map relationships explicitly, but TopLink allows some defaulting. Use these annotations to specify the type and characteristics of entity relationships to fine-tune how your database implements these relationships.	@OneToOne @ManyToOne @OneToMany @ManyToMany @MapKey @OrderBy
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 defined by a single entity class. Use these annotations if your entity class inherits some or all persistent fields from one or more superclasses.	@Inheritance @DiscriminatorColumn @DiscriminatorValue @MappedSuperclass @AssociationOverride @AssociationOverrides @AttributeOverride @AttributeOverrides
Locking	By default, TopLink JPA assumes that the application is responsible for data consistency. It is recommended that you use this annotation to enable TopLink JPA-managed optimistic locking.	@Version
Lifecycle Callback Events	By default, TopLink JPA handles all persistence operations. Use these annotations to associate methods with JPA lifecycle 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.	@PrePersist @PostPersist @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 manager to create and execute queries dynamically or you can pre-define queries and execute them by name at run time. Use these annotations to pre-define queries and manage their result sets.	@NamedQuery @NamedQueries @NamedNativeQuery @NamedNativeQueries @QueryHint @ColumnResult @EntityResult @FieldResult @SqlResultSetMapping @SqlResultSetMappings

Entity

By default, TopLink JPA assumes that a Java class is non-persistent and not eligible for JPA services unless it is decorated with this annotation.

Use this annotation to designate a plain old Java object (POJO) class as an entity so that you can use it with JPA services.

You must designate a class as a JPA entity (either using this annotation or the 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.

Use these annotations to override this default behavior and fine-tune the relationship between your object model and data model.

@PrimaryKeyJoinColumn

@PrimaryKeyJoinColumns

@JoinTable

@UniqueConstraint

Identity

By default, TopLink JPA assumes that each entity must have at least one field or property that serves as a primary key.

Use these annotations to specify one of the following:

one @Id
multiple @Id and an @IdClass
one @EmbeddedId

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.

Relationship Mappings

TopLink JPA requires that you map relationships explicitly, but TopLink allows some defaulting.

Use these annotations to specify the type and characteristics of entity relationships to fine-tune how your database implements these relationships.

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.

@AssociationOverrides

Inheritance

By default, TopLink JPA assumes that all persistent fields are defined by a single entity class.

Use these annotations if your entity class inherits some or all persistent fields from one or more superclasses.

@AssociationOverrides

@AttributeOverride

@AttributeOverrides

Locking

By default, TopLink JPA assumes that the application is responsible for data consistency.

It is recommended that you use this annotation to enable TopLink JPA-managed optimistic locking.

@Version

Lifecycle Callback Events

By default, TopLink JPA handles all persistence operations.

Use these annotations to associate methods with JPA lifecycle 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.

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

Queries

In an application that uses TopLink JPA, you can use an entity manager to create and execute queries dynamically or you can pre-define queries and execute them by name at run time.

Use these annotations to pre-define queries and manage their result sets.

@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

Required

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

joinColumns

Required

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.

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

Attribute	Required	Description
`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

Attribute	Required	Description
`name`		The name of the field or property defined in the embedded object or mapped superclass.
`column`		The @Column that is being mapped to the persistent attribute. The mapping type will remain the same as is defined in the embeddable class or mapped superclass.

Example 1-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

Attribute	Required	Description
`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

Attribute Required Description

fetch

Optional

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

Attribute	Required	Description
`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

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

Attribute	Required	Description
`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

Attribute	Required	Description
`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

Attribute	Required	Description
`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-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

Attribute Required Description

name

Optional

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 pre-existing 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.

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

Attribute	Required	Description
`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

Attribute Required Description

entityClass

Required

Set entityClass to the Class of the entity returned by the query.

fields

Optional

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.

discriminatorColumn

Optional

Default: empty String.

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",       column="order_id"),
                @FieldResult(name="quantity", column="order_quantity"),
                @FieldResult(name="item",     column="order_item")
            }
        ),
        @EntityResult(
            entityClass=Item.class,
            fields={
                @FieldResult(name="id",       column="item_id"),
                @FieldResult(name="name",     column="item_name")
            }
        )
    }
)
@Entity
public class Order {
    @Id
    protected int id;
    protected long quantity;
    @ManyToOne
    protected Item item;
    ...
}

Example 1-23 Item Entity

@Entity
public class Item {
    @Id
    protected int id;
    protected String 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

Attribute Required Description

value

Optional

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}

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

Attribute	Required	Description
`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.
`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",       column="order_id"),
                @FieldResult(name="quantity", column="order_quantity"),
                @FieldResult(name="item",     column="order_item")
            }
        ),
        @EntityResult(
            entityClass=Item.class,
            fields={
                @FieldResult(name="id",       column="item_id"),
                @FieldResult(name="name",     column="item_name")
            }
        )
    }
)
@Entity
public class Order {
    @Id
    protected int id;
    protected long quantity;
    @ManyToOne
    protected Item item;
    ...
}

Example 1-31 Item Entity

@Entity
public class Item {
    @Id
    protected int id;
    protected String name;
    ...
}

Example 1-32 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], ...}

@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

Attribute Required Description

strategy

Optional

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

Optional

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.

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

Attribute	Required	Description
`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

Attribute Required Description

strategy

Optional

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 1This 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 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

Attribute	Required	Description
`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

Attribute	Required	Description
`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
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

Attribute	Required	Description
`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 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

Attribute	Required	Description
`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

Attribute Required Description

targetEntity

Optional

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

Optional

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

Optional

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

Attribute Required Description

name

Optional

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

Attribute	Required	Description
`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

Attribute	Required	Description
`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`.
`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.

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

Attribute	Required	Description
`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

Attribute Required Description

name

Required

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

Required

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

Optional

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 relationships (see @JoinTable)

Table 1-29 lists the attributes of this annotation . For more details, see the API.

Table 1-29 @OneToMany Attributes

Attribute	Required	Description
`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

Attribute	Required	Description
`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

Attribute Required Description

value

Optional

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: " property-or-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

Attribute	Required	Description
`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 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

Attribute	Required	Description
`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

Attribute	Required	Description
`name`		To specify the name of the persistence property, set `name` to the `String` property name.
`value`		To specify the value of the persistence property, set `value` to the `String` property value you want.

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

Attribute Required Description

name

Optional

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

Optional

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

Attribute	Required	Description
`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

Attribute Required Description

name

Optional

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

Optional

Default: TopLink JPA assumes one of the following names for 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

Optional

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

Attribute	Required	Description
`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

Table 1-39 lists the attributes of this annotation . For more details, see the API.

Table 1-39 @QueryHint Attributes

Attribute	Required	Description
`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

Attribute	Required	Description
`name`		If your entity uses a secondary table, set `name` to the `String` table name.
`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.
`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

Attribute	Required	Description
`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

Attribute	Required	Description
`name`		The name of the `SequenceGenerator` must match the generator name in a `GeneratedValue` with its `strategy` set to `SEQUENCE`.
`sequenceName`		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.
`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 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

Attribute Required Description

name

Required

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

Optional

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

Optional

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",       column="order_id"),
                @FieldResult(name="quantity", column="order_quantity"),
                @FieldResult(name="item",     column="order_item")
            }
        ),
        @EntityResult(
            entityClass=Item.class,
            fields={
                @FieldResult(name="id",       column="item_id"),
                @FieldResult(name="name",     column="item_name"),
            }
        )
    }
)
@Entity
public class Order {
    @Id
    protected int id;
    protected long quantity;
    @ManyToOne
    protected Item item;
    ...
}

Example 1-81 Item Entity

@Entity
public class Item {
    @Id
    protected int id;
    protected String name;
    ...
}

Example 1-82 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, "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

Attribute	Required	Description
`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

Attribute	Required	Description
`name`		Default: TopLink JPA assumes that an entity's database table has the 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

Attribute	Required	Description
`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).
`table`		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.
`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` 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

Attribute Required Description

value

Required

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

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 {    @Id int id;    @Transient Session currentSession;    ...}

@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

Attribute	Required	Description
`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:

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
F
- @FieldResult
G
- @GeneratedValue
I
J
L
- @Lob
M
N
O
P
Q
- @QueryHint
S
T
U
- @UniqueConstraint
V
- @Version

	Popular Downloads
Untitled Document Berkeley DB Enterprise Manager Database EE and XE Developer VMs Enterprise Pack for Eclipse Java JDeveloper and ADF Oracle Linux and Oracle VM MySQL NetBeans IDE NoSQL Database Solaris SQL Developer VirtualBox WebLogic Server

E-mail this page

Printer View

TopLink JPA Annotation Reference

@AssociationOverride

@AssociationOverrides

@AttributeOverride

@AttributeOverrides

@Basic

@Column

@ColumnResult

@DiscriminatorColumn

@DiscriminatorValue

@Embeddable

@Embedded

@EmbeddedId

@Entity

@EntityListeners

@EntityResult

@Enumerated

@ExcludeDefaultListeners

@ExcludeSuperclassListeners

@FieldResult

@GeneratedValue

@Id

@IdClass

@Inheritance

@JoinColumn

@JoinColumns

@JoinTable

@Lob

@ManyToMany

@ManyToOne

@MapKey

@MappedSuperclass

@NamedNativeQueries

@NamedNativeQuery

@NamedQueries

@NamedQuery

@OneToMany

@OneToOne

@OrderBy

@PersistenceContext

@PersistenceContexts

@PersistenceProperty

@PersistenceUnit

@PersistenceUnits

@PrimaryKeyJoinColumn

@PrimaryKeyJoinColumns

@QueryHint

@SecondaryTable

@SecondaryTables

@SequenceGenerator

@SqlResultSetMapping

@SqlResultSetMappings

@Table

@TableGenerator

@Temporal

@Transient

@UniqueConstraint

@Version

Lifecycle Event Annotations

@PostLoad

@PostPersist

@PostRemove

@PostUpdate

@PrePersist

@PreRemove

@PreUpdate

Index of Annotations

Hardware and Software, Engineered to Work Together