Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Using EclipseLink JPA Extensions (ELUG)"

(How to Use the @CollectionTable Annotation)
m (Replacing page with 'This page is now obsolete. Please see the [http://www.eclipse.org/eclipselink/documentation/ EclipseLink JPA Extensions Guide] for the current information.')
 
(134 intermediate revisions by 15 users not shown)
Line 1: Line 1:
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
+
This page is now obsolete. Please see the  
[[Special:Whatlinkshere/Using EclipseLink JPA Extensions (ELUG)|Related Topics]]</div>
+
[http://www.eclipse.org/eclipselink/documentation/ EclipseLink JPA Extensions Guide] for the current information.
 
+
The Java Persistence API (JPA), part of the Java Enterprise Edition 5 (Java EE 5) 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.
+
 
+
EclipseLink JPA provides extensions to what is defined in the JPA specification. These extensions come in persistence unit properties, query hints, annotations, EclipseLink own XML metadata, and custom API.
+
 
+
This section explains where and how you use the extensions to customize JPA behavior to meet your application requirements.
+
 
+
For more information, see the following:
+
* ''EclipseLink API Reference''
+
* [http://jcp.org/aboutJava/communityprocess/pfd/jsr220/indexl ''JSR-220 Enterprise JavaBeans v.3.0''] ''Java Persistence API specification''
+
* [http://java.sun.com/javaee/5/docs/api/index.html?javax/persistence/package-summary.html ''Java EE 5 SDK JPA Javadoc'']
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Mapping==
+
EclipseLink defines the following mapping metadata annotations (in addition to JPA-defined ones):
+
* <tt>[[#How to Use the @BasicCollection Annotation|@BasicCollection]]</tt>
+
* <tt>[[#How to Use the @BasicMap Annotation|@BasicMap]]</tt>
+
* <tt>[[#How to Use the @CollectionTable Annotation|@CollectionTable]]</tt>
+
* <tt>[[#How to Use the @PrivateOwned Annotation|@PrivateOwned]]</tt>
+
* <tt>[[#How to Use the @JoinFetch Annotation|@JoinFetch]]</tt>
+
* <tt>[[#How to Use the @Mutable Annotation|@Mutable]]</tt>
+
* <tt>[[#How to Use the @Transformation Annotation|@Transformation]]</tt>
+
 
+
EclipseLink persistence provider searches mapping annotations in the following order:
+
* <tt>[[#How to Use the @BasicCollection Annotation|@BasicCollection]]</tt>
+
* <tt>[[#How to Use the @BasicMap Annotation|@BasicMap]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@EmbeddedId|@EmbeddedId]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Embedded)|@Embedded]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToMany|@ManyToMany]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToOne|@ManyToOne]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToMany|@OneToMany]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|@OneToOne]]</tt>
+
 
+
EclipseLink persistence provider applies the first annotation that it finds; it ignores other mapping annotations, if specified. In most cases, EclipseLink does not log warnings or throw exceptions for duplicate or incompatible mapping annotations.
+
 
+
If EclipseLink persistence provider does not find any of the mapping annotations from the preceding list, it applies the defaults defined by the JPA specification: not necessarily the <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|@Basic]]</tt> annotation.
+
 
+
 
+
 
+
===How to Use the @BasicCollection Annotation===
+
You can use the <tt>@BasicCollection</tt> annotation to map an <tt>org.eclipse.persistence.mappings.DirectCollectionMapping</tt>, which stores a collection of simple types, such as <tt>String</tt>, <tt>Number</tt>, <tt>Date</tt>, and so on, in a single table. The table must store the value and the foreign key to the source object.
+
 
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface BasicCollection {
+
    FetchType fetch() default LAZY;
+
    Column valueColumn() default @Column;
+
}
+
 
+
Use the <tt>@BasicCollection</tt> annotation in conjunction with a <tt>[[#How to Use the @CollectionTable Annotation|@CollectionTable]]</tt> annotation. You can also use it in conjunction with <tt>[[#How to Use the @Convert Annotation|@Convert]]</tt> to modify the data value(s) during reading and writing of the collection, as well as with the <tt>[[#How to Use the @JoinFetch Annotation|@JoinFetch]]</tt> annotation.
+
 
+
This table lists attributes of the <tt>@BasicCollection</tt> annotation.
+
 
+
<span id="Table 19-1"></span>
+
''''' Attributes of the @BasicCollection Annotation'''''
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @BasicCollection Annotation" summary="This table lists the attributes of EclipseLink JPA @BasicCollection annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t2" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t2" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t2" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t2" headers="r1c1-t2" align="left" |
+
<tt>fetch</tt>
+
| headers="r2c1-t2 r1c2-t2" align="left" |
+
The <tt>javax.persistence.FetchType</tt> enumerated type that defines whether EclipseLink should lazily load or eagerly fetch the value of the field or property.
+
| headers="r2c1-t2 r1c3-t2" align="left" |
+
<tt>FetchType.LAZY</tt>
+
| headers="r2c1-t2 r1c4-t2" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r3c1-t2" headers="r1c1-t2" align="left" |
+
<tt>valueColumn</tt>
+
| headers="r3c1-t2 r1c2-t2" align="left" |
+
The name of the value column (<tt>javax.persistence.Column</tt>) that holds the direct collection data.
+
| headers="r3c1-t2 r1c3-t2" align="left" |
+
<tt>@Column</tt>Note: EclipseLink persistence provider sets the default to the name of the field or property.
+
| headers="r3c1-t2 r1c4-t2" align="left" |
+
optional
+
|}
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' If you specify <tt>@BasicCollection</tt> on an attribute of type <tt>Map</tt>, EclipseLink will throw an exception: the type must be <tt>Collection</tt>, <tt>Set</tt> or <tt>List</tt>. If you specify the fetch type as <tt>LAZY</tt>, Collection implementation classes will also not be valid.
+
|}
+
 
+
 
+
This example shows how to use the <tt>@BasicCollection</tt> annotation to specify <tt>Employee</tt> field <tt>responsibilities</tt>.
+
 
+
 
+
<span id="Example 19-1"></span>
+
''''' Usage of the @BasicCollection Annotation'''''
+
@Entity
+
public class Employee implements Serializable{
+
    ...
+
    @BasicCollection (
+
        fetch=FetchType.EAGER,
+
        valueColumn=@Column(name="DESCRIPTION")
+
    )
+
    @CollectionTable (
+
        name="RESPONS",
+
        primaryKeyJoinColumns=
+
        {@PrimaryKeyJoinColumn(name="EMPLOYEE_ID", referencedColumnName="EMP_ID")}
+
    )
+
    public Collection getResponsibilities() {
+
        return responsibilities;
+
    }
+
    ...
+
}
+
 
+
To further customize your mapping, use [[Configuring%20a%20Relational%20Direct%20Collection%20Mapping (ELUG)|the DirectCollectionMapping API]].
+
 
+
===How to Use the @BasicMap Annotation===
+
You can use the <tt>@BasicMap</tt> annotation to map an <tt>[[Introduction to Relational Mappings%20(ELUG)#Direct Map Mapping|org.eclipse.persistence.mappings.DirectMapMapping]]</tt>, which stores a collection of key-value pairs of simple types, such as <tt>String</tt>, <tt>Number</tt>, <tt>Date</tt>, and so on, in a single table. The table must store the value and the foreign key to the source object.
+
 
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface BasicMap {
+
    FetchType fetch() default LAZY;
+
    Column keyColumn();
+
    Convert keyConverter() default @Convert;
+
    Column valueColumn() default @Column;
+
    Convert valueConverter() default @Convert;
+
}
+
 
+
Use the <tt>@BasicMap</tt> annotation in conjunction with a <tt>[[#How to Use the @CollectionTable Annotation|@CollectionTable]]</tt> annotation, as well as with the <tt>[[#How to Use the @JoinFetch Annotation|@JoinFetch]]</tt> annotation.
+
 
+
This table lists attributes of the <tt>@BasicMap</tt> annotation.
+
 
+
<span id="Table 19-2"></span>
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @BasicMap Annotation" summary="This table lists the attributes of EclipseLink JPA @BasicMap annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t4" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t4" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t4" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t4" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t4" headers="r1c1-t4" align="left" |
+
<tt>fetch</tt>
+
| headers="r2c1-t4 r1c2-t4" align="left" |
+
Set this attribute to the <tt>javax.persistence.FetchType</tt> enumerated type to define whether EclipseLink persistence provider has to lazily load or eagerly fetch the value of the field or property.
+
| headers="r2c1-t4 r1c3-t4" align="left" |
+
<tt>FetchType.LAZY</tt>
+
| headers="r2c1-t4 r1c4-t4" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r3c1-t4" headers="r1c1-t4" align="left" |
+
<tt>keyColumn</tt>
+
| headers="r3c1-t4 r1c2-t4" align="left" |
+
Set this attribute to the name of the data column (<tt>javax.persistence.Column</tt>) that holds the direct map key.
+
| headers="r3c1-t4 r1c3-t4" align="left" |
+
<tt><field-name>_KEY</tt> or <tt><property-name>_KEY</tt> (in uppercase characters)
+
| headers="r3c1-t4 r1c4-t4" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r4c1-t4" headers="r1c1-t4" align="left" |
+
<tt>keyConverter</tt>
+
| headers="r4c1-t4 r1c2-t4" align="left" |
+
Set this attribute to the key converter (<tt>[[#How to Use the @Convert Annotation|@Convert]]</tt>).
+
| headers="r4c1-t4 r1c3-t4" align="left" |
+
<tt>@Convert</tt> – an equivalent of specifying <tt>@Convert("none")</tt> resulting in no converter added to the direct map key.
+
| headers="r4c1-t4 r1c4-t4" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r5c1-t4" headers="r1c1-t4" align="left" |
+
<tt>valueColumn</tt>
+
| headers="r5c1-t4 r1c2-t4" align="left" |
+
Set this attribute to the name of the value column (<tt>javax.persistence.Column</tt>) that holds the direct collection data.
+
| headers="r5c1-t4 r1c3-t4" align="left" |
+
<tt>@Column</tt><br>
+
Field or property.
+
| headers="r5c1-t4 r1c4-t4" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r6c1-t4" headers="r1c1-t4" align="left" |
+
<tt>valueConverter</tt>
+
| headers="r6c1-t4 r1c2-t4" align="left" |
+
Set this attribute to the value converter (<tt>[[#How to Use the @Convert Annotation|@Convert]]</tt>).
+
| headers="r6c1-t4 r1c3-t4" align="left" |
+
<tt>@Convert</tt> – an equivalent of specifying <tt>@Convert("none")</tt> resulting in no converter added to the direct map key.
+
| headers="r6c1-t4 r1c4-t4" align="left" |
+
optional
+
|}
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' If you specify <tt>@BasicMap</tt> on an attribute of type <tt>Collection</tt>, EclipseLink will throw an exception: the type must be <tt>Map</tt>. If you specify the fetch type as <tt>LAZY</tt>, Map implementation classes are also not valid.
+
|}
+
 
+
 
+
This example shows how to use the <tt>@BasicMap</tt> annotation to specify <tt>Employee</tt> field <tt>licenses</tt>.
+
 
+
<span id="Example 19-2"></span>
+
''''' Usage of the @BasicMap Annotation'''''
+
@Entity
+
@Table(name="CMP3_EMPLOYEE")
+
@TypeConverter(
+
    name="Integer2String",
+
    dataType=Integer.class,
+
    objectType=String.class
+
)
+
public class Employee implements Serializable{
+
    ...
+
    @BasicMap (
+
        fetch=FetchType.EAGER,
+
        keyColumn=@Column(name="LICENSE"),
+
        keyConverter=@Convert("licenseConverter"),
+
        valueColumn=@Column(name="STATUS"),
+
        valueConverter=@Convert("Integer2String")
+
    )
+
    @ObjectTypeConverter(
+
        name="licenseConverter",
+
        conversionValues={
+
            @ConversionValue(dataValue="AL", objectValue="Alcohol License"),
+
            @ConversionValue(dataValue="FD", objectValue="Food License"),
+
            @ConversionValue(dataValue="SM", objectValue="Smoking License"),
+
            @ConversionValue(dataValue="SL", objectValue="Site Licence")}
+
    )
+
    @CollectionTable (
+
        name="LICENSE",
+
        primaryKeyJoinColumns={@PrimaryKeyJoinColumn(name="REST_ID")}
+
    )
+
    public Map<String, String> getLicenses() {
+
        return licenses;
+
    }
+
    ...
+
}
+
 
+
To further customize your mapping, use the [[Configuring%20a%20Relational%20Direct%20Map%20Mapping%20(ELUG)|<tt>DirectMapMapping</tt> API]].
+
 
+
===How to Use the @CollectionTable Annotation===
+
 
+
You can use the <tt>@CollectionTable</tt> annotation in conjunction with a <tt>[[#How to Use the @BasicCollection Annotation|@BasicCollection]]</tt> annotation or the <tt>[[#How to Use the @BasicMap Annotation|@BasicMap]]</tt> annotation. If you do not specify the <tt>@CollectionTable</tt>, EclipseLink persistence provider will use the defaults.
+
 
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface CollectionTable {
+
    String name() default "";
+
    String catalog() default "";
+
    String schema() default "";
+
    PrimaryKeyJoinColumn[] primaryKeyJoinColumns() default {};
+
    UniqueConstraint[] uniqueConstraints() default {};
+
}
+
 
+
This table lists attributes of the <tt>@CollectionTable</tt> annotation.
+
 
+
<span id="Table 19-3"></span>
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @CollectionTable Annotation" summary="This table lists the attributes of EclipseLink JPA @CollectionTable annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t6" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t6" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t6" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t6" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t6" headers="r1c1-t6" align="left" |
+
<tt>name</tt>
+
| headers="r2c1-t6 r1c2-t6" align="left" |
+
Set this attribute to the <tt>String</tt> name for your collection table.
+
| headers="r2c1-t6 r1c3-t6" align="left" |
+
empty <tt>String</tt> <br>
+
Note: EclipseLink persistence provider applies the following concatenated <tt>String</tt> as a default: the name of the source entity + "_" + the name of the relationship property or field of the source entity.
+
| headers="r2c1-t6 r1c4-t6" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r3c1-t6" headers="r1c1-t6" align="left" |
+
<tt>catalog</tt>
+
| headers="r3c1-t6 r1c2-t6" align="left" |
+
Set this attribute to the <tt>String</tt> name of the table's catalog.
+
| headers="r3c1-t6 r1c3-t6" align="left" |
+
empty <tt>String</tt><br>
+
Note: EclipseLink persistence provider sets the default to the persistence unit's default catalog.
+
| headers="r3c1-t6 r1c4-t6" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r4c1-t6" headers="r1c1-t6" align="left" |
+
<tt>schema</tt>
+
| headers="r4c1-t6 r1c2-t6" align="left" |
+
Set this attribute to the <tt>String</tt> name of the table's schema.
+
| headers="r4c1-t6 r1c3-t6" align="left" |
+
empty <tt>String</tt><br>
+
Note: EclipseLink persistence provider sets the default to the persistence unit's default schema.
+
| headers="r4c1-t6 r1c4-t6" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r5c1-t6" headers="r1c1-t6" align="left" |
+
<tt>primaryKeyJoinColumns</tt>
+
| headers="r5c1-t6 r1c2-t6" align="left" |
+
Set this attribute to an array of <tt>javax.persistence.PrimaryKeyJoinColumn</tt> instances to specify a primary key column that is used as a foreign key to join to another table. If the source entity uses a composite primary key, you must specify a primary key join column for each field of the composite primary key. If the source entity uses a single primary key, you may choose to specify a primary key join column (optional). Otherwise, EclipseLink persistence provider will apply the following defaults:
+
* <tt>javax.persistence.PrimaryKeyJoinColumn</tt> <tt>name</tt> – the same name as the primary key column of the primary table of the source entity;
+
* <tt>javax.persistence.PrimaryKeyJoinColumn referencedColumnName</tt> – the same name of the primary key column of the primary table of the source entity.<br>
+
 
+
If the source entity uses a composite primary key and you failed to specify the primary key join columns, EclipseLink will throw an exception.
+
| headers="r5c1-t6 r1c3-t6" align="left" |
+
empty <tt>PrimaryKeyJoinColumn</tt> array
+
| headers="r5c1-t6 r1c4-t6" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r6c1-t6" headers="r1c1-t6" align="left" |
+
<tt>uniqueConstraints</tt>
+
| headers="r6c1-t6 r1c2-t6" align="left" |
+
Set this attribute to an array of <tt>javax.persistence.UniqueConstraint</tt> instances that you want to place on the table. These constraints are only used if table generation is in effect.
+
| headers="r6c1-t6 r1c3-t6" align="left" |
+
empty <tt>UniqueConstraint</tt> array
+
| headers="r6c1-t6 r1c4-t6" align="left" |
+
optional
+
|}
+
 
+
 
+
This example shows how to use the <tt>@CollectionTable</tt> annotation to specify <tt>Employee</tt> field <tt>responsibilities</tt>.
+
 
+
<span id="Example 19-3"></span>
+
''''' Usage of the @CollectionTable Annotation'''''
+
@Entity
+
public class Employee implements Serializable{
+
    ...
+
    @BasicCollection (
+
        fetch="LAZY",
+
        valueColumn=@Column(name="DESCRIPTION")
+
    )
+
    @CollectionTable (
+
        name="RESPONS",
+
        primaryKeyJoinColumns=
+
        {@PrimaryKeyJoinColumn(name="EMPLOYEE_ID", referencedColumnName="EMP_ID")}
+
    )
+
    public Collection getResponsibilities() {
+
        return responsibilities;
+
    }
+
    ...
+
}
+
 
+
===How to Use the @PrivateOwned Annotation===
+
 
+
Use the <tt>@PrivateOwned</tt> annotation in conjunction with a <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|@OneToOne]]</tt> annotation, or a <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToMany|@OneToMany]]</tt> annotation.
+
 
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface PrivateOwned { ... }
+
 
+
The <tt>@PrivateOwned</tt> annotation does not have attributes.
+
 
+
This example shows how to use the <tt>@PrivateOwned</tt> annotation to specify <tt>Employee</tt> field <tt>phoneNumbers</tt>.
+
 
+
<span id="Example 19-4"></span>
+
''''' Usage of the @PrivateOwned Annotation'''''
+
@Entity
+
public class Employee implements Serializable {
+
    ...
+
    @OneToMany(cascade=ALL, mappedBy="employee")
+
    @PrivateOwned
+
    public Collection<PhoneNumber> getPhoneNumbers() {
+
        return phoneNumbers;
+
    }
+
    ...
+
}
+
 
+
 
+
====What You May Need to Know About Private Ownership of Objects====
+
 
+
When the referenced object is privately owned, the referenced child object cannot exist without the parent object.
+
 
+
When you tell EclipseLink that a relationship is privately owned, you are specifying the following:
+
 
+
* If the source of a privately owned relationship is deleted, then delete the target. Note that this is equivalent of setting a cascade delete.<br>For more information, see the following:
+
** [[Introduction%20to%20Descriptors%20(ELUG)#Optimistic Version Locking Policies and Cascading|Optimistic Version Locking Policies and Cascading]]
+
** Section 3.2.2 "Removal" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]
+
** Section 3.5.2 "Semantics of the Life Cycle Callback Methods for Entities" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]
+
** Section 4.10 "Bulk Update and Delete Operations" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]
+
** [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|@OneToOne]]
+
** [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToOne|@ManyToOne]]
+
** [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToMany|@OneToMany]]
+
* If you remove the reference to a target from a source, then delete the target.
+
 
+
Do not configure privately owned relationships to objects that might be shared. An object should not be the target in more than one relationship if it is the target in a privately owned relationship.
+
 
+
The exception to this rule is the case when you have a many-to-many relationship in which a relation object is mapped to a relation table and is referenced through a one-to-many relationship by both the source and the target. In this case, if the one-to-many mapping is configured as privately owned, then when you delete the source, all the association objects will be deleted.
+
 
+
For more information, see [[Using%20Basic%20Unit%20of%20Work%20API%20(ELUG)#How to Use the privateOwnedRelationship Attribute|How to Use the privateOwnedRelationship Attribute]].
+
 
+
 
+
 
+
===How to Use the @JoinFetch Annotation===
+
 
+
You can specify the <tt>@JoinFetch</tt> annotation for the following mappings:
+
 
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|@OneToOne]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToMany|@OneToMany]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToOne|@ManyToOne]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToMany|@ManyToMany]]</tt>
+
* <tt>[[#How to Use the @BasicCollection Annotation|@BasicCollection]]</tt>
+
* <tt>[[#How to Use the @BasicMap Annotation|@BasicMap]]</tt>
+
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface JoinFetch { ... }
+
 
+
Using the <tt>@JoinFetch</tt> annotation, you can enable the joining and reading of the related objects in the same query as the source object.
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' We recommend setting join fetching at the query level, as not all queries require joining. For more information, see [[Using%20Basic%20Query%20API%20(ELUG)#Using Join Reading with ObjectLevelReadQuery|Using Join Reading with ObjectLevelReadQuery]].
+
|}
+
 
+
 
+
Alternatively, you can use batch reading, especially for collection relationships. For more information, see [[Using%20Basic%20Query%20API%20(ELUG)#Using_Batch_Reading|Using Batch Reading]].
+
 
+
This table lists attributes of the <tt>@JoinFetch</tt> annotation.
+
 
+
<span id="Table 19-4"></span>
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @JoinFetch Annotation" summary="This table lists the attributes of EclipseLink JPA @BasicCollection annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t8" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t8" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t8" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t8" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t8" headers="r1c1-t8" align="left" |
+
<tt>value</tt>
+
| headers="r2c1-t8 r1c2-t8" align="left" |
+
Set this attribute to the <tt>org.eclipse.persistence.annotations.JoinFetchType</tt> enumerated type of the fetch that you will be using.
+
 
+
The following are the valid values for the <tt>JoinFetchType</tt><nowiki>:</nowiki>
+
* <tt>INNER</tt> – This option provides the inner join fetching of the related object.<br>Note: Inner joining does not allow for null or empty values.
+
* <tt>OUTER</tt> – This option provides the outer join fetching of the related object.<br>Note: Outer joining allows for null or empty values.<br>
+
 
+
For more information, see the following:
+
* [[Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#What You May Need to Know About Joins|What You May Need to Know About Joins]]
+
* [[Using%20Basic%20Query%20API%20(ELUG)#Using Join Reading with ObjectLevelReadQuery|Using Join Reading with ObjectLevelReadQuery]]
+
* [[Configuring%20a%20Relational%20Mapping%20(ELUG)#Configuring Joining at the Mapping Level|Configuring Joining at the Mapping Level]]
+
| headers="r2c1-t8 r1c3-t8" align="left" |
+
<tt>JoinFetchType.INNER</tt>
+
| headers="r2c1-t8 r1c4-t8" align="left" |
+
optional
+
|}
+
 
+
 
+
This example shows how to use the <tt>@JoinFetch</tt> annotation to specify <tt>Employee</tt> field <tt>managedEmployees</tt>.
+
 
+
<span id="Example 19-5"></span>
+
''''' Usage of the @JoinFetch Annotation'''''
+
@Entity
+
public class Employee implements Serializable {
+
    ...
+
    @OneToMany(cascade=ALL, mappedBy="owner")
+
    @JoinFetch(value=OUTER)
+
    public Collection<Employee> getManagedEmployees() {
+
        return managedEmployees;
+
    }
+
    ...
+
}
+
 
+
 
+
 
+
===How to Use the @Mutable Annotation===
+
 
+
You can specify the <tt>@Mutable</tt> annotation for the following mappings:
+
 
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|@Basic]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Id|@Id]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Configuring Locking|@Version]]</tt>
+
* <tt>[[#How to Use the @Transformation Annotation|@Transformation]]</tt>
+
 
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface Mutable { ... }
+
 
+
Using the <tt>@Mutable</tt> annotation, you can indicate that the value of a complex field itself can be changed or not changed (instead of being replaced).
+
 
+
By default, EclipseLink assumes that <tt>Serializable</tt> types are mutable. In other words, EclipseLink assumes the default <tt>@Mutable(value=true)</tt>.
+
 
+
You can override this configuration using <tt>@Mutable(value=false)</tt>.
+
 
+
By default, EclipseLink assumes that all <tt>@Basic</tt> mapping types, except <tt>Serializable</tt> types, are immutable.
+
 
+
You can override this configuration using <tt>@Mutable(value=true)</tt>. For example, if you need to call <tt>Date</tt> or <tt>Calendar</tt> set methods, you can decorate a <tt>Date</tt> or <tt>Calendar</tt> persistent field using <tt>@Mutable(value=true)</tt>.
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' For <tt>Date</tt> and <tt>Calendar</tt> types only, you can configure all such persistent fields as mutable by setting global persistence unit property <tt>eclipselink.temporal.mutable</tt> to <tt>true</tt>. For more information, see the  [[#Table 19-6|EclipseLink JPA Persistence Unit Properties for Mappings]] table.
+
|}
+
 
+
 
+
Mutable basic mappings affect the overhead of change tracking. Attribute change tracking can only be weaved with immutable mappings.
+
 
+
For more information, see the following:
+
* [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Unit of Work and Change Policy|Unit of Work and Change Policy]]
+
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Using Weaving|Using Weaving]]
+
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Mutability|Mutability]]
+
 
+
This table lists attributes of the <tt>@Mutable</tt> annotation.
+
 
+
<span id="Table 19-5"></span>
+
''''' Attributes of the @Mutable Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @Mutable Annotation" summary="This table lists the attributes of EclipseLink JPA @BasicCollection annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t10" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t10" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t10" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t10" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t10" headers="r1c1-t10" align="left" |
+
<tt>value</tt>
+
| headers="r2c1-t10 r1c2-t10" align="left" |
+
Set this attribute to one of the following <tt>boolean</tt> values:
+
* <tt>true</tt> – The object is mutable.
+
* <tt>false</tt> – The object is immutable.
+
| headers="r2c1-t10 r1c3-t10" align="left" |
+
<tt>true</tt>
+
| headers="r2c1-t10 r1c4-t10" align="left" |
+
optional
+
|}
+
 
+
 
+
This example shows how to use the <tt>@Mutable</tt> annotation to specify <tt>Employee</tt> field <tt>hireDate</tt>.
+
 
+
<span id="Example 19-6"></span>
+
''''' Usage of the @Mutable Annotation'''''
+
 
+
@Entity
+
public class Employee implements Serializable {
+
    ...
+
    @Temporal(DATE)
+
    @Mutable
+
    public Calendar getHireDate() {
+
        return hireDate;
+
    }
+
    ...
+
}
+
 
+
 
+
 
+
===How to Use the @Transformation Annotation===
+
 
+
You can use the <tt>@Transformation</tt> annotation to map an <tt>[[Introduction%20to%20Relational%20Mappings%20(ELUG)#Transformation Mapping|org.eclipse.persistence.mappings.TransformationMapping]]</tt>, which allows to map an attribute to one or more database columns. The <tt>@Transformation</tt> annotation is optional for transformation mappings.
+
 
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface Transformation { ... }
+
 
+
Use the <tt>@Transformation</tt> annotation in conjunction with a <tt>[[#How to Use the @CollectionTable Annotation|@CollectionTable]]</tt> annotation, as well as with the <tt>[[#How to Use the @JoinFetch Annotation|@JoinFetch]]</tt> annotation.
+
 
+
This table lists attributes of the <tt>@Transformation</tt> annotation.
+
 
+
<span id="Table 19-500"></span>
+
''''' Attributes of the @Transformation Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @Transformation Annotation" summary="This table lists the attributes of EclipseLink JPA @Transformation annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t10" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t10" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t10" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t10" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t10" headers="r1c1-t10" align="left" |
+
<tt>fetch</tt>
+
| headers="r2c1-t10 r1c2-t10" align="left" |
+
The <tt>javax.persistence.FetchType</tt> enumerated type that defines whether EclipseLink should lazily load or eagerly fetch the value of the field or property.
+
| headers="r2c1-t10 r1c3-t10" align="left" |
+
<tt>FetchType.EAGER</tt>
+
| headers="r2c1-t10 r1c4-t10" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r2c1-t10" headers="r1c1-t10" align="left" |
+
<tt>optional</tt>
+
| headers="r2c1-t10 r1c2-t10" align="left" |
+
Set this attribute to define whether or not the value of the field or property may be null.
+
 
+
Note: the value you set is disregarded for primitive types, which are considered mandatory.
+
 
+
The following are valid values:
+
* <tt>true</tt> - The value of the field or property may be <tt>null</tt>.
+
* <tt>false</tt> - The value of the field or property may not be <tt>null</tt>.
+
| headers="r2c1-t10 r1c3-t10" align="left" |
+
<tt>true</tt>
+
| headers="r2c1-t10 r1c4-t10" align="left" |
+
optional
+
|}
+
 
+
 
+
For more information, see the following:
+
* [[#How to Use the @ReadTransformer Annotation|How to Use the @ReadTransformer Annotation]]
+
* [[#How to Use the @WriteTransformer Annotation|How to Use the @WriteTransformer
+
Annotation]]
+
 
+
===How to Use the Persistence Unit Properties for Mappings===
+
 
+
This table lists the persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure EclipseLink mappings.
+
 
+
 
+
<span id="Table 19-6"></span>
+
''''' EclipseLink JPA Persistence Unit Properties for Mappings'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for Mappings" summary="This table lists EclipseLink JPA persistence.xml extensions for EclipseLink customization and validation." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t11" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t11" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t11" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t11" headers="r1c1-t11" align="left" |
+
<tt>eclipselink.temporal.mutable</tt>
+
| headers="r2c1-t11 r1c2-t11" align="left" |
+
Specify whether or not EclipseLink JPA should handle all <tt>Date</tt> and <tt>Calendar</tt> persistent fields as mutable objects.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – all <tt>Date</tt> and <tt>Calendar</tt> persistent fields are mutable.
+
* <tt>false</tt> – all <tt>Date</tt> and <tt>Calendar</tt> persistent fields are immutable.<br>
+
 
+
For more information, see the following:
+
* [[#How to Use the @Mutable Annotation|How to Use the @Mutable Annotation]]
+
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Mutability|Mutability]]
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.temporal.mutable" value="true"/>
+
<br>
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.TEMPORAL_MUTABLE, "false");
+
| headers="r2c1-t11 r1c3-t11" align="left" |
+
<tt>false</tt>
+
|}
+
 
+
 
+
For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:
+
* [[#What you May Need to Know About Overriding Annotations in JPA|What you May Need to Know About Overriding Annotations in JPA]]
+
* [[#What you May Need to Know About EclipseLink JPA Overriding Mechanisms (ELUG)|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
For more information about persistence unit properties, see [[#What you May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What you May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
==Using EclipseLink JPA Converters==
+
 
+
EclipseLink defines the following converter annotations (in addition to JPA-defined ones):
+
 
+
* <tt>[[#How to Use the @Converter Annotation|@Converter]]</tt>
+
* <tt>[[#How to Use the @TypeConverter Annotation|@TypeConverter]]</tt>
+
* <tt>[[#How to Use the @ObjectTypeConverter Annotation|@ObjectTypeConverter]]</tt>
+
* <tt>[[#How to Use the @StructConverter Annotation|@StructConverter]]</tt>
+
* <tt>[[#How to Use the @Convert Annotation|@Convert]]</tt>
+
 
+
EclipseLink persistence provider searches the converter annotations in the following order:
+
 
+
* <tt>[[#How to Use the @Convert Annotation|@Convert]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Enumerated|@Enumerated]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Lob|@Lob]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Temporal|@Temporal]]</tt>
+
* Serialized (automatic)
+
 
+
You can define converters at the class, field and property level. You can specify EclipseLink converters on the following classes:
+
 
+
* <tt>@Entity</tt> (see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification])
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@MappedSuperclass|@MappedSuperclass]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Embeddable|@Embeddable]]</tt>
+
 
+
You can use EclipseLink converters with the following mappings:
+
 
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|@Basic]]</tt>
+
* <tt>[[#How to Use the @BasicMap Annotation|@BasicMap]]</tt>
+
* <tt>[[#How to Use the @BasicCollection Annotation|@BasicCollection]]</tt>
+
 
+
If you specify a converter with any other type of mapping annotation, EclipseLink will throw an exception.
+
 
+
 
+
 
+
===How to Use the @Converter Annotation===
+
 
+
You can use <tt>@Converter</tt> annotation to specify a custom converter for modification of the data value(s) during the reading and writing of a mapped attribute.
+
+
@Target({TYPE, METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface Converter { ... }
+
 
+
This table lists attributes of the <tt>@Converter</tt> annotation.
+
 
+
<span id="Table 19-7"></span>
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @Converter Annotation" summary="This table lists the attributes of EclipseLink JPA @Converter annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t12" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t12" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t12" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t12" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t12" headers="r1c1-t12" align="left" |
+
<tt>name</tt>
+
| headers="r2c1-t12 r1c2-t12" align="left" |
+
Set this attribute to the <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit
+
| headers="r2c1-t12 r1c3-t12" align="left" |
+
no default
+
| headers="r2c1-t12 r1c4-t12" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r3c1-t12" headers="r1c1-t12" align="left" |
+
<tt>converterClass</tt>
+
| headers="r3c1-t12 r1c2-t12" align="left" |
+
Set this attribute to the <tt>Class</tt> of your converter. This class must implement the EclipseLink <tt>org.eclipse.persistence.mappings.converters.Converter</tt> interface.
+
| headers="r3c1-t12 r1c3-t12" align="left" |
+
no default
+
| headers="r3c1-t12 r1c4-t12" align="left" |
+
required
+
|}
+
 
+
 
+
This example shows how to use the <tt>@Converter</tt> annotation to specify <tt>Employee</tt> field <tt>gender</tt>.
+
 
+
<span id="Example 19-7"></span>
+
''''' Usage of the @Converter Annotation'''''
+
@Entity
+
public class Employee implements Serializable{
+
    ...
+
    @Basic
+
    @Converter (
+
        name="genderConverter",
+
        converterClass=org.myorg.converters.GenderConverter.class
+
    )
+
    @Convert("genderConverter")
+
    public String getGender() {
+
        return gender;
+
    }
+
    ...
+
}
+
 
+
 
+
 
+
===How to Use the @TypeConverter Annotation===
+
The <tt>@TypeConverter</tt> is an EclipseLink-specific annotation. You can use it to specify an <tt>org.eclipse.persistence.mappings.converters.TypeConversionConverter</tt> for modification of the data value(s) during the reading and writing of a mapped attribute.
+
+
@Target({TYPE, METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface TypeConverter { ... }
+
 
+
This table lists attributes of the <tt>@TypeConverter</tt> annotation.
+
 
+
<span id="Table 19-8"></span>
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @TypeConverter Annotation" summary="This table lists the attributes of EclipseLink JPA @TypeConverter annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t13" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t13" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t13" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t13" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t13" headers="r1c1-t13" align="left" |
+
<tt>name</tt>
+
| headers="r2c1-t13 r1c2-t13" align="left" |
+
Set this attribute to the <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit.
+
| headers="r2c1-t13 r1c3-t13" align="left" |
+
no default
+
| headers="r2c1-t13 r1c4-t13" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r3c1-t13" headers="r1c1-t13" align="left" |
+
<tt>dataType</tt>
+
| headers="r3c1-t13 r1c2-t13" align="left" |
+
Set this attribute to the type stored in the database.
+
| headers="r3c1-t13 r1c3-t13" align="left" |
+
<tt>void.class</tt><sup>1</sup>
+
| headers="r3c1-t13 r1c4-t13" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r4c1-t13" headers="r1c1-t13" align="left" |
+
<tt>objectType</tt>
+
| headers="r4c1-t13 r1c2-t13" align="left" |
+
Set the value of this attribute to the type stored on the entity.
+
| headers="r4c1-t13 r1c3-t13" align="left" |
+
<tt>void.class</tt><sup>1</sup>
+
| headers="r4c1-t13 r1c4-t13" align="left" |
+
optional
+
|}
+
<br><sup>1</sup> The default is inferred from the type of the persistence field or property.
+
 
+
 
+
This example shows how to use the <tt>@TypeConverter</tt> annotation to convert the <tt>Double</tt> value stored in the database to a <tt>Float</tt> value stored in the entity.
+
 
+
<span id="Example 19-8"></span>
+
''''' Usage of the @TypeConverter Annotation'''''
+
@Entity
+
public class Employee implements Serializable{
+
    ...
+
    @TypeConverter (
+
        name="doubleToFloat",
+
        dataType=Double.class,
+
        objectType=Float.class,
+
    )
+
    @Convert("doubleToFloat")
+
    public Number getGradePointAverage() {
+
        return gradePointAverage;
+
    }
+
    ...
+
}
+
 
+
 
+
 
+
===How to Use the @ObjectTypeConverter Annotation===
+
 
+
You can use the <tt>@ObjectTypeConverter</tt> annotation to specify an <tt>org.eclipse.persistence.mappings.converters.ObjectTypeConverter</tt> that converts a fixed number of database data value(s) to Java object value(s) during the reading and writing of a mapped attribute.
+
 
+
@Target({TYPE, METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface ObjectTypeConverter { ... }
+
 
+
This table lists attributes of the <tt>@ObjectTypeConverter</tt> annotation.
+
 
+
<span id="Table 19-9"></span>
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @ObjectTypeConverter Annotation" summary="This table lists the attributes of EclipseLink JPA @ObjectTypeConverter annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t14" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t14" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t14" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t14" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t14" headers="r1c1-t14" align="left" |
+
<tt>name</tt>
+
| headers="r2c1-t14 r1c2-t14" align="left" |
+
Set this attribute to the <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit
+
| headers="r2c1-t14 r1c3-t14" align="left" |
+
no default
+
| headers="r2c1-t14 r1c4-t14" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r3c1-t14" headers="r1c1-t14" align="left" |
+
<tt>dataType</tt>
+
| headers="r3c1-t14 r1c2-t14" align="left" |
+
Set this attribute to the type stored in the database.
+
| headers="r3c1-t14 r1c3-t14" align="left" |
+
<tt>void.class</tt><sup>1</sup>
+
| headers="r3c1-t14 r1c4-t14" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r4c1-t14" headers="r1c1-t14" align="left" |
+
<tt>objectType</tt>
+
| headers="r4c1-t14 r1c2-t14" align="left" |
+
Set the value of this attribute to the type stored on the entity.
+
| headers="r4c1-t14 r1c3-t14" align="left" |
+
<tt>void.class</tt><sup>1</sup>
+
| headers="r4c1-t14 r1c4-t14" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r5c1-t14" headers="r1c1-t14" align="left" |
+
<tt>conversionValues</tt>
+
| headers="r5c1-t14 r1c2-t14" align="left" |
+
Set the value of this attribute to the array of conversion values (instances of <tt>ConversionValue</tt><nowiki>: </nowiki><tt>String objectValue</tt> and <tt>String dataValue</tt>. See the [[#Example 19-9| Usage of the @ObjectTypeConverter Annotation]] example, to be used with the object converter.
+
| headers="r5c1-t14 r1c3-t14" align="left" |
+
no default
+
| headers="r5c1-t14 r1c4-t14" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r6c1-t14" headers="r1c1-t14" align="left" |
+
<tt>defaultObjectValue</tt>
+
| headers="r6c1-t14 r1c2-t14" align="left" |
+
Set the value of this attribute to the default object value. Note that this argument is for dealing with legacy data if the data value is missing.
+
| headers="r6c1-t14 r1c3-t14" align="left" |
+
empty <tt>String</tt>
+
| headers="r6c1-t14 r1c4-t14" align="left" |
+
optional
+
|}
+
<br><sup>1</sup> The default is inferred from the type of the persistence field or property.
+
 
+
This example shows how to use the <tt>@ObjectTypeConverter</tt> annotation to specify the <tt>Employee</tt> field <tt>gender</tt>.
+
 
+
<span id="Example 19-9"></span>
+
''''' Usage of the @ObjectTypeConverter Annotation'''''
+
public class Employee implements Serializable{
+
    ...
+
    @ObjectTypeConverter (
+
        name="genderConverter",
+
        dataType=java.lang.String.class,
+
        objectType=java.lang.String.class,
+
        conversionValues={
+
            @ConversionValue(dataValue="F", objectValue="Female"),
+
            @ConversionValue(dataValue="M", objectValue="Male")}
+
    )
+
    @Convert("genderConverter")
+
    public String getGender() {
+
        return gender;
+
    }
+
    ...
+
}
+
 
+
 
+
 
+
===How to Use the @StructConverter Annotation===
+
 
+
The <tt>@StructConverter</tt> is an EclipseLink-specific annotation. You can add it to an <tt>org.eclipse.persistence.platform.database.DatabasePlatform</tt> using its <tt>addStructConverter</tt> method to enable custom processing of <tt>java.sql.Struct</tt> types.
+
+
@Target({TYPE, METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface StructConverter { ... }
+
 
+
This table lists attributes of the <tt>@StructConverter</tt> annotation.
+
 
+
<span id="Table 19-10"></span>
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @StructConverter Annotation" summary="Lists attributes of the @StructConverter annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t15" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t15" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t15" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t15" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t15" headers="r1c1-t15" align="left" |
+
<tt>name</tt>
+
| headers="r2c1-t15 r1c2-t15" align="left" |
+
Set this attribute to the <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit.
+
| headers="r2c1-t15 r1c3-t15" align="left" |
+
no default
+
| headers="r2c1-t15 r1c4-t15" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r3c1-t15" headers="r1c1-t15" align="left" |
+
<tt>converter</tt>
+
| headers="r3c1-t15 r1c2-t15" align="left" |
+
Set this attribute to the converter class as a <tt>String</tt>. This class must implement the EclipseLink <tt>org.eclipse.persistence.mappings.converters.Converter</tt> interface.
+
| headers="r3c1-t15 r1c3-t15" align="left" |
+
no default
+
| headers="r3c1-t15 r1c4-t15" align="left" |
+
required
+
|}
+
 
+
 
+
This example shows how to define the <tt>@StructConverter</tt>.
+
 
+
<span id="Example 19-10"></span>
+
''''' Defining the @StructConverter'''''
+
@StructConverter(name="MyType",
+
    converter="myproject.converters.MyStructConverter")
+
 
+
You can specify the <tt>@StructConverter</tt> annotation anywhere in an <tt>Entity</tt> with the scope being the whole session.
+
 
+
EclipseLink will throw an exception if you add more than one <tt>StructConverter</tt> that affects the same Java type.
+
 
+
A <tt>@StructConverter</tt> exists in the same namespaces as <tt>[[#How to Use the @Converter Annotation|@Converter]]</tt>. EclipseLink will throw a validation exception if you add a <tt>Converter</tt> and a <tt>StructConverter</tt> of the same name.
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' You can also configure structure converters in a <tt>sessions.xml</tt> file (see [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]]).
+
|}
+
 
+
 
+
 
+
====Using Structure Converters to Configure Mappings====
+
 
+
In EclipseLink, a <tt>DatabasePlatform</tt> (see [[Introduction%20to%20Data%20Access%20(ELUG)#Database Platforms|Database Platforms]]) holds a structure converter. An <tt>org.eclipse.persistence.database.platform.converters.StructConverter</tt> affects all objects of a particular type read into the <tt>Session</tt> that has that <tt>DatabasePlatform</tt>. This prevents you from configuring the <tt>StructConverter</tt> on a mapping-by-mapping basis. To configure mappings that use the <tt>StructConverter</tt>, you call their <tt>setFieldType(java.sql.Types.STRUCT)</tt> method. You must call this method on all mappings that the <tt>StructConverter</tt> will affect – if you do not call it, errors might occur.
+
 
+
The JPA specification requires all <tt>@Basic</tt> mappings (see [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|@Basic]]) that map to a non-primitive or a non-primitive-wrapper type have a serialized converter added to them. This enables certain <tt>STRUCT</tt> types to map to a field without serialization.
+
 
+
You can use the existing <tt>[[#How to Use the @Convert Annotation|@Convert]]</tt> annotation with its <tt>value</tt> attribute set to the <tt>StructConverter</tt> name – in this case, EclipseLink will apply appropriate settings to the mapping. This setting will be required on all mappings that use a type for which a <tt>StructConverter</tt> has been defined. Failing to configure the mapping with the <tt>@Convert</tt> will cause an error.
+
 
+
For more information, see the following:
+
* [[Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational Data Type Structure Mapping|Object-Relational Data Type Structure Mapping]]
+
* [[Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)|Object-Relational Data Type Descriptors]]
+
 
+
 
+
 
+
===How to Use the @Convert Annotation===
+
 
+
The <tt>@Convert</tt> annotation specifies that a named converter should be used with the corresponding mapped attribute.
+
 
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface Convert { ... }
+
 
+
The <tt>@Convert</tt> has the following reserved names:
+
 
+
* <tt>serialized</tt> – places the <tt>org.eclipse.persistence.mappings.converters.SerializedObjectConverter</tt> on the associated mapping.
+
* <tt>none</tt> – does not place a converter on the associated mapping.
+
 
+
This table lists attributes of the <tt>@Convert</tt> annotation.
+
 
+
<span id="Table 19-11"></span>
+
''''' Attributes of the @Convert Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @Convert Annotation" summary="This table lists the attributes of EclipseLink JPA @Convert annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t17" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t17" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t17" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t17" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t17" headers="r1c1-t17" align="left" |
+
<tt>value</tt>
+
| headers="r2c1-t17 r1c2-t17" align="left" |
+
Set this attribute to the <tt>String</tt> name for your converter.
+
| headers="r2c1-t17 r1c3-t17" align="left" |
+
<tt>"none" String</tt>
+
| headers="r2c1-t17 r1c4-t17" align="left" |
+
optional
+
|}
+
 
+
 
+
This example shows how to use the <tt>@Convert</tt> annotation to define the <tt>Employee</tt> field <tt>gender</tt>.
+
 
+
<span id="Example 19-11"></span>
+
''''' Usage of the @Convert Annotation'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@Converter(
+
    name="genderConverter",
+
        converterClass=org.myorg.converters.GenderConverter.class
+
)
+
public class Employee implements Serializable{
+
    ...
+
    @Basic
+
    @Convert("genderConverter")
+
    public String getGender() {
+
        return gender;
+
    }
+
    ...
+
}
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Entity Caching==
+
 
+
The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. EclipseLink uses the cache to do the following:
+
 
+
* Improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.
+
* Manage locking and isolation level.
+
* Manage object identity.
+
 
+
For more information about the EclipseLink cache and its default behavior, see [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]].
+
 
+
EclipseLink defines the following entity caching annotations:
+
 
+
* <tt>[[#How to Use the @Cache Annotation|@Cache]]</tt>
+
* <tt>[[#How to Use the @TimeOfDay Annotation|@TimeOfDay]]</tt>
+
 
+
EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache (see [[#How to Use the Persistence Unit Properties for Caching|How to Use the Persistence Unit Properties for Caching]]). These properties may compliment or provide an alternative to the usage of annotations.
+
 
+
For more information, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]]
+
 
+
 
+
 
+
===How to Use the @Cache Annotation===
+
 
+
EclipseLink uses identity maps to cache objects in order to enhance performance, as well as maintain object identity. You can control the cache and its behavior by decorating your entity classes with the <tt>@Cache</tt> annotation.
+
 
+
@Target({TYPE})
+
@Retention(RUNTIME)
+
public @interface Cache {
+
    CacheType type() default SOFT_WEAK;
+
    int size() default 100;
+
    boolean shared() default true;
+
    int expiry() default -1;
+
    TimeOfDay expiryTimeOfDay() default @TimeOfDay(specified=false);
+
    boolean alwaysRefresh() default false;
+
    boolean refreshOnlyIfNewer() default false;
+
    boolean disableHits() default false;
+
    CacheCoordinationType coordinationType() default SEND_OBJECT_CHANGES;
+
}
+
 
+
You may define the <tt>@Cache</tt> annotation on the following:
+
 
+
* <tt>@Entity</tt> (see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]);
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@MappedSuperclass|@MappedSuperclass]]</tt>;
+
* the root of the inheritance hierarchy (if applicable).<br>
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' If you define the <tt>@Cache</tt> annotation on an inheritance subclass, the annotation will be ignored.
+
|}<br>
+
 
+
 
+
<span id="Table 19-12"></span>
+
''''' Attributes of the @Cache Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @Cache Annotation" summary="This table lists the attributes of EclipseLink JPA Cache annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t19" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t19" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t19" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t19" align="left" valign="bottom" | '''Required or Optional'''
+
! id="r1c5-t19" align="left" valign="bottom" | '''Override with Persistence Unit Property'''
+
|- align="left" valign="top"
+
| id="r2c1-t19" headers="r1c1-t19" align="left" |
+
<tt>type</tt>
+
| headers="r2c1-t19 r1c2-t19" align="left" |
+
Set this attribute to the type (<tt>org.eclipse.persistence.annotations.CacheType</tt> enumerated type) of the cache that you will be using.
+
 
+
The following are the valid values for the <tt>CacheType</tt><nowiki>:</nowiki>
+
* <tt>FULL</tt> – This option provides full caching and guaranteed identity: all objects are cached and not removed. <br>Note: this process may be memory-intensive when many objects are read.
+
* <tt>WEAK</tt> – This option is similar to <tt>FULL</tt>, except that objects are referenced using weak references. This option uses less memory than <tt>FULL</tt>, allows complete garbage collection and provides full caching and guaranteed identity. We recommend using this identity map for transactions that, once started, stay on the server side.
+
* <tt>SOFT</tt> – This option is similar to <tt>WEAK</tt> except that the map holds the objects using soft references. This identity map enables full garbage collection when memory is low. It provides full caching and guaranteed identity.
+
* <tt>SOFT_WEAK</tt> – This option is similar to <tt>WEAK</tt> except that it maintains a most frequently used subcache that uses soft references. The size of the subcache is proportional to the size of the identity map. The subcache uses soft references to ensure that these objects are garbage-collected only if the system is low on memory. We recommend using this identity map in most circumstances as a means to control memory used by the cache.
+
* <tt>HARD_WEAK</tt> – This option is similar to <tt>SOFT_WEAK</tt> except that it maintains a most frequently used subcache that uses hard references. Use this identity map if soft references are not suitable for your platform.
+
* <tt>CACHE</tt> – With this option, a cache identity map maintains a fixed number of objects that you specify in your application. Objects are removed from the cache on a least-recently-used basis. This option allows object identity for the most commonly used objects. <br>Note: this option furnishes caching and identity, but does not guarantee identity.
+
* <tt>NONE</tt> – This option does not preserve object identity and does not cache objects. We do not recommend using this option.
+
| headers="r2c1-t19 r1c3-t19" align="left" |
+
<tt>CacheType.SOFT_WEAK</tt>
+
| headers="r2c1-t19 r1c4-t19" align="left" |
+
optional
+
| headers="r2c1-t19 r1c5-t19" align="left" |
+
- <tt>[[#eclipselink.cache.type.<ENTITY>|eclipselink.cache.type.<ENTITY>]]</tt>- <tt>[[#eclipselink.cache.type.default|eclipselink.cache.type.default]]</tt>
+
|- align="left" valign="top"
+
| id="r3c1-t19" headers="r1c1-t19" align="left" |
+
<tt>size</tt>
+
| headers="r3c1-t19 r1c2-t19" align="left" |
+
Set this attribute to an <tt>int</tt> value to define the size of cache to use.
+
| headers="r3c1-t19 r1c3-t19" align="left" |
+
100
+
| headers="r3c1-t19 r1c4-t19" align="left" | <br>
+
| headers="r3c1-t19 r1c5-t19" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r4c1-t19" headers="r1c1-t19" align="left" |
+
<tt>shared</tt>
+
| headers="r4c1-t19 r1c2-t19" align="left" |
+
Set this attribute to a <tt>boolean</tt> value to indicate whether cached instances should be in the shared cache or in a client isolated cache (see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Isolated Client Session Cache|Isolated Client Session Cache]]).
+
 
+
The following are the valid values:
+
* <tt>true</tt> - use shared cache for cached instances;
+
* <tt>false</tt> - use client isolated cache for cached instances.
+
| headers="r4c1-t19 r1c3-t19" align="left" |
+
<tt>true</tt>
+
| headers="r4c1-t19 r1c4-t19" align="left" |
+
optional
+
| headers="r4c1-t19 r1c5-t19" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r5c1-t19" headers="r1c1-t19" align="left" |
+
<tt>expiry</tt>
+
| headers="r5c1-t19 r1c2-t19" align="left" |
+
Set this attribute to the <tt>int</tt> value to enable the expiration of the cached instance after a fixed period of time (milliseconds). Queries executed against the cache after this will be forced back to the database for a refreshed copy.
+
| headers="r5c1-t19 r1c3-t19" align="left" |
+
-1 (no expiry)
+
| headers="r5c1-t19 r1c4-t19" align="left" |
+
optional
+
| headers="r5c1-t19 r1c5-t19" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r6c1-t19" headers="r1c1-t19" align="left" |
+
<tt>expiryTimeOfDay</tt>
+
| headers="r6c1-t19 r1c2-t19" align="left" |
+
Set this attribute to a specific time of day (<tt>org.eclipse.persistence.annotations.TimeOfDay</tt>) when the cached instance will expire. Queries executed against the cache after this will be forced back to the database for a refreshed copy.
+
| headers="r6c1-t19 r1c3-t19" align="left" |
+
<tt>@TimeOfDay(specified=false)</tt>
+
| headers="r6c1-t19 r1c4-t19" align="left" |
+
optional
+
| headers="r6c1-t19 r1c5-t19" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r7c1-t19" headers="r1c1-t19" align="left" |
+
<tt>alwaysRefresh</tt>
+
| headers="r7c1-t19 r1c2-t19" align="left" |
+
Set this attribute to a <tt>boolean</tt> value of <tt>true</tt> to force all queries that go to the database to always refresh the cache.
+
| headers="r7c1-t19 r1c3-t19" align="left" |
+
<tt>false</tt>
+
| headers="r7c1-t19 r1c4-t19" align="left" |
+
optional
+
| headers="r7c1-t19 r1c5-t19" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r8c1-t19" headers="r1c1-t19" align="left" |
+
<tt>refreshOnlyIfNewer</tt>
+
| headers="r8c1-t19 r1c2-t19" align="left" |
+
Set this attribute to a <tt>boolean</tt> value of <tt>true</tt> to force all queries that go to the database to refresh the cache only if the data received from the database by a query is newer than the data in the cache (as determined by the optimistic locking field).
+
 
+
Note: This option only applies if one of the other refreshing options, such as <tt>alwaysRefresh</tt>, is already enabled.
+
 
+
Note: A version field is necessary to apply this feature.
+
 
+
For more information, see the following:
+
* [[#What You May Need to Know About Version Fields|What You May Need to Know About Version Fields]]
+
* [[Introduction%20to%20Descriptors%20(ELUG)#Optimistic Version Locking Policies|Optimistic Version Locking Policies]]
+
* [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Configuring Locking|Configuring Locking]]
+
* Section 3.4 "Optimistic Locking and Concurrency" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]
+
* Section 9.1.17 "Version Annotation" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]
+
| headers="r8c1-t19 r1c3-t19" align="left" |
+
<tt>false</tt>
+
| headers="r8c1-t19 r1c4-t19" align="left" |
+
optional
+
| headers="r8c1-t19 r1c5-t19" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r9c1-t19" headers="r1c1-t19" align="left" |
+
<tt>disableHits</tt>
+
| headers="r9c1-t19 r1c2-t19" align="left" |
+
Set this attribute to a <tt>boolean</tt> value of <tt>true</tt> to force all queries to bypass the cache for hits, but still resolve against the cache for identity. This forces all queries to hit the database.
+
| headers="r9c1-t19 r1c3-t19" align="left" |
+
<tt>false</tt>
+
| headers="r9c1-t19 r1c4-t19" align="left" |
+
optional
+
| headers="r9c1-t19 r1c5-t19" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r10c1-t19" headers="r1c1-t19" align="left" |
+
<tt>coordinationType</tt>
+
| headers="r10c1-t19 r1c2-t19" align="left" |
+
Set this attribute to the cache coordination mode (<tt>org.eclipse.persistence.annotations.CacheCoordinationType</tt> enumerated type).
+
 
+
The following are the valid values for the <tt>CacheCoordinationType</tt><nowiki>:</nowiki>
+
* <tt>SEND_OBJECT_CHANGES</tt> – This option sends a list of changed objects (including information about the changes). This data is merged into the receiving cache.
+
* <tt>INVALIDATE_CHANGED_OBJECTS</tt> – This option sends a list of the identities of the objects that have changed. The receiving cache invalidates the objects (rather than changing any of the data).
+
* <tt>SEND_NEW_OBJECTS_WITH_CHANGES</tt> – This option is similar to <tt>SEND_OBJECT_CHANGES</tt> except it also includes any newly created objects from the transaction.
+
* <tt>NONE</tt> – This option does not coordinate cache.<br>For more information, see [[Introduction%20to%20Cache%20(ELUG)#Cache Coordination|Cache Coordination]].
+
| headers="r10c1-t19 r1c3-t19" align="left" |
+
<tt>CacheCoordinationType.SEND_OBJECT_CHANGES</tt>
+
| headers="r10c1-t19 r1c4-t19" align="left" |
+
optional
+
| headers="r10c1-t19 r1c5-t19" align="left" | <br>
+
|}
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' If you define the <tt>@Cache</tt> annotation on <tt>@Embeddable</tt> (see [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Embeddable|@Embeddable]]), EclipseLink will throw an exception.
+
|}
+
 
+
 
+
This example shows how to achieve the desired behavior of the EclipseLink cache by defining the attributes of the <tt>@Cache</tt> annotation.
+
 
+
 
+
<span id="Example 19-12"></span>
+
''''' Usage of @Cache Annotation'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@Cache (
+
    type=CacheType.WEAK,
+
    isolated=false,
+
    expiry=600000,
+
    alwaysRefresh=true,
+
    disableHits=true,
+
    coordinationType=INVALIDATE_CHANGED_OBJECTS
+
    )
+
public class Employee implements Serializable {
+
    ...
+
}
+
 
+
 
+
 
+
====What You May Need to Know About Version Fields====
+
 
+
By default, EclipseLink persistence provider assumes that the application is responsible for data consistency.
+
 
+
Use the <tt>@Version</tt> annotation (see [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#Configuring Locking|Configuring Locking]]) to enable the JPA-managed optimistic locking by specifying the version field or property of an entity class that serves as its optimistic lock value (recommended).
+
 
+
When choosing a version field or property, ensure that the following is true:
+
 
+
* there is only one version field or property per entity;
+
* you choose a property or field persisted to the primary table (see Section 9.1.1 "Table Annotation" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]);
+
* your application does not modify the version property or field.
+
 
+
===How to Use the Persistence Unit Properties for Caching===
+
 
+
The [[#Table 19-13|EclipseLink JPA Properties for Caching]] table lists the persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure the EclipseLink cache.
+
 
+
For more information, see the following:
+
 
+
* [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]]
+
* [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]]
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]]
+
 
+
 
+
<span id="Table 19-13"></span>
+
''''' EclipseLink JPA Properties for Caching'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Properties for Caching" summary="This table lists EclipseLink JPA persistence.xml extensions for the EclipseLink cache." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t21" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t21" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t21" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t21" headers="r1c1-t21" align="left" |
+
<tt>eclipselink.cache.type.default</tt>
+
| headers="r2c1-t21 r1c2-t21" align="left" |
+
The default type of session cache.
+
 
+
A session cache is a shared cache that services clients attached to a given session. When you read objects from or write objects to the data source using a client session, EclipseLink saves a copy of the objects in the parent server session's cache and makes them accessible to child client sessions. From a JPA perspective, an <tt>EntityManagerFactory</tt> wraps an <tt>org.eclipse.persistence.sessions.server.ServerSession</tt><nowiki>; entity managers wrap an </nowiki><tt>org.eclipse.persistence.sessions.UnitOfWork</tt> and <tt>org.eclipse.persistence.sessions.server.ClientSession</tt>. For more information about sessions, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Introduction to EclipseLink Sessions]].
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.CacheType</tt><nowiki>:</nowiki>
+
* <tt>Full</tt> – This option provides full caching and guaranteed identity: objects are never flushed from memory unless they are deleted.<br>For more information, see [[Introduction%20to%20Cache%20(ELUG)#Full Identity Map|Full Identity Map]].
+
* <tt>Weak</tt> – This option is similar to <tt>Full</tt>, except that objects are referenced using weak references. This option uses less memory than <tt>Full</tt>, but does not provide a durable caching strategy across client/server transactions. We recommend using this identity map for transactions that, once started, stay on the server side.<br>For more information, see [[Introduction%20to%20Cache%20(ELUG)#Weak Identity Map|Weak Identity Map]].
+
* <tt>Soft</tt> – This option is similar to <tt>Weak</tt> except that the map holds the objects using soft references. This identity map enables full garbage collection when memory is low. It provides full caching and guaranteed identity.<br>For more information, see [[Introduction%20to%20Cache%20(ELUG)#Soft Identity Map|Soft Identity Map]].
+
* <tt>SoftWeak</tt> – This option is similar to <tt>Weak</tt> except that it maintains a most frequently used subcache that uses soft references. We recommend using this identity map in most circumstances as a means to control memory used by the cache.<br>For more information, see [[Introduction%20to%20Cache%20(ELUG)#Soft Cache Weak Identity Map and Hard Cache Weak Identity Map|Soft Cache Weak Identity Map and Hard Cache Weak Identity Map]].
+
* <tt>HardWeak</tt> – This option is similar to <tt>Weak</tt> except that it maintains a most frequently used subcache that uses hard references.<br>For more information, see [[Introduction%20to%20Cache%20(ELUG)#Soft Cache Weak Identity Map and Hard Cache Weak Identity Map|Soft Cache Weak Identity Map and Hard Cache Weak Identity Map]].
+
* <tt>NONE</tt> – This option does not preserve object identity and does not cache objects. Oracle does not recommend using this option.<br>For more information, see [[Introduction%20to%20Cache%20(ELUG)#No Identity Map|No Identity Map]].
+
 
+
'''Note''': The values are case-sensitive.
+
 
+
'''Note''': Using this property, you can override the <tt>@Cache</tt> annotation (see [[#How to Use the @Cache Annotation|How to Use the @Cache Annotation]]) attribute [[#type|type]].
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.cache.type.default" value="Full"/>
+
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.CacheType;
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CACHE_TYPE_DEFAULT, CacheType.Full);
+
| headers="r2c1-t21 r1c3-t21" align="left" |
+
<tt>CacheType.SoftWeak</tt>
+
|- align="left" valign="top"
+
| id="r3c1-t21" headers="r1c1-t21" align="left" |
+
<tt>eclipselink.cache.size.default</tt>
+
| headers="r3c1-t21 r1c2-t21" align="left" |
+
The default maximum number of objects allowed in an EclipseLink cache.
+
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> as a <tt>String</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.cache.size.default" value="5000"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CACHE_SIZE_DEFAULT, 5000);
+
| headers="r3c1-t21 r1c3-t21" align="left" |
+
1000
+
|- align="left" valign="top"
+
| id="r4c1-t21" headers="r1c1-t21" align="left" |
+
<tt>eclipselink.cache.shared.default</tt>
+
| headers="r4c1-t21 r1c2-t21" align="left" |
+
The default for whether or not the EclipseLink session cache is shared by multiple client sessions.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – The session cache services all clients attached to the session. When you read objects from or write objects to the data source using a client session, EclipseLink saves a copy of the objects in the parent server session's cache and makes them accessible to all other processes in the session.
+
* <tt>false</tt> – The session cache services a single, isolated client exclusively. The isolated client can reference objects in a shared session cache but no client can reference objects in the isolated client's exclusive cache.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.cache.shared.default" value="true"/>
+
 
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CACHE_SHARED_DEFAULT, "true");
+
| headers="r4c1-t21 r1c3-t21" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r5c1-t21" headers="r1c1-t21" align="left" |
+
<span id="eclipselink.cache.type.ENTITY"></span>
+
<tt>eclipselink.cache.type.<ENTITY></tt>
+
| headers="r5c1-t21 r1c2-t21" align="left" |
+
The type of session cache for the JPA entity named <tt><ENTITY></tt> or with the class name <tt><ENTITY></tt>.<br>For more information on entity names, see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.CacheType</tt><nowiki>:</nowiki>
+
* <tt>Full</tt> – see <tt>[[#eclipselink.cache.type.default|eclipselink.cache.type.default]]</tt>
+
* <tt>HardWeak</tt> – see <tt>[[#eclipselink.cache.type.default|eclipselink.cache.type.default]]</tt>
+
* <tt>NONE</tt> – see <tt>[[#eclipselink.cache.type.default|eclipselink.cache.type.default]]</tt>
+
* <tt>SoftWeak</tt> – see <tt>[[#eclipselink.cache.type.default|eclipselink.cache.type.default]]</tt>
+
* <tt>Weak</tt> – see <tt>[[#eclipselink.cache.type.default|eclipselink.cache.type.default]]</tt><br>Note: Using this property, you can override the <tt>[[#How to Use the @Cache Annotation|@Cache]]</tt> annotation's attribute <tt>[[#type|type]]</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.cache.type.Order" value="Full"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.CacheType;
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CACHE_TYPE+".Order", CacheType.Full);
+
| headers="r5c1-t21 r1c3-t21" align="left" |
+
<tt>eclipselink.cache.type.default</tt>
+
|- align="left" valign="top"
+
| id="r6c1-t21" headers="r1c1-t21" align="left" |
+
<tt>eclipselink.cache.size.<ENTITY></tt>
+
| headers="r6c1-t21 r1c2-t21" align="left" |
+
The maximum number of JPA entities of the type denoted by JPA entity name <tt><ENTITY></tt> allowed in an EclipseLink cache. For more information on entity names, see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].
+
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> as a <tt>String</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.cache.size.Order" value="5000"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CACHE_SIZE+".Order", 1000);
+
| headers="r6c1-t21 r1c3-t21" align="left" |
+
eclipselink.cache.size.default
+
|- align="left" valign="top"
+
| id="r7c1-t21" headers="r1c1-t21" align="left" |
+
<tt>eclipselink.cache.shared.<ENTITY></tt>
+
| headers="r7c1-t21 r1c2-t21" align="left" |
+
Whether or not the EclipseLink session cache is shared by multiple client sessions for JPA entities of the type denoted by JPA entity name <tt><ENTITY></tt>.<br>For more information on entity names, see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].
+
 
+
The following are the valid values:
+
* <tt>true</tt> – The session cache services all clients attached to the session. When you read objects from or write objects to the data source using a client session, EclipseLink saves a copy of the objects in the parent server session's cache and makes them accessible to all other processes in the session.
+
* <tt>false</tt> – The session cache services a single, isolated client exclusively. The isolated client can reference objects in a shared session cache but no client can reference objects in the isolated client's exclusive cache.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.cache.shared.Order" value="true"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CACHE_SHARED+".Order", "true");
+
| headers="r7c1-t21 r1c3-t21" align="left" |
+
<tt>eclipselink.cache.shared.default</tt>
+
|- align="left" valign="top"
+
| id="r7c1-t21" headers="r1c1-t21" align="left" |
+
<tt>eclipselink.flush-clear.cache</tt>
+
| headers="r7c1-t21 r1c2-t21" align="left" |
+
Defines the <tt>EntityManager</tt> cache behaviour after a call to the <tt>flush</tt> method followed by a call to the <tt>clear</tt> method. You can specify this property while creating either an <tt>EntityManagerFactory</tt> (either in the map passed to the <tt>createEntityManagerFactory</tt> method, or in the <tt>persistence.xml</tt> file), or an <tt>EntityManager</tt> (in the map passed to the <tt>createEntityManager</tt> method). Note that the latter overrides the former.
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.FlushClearCache</tt>:
+
* <tt>Drop</tt> – The call to the <tt>clear</tt> method results in a drop of the entire <tt>EntityManager</tt>’s cache. This mode is the fastest and uses the least memory. However, after commit the shared cache might potentially contain stale data.
+
* <tt>DropInvalidate</tt> – Even though the call to the <tt>clear</tt> method results in a drop of the entire <tt>EntityManager</tt>’s cache, classes that have at least one object updated or deleted are invalidated in the shared cache at commit time. This mode is slower than <tt>Drop</tt>, but as efficient memory usage-wise, and prevents stale data.
+
* <tt>Merge</tt> – The call to the <tt>clear</tt> method results in a drop from the <tt>EntityManager</tt>’s cache of objects that have not been flushed. This mode leaves the shared cache in a perfect state after commit. However, it is the least memory-efficient mode; the memory might even run out in a very large transaction.
+
* <tt>DEFAULT</tt> – The default is <tt>DropInvalidate</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.flush-clear.cache" value="Drop"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.FLUSH_CLEAR_CACHE, FlushClearCache.Drop);
+
| headers="r7c1-t21 r1c3-t21" align="left" |
+
<tt>FlushClearCache.DropInvalidate</tt>
+
 
+
|}
+
 
+
 
+
 
+
===How to Use the @TimeOfDay Annotation===
+
 
+
You can use the <tt>@TimeOfDay</tt> annotation to specify a time of day using a <tt>Calendar</tt> instance. By doing so, you configure cache expiry on an entity class.
+
+
@Target({})
+
@Retention(RUNTIME)
+
public @interface TimeOfDay { ... }
+
 
+
This table lists attributes of the <tt>@TimeOfDay</tt> annotation.
+
 
+
 
+
<span id="Table 19-14"></span>
+
''''' Attributes of the @TimeOfDay Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @TimeOfDay Annotation" summary="This table lists the attributes of EclipseLink JPA @TimeOfDay annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t22" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t22" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t22" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t22" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t22" headers="r1c1-t22" align="left" |
+
<tt>hour</tt>
+
| headers="r2c1-t22 r1c2-t22" align="left" |
+
Set this attribute to the <tt>int</tt> value representing an hour of the day.
+
| |
+
0
+
| headers="r2c1-t22 r1c4-t22" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r3c1-t22" headers="r1c1-t22" align="left" |
+
<tt>minute</tt>
+
| headers="r3c1-t22 r1c2-t22" align="left" |
+
Set this attribute to the <tt>int</tt> value representing a minute of the day.
+
| |
+
0
+
| headers="r3c1-t22 r1c4-t22" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r4c1-t22" headers="r1c1-t22" align="left" |
+
<tt>second</tt>
+
| headers="r4c1-t22 r1c2-t22" align="left" |
+
Set this attribute to the <tt>int</tt> value representing a second of the day.
+
| |
+
0
+
| headers="r4c1-t22 r1c4-t22" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r5c1-t22" headers="r1c1-t22" align="left" |
+
<tt>millisecond</tt>
+
| headers="r5c1-t22 r1c2-t22" align="left" |
+
Set this attribute to the <tt>int</tt> value representing a millisecond of the day.
+
| |
+
0
+
| headers="r5c1-t22 r1c4-t22" align="left" |
+
optional
+
|}
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Customization and Optimization==
+
 
+
EclipseLink defines one descriptor customizer annotation – <tt>@Customizer</tt> (see [[#How to Use the @Customizer Annotation|How to Use the @Customizer Annotation]]).
+
 
+
EclipseLink also provides a number of persistence unit properties that you can specify to configure EclipseLink customization and validation (see [[#How to Use the Persistence Unit Properties for Customization and Validation|How to Use the Persistence Unit Properties for Customization and Validation]]). These properties may compliment or provide an alternative to the usage of annotations.
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' Persistence unit properties always override the corresponding annotations' attributes.
+
 
+
For more information, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]]
+
|}
+
 
+
 
+
In addition, EclipseLink provides a persistence unit property that you can specify to optimize your application (see [[#How to Use the Persistence Unit Properties for Optimization|How to Use the Persistence Unit Properties for Optimization]]).
+
 
+
 
+
 
+
===How to Use the @Customizer Annotation===
+
 
+
Use the <tt>@Customizer</tt> annotation to specify a class that implements the <tt>org.eclipse.persistence.sessions.factories.DescriptorCustomizer</tt> interface and that is to be run against a class' descriptor after all metadata processing has been completed. See <tt>[[#eclipselink.descriptor.customizer.<ENTITY>|eclipselink.descriptor.customizer.<ENTITY>]]</tt> for more information.
+
 
+
@Target({TYPE})
+
@Retention(RUNTIME)
+
public @interface Customizer { ... }
+
 
+
You can define the <tt>@Customizer</tt> annotation on the following:
+
 
+
* <tt>@Entity</tt> (see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]);
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@MappedSuperclass|@MappedSuperclass]]</tt>
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Embeddable|@Embeddable]]</tt>
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' A <tt>@Customizer</tt> is not inherited from its parent classes.
+
|}
+
 
+
 
+
This table lists attributes of the <tt>@Customizer</tt> annotation.
+
 
+
 
+
<span id='Table 19-15'></span>
+
''''' Attributes of the @Customizer Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @Customizer Annotation" summary="This table lists the attributes of EclipseLink JPA @Customizer annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t25" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t25" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t25" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t25" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t25" headers="r1c1-t25" align="left" |
+
<tt>value</tt>
+
| headers="r2c1-t25 r1c2-t25" align="left" |
+
Set this attribute to the <tt>Class</tt> of the descriptor customizer that you want to apply to your entity's descriptor.
+
| headers="r2c1-t25 r1c3-t25" align="left" |
+
no default
+
| headers="r2c1-t25 r1c4-t25" align="left" |
+
required
+
|}
+
 
+
 
+
This example shows how to use the <tt>@Customizer</tt> annotation.
+
 
+
 
+
<span id="Example 19-13"></span>
+
''''' Usage of the @Customizer Annotation'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@Customizer(mypackage.MyCustomizer.class)
+
public class Employee implements Serializable {
+
    ...
+
}
+
 
+
 
+
 
+
===How to Use the Persistence Unit Properties for Customization and Validation===
+
 
+
This table lists the persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure EclipseLink customization and validation.
+
 
+
 
+
<span id="Table 19-16"></span>
+
''''' EclipseLink JPA Properties for Customization and Validation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for Customization and Validation" summary="This table lists EclipseLink JPA persistence.xml extensions for EclipseLink customization and validation." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t26" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t26" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t26" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.orm.throw.exceptions</tt>
+
| headers="r2c1-t26 r1c2-t26" align="left" |
+
Specify whether or not EclipseLink JPA should throw an exception or log a warning when it encounters a problem with any of the files listed in a <tt>persistence.xml</tt> file <tt><mapping-file></tt> element.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – throw exceptions.
+
* <tt>false</tt> – log warning only.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="oracle.orm.throw.exceptions" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.ECLIPSELINK_ORM_THROW_EXCEPTIONS, "false");
+
| headers="r2c1-t26 r1c3-t26" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r2c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.exception-handler</tt>
+
| headers="r2c1-t26 r1c2-t26" align="left" |
+
Specify an EclipseLink exception handler class: a Java class that implements the <tt>org.eclipse.persistence.exceptions.ExceptionHandler</tt> interface and provides a default (zero-argument) constructor. Use this class’ <tt>handleException</tt> method, which takes a <tt>java.lang.RuntimeException</tt>, to rethrow the exception, throw a different exception, or retry a query or a database operation.
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Exception Handlers|Exception Handlers]].
+
 
+
Valid values: class name of an <tt>ExceptionHandler</tt> class fully qualified by its package name.
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.exception-handler" value="my.package.MyExceptionHandler">
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.EXCEPTION_HANDLER_CLASS, "my.package.MyExceptionHandler");
+
| headers="r2c1-t26 r1c3-t26" align="left" |
+
<tt></tt>
+
|- align="left" valign="top"
+
| id="r3c1-t26" headers="r1c1-t26" align="left" |
+
<span id="eclipselink.weaving"></span>
+
<tt>eclipselink.weaving</tt>
+
| headers="r3c1-t26 r1c2-t26" align="left" |
+
Control whether or not the weaving of the entity classes is performed. The EclipseLink JPA persistence provider uses weaving to enhance JPA entities for such things as lazy loading, change tracking, fetch groups, and internal optimizations.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – weave entity classes dynamically.
+
* <tt>false</tt> – do not weave entity classes.
+
* <tt>static</tt> – weave entity classes statically.<br>
+
This assumes that classes have already been statically woven. Run the static weaver on the classes before deploying them.
+
 
+
For more information, see the following:
+
* [[#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]]
+
* [[#How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent|How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent]]
+
* [[#How to Configure Static Weaving for JPA Entities|How to Configure Static Weaving for JPA Entities]]
+
 
+
 
+
:'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.weaving" value="false"/>
+
 
+
:'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.WEAVING, "false");
+
| headers="r3c1-t26 r1c3-t26" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r4c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.weaving.lazy</tt>
+
| headers="r4c1-t26 r1c2-t26" align="left" |
+
Enable or disable the lazy one-to-one (see [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|@OneToOne]]) mapping through weaving.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable lazy one-to-one mapping through weaving.
+
* <tt>false</tt> – disable lazy one-to-one mapping through weaving.
+
 
+
'''Note''': you may set this option only if the <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> option is set to <tt>true</tt>. The purpose of the <tt>eclipselink.weaving.lazy</tt> option is to provide more granular control over weaving.
+
 
+
For more information, see the following:
+
* [[#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]]
+
* [[#What You May Need to Know About EclipseLink JPA Lazy Loading|What You May Need to Know About EclipseLink JPA Lazy Loading]]
+
 
+
 
+
:'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.weaving.lazy" value="false"/>
+
 
+
:'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.WEAVING_LAZY, "false");
+
| headers="r4c1-t26 r1c3-t26" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r5c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.weaving.changetracking</tt>
+
| headers="r5c1-t26 r1c2-t26" align="left" |
+
Enable or disable the <tt>AttributeLevelChangeTracking</tt> through weaving.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable the <tt>AttributeLevelChangeTracking</tt> through weaving. When enabled, only classes with all mappings allowing change tracking have change tracking enabled.
+
* <tt>false</tt> – disable the <tt>AttributeLevelChangeTracking</tt> through weaving. Use this setting if the following applies:
+
** you cannot weave at all;
+
** you do not want your classes to be changed during weaving (for example, for debugging purposes);
+
** you wish to disable this feature for configurations that do not support it (for example, you are mutating the <tt>java.util.Date</tt> or <tt>java.util.Calendar</tt>, you are using property access but modifying the underlying instance variables).
+
 
+
'''Note''': you may set this option only if the <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> option is set to <tt>true</tt>. The purpose of the <tt>eclipselink.weaving.changetracking</tt> option is to provide more granular control over weaving.
+
 
+
For more information, see the following:
+
* [[#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]]
+
* [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Change Policy|Configuring Change Policy]]
+
 
+
 
+
:'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.weaving.changetracking" value="false"/>
+
 
+
:'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.WEAVING_CHANGE_TRACKING, "false");
+
| headers="r5c1-t26 r1c3-t26" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r6c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.weaving.fetchgroups</tt>
+
| headers="r6c1-t26 r1c2-t26" align="left" |
+
Enable or disable fetch groups through weaving.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable the use of fetch groups through weaving.
+
* <tt>false</tt> – disable the use of fetch groups. Use this setting if the following applies:
+
** you cannot weave at all;
+
** you do not want your classes to be changed during weaving (for example, for debugging purposes);- you wish to disable this feature for configurations that do not support it.
+
 
+
'''Note''': you may set this option only if the <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> option is set to <tt>true</tt>. The purpose of the <tt>eclipselink.weaving.fetchgroups</tt> option is to provide more granular control over weaving.
+
 
+
For more information, see the following:
+
* [[#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]]
+
* [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Fetch Groups|Configuring Fetch Groups]]
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.weaving.fetchgroups" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.WEAVING_FETCHGROUPS, "false");
+
| headers="r6c1-t26 r1c3-t26" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r8c1-t26" headers="r1c1-t26" align="left" |
+
<span id="eclipselink.weaving.internal"></span>
+
<tt>eclipselink.weaving.internal</tt>
+
| headers="r8c1-t26 r1c2-t26" align="left" |
+
Enable or disable internal optimizations through weaving.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable internal optimizations through weaving.
+
* <tt>false</tt> – disable internal optimizations through weaving.
+
 
+
'''Note''': you may set this option only if the <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> option is set to <tt>true</tt>. The purpose of the <tt>eclipselink.weaving.internal</tt> option is to provide more granular control over weaving.
+
 
+
For more information, see [[#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]].
+
 
+
 
+
:'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.weaving.internal" value="false"/>
+
 
+
:'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.WEAVING_INTERNAL, "false");
+
| headers="r8c1-t26 r1c3-t26" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r8c1-t26" headers="r1c1-t26" align="left" |
+
<span id="eclipselink.eager"></span>
+
<tt>eclipselink.weaving.eager</tt>
+
| headers="r8c1-t26 r1c2-t26" align="left" |
+
Enable or disable indirection on eager relationships through weaving.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable indirection on eager relationships through weaving.
+
* <tt>false</tt> – disable indirection on eager relationships through weaving.
+
 
+
'''Note''': you may set this option only if the <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> option is set to <tt>true</tt>. The purpose of the <tt>eclipselink.weaving.eager</tt> option is to provide more granular control over weaving.
+
 
+
For more information, see the following:
+
* [[#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]]
+
* [[Introduction%20to%20Mappings%20(ELUG)#Value Holder Indirection|Value Holder Indirection]]
+
 
+
 
+
:'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.weaving.eager" value="true"/>
+
 
+
:'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.WEAVING_EAGER, "true");
+
| headers="r8c1-t26 r1c3-t26" align="left" |
+
<tt>false</tt>
+
 
+
|- align="left" valign="top"
+
| id="r7c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.session.customizer</tt>
+
| headers="r7c1-t26 r1c2-t26" align="left" |
+
Specify an EclipseLink session customizer class: a Java class that implements the <tt>org.eclipse.persistence.sessions.factories.SessionCustomizer</tt> interface and provides a default (zero-argument) constructor. Use this class' <tt>customize</tt> method, which takes an <tt>org.eclipse.persistence.sessions.Session</tt>, to programmatically access advanced EclipseLink session API.
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Customization|Session Customization]].
+
 
+
Valid values: class name of a <tt>SessionCustomizer</tt> class fully qualified by its package name.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.session.customizer" value="acme.sessions.MySessionCustomizer"/>
+
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.SESSION_CUSTOMIZER, "acme.sessions.MySessionCustomizer");
+
| headers="r7c1-t26 r1c3-t26" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r8c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.descriptor.customizer.<ENTITY></tt>
+
| headers="r8c1-t26 r1c2-t26" align="left" |
+
Specify an EclipseLink descriptor customizer class – a Java class that implements the <tt>org.eclipse.persistence.sessions.factories.DescriptorCustomizer</tt> interface and provides a default (zero-argument) constructor. Use this class's <tt>customize</tt> method, which takes an <tt>org.eclipse.persistence.descriptors.ClassDescriptor</tt>, to programmatically access advanced EclipseLink descriptor and mapping API for the descriptor associated with the JPA entity named <tt><ENTITY></tt>.
+
 
+
For more information on entity names, see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]
+
 
+
For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Descriptor Customization|Descriptor Customization]].
+
 
+
'''Note''': EclipseLink does not support multiple descriptor customizers.Valid values: class name of a <tt>DescriptorCustomizer</tt> class fully qualified by its package name.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.descriptor.customizer.Order" value="acme.sessions.MyDescriptorCustomizer"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.DESCRIPTOR_CUSTOMIZER+".Order", "acme.sessions.MyDescriptorCustomizer");
+
| headers="r8c1-t26 r1c3-t26" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r8c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.validation-only</tt>
+
| headers="r8c1-t26 r1c2-t26" align="left" |
+
Specify whether or not deployment should be for validation only.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – deployment is only for validation; the EclipseLink session will not log in.
+
* <tt>false</tt> – normal deployment; the EclipseLink session will log in.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.validation-only" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.ECLIPSELINK_VALIDATION_ONLY_PROPERTY, "false");
+
| headers="r8c1-t26 r1c3-t26" align="left" |
+
<tt>true</tt><br>
+
|- align="left" valign="top"
+
| id="r8c1-t26" headers="r1c1-t26" align="left" |
+
<tt>eclipselink.classloader</tt>
+
| headers="r8c1-t26 r1c2-t26" align="left" |
+
Specify the class loader to use for creation of an <tt>EntityManagerFactory</tt> in the property map passed to the <tt>createEntityManagerFactory</tt> method.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.classloader" value="MyClassloader"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CLASSLOADER, "MyClassloader");
+
| headers="r8c1-t26 r1c3-t26" align="left" |
+
|}
+
 
+
<br>
+
 
+
For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]]
+
 
+
For more information about persistence unit properties, see [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
 
+
 
+
===How to Use the Persistence Unit Properties for Optimization===
+
 
+
This table lists the persistence unit properties that you can define in a <tt>persistence.xml</tt> file to optimize your EclipseLink application.
+
 
+
 
+
<span id="Table 19-17"></span>
+
''''' EclipseLink JPA Persistence Unit Properties for Optimization'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for Optimization" summary="This table lists properties for optimization." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t27" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t27" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t27" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t27" headers="r1c1-t27" align="left" |
+
<tt>eclipselink.profiler</tt>
+
| headers="r2c1-t27 r1c2-t27" align="left" |
+
The type of the performance profiler.
+
 
+
For more information on performance profilers, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|Optimizing the EclipseLink Application]].
+
 
+
The following are the valid values for the use in a <tt>persistence.xml</tt> file and for the  <tt>org.eclipse.persistence.config.ProfilerType</tt><nowiki>:</nowiki>
+
* <tt>DMSPerformanceProfiler</tt> – Use the DMS performance profiler (<tt>org.eclipse.persistence.tools.profiler.DMSPerformanceProfiler</tt> class).
+
* <tt>PerformanceProfiler</tt> – Use EclipseLink performance profiler (<tt>org.eclipse.persistence.tools.profiler.PerformanceProfiler</tt> class). For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Measuring EclipseLink Performance with the EclipseLink Profiler|Measuring EclipseLink Performance with the EclipseLink Profiler]].
+
* <tt>QueryMonitor</tt> – Monitor query executions and cache hits (<tt>org.eclipse.persistence.tools.profiler.QueryMonitor</tt> class).This option provides a simple low-overhead means for measuring performance of query executions and cache hits. You may want to use this option for performance analysis in a complex system. Enable this monitor by setting the <tt>org.eclipse.persistence.querymonitor</tt> system property to <tt>true</tt>.
+
* <tt>NoProfiler</tt> – Do not use a performance profiler.
+
* Custom profiler – Use your own custom profiler class. Create it by implementing the <tt>org.eclipse.persistence.sessions.SessionProfiler</tt> interface and providing a no-argument constructor.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.profiler" value="PerformanceProfiler"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
 
+
import org.eclipse.persistence.config.ProfilerType;
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.PROFILER, ProfilerType.PerformanceProfiler);
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.profiler" value="mypackage.com.MyProfiler"/>
+
 
+
'''Note''': Ensure that <tt>MyProfiler</tt> is in your classpath.
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.ProfilerType;
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.PROFILER, "mypackage.com.MyProfiler");
+
| headers="r2c1-t27 r1c3-t27" align="left" |
+
<tt>NoProfiler</tt>
+
|}
+
 
+
 
+
For information about optimization, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|Optimizing the EclipseLink Application]]
+
 
+
For more information about persistence unit properties, see [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Declaration of Read-Only Classes==
+
 
+
EclipseLink defines one annotation that you can use to declare classes as read-only – <tt>[[#How to Use the @ReadOnly Annotation|@ReadOnly]]</tt>.
+
 
+
For more information, see the following:
+
* [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Read-Only Descriptors|Configuring Read-Only Descriptors]]
+
* [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Declaring Read-Only Classes|Declaring Read-Only Classes]]
+
 
+
 
+
 
+
===How to Use the @ReadOnly Annotation===
+
 
+
Use the <tt>@ReadOnly</tt> annotation to specify that a class is read-only (see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Declaring Read-Only Classes|Declaring Read-Only Classes]]).
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' Any changes made within a managed instance in a transaction or to a detached instance and merged will have no effect in the context of a read-only entity class.
+
|}
+
 
+
+
@Target({TYPE})
+
@Retention(RUNTIME)
+
public @interface ReadOnly { ... }
+
+
 
+
You can define the <tt>@ReadOnly</tt> annotation on the following:
+
 
+
* <tt>@Entity</tt> (see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]);
+
* <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@MappedSuperclass|@MappedSuperclass]]</tt>;
+
* the root of the inheritance hierarchy (if applicable).
+
 
+
The <tt>@ReadOnly</tt> annotation does not have attributes.
+
 
+
This example shows how to use the <tt>@ReadOnly</tt> annotation.
+
 
+
 
+
<span id="Example 19-14"></span>
+
''''' Usage of the @ReadOnly Annotation'''''
+
@Entity
+
@ReadOnly
+
public class Employee implements Serializable {
+
    ...
+
}
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Transformation==
+
 
+
EclipseLink defines the following transformation annotations:
+
 
+
* <tt>[[#How to Use the @ReadTransformer Annotation|@ReadTransformer]]</tt>
+
* <tt>[[#How to Use the @WriteTransformer Annotation|@WriteTransformer]]</tt>
+
* <tt>[[#How to Use the @WriteTransformers Annotation|@WriteTransformers]]</tt>
+
 
+
Use these annotations with the <tt>[[#How to Use the @Transformation Annotation|@Transformation]]</tt> mapping to define transformation of one or more database column values into an attribute value, and vice versa.
+
 
+
 
+
 
+
===How to Use the @ReadTransformer Annotation===
+
 
+
Using the <tt>@ReadTransformer</tt> annotation, you can define transformation of one or more database column values into an attribute value. Note that you can only use this annotation if the <tt>[[#How to Use the @Transformation Annotation|@Transformation]]</tt> mapping is not write-only.
+
 
+
@Target(value={METHOD,FIELD})
+
@Retention(value=RUNTIME)
+
public @interface ReadTransformer
+
 
+
This table lists attributes of the <tt>@ReadTransformer</tt> annotation.
+
 
+
 
+
<span id='Table 19-211'></span>
+
''''' Attributes of the @ReadTransformer Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @ReadTransformer Annotation" summary="This table lists the attributes of EclipseLink JPA @ReadTransformer annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t34" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t34" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t34" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t34" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t34" headers="r1c1-t34" align="left" |
+
<tt>method</tt>
+
| headers="r2c1-t34 r1c2-t34" align="left" |
+
Set this attribute to the String method name that the mapped class must have. This method does not assign a value to the attribute; instead, it returns the value to be assigned to the attribute.
+
| headers="r2c1-t34 r1c3-t34" align="left" |
+
empty <tt>String</tt>
+
| headers="r2c1-t34 r1c4-t34" align="left" |
+
required/optional<sup>1</sup>
+
|- align="left" valign="top"
+
| id="r2c1-t34" headers="r1c1-t34" align="left" |
+
<tt>transformerClass</tt>
+
| headers="r2c1-t34 r1c2-t34" align="left" |
+
Set this attribute to the <tt>Class</tt> that implements the <tt>org.eclipse.persistence.mappings.transformers.AttributeTransformer</tt> interface. This will instantiate the class and use its <tt>buildAttributeValue</tt> method to create the value to be assigned to the attribute.
+
 
+
For more information, see see [[Configuring%20a%20Mapping%20(ELUG)#How to Configure Attribute Transformer Using Java|How to Configure Attribute Transformer Using Java]].
+
| headers="r2c1-t34 r1c3-t34" align="left" |
+
<tt>void.class</tt>
+
| headers="r2c1-t34 r1c4-t34" align="left" |
+
required/optional<sup>1</sup>
+
|}
+
<br><sup> 1 </sup>You must specify either the <tt>transformerClass</tt> or <tt>method</tt>, but not both<br>
+
 
+
 
+
 
+
===How to Use the @WriteTransformer Annotation===
+
 
+
Using the <tt>@WriteTransformer</tt> annotation, you can define transformation of an attribute value to a single database column value. Note that you can only use this annotation if the <tt>[[#How to Use the @Transformation Annotation|@Transformation]]</tt> mapping is not read-only.
+
 
+
@Target(value={METHOD,FIELD})
+
@Retention(value=RUNTIME)
+
public @interface WriteTransformer
+
 
+
This table lists attributes of the <tt>@WriteTransformer</tt> annotation.
+
 
+
 
+
<span id='Table 19-212'></span>
+
''''' Attributes of the @WriteTransformer Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @WriteTransformer Annotation" summary="This table lists the attributes of EclipseLink JPA @WriteTransformer annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t34" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t34" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t34" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t34" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t34" headers="r1c1-t34" align="left" |
+
<tt>method</tt>
+
| headers="r2c1-t34 r1c2-t34" align="left" |
+
Set this attribute to the <tt>String</tt> method name that the mapped class must have. This method returns the value to be written into the database column.
+
 
+
Note: for proper support of [[#Using EclipseLink JPA Extensions for Schema Generation|DDL generation]] and [[#Using EclipseLink JPA Extensions for Returning Policy|returning policy]], define the method to return not just an <tt>Object</tt>, but a particular type, as the following example shows:
+
public Time getStartTime()
+
The method may require a <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Transient|@Transient]]</tt> annotation to avoid being mapped as the <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|@Basic]]</tt> by default.
+
| headers="r2c1-t34 r1c3-t34" align="left" |
+
empty <tt>String</tt>
+
| headers="r2c1-t34 r1c4-t34" align="left" |
+
required/optional <sup> 1 </sup>
+
|- align="left" valign="top"
+
| id="r2c1-t34" headers="r1c1-t34" align="left" |
+
<tt>transformerClass</tt>
+
| headers="r2c1-t34 r1c2-t34" align="left" |
+
Set this attribute to the <tt>Class</tt> that implements the <tt>org.eclipse.persistence.mappings.transformers.FieldTransformer</tt> interface. This will instantiate the class and use its <tt>buildFieldValue</tt> method to create the value to be written into the database column.
+
 
+
For more information, see see [[Configuring%20a%20Mapping%20(ELUG)#How to Configure Field Transformer Associations Using Java|How to Configure Field Transformer Associations]].
+
 
+
Note: for proper support of [[#Using EclipseLink JPA Extensions for Schema Generation|DDL generation]] and [[#Using EclipseLink JPA Extensions for Returning Policy|returning policy]], define the method to return not just an <tt>Object</tt>, but a relevant Java type, as the following example shows:
+
public Time buildFieldValue(Object instance, String fieldName, Session session)
+
| headers="r2c1-t34 r1c3-t34" align="left" |
+
<tt>void.class</tt>
+
| headers="r2c1-t34 r1c4-t34" align="left" |
+
required/optional <sup> 1 </sup>
+
|- align="left" valign="top"
+
| id="r2c1-t34" headers="r1c1-t34" align="left" |
+
<tt>column</tt>
+
| headers="r2c1-t34 r1c2-t34" align="left" |
+
Set this attribute to a <tt>Column</tt> into which the value should be written.
+
 
+
You may choose not to set this attribute if a single <tt>WriteTransformer</tt> annotates an attribute. In this case, the attribute's name will be used as a column name.
+
| headers="r2c1-t34 r1c3-t34" align="left" |
+
<tt>@javax.persistence.Column</tt> (see Section 9.1.5 "Column Annotation" of the JPA specification)
+
| headers="r2c1-t34 r1c4-t34" align="left" |
+
required
+
|}
+
<br><sup> 1 </sup>You must specify either the <tt>transformerClass</tt> or <tt>method</tt>, but not both.<br>
+
 
+
 
+
 
+
===How to Use the @WriteTransformers Annotation===
+
 
+
Use the <tt>@WriteTransformers</tt> annotation to wrap multiple <tt>[[#How to Use the @WriteTransformers Annotation|write transformers]]</tt>. Note that you can only use this annotation if the <tt>[[#How to Use the @Transformation Annotation|@Transformation]]</tt> mapping is not read-only.
+
 
+
@Target(value={METHOD,FIELD})
+
@Retention(value=RUNTIME)
+
public @interface WriteTransformers
+
 
+
This table lists attributes of the <tt>@WriteTransformers</tt> annotation.
+
 
+
 
+
<span id='Table 19-213'></span>
+
''''' Attributes of the @WriteTransformers Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @WriteTransformers Annotation" summary="This table lists the attributes of EclipseLink JPA @WriteTransformers annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t34" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t34" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t34" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t34" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t34" headers="r1c1-t34" align="left" |
+
<tt>value</tt>
+
| headers="r2c1-t34 r1c2-t34" align="left" |
+
Set this attribute to the array of <tt>[[#How to Use the @WriteTransformer Annotation|WriteTransformer]]</tt>.
+
| headers="r2c1-t34 r1c3-t34" align="left" |
+
no default
+
| headers="r2c1-t34 r1c4-t34" align="left" |
+
optional
+
|}
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Returning Policy==
+
 
+
The returning policy enables <tt>INSERT</tt> or <tt>UPDATE</tt> operations to return values back into the object being written. These values include table default values, trigger or stored procedures computed values. For more information, see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Returning Policy|Configuring Returning Policy]].
+
 
+
EclipseLink defines the following returning policy annotations:
+
* <tt>[[#How to Use the @ReturnInsert Annotation|@ReturnInsert]]</tt>
+
* <tt>[[#How to Use the @ReturnUpdate Annotation|@ReturnUpdate]]</tt>
+
 
+
 
+
 
+
===How to Use the @ReturnInsert Annotation===
+
 
+
You can only specify the <tt>@ReturnInsert</tt> for a <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|@Basic]]</tt> mapping.
+
 
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface ReturnInsert { ... }
+
 
+
This table lists attributes of the <tt>@ReturnInsert</tt> annotation.
+
 
+
 
+
<span id="Table 19-18"></span>
+
''''' Attributes of the @ReturnInsert Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @ReturnInsert Annotation" summary="This table lists the attributes of EclipseLink JPA @ReturnInsert annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t29" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t29" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t29" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t29" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t29" headers="r1c1-t29" align="left" |
+
<tt>returnOnly</tt>
+
| headers="r2c1-t29 r1c2-t29" align="left" |
+
Set this attribute to the <tt>boolean</tt> value of <tt>true</tt> if you want a return of a value for this field, without including the field in the insert.
+
| headers="r2c1-t29 r1c3-t29" align="left" |
+
<tt>false</tt>
+
| headers="r2c1-t29 r1c4-t29" align="left" |
+
optional
+
|}
+
 
+
 
+
The [[#Example 19-15|Usage of the @ReturnInsert Annotation Without Arguments]] example shows how to use the <tt>@ReturnInsert</tt> annotation without specifying the value for the <tt>returnOnly</tt> argument, therefore accepting the default value of <tt>false</tt>. The [[#Example 19-16|Usage of the @ReturnInsert Annotation with Arguments]] example shows how to set the value of the <tt>returnOnly</tt> argument to <tt>true</tt>.
+
 
+
<span id="Example 19-15"></span>
+
''''' Usage of the @ReturnInsert Annotation Without Arguments'''''
+
@ReturnInsert
+
public String getFirstName() {
+
    return firstName;
+
}
+
 
+
 
+
<span id="Example 19-16"></span>
+
''''' Usage of the @ReturnInsert Annotation with Arguments'''''
+
@ReturnInsert(returnOnly=true)
+
public String getFirstName() {
+
    return firstName;
+
}
+
 
+
 
+
 
+
===How to Use the @ReturnUpdate Annotation===
+
 
+
You can only specify the <tt>@ReturnUpdate</tt> for a <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|@Basic]]</tt> mapping.
+
+
@Target({METHOD, FIELD})
+
@Retention(RUNTIME)
+
public @interface ReturnUpdate { ... }
+
 
+
The <tt>@ReturnUpdate</tt> annotation does not have attributes.
+
 
+
This example shows how to use the <tt>@ReturnUpdate</tt> annotation.
+
 
+
 
+
<span id="Example 19-17"></span>
+
''''' Usage of the @ReturnUpdate Annotation'''''
+
@ReturnUpdate
+
public String getFirstName() {
+
    return firstName;
+
}
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Optimistic Locking==
+
 
+
EclipseLink defines one annotation for optimistic locking – <tt>[[#How to Use the @OptimisticLocking Annotation|@OptimisticLocking]]</tt>.
+
 
+
For more information, see the following:
+
 
+
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Optimistic Locking|Optimistic Locking]]
+
* [[Configuring%20a%20Descriptor%20(ELUG)#Configuring an Optimistic Locking Policy|Configuring an Optimistic Locking Policy]]
+
 
+
 
+
 
+
===How to Use the @OptimisticLocking Annotation===
+
 
+
You can use the <tt>@OptimisticLocking</tt> annotation to specify the type of optimistic locking that EclipseLink should use when updating or deleting entities.
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' EclipseLink supports additional optimistic locking policies beyond what is supported through the JPA specification (such as <tt>@Version</tt> - see Section 9.1.17 "Version Annotation" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]). When mapping to a database schema where a version column does not exist and cannot be added, these locking policies enable the concurrency protection.
+
|}
+
 
+
+
@Target({TYPE})
+
@Retention(RUNTIME)
+
public @interface OptimisticLocking { ... }
+
+
This table lists attributes of the <tt>@OptimisticLocking</tt> annotation.
+
 
+
 
+
<span id="Table 19-19"></span>
+
''''' Attributes of the @OptimisticLocking Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @OptimisticLocking Annotation" summary="This table lists the attributes of EclipseLink JPA @OptimisticLocking annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t31" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t31" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t31" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t31" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t31" headers="r1c1-t31" align="left" |
+
<tt>type</tt>
+
| headers="r2c1-t31 r1c2-t31" align="left" |
+
Set this attribute to the type (<tt>org.eclipse.persistence.annotations.OptimisticLockingType</tt> enumerated type) of the optimistic locking policy that you will be using.
+
 
+
The following are the valid values for the <tt>OptimisticLockingType</tt><nowiki>:</nowiki>
+
* <tt>ALL_COLUMNS</tt> – Use this type of locking policy to compare every field in the table in the <tt>WHERE</tt> clause during an update or a delete operation. If any field has been changed, EclipseLink will throw an optimistic locking exception.
+
* <tt>CHANGED_COLUMNS</tt> – Use this type of locking policy to compare changed fields in the table in the <tt>WHERE</tt> clause during an update operation. If any field has been changed, EclipseLink will throw an optimistic locking exception.<br><br>Note: performing the same during a delete operation will only compare primary keys.
+
* <tt>SELECTED_COLUMNS</tt> – Use this type of locking policy to compare selected fields in the table in the <tt>WHERE</tt> clause during an update or a delete operation. If any field has been changed, EclipseLink will throw an optimistic locking exception.<br><br>Note: specified fields must be mapped and must not be primary keys.<br><br>Note: EclipseLink will throw an exception if you set the <tt>SELECTED_COLUMNS</tt> type, but fail to specify the <tt>selectedColumns</tt>. You must also specify the <tt>name</tt> attribute of the <tt>Column</tt>.
+
* <tt>VERSION_COLUMN</tt> – Use this type of locking policy to compare a single version number in the <tt>WHERE</tt> clause during an update operation.<br><br>Note: the version field must be mapped and must not be the primary key.<br><br>Note: this functionality is equivalent to the functionality of the <tt>@Version</tt> annotation (see Section 9.1.17 "Version Annotation" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]) in JPA. If you use this option, you must also provide the <tt>@Version</tt> annotation on the version field or property.<br>For more information, see [[#What You May Need to Know About Version Fields|What You May Need to Know About Version Fields]].
+
| headers="r2c1-t31 r1c3-t31" align="left" |
+
<tt>OptimisticLockingType.VERSION_COLUMN</tt>
+
| headers="r2c1-t31 r1c4-t31" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r3c1-t31" headers="r1c1-t31" align="left" |
+
<tt>selectedColumns</tt>
+
| headers="r3c1-t31 r1c2-t31" align="left" |
+
Set this attribute to an array of <tt>javax.persistence.Column</tt> instances.
+
 
+
For an optimistic locking policy of type [[#SELECTED_COLUMNS|SELECTED_COLUMNS]], this annotation member becomes a required field.
+
 
+
Note: EclipseLink will throw an exception if you set the [[#SELECTED_COLUMNS|SELECTED_COLUMNS]] type, but fail to specify the <tt>selectedColumns</tt>. You must also specify the <tt>name</tt> attribute of the <tt>Column</tt>.
+
| headers="r3c1-t31 r1c3-t31" align="left" |
+
empty <tt>Column</tt> array
+
| headers="r3c1-t31 r1c4-t31" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r4c1-t31" headers="r1c1-t31" align="left" |
+
<tt>cascade</tt>
+
| headers="r4c1-t31 r1c2-t31" align="left" |
+
Set the value of this attribute to a <tt>boolean</tt> value of <tt>true</tt> to specify that the optimistic locking policy should cascade the lock.
+
 
+
By enabling cascading you configure EclipseLink to automatically force a version field update on a parent object when its privately owned child object's version field changes.
+
 
+
Note: In the current release, only supported with [[#VERSION_COLUMN|VERSION_COLUMN]] locking.
+
 
+
For more information, see the following:
+
* [[Introduction%20to%20Descriptors%20(ELUG)#Optimistic Version Locking Policies and Cascading|Optimistic Version Locking Policies and Cascading]]
+
* [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Optimistic Locking Policy Cascading|Configuring Optimistic Locking Policy Cascading]]
+
| headers="r4c1-t31 r1c3-t31" align="left" |
+
<tt>false</tt>
+
| headers="r4c1-t31 r1c4-t31" align="left" |
+
optional
+
|}
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' Setting an <tt>@OptimisticLocking</tt> may override any <tt>@Version</tt> specification (see Section 9.1.17 "Version Annotation" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]) on the entity: EclipseLink will not throw an exception, but will log a warning.
+
 
+
You can specify <tt>@Version</tt> without any <tt>@OptimisticLocking</tt> specification to define a version locking policy (<tt>org.eclipse.persistence.descriptors.VersionLockingPolicy</tt>) on the source entity.
+
|}
+
 
+
 
+
This example shows how to use the <tt>@OptimisticLocking</tt> annotation with the <tt>ALL_COLUMNS</tt> type.
+
 
+
<span id="Example 19-18"></span>
+
''''' Usage of the @OptimisticLocking Annotation - ALL_COLUMNS'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@OptimisticLocking(type=OptimisticLockingType.ALL_COLUMNS)
+
public class Employee implements Serializable{
+
+
    private Integer id;
+
    private String firstName;
+
    private String lastName;
+
    ...
+
}
+
 
+
 
+
The following example shows how to use the <tt>@OptimisticLocking</tt> annotation with the <tt>CHANGED_COLUMNS</tt> type.
+
 
+
<span id="Example 19-19"></span>
+
''''' Usage of the @OptimisticLocking Annotation - CHANGED_COLUMNS'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@OptimisticLocking(type=OptimisticLockingType.CHANGED_COLUMNS)
+
public class Employee implements Serializable{
+
+
    private Integer id;
+
    private String firstName;
+
    private String lastName;
+
    ...
+
}
+
 
+
 
+
The following example shows how to use the <tt>@OptimisticLocking</tt> annotation with the <tt>SELECTED_COLUMNS</tt> type.
+
 
+
<span id="Example 19-20"></span>
+
''''' Usage of the @OptimisticLocking Annotation - SELECTED_COLUMNS'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@OptimisticLocking(
+
    type=OptimisticLockingType.SELECTED_COLUMNS,
+
    selectedColumns={@Column(name="id"), @Column(name="lastName")}
+
)
+
public class Employee implements Serializable{
+
+
    @Id
+
    private Integer id;
+
    private String lastName;
+
    private String lastName;
+
    ...
+
}
+
 
+
 
+
The following example shows how to use the <tt>@OptimisticLocking</tt> annotation with the <tt>VERSION_COLUMN</tt> type.
+
 
+
<span id="Example 19-21"></span>
+
''''' Usage of the @OptimisticLocking Annotation - VERSION_COLUMN'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@OptimisticLocking(type=OptimisticLockingType.VERSION_COLUMN, cascade=true)
+
public class Employee implements Serializable{
+
+
    private String firstName;
+
    private String lastName;
+
    @Version private int version;
+
    ...
+
}
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Stored Procedure Query==
+
 
+
EclipseLink defines the following stored procedure query annotations:
+
 
+
* <tt>[[#How to Use the @NamedStoredProcedureQuery Annotation|@NamedStoredProcedureQuery]]</tt>;
+
* <tt>[[#How to Use the @NamedStoredProcedureQueries Annotation|@NamedStoredProcedureQueries]]</tt>.
+
 
+
You can execute a stored procedure query like any other named query (see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)|Named Queries]]). For more information, see [[EclipseLink/UserGuide/Queries (ELUG)|Queries]].
+
 
+
 
+
 
+
===How to Use the @NamedStoredProcedureQuery Annotation===
+
 
+
Use the <tt>@NamedStoredProcedureQuery</tt> to define queries that call stored procedures as named queries.
+
 
+
@Target({TYPE})
+
@Retention(RUNTIME)
+
public @interface NamedStoredProcedureQuery { ... }
+
 
+
This table lists attributes of the <tt>@NamedStoredProcedureQuery</tt> annotation.
+
 
+
 
+
<span id="Table 19-20"></span>
+
''''' Attributes of the @NamedStoredProcedureQuery Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @NamedStoredProcedureQuery Annotation" summary="This table lists the attributes of EclipseLink JPA @NamedStoredProcedureQuery annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t33" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t33" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t33" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t33" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t33" headers="r1c1-t33" align="left" |
+
<tt>name</tt>
+
| headers="r2c1-t33 r1c2-t33" align="left" |
+
Set this attribute to the unique <tt>String</tt> name that references this stored procedure query.
+
| headers="r2c1-t33 r1c3-t33" align="left" |
+
no default
+
| headers="r2c1-t33 r1c4-t33" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r3c1-t33" headers="r1c1-t33" align="left" |
+
<tt>hints</tt>
+
| headers="r3c1-t33 r1c2-t33" align="left" |
+
Set this attribute to an array of <tt>javax.persistence.QueryHint</tt> instances.
+
| headers="r3c1-t33 r1c3-t33" align="left" |
+
empty <tt>QueryHint</tt> array
+
| headers="r3c1-t33 r1c4-t33" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r4c1-t33" headers="r1c1-t33" align="left" |
+
<tt>resultClass</tt>
+
| headers="r4c1-t33 r1c2-t33" align="left" |
+
Set this attribute to the <tt>Class</tt> of the query result.
+
| headers="r4c1-t33 r1c3-t33" align="left" |
+
<tt>void.class</tt>
+
| headers="r4c1-t33 r1c4-t33" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r5c1-t33" headers="r1c1-t33" align="left" |
+
<tt>resultSetMapping</tt>
+
| headers="r5c1-t33 r1c2-t33" align="left" |
+
Set this attribute to the <tt>String</tt> name of the <tt>javax.persistence.SQLResultSetMapping</tt> instance.
+
| headers="r5c1-t33 r1c3-t33" align="left" |
+
empty <tt>String</tt>
+
| headers="r5c1-t33 r1c4-t33" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r6c1-t33" headers="r1c1-t33" align="left" |
+
<tt>procedureName</tt>
+
| headers="r6c1-t33 r1c2-t33" align="left" |
+
Set this attribute to the <tt>String</tt> name of the stored procedure.
+
| headers="r6c1-t33 r1c3-t33" align="left" |
+
no default
+
| headers="r6c1-t33 r1c4-t33" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r7c1-t33" headers="r1c1-t33" align="left" |
+
<tt>returnsResultSet</tt>
+
| headers="r7c1-t33 r1c2-t33" align="left" |
+
Set this attribute to the <tt>boolean</tt> value of <tt>false</tt> to disable the return of the result set.
+
| headers="r7c1-t33 r1c3-t33" align="left" |
+
<tt>true</tt>
+
| headers="r7c1-t33 r1c4-t33" align="left" |
+
optional
+
|- align="left" valign="top"
+
| id="r8c1-t33" headers="r1c1-t33" align="left" |
+
<tt>parameters</tt>
+
| headers="r8c1-t33 r1c2-t33" align="left" |
+
Set the value of this attribute to an array of <tt>StoredProcedureParameter</tt> instances to define arguments to the stored procedure.
+
 
+
The following are attributes of the <tt>StoredProcedureParameter</tt><nowiki>:</nowiki>
+
* <tt>direction</tt> – Set the value of this attribute to define the direction (<tt>org.eclipse.persistence.annotations.Direction</tt> enumerated type) of the stored procedure parameter.<br>The default value is an empty <tt>Direction.IN</tt>.<br><br>The following are valid values for <tt>Direction.IN</tt><nowiki>:</nowiki>
+
** <tt>IN</tt> – Input parameter
+
** <tt>OUT</tt> – Output parameter
+
** <tt>IN_OUT</tt> – Input and output parameter
+
** <tt>OUT_CURSOR</tt> – Output cursor<br>You are not required to set the value of this attribute.<br><br>Note: EclipseLink will throw an exception if you set more than one parameter to the <tt>OUT_CURSOR</tt> type.
+
* <tt>name</tt> – Set this attribute to the <tt>String</tt> name of the stored procedure parameter.<br>The default value is an empty <tt>String</tt>.<br>You are not required to set the value of this attribute.
+
* <tt>queryParameter</tt> – Set this attribute to the <tt>String</tt> name of the query parameter.You are required to set the value of this attribute.
+
* <tt>type</tt> – Set this attribute to the type of Java <tt>Class</tt> that you want to receive back from the procedure. This depends on the type returned from the procedure.<br>The default value is <tt>void.class</tt>.<br>You are not required to set the value of this attribute.
+
* <tt>jdbcType</tt> – Set this attribute to the <tt>int</tt> value of JDBC type code. This depends on the type returned from the procedure.<br>The default value is -1.<br>You are not required to set the value of this attribute.
+
* <tt>jdbcTypeName</tt> – Set this attribute to the <tt>String</tt> value of the JDBC type name.<br>The default value is an empty <tt>String</tt>.<br>You are not required to set the value of this attribute.<br><br>Note: setting of this attribute may be required for <tt>ARRAY</tt> or <tt>STRUCT</tt> types.
+
 
+
For more information, see the following:
+
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#StoredProcedureCall|StoredProcedureCall]]
+
* [[Using%20Basic%20Query%20API%20(ELUG)#|Using a StoredProcedureCall]]
+
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Call Queries|Call Queries]]
+
| headers="r8c1-t33 r1c3-t33" align="left" |
+
empty <tt>StoredProcedureParameter</tt> array
+
| headers="r8c1-t33 r1c4-t33" align="left" |
+
optional
+
|}
+
 
+
 
+
This example shows how to use the <tt>@NamedStoredProcedureQuery</tt> annotation.
+
 
+
<span id="Example 19-22"></span>
+
''''' Usage of the @NamedStoredProcedureQuery Annotation'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@NamedStoredProcedureQuery(
+
    name="ReadEmployee",
+
    procedureName="Read_Employee",
+
    parameters={
+
        @StoredProcedureParameter(queryParamater="EMP_ID")}
+
)
+
public class Employee implements Serializable{
+
    ...
+
}
+
 
+
===How to Use the @NamedStoredProcedureQueries Annotation===
+
 
+
Use the <tt>@NamedStoredProcedureQueries</tt> to define queries that call stored procedures as named queries.
+
+
@Target({TYPE})
+
@Retention(RUNTIME)
+
public @interface NamedStoredProcedureQueries { ... }
+
 
+
This table lists attributes of the <tt>@NamedStoredProcedureQueries</tt> annotation.
+
 
+
 
+
<span id='Table 19-21'></span>
+
''''' Attributes of the @NamedStoredProcedureQueries Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @NamedStoredProcedureQueries Annotation" summary="This table lists the attributes of EclipseLink JPA @NamedStoredProcedureQuery annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t34" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t34" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t34" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t34" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t34" headers="r1c1-t34" align="left" |
+
<tt>value</tt>
+
| headers="r2c1-t34 r1c2-t34" align="left" |
+
Set this attribute to the array of the <tt>[[#How to Use the @NamedStoredProcedureQuery Annotation|@NamedStoredProcedureQuery]]</tt> annotations.
+
| headers="r2c1-t34 r1c3-t34" align="left" |
+
no default
+
| headers="r2c1-t34 r1c4-t34" align="left" |
+
required
+
|}
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for JDBC==
+
 
+
EclipseLink JPA provides persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure how EclipseLink will use the connections returned from the data source used. These properties are divided into the two following categories:
+
 
+
* Options that you can use to configure how EclipseLink communicates with the JDBC connection (see [[#How to Use EclipseLink JPA Extensions for JDBC Connection Communication|How to Use EclipseLink JPA Extensions for JDBC Connection Communication]]).
+
* Options that you can use to configure EclipseLink own connection pooling (see [[#How to Use EclipseLink JPA Extensions for JDBC Connection Pooling|How to Use EclipseLink JPA Extensions for JDBC Connection Pooling]]).
+
 
+
 
+
 
+
===How to Use EclipseLink JPA Extensions for JDBC Connection Communication===
+
 
+
This table  lists the EclipseLink JPA persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure how EclipseLink communicates with the JDBC connection.
+
 
+
 
+
<span id="Table 19-22"></span>
+
''''' EclipseLink JPA Persistence Unit Properties for JDBC Connection Communication'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for JDBC Connection Communication" summary="This table lists EclipseLink JPA persistence.xml extensions for EclipseLink JDBC (JSE)" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t35" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t35" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t35" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.bind-parameters</tt>
+
| headers="r2c1-t35 r1c2-t35" align="left" |
+
Control whether or not the query uses parameter binding.<sup>1</sup>
+
 
+
For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization]].
+
 
+
The following are the valid values:
+
* <tt>true</tt> – bind all parameters.
+
* <tt>false</tt> – do not bind parameters.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.bind-parameters" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_BIND_PARAMETERS, "false");
+
| headers="r2c1-t35 r1c3-t35" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r3c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.native-sql</tt>
+
| headers="r3c1-t35 r1c2-t35" align="left" |
+
Enable or disable EclipseLink's generation of database platform-specific SQL (as opposed to generic SQL).<sup>2</sup>
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable EclipseLink's generation of database platform-specific SQL.
+
* <tt>false</tt> – disable generation of database platform-specific SQL by EclipseLink.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.native-sql" value="true"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.NATIVE_SQL, "true");
+
| headers="r3c1-t35 r1c3-t35" align="left" |
+
<tt>false</tt>
+
|- align="left" valign="top"
+
| id="r4c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.batch-writing</tt>
+
| headers="r4c1-t35 r1c2-t35" align="left" |
+
Specify the use of batch writing to optimize transactions with multiple write operations<sup>2</sup>.
+
 
+
Set the value of this property into the session at deployment time.
+
 
+
The following are the valid values for org.eclipse.persistence.config.BatchWriting:
+
* <tt>JDBC</tt> – use JDBC batch writing.
+
* <tt>Buffered</tt> – do not use either JDBC batch writing nor native platform batch writing.
+
* <tt>Oracle-JDBC</tt> – use both JDBC batch writing and Oracle native platform batch writing.<br>Use <tt>OracleJDBC</tt> in your property map.
+
* <tt>None</tt> – do not use batch writing (turn it off).
+
 
+
Note: if you set any other value, EclipseLink will throw an exception.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.batch-writing" value="Oracle-JDBC"/>
+
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.BATCH_WRITING, BatchWriting.OracleJDBC);
+
| headers="r4c1-t35 r1c3-t35" align="left" |
+
<tt>None</tt>
+
|- align="left" valign="top"
+
| id="r5c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.cache-statements</tt>
+
| headers="r5c1-t35 r1c2-t35" align="left" |
+
Enable or disable EclipseLink internal statement caching.<sup>2</sup>
+
 
+
Note: we recommend enabling this functionality if you are using EclipseLink connection pooling.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable EclipseLink's internal statement caching.
+
* <tt>false</tt> – disable internal statement caching.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.cache-statements" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CACHE_STATEMENTS, "false");
+
| headers="r5c1-t35 r1c3-t35" align="left" |
+
<tt>false</tt>
+
|- align="left" valign="top"
+
| id="r6c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.cache-statements.size</tt>
+
| headers="r6c1-t35 r1c2-t35" align="left" |
+
The number of statements held when using internal statement caching.<sup>2</sup>
+
 
+
Set the value at the deployment time.
+
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.cache-statements.size" value="2"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CACHE_STATEMENTS_SIZE, "2");
+
| headers="r6c1-t35 r1c3-t35" align="left" |
+
50
+
|- align="left" valign="top"
+
| id="r7c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.driver</tt>
+
| headers="r7c1-t35 r1c2-t35" align="left" |
+
The class name of the JDBC driver you want to use, fully qualified by its package name. This class must be on your application classpath.<sup>3</sup>
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/>
+
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_DRIVER, "oracle.jdbc.driver.OracleDriver");
+
| headers="r7c1-t35 r1c3-t35" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r8c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.password</tt>
+
| headers="r8c1-t35 r1c2-t35" align="left" |
+
The password for your JDBC user.<sup>3</sup>
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.password" value="tiger"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_PASSWORD, "tiger");
+
| headers="r8c1-t35 r1c3-t35" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r9c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.url</tt>
+
| headers="r9c1-t35 r1c2-t35" align="left" |
+
The JDBC connection URL required by your JDBC driver.<sup>3</sup>
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.url" value="jdbc:oracle:thin:@MYHOST:1521:MYSID"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_URL, "jdbc:oracle:thin:@MYHOST:1521:MYSID");
+
| headers="r9c1-t35 r1c3-t35" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r10c1-t35" headers="r1c1-t35" align="left" |
+
<tt>eclipselink.jdbc.user</tt>
+
| headers="r10c1-t35 r1c2-t35" align="left" |
+
The user name for your JDBC user.<sup>3</sup>
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.url" value="scott"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_USER, "scott");
+
| headers="r10c1-t35 r1c3-t35" align="left" | <br>
+
|}
+
<sup>1</sup> This property applies when used in a Java SE environment.
+
<sup>2</sup> This property applies when used both in a Java SE and Java EE environment.
+
<sup>3</sup> This property applies when used in a Java SE environment or a resource-local persistence unit (see Section 5.5.2 "Resource-Local Entity Managers" and Section 6.2.1.2 "transaction-type" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification])
+
 
+
 
+
For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
For more information about persistence unit properties, see [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
 
+
 
+
===How to Use EclipseLink JPA Extensions for JDBC Connection Pooling===
+
 
+
This table lists the EclipseLink JPA persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure EclipseLink [[Introduction%20to%20Data%20Access%20(ELUG)#Internal Connection Pools|internal connection pooling]].
+
 
+
 
+
<span id="Table 19-23"></span>
+
''''' EclipseLink JPA Persistence Unit Properties for JDBC Connection Pooling'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for JDBC Connection Pooling" summary="This table lists EclipseLink JPA persistence.xml extensions for EclipseLink JDBC (JSE)" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t36" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t36" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t36" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t36" headers="r1c1-t36" align="left" |
+
<tt>eclipselink.jdbc.read-connections.max</tt>
+
| headers="r2c1-t36 r1c2-t36" align="left" |
+
The maximum number of connections allowed in the JDBC read connection pool.<sup>1</sup>
+
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.read-connections.max" value="3"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_READ_CONNECTIONS_MAX, "3");
+
| headers="r2c1-t36 r1c3-t36" align="left" |
+
2
+
|- align="left" valign="top"
+
| id="r3c1-t36" headers="r1c1-t36" align="left" |
+
<tt>eclipselink.jdbc.read-connections.min</tt>
+
| headers="r3c1-t36 r1c2-t36" align="left" |
+
The minimum number of connections allowed in the JDBC read connection pool.<sup>1</sup>
+
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.read-connections.min" value="1"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_READ_CONNECTIONS_MIN, "1");
+
| headers="r3c1-t36 r1c3-t36" align="left" |
+
2
+
|- align="left" valign="top"
+
| id="r4c1-t36" headers="r1c1-t36" align="left" |
+
<tt>eclipselink.jdbc.read-connections.shared</tt>
+
| headers="r4c1-t36 r1c2-t36" align="left" |
+
Specify whether or not to allow concurrent use of shared read connections.<sup>1</sup>
+
 
+
The following are the valid values:
+
* <tt>true</tt> – allow concurrent use of shared read connections.
+
* <tt>false</tt> – do not allow the concurrent use of shared read connections; concurrent readers are each allocated their own read connection.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.read-connections.shared" value="true"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_READ_CONNECTIONS_SHARED, "true");
+
| headers="r4c1-t36 r1c3-t36" align="left" |
+
<tt>false</tt>
+
|- align="left" valign="top"
+
| id="r5c1-t36" headers="r1c1-t36" align="left" |
+
<tt>eclipselink.jdbc.write-connections.max</tt>
+
| headers="r5c1-t36 r1c2-t36" align="left" |
+
The maximum number of connections allowed in the JDBC write connection pool.<sup>1</sup>
+
 
+
Valid values:  to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.write-connections.max" value="5"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_WRITE_CONNECTIONS_MAX, "5");
+
| headers="r5c1-t36 r1c3-t36" align="left" |
+
10
+
|- align="left" valign="top"
+
| id="r6c1-t36" headers="r1c1-t36" align="left" |
+
<tt>eclipselink.jdbc.write-connections.min</tt>
+
| headers="r6c1-t36 r1c2-t36" align="left" |
+
The maximum number of connections allowed in the JDBC write connection pool.<sup>1</sup>
+
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.jdbc.write-connections.min" value="2"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.JDBC_WRITE_CONNECTIONS_MIN, "2");
+
| headers="r6c1-t36 r1c3-t36" align="left" |
+
5
+
|}
+
<br><sup>1</sup> This property applies when used in a Java SE environment.
+
 
+
 
+
For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
For more information about persistence unit properties, see [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|hat You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Logging==
+
 
+
This table lists the EclipseLink JPA persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure EclipseLink [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|logging]].
+
 
+
 
+
<span id="Table 19-24"></span>
+
'''''EclipseLink JPA Persistence Unit Properties for Logging'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for Logging" summary="This table lists EclipseLink JPA persistence.xml extensions for EclipseLink logging." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t37" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t37" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t37" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t37" headers="r1c1-t37" align="left" |
+
<tt>eclipselink.logging.logger</tt>
+
| headers="r2c1-t37 r1c2-t37" align="left" |
+
Select the type of logger to use.
+
 
+
The following are the valid values for the use in the <tt>persistence.xml</tt> file and for the <tt>org.eclipse.persistence.config.PersistenceUnitProperties</tt>:
+
* <tt>DefaultLogger</tt> – the EclipseLink native logger <tt>org.eclipse.persistence.logging.DefaultSessionLog</tt>.
+
* <tt>JavaLogger</tt> – the <tt>java.util.logging</tt> logger <tt>org.eclipse.persistence.logging.JavaLog</tt>.
+
* <tt>ServerLogger</tt> – the <tt>java.util.logging</tt> logger <tt>org.eclipse.persistence.platform.server.ServerLog</tt>. Integrates with the application server's logging as define in the <tt>org.eclipse.persistence.platform.server.ServerPlatform.</tt>
+
* Fully qualified class name of a custom logger. The custom logger must implement the <tt>org.eclipse.persistence.logging.SessionLog</tt> interface.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.logging.logger" value="acme.loggers.MyCustomLogger" />
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.LOGGING_LOGGER, "acme.loggers.MyCustomLogger" />
+
| headers="r2c1-t37 r1c3-t37" align="left" |
+
<tt>DefaultLogger</tt>
+
|- align="left" valign="top"
+
| id="r3c1-t37" headers="r1c1-t37" align="left" |
+
<tt>eclipselink.logging.level</tt>
+
| headers="r3c1-t37 r1c2-t37" align="left" |
+
Control the amount and detail of log output by configuring the log level (in ascending order of information).
+
 
+
The following are the valid values for the use in the <tt>persistence.xml</tt> file and for the <tt>java.util.logging.Level</tt>:<nowiki>:</nowiki>
+
* <tt>OFF</tt> – disables logging
+
* <tt>SEVERE</tt> – logs exceptions indicating EclipseLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.
+
* <tt>WARNING</tt> – logs exceptions that do not force EclipseLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.
+
* <tt>INFO</tt> – logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.
+
* <tt>CONFIG</tt> – logs only login, JDBC connection, and database information.
+
* <tt>FINE</tt> – logs SQL.
+
* <tt>FINER</tt> – similar to warning. Includes stack trace.
+
* <tt>FINEST</tt> – includes additional low level information.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.logging.level" value="OFF"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import java.util.logging.Level;
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.LOGGING_LEVEL, Level.OFF);
+
| headers="r3c1-t37 r1c3-t37" align="left" |
+
<tt>Level.INFO</tt>
+
|- align="left" valign="top"
+
| id="r4c1-t37" headers="r1c1-t37" align="left" |
+
<tt>eclipselink.logging.timestamp</tt>
+
| headers="r4c1-t37 r1c2-t37" align="left" |
+
Control whether the timestamp is logged in each log entry.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – log a timestamp.
+
* <tt>false</tt> – do not log a timestamp.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.logging.timestamp" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.LOGGING_TIMESTAMP, "false");
+
| headers="r4c1-t37 r1c3-t37" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r5c1-t37" headers="r1c1-t37" align="left" |
+
<tt>eclipselink.logging.thread</tt>
+
| headers="r5c1-t37 r1c2-t37" align="left" |
+
Control whether a thread identifier is logged in each log entry.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – log a thread identifier.
+
* <tt>false</tt> – do not log a thread identifier.
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.logging.thread" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.LOGGING_THREAD, "false");
+
| headers="r5c1-t37 r1c3-t37" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r6c1-t37" headers="r1c1-t37" align="left" |
+
<tt>eclipselink.logging.session</tt>
+
| headers="r6c1-t37 r1c2-t37" align="left" |
+
Control whether an EclipseLink session identifier is logged in each log entry.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – log an EclipseLink session identifier.
+
* <tt>false</tt> – do not log an EclipseLink session identifier.
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.logging.session" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.LOGGING_SESSION, "false");
+
| headers="r6c1-t37 r1c3-t37" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r7c1-t37" headers="r1c1-t37" align="left" |
+
<tt>eclipselink.logging.exceptions</tt>
+
| headers="r7c1-t37 r1c2-t37" align="left" |
+
Control whether the exceptions thrown from within the EclipseLink code are logged prior to returning the exception to the calling application. Ensures that all exceptions are logged and not masked by the application code.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – log all exceptions.
+
* <tt>false</tt> – do not log exceptions.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.logging.exceptions" value="true"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.LOGGING_EXCEPTIONS, "true");
+
| headers="r7c1-t37 r1c3-t37" align="left" |
+
<tt>false</tt>
+
|- align="left" valign="top"
+
| id="r8c1-t37" headers="r1c1-t37" align="left" |
+
<tt>eclipselink.logging.file</tt>
+
| headers="r8c1-t37 r1c2-t37" align="left" |
+
Specify a file location for the log output (instead of the standard out).<sup>1</sup>
+
 
+
Valid values: a string location to a directory in which you have write access. The location may be relative to your current working directory or absolute.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.logging.file" value="C:\myout\"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.LOGGING_FILE, "C:\myout\");
+
| headers="r8c1-t37 r1c3-t37" align="left" | <br>
+
|}
+
<br><sup>1</sup> This property applies when used in a Java SE environment.
+
 
+
For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
For more information about persistence unit properties, see [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Session, Target Database and Target Application Server==
+
 
+
This table lists the EclipseLink JPA persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure EclipseLink extensions for session, as well as the target database and application server.
+
 
+
 
+
<span id="Table 19-25"></span>
+
''''' EclipseLink JPA Persistence Unit Properties for Database, Session, and Application Server'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for Database, Session, and Application Server" summary="This table lists EclipseLink JPA persistence.xml extensions for EclipseLink database, session, and Application server." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t38" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t38" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t38" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t38" headers="r1c1-t38" align="left" |
+
<tt>eclipselink.session-name</tt>
+
| headers="r2c1-t38 r1c2-t38" align="left" |
+
Specify the name by which the EclipseLink session is stored in the static session manager. Use this option if you need to access the EclipseLink shared session outside of the context of the JPA or to use a pre-existing EclipseLink session configured through an EclipseLink <tt>sessions.xml</tt> file.
+
 
+
Valid values: a valid EclipseLink session name that is unique in a server deployment.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.session-name" value="MySession"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.SESSION_NAME, "MySession");
+
| headers="r2c1-t38 r1c3-t38" align="left" |
+
EclipseLink-generated unique name.
+
|- align="left" valign="top"
+
| id="r3c1-t38" headers="r1c1-t38" align="left" |
+
<tt>eclipselink.sessions-xml</tt>
+
| headers="r3c1-t38 r1c2-t38" align="left" |
+
Specify persistence information loaded from the EclipseLink session configuration file (<tt>sessions.xml</tt>).
+
 
+
You can use this option as an alternative to annotations and deployment XML. If you specify this property, EclipseLink will override all class annotation and the object relational mapping from the <tt>persistence.xml</tt>, as well as <tt>ORM.xml</tt> and other mapping files, if present. For more information, see [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|hat You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
Indicate the session by setting the <tt>eclipselink.session-name</tt> property.
+
 
+
Note: If you do not specify the value for this property, <tt>sessions.xml</tt> file will not be used.
+
 
+
Valid values: the resource name of the sessions XML file.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.sessions-xml" value="mysession.xml"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.SESSIONS_XML, "mysession.xml");
+
| headers="r3c1-t38 r1c3-t38" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r4c1-t38" headers="r1c1-t38" align="left" |
+
<tt>eclipselink.session-event-listener</tt>
+
| headers="r4c1-t38 r1c2-t38" align="left" |
+
Specify a descriptor event listener to be added during bootstrapping.
+
 
+
For more information, see [[Developing%20Applications%20Using%20EclipseLink%20JPA%20(ELUG)#Obtaining an Entity Manager Factory in Java SE Environment|Obtaining an Entity Manager Factory in Java SE Environment]].
+
 
+
Valid values: qualified class name for a class that implements the <tt>org.eclipse.persistence.sessions.SessionEventListener</tt> interface.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.session-event-listener" value="mypackage.MyClass.class"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.SESSION_EVENT_LISTENER_CLASS, "mypackage.MyClass.class");
+
| headers="r4c1-t38 r1c3-t38" align="left" | <br>
+
|- align="left" valign="top"
+
| id="r5c1-t38" headers="r1c1-t38" align="left" |
+
<tt>eclipselink.session.include.descriptor.queries</tt>
+
| headers="r5c1-t38 r1c2-t38" align="left" |
+
Enable or disable the default copying of all [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Named Queries|named queries]] from the descriptors to the session. These queries include the ones defined using EclipseLink API, descriptor [[Introduction%20to%20Descriptors%20(ELUG)#Amendment and After-Load Methods|amendment methods]], and so on.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable the default copying of all named queries from the descriptors to the session.
+
* <tt>false</tt> – disable the default copying of all named queries from the descriptors to the session.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.session.include.descriptor.queries" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.INCLUDE_DESCRIPTOR_QUERIES, "false");
+
| headers="r5c1-t38 r1c3-t38" align="left" |
+
<tt>true</tt>
+
|- align="left" valign="top"
+
| id="r6c1-t38" headers="r1c1-t38" align="left" |
+
<tt>eclipselink.target-database</tt>
+
| headers="r6c1-t38 r1c2-t38" align="left" |
+
Specify the type of database that your JPA application uses. The <tt>org.eclipse.persistence.config.TargetDatabase</tt> enumerated type contains an entry for many of the more common database types supported.
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.TargetDatabase</tt><nowiki>:</nowiki>
+
* <tt>Attunity</tt> – configure the persistence provider to use an Attunity database.
+
* <tt>Auto</tt> – EclipseLink accesses the database and uses the metadata that JDBC provides to determine the target database. Applicable to JDBC drives that support this metadata.
+
* <tt>Cloudscape</tt> – configure the persistence provider to use a Cloudscape database.
+
* <tt>Database</tt> – configure the persistence provider to use a generic choice if your target database is not listed here and your JDBC driver does not support the use of metadata that the <tt>Auto</tt> option requires.
+
* <tt>DB2</tt> – configure the persistence provider to use a DB2 database.
+
* <tt>DB2Mainframe</tt> – configure the persistence provider to use a DB2Mainframe database.
+
* <tt>DBase</tt> – configure the persistence provider to use a DBase database.
+
* <tt>Derby</tt> – configure the persistence provider to use a Derby database.
+
* <tt>HSQL</tt> – configure the persistence provider to use an HSQL database.
+
* <tt>Informix</tt> – configure the persistence provider to use an Informix database.
+
* <tt>JavaDB</tt> – configure the persistence provider to use a JavaDB database.
+
* <tt>MySQLPlatform</tt> – configure the persistence provider to use a MySQLPlatform database.
+
* <tt>Oracle</tt> – configure the persistence provider to use an Oracle Database.
+
* <tt>PointBase</tt> – configure the persistence provider to use a PointBase database.
+
* <tt>PostgreSQL</tt> – configure the persistence provider to use a PostgreSQL database.
+
* <tt>SQLAnyWhere</tt> – configure the persistence provider to use an SQLAnyWhere database.
+
* <tt>SQLServer</tt> – configure the persistence provider to use an SQLServer database.
+
* <tt>Sybase</tt> – configure the persistence provider to use a Sybase database.
+
* <tt>TimesTen</tt> – configure the persistence provider to use a TimesTen database.
+
 
+
You can also set the value to the fully qualified classname of a subclass of the <tt>org.eclipse.persistence.platform.DatabasePlatform</tt> class.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.target-database" value="Oracle"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.TargetDatabase;
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.TARGET_DATABASE, TargetDatabase.Oracle);
+
| headers="r6c1-t38 r1c3-t38" align="left" |
+
<tt>Auto</tt>
+
|- align="left" valign="top"
+
| id="r7c1-t38" headers="r1c1-t38" align="left" |
+
<tt>eclipselink.target-server</tt>
+
| headers="r7c1-t38 r1c2-t38" align="left" |
+
Specify the type of application server that your JPA application uses.
+
 
+
The following are the valid values for the use in the <tt>persistence.xml</tt> file and the <tt>org.eclipse.persistence.config.TargetServer</tt><nowiki>:</nowiki>
+
* <tt>None</tt> – configure the persistence provider to use no application server.
+
* <tt>OC4J</tt> – configure the persistence provider to use OC4J.<br>Note: this server sets this property automatically, so you do not need to set it, unless it is disabled.
+
* <tt>SunAS9</tt> – configure the persistence provider to use Sun Application Server version 9.<br>Note: this server sets this property automatically, so you do not need to set it, unless it is disabled.
+
* <tt>WebSphere</tt> – configure the persistence provider to use WebSphere Application Server.
+
* <tt>WebSphere_6_1</tt> – configure the persistence provider to use WebSphere Application Server version 6.1.
+
* <tt>WebLogic</tt> – configure the persistence provider to use WebLogic Application Server.
+
* <tt>WebLogic_9</tt> – configure the persistence provider to use WebLogic Application Server version 9.
+
* <tt>WebLogic_10</tt> – configure the persistence provider to use WebLogic Application Server version 10.
+
* <tt>JBoss</tt> – configure the persistence provider to use JBoss Application Server.
+
* Fully qualified class name of a custom server class that implements <tt>org.eclipse.persistence.platform.ServerPlatform</tt> interface.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.target-server" value="OC4J_10_1_3"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.TargetServer;
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.TARGET_SERVER, TargetServer.OC4J_10_1_3);
+
| headers="r7c1-t38 r1c3-t38" align="left" |
+
<tt>None</tt>
+
|}
+
 
+
 
+
For information about the configuration of platforms, see the following:
+
 
+
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Target Platforms|Target Platforms]]
+
* [[Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)|Integrating EclipseLink with an Application Server]]
+
* [[Introduction%20to%20Projects (ELUG)|Projects and Platforms]]
+
* [[Introduction%20to%20Data%20Access%20(ELUG)|Database Platforms]]
+
 
+
For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
For more information about persistence unit properties, see [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Schema Generation==
+
 
+
This table lists the EclipseLink JPA persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure schema generation.
+
 
+
 
+
<span id="Table 19-26"></span>
+
''''' EclipseLink JPA Persistence Unit Properties for Schema Generation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for Schema Generation" summary="This table lists EclipseLink JPA persistence.xml extensions for Java2DB schema generation." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t39" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t39" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t39" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t39" headers="r1c1-t39" align="left" |
+
<span id="eclipselink.ddl-generation"></span><tt>eclipselink.ddl-generation</tt>
+
| headers="r2c1-t39 r1c2-t39" align="left" |
+
Specify what Data Definition Language (DDL) generation action you want for your JPA entities. To specify the DDL generation target, see <tt>[[#eclipselink.ddl-generation.output-mode|eclipselink.ddl-generation.output-mode]]</tt>.
+
 
+
The following are the valid values for the use in a <tt>persistence.xml</tt> file:
+
* <tt>none</tt> – do not generate DDL; no schema is generated.
+
* <tt>create-tables</tt> – create DDL for non-existent tables; leave existing tables unchanged (see also <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt>).
+
* <tt>drop-and-create-tables</tt> – create DDL for all tables; drop all existing tables (see also <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt> and <tt>[[#eclipselink.drop-ddl-jdbc-file-name|eclipselink.drop-ddl-jdbc-file-name]]</tt>).
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.PersistenceUnitProperties</tt><nowiki>:</nowiki>
+
* <tt>NONE</tt> – see <tt>none</tt>.
+
* <tt>CREATE_ONLY</tt> – see <tt>create-tables</tt>.
+
* <tt>DROP_AND_CREATE</tt> – see <tt>drop-and-create-tables</tt>.
+
 
+
If you are using persistence in a Java SE environment and would like to create the DDL files without creating tables, additionally define a Java system property <tt>INTERACT_WITH_DB</tt> and set its value to <tt>false</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.ddl-generation" value="create-tables"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.DDL_GENERATION, PersistenceUnitProperties.CREATE_ONLY);
+
| headers="r2c1-t39 r1c3-t39" align="left" |
+
<tt>none</tt> or <tt>PersistenceUnitProperties.NONE</tt>
+
|- align="left" valign="top"
+
| id="r3c1-t39" headers="r1c1-t39" align="left" |
+
<span id="eclipselink.application-location"></span><tt>eclipselink.application-location</tt>
+
| headers="r3c1-t39 r1c2-t39" align="left" |
+
Specify where EclipseLink should write generated DDL files (see <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt> and <tt>[[#eclipselink.drop-ddl-jdbc-file-name|eclipselink.drop-ddl-jdbc-file-name]]</tt>). Files are written if <tt>[[#eclipselink.ddl-generation|eclipselink.ddl-generation]]</tt> is set to anything other than <tt>none</tt>.
+
 
+
Valid values: a file specification to a directory in which you have write access. The file specification may be relative to your current working directory or absolute. If it does not end in a file separator, EclipseLink will append one valid for your operating system.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.application-location" value="C:\ddl\"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.APP_LOCATION, "C:\ddl\");
+
| headers="r3c1-t39 r1c3-t39" align="left" |
+
<tt>"."+File.separator or <tt>PersistenceUnitProperties.DEFAULT_APP_LOCATION</tt></tt>
+
|- align="left" valign="top"
+
| id="r4c1-t39" headers="r1c1-t39" align="left" |
+
<span id="eclipselink.create-ddl-jdbc-file-name"></span><tt>eclipselink.create-ddl-jdbc-file-name</tt>
+
| headers="r4c1-t39 r1c2-t39" align="left" |
+
Specify the file name of the DDL file that EclipseLink generates containing SQL statements to create tables for JPA entities. This file is written to the location specified by <tt>[[#eclipselink.application-location|eclipselink.application-location]]</tt> when <tt>[[#eclipselink.ddl-generation|eclipselink.ddl-generation]]</tt> is set to <tt>create-tables</tt> or <tt>drop-and-create-tables</tt>.
+
 
+
Valid values: a file name valid for your operating system. Optionally, you may prefix the file name with a file path as long as the concatenation of <tt>[[#eclipselink.application-location|eclipselink.application-location]]</tt> + <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt> is a valid file specification for your operating system.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.create-ddl-jdbc-file-name" value="create.sql"/>
+
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.CREATE_JDBC_DDL_FILE, "create.sql");
+
 
+
| headers="r4c1-t39 r1c3-t39" align="left" |
+
<span id="createDDL.jdbc"></span><tt>createDDL.jdbc</tt> or <tt>PersistenceUnitProperties.DEFAULT_CREATE_JDBC_FILE_NAME</tt>
+
|- align="left" valign="top"
+
| id="r5c1-t39" headers="r1c1-t39" align="left" |
+
<tt>eclipselink.drop-ddl-jdbc-file-name</tt>
+
| headers="r5c1-t39 r1c2-t39" align="left" |
+
Specify the file name of the DDL file that EclipseLink generates containing the SQL statements to drop tables for JPA entities. This file is written to the location specified by <tt>[[#eclipselink.application-location|eclipselink.application-location]]</tt> when <tt>[[#eclipselink.ddl-generation|eclipselink.ddl-generation]]</tt> is set to <tt>drop-and-create-tables</tt>.
+
 
+
Valid values: a file name valid for your operating system. Optionally, you may prefix the file name with a file path as long as the concatenation of <tt>[[#eclipselink.application-location|eclipselink.application-location]]</tt> + <tt>[[#eclipselink.drop-ddl-jdbc-file-name|eclipselink.drop-ddl-jdbc-file-name]]</tt> is a valid file specification for your operating system.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.drop-ddl-jdbc-file-name" value="drop.sql"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.DROP_JDBC_DDL_FILE, "drop.sql");
+
| headers="r5c1-t39 r1c3-t39" align="left" |
+
<tt>dropDDL.jdbc</tt> or <tt>PersistenceUnitProperties.DEFAULT_DROP_JDBC_FILE_NAME</tt>
+
|- align="left" valign="top"
+
| id="r6c1-t39" headers="r1c1-t39" align="left" |
+
<span id="eclipselink.ddl-generation.output-mode"></span><tt>eclipselink.ddl-generation.output-mode</tt>
+
| headers="r6c1-t39 r1c2-t39" align="left" |
+
Use this property to specify the DDL generation target.
+
 
+
The following are the valid values for the use in the <tt>persistence.xml</tt> file<nowiki>:</nowiki>
+
* <tt>both</tt> – generate SQL files and execute them on the database.<br>If <tt>[[#eclipselink.ddl-generation|eclipselink.ddl-generation]]</tt> is set to <tt>create-tables</tt>, then <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt> is written to <tt>[[#eclipselink.application-location|eclipselink.application-location]]</tt> and executed on the database.<br>If <tt>[[#eclipselink.ddl-generation|eclipselink.ddl-generation]]</tt> is set to <tt>drop-and-create-tables</tt>, then both <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt> and <tt>[[#eclipselink.drop-ddl-jdbc-file-name|eclipselink.drop-ddl-jdbc-file-name]]</tt> are written to <tt>[[#eclipselink.application-location|eclipselink.application-location]]</tt> and both SQL files are executed on the database.
+
* <tt>database</tt> – execute SQL on the database only (do not generate SQL files).
+
* <tt>sql-script</tt> – generate SQL files only (do not execute them on the database).<br>If <tt>[[#eclipselink.ddl-generation|eclipselink.ddl-generation]]</tt> is set to <tt>create-tables</tt>, then <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt> is written to <tt>[[#eclipselink.application-location|eclipselink.application-location]]</tt>. It is not executed on the database.<br>If <tt>[[#eclipselink.ddl-generation|eclipselink.ddl-generation]]</tt> is set to <tt>drop-and-create-tables</tt>, then both <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt> and <tt>[[#eclipselink.drop-ddl-jdbc-file-name|eclipselink.drop-ddl-jdbc-file-name]]</tt> are written to <tt>[[#eclipselink.application-locatio|eclipselink.application-location]]</tt>. Neither is executed on the database.
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.PersistenceUnitProperties</tt><nowiki>:</nowiki>
+
* <tt>DDL_BOTH_GENERATION</tt> – see <tt>both</tt>.
+
* <tt>DDL_DATABASE_GENERATION</tt> – see <tt>database</tt>.
+
* <tt>DDL_SQL_SCRIPT_GENERATION</tt> – see <tt>sql-script</tt>.
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.ddl-generation.output-mode" value="database"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.DDL_GENERATION_MODE, PersistenceUnitProperties.DDL_DATABASE_GENERATION);
+
| headers="r6c1-t39 r1c3-t39" align="left" |
+
Container or Java EE mode: <tt>sql-script</tt> or <tt>PersistenceUnitProperties.DDL_SQL_SCRIPT_GENERATION</tt>
+
 
+
Note: This setting may be overridden by containers with specific EclipseLink support. Please, refer to your container documentation for details.
+
 
+
Bootstrap or Java SE mode: <tt>both</tt> or <tt>PersistenceUnitProperties.DDL_BOTH_GENERATION</tt>
+
|}
+
<br>
+
 
+
For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
For more information about persistence unit properties, see [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Extensions for Tracking Changes==
+
 
+
Within a transaction, EclipseLink automatically tracks entity changes.
+
 
+
EclipseLink defines one annotation for tracking changes – <tt>[[#How to Use the @ChangeTracking Annotation|@ChangeTracking]]</tt> annotation.
+
 
+
EclipseLink also provides a number of persistence unit properties that you can specify to configure EclipseLink change tracking (see [[#How to Use the Persistence Unit Properties for Change Tracking|How to Use the Persistence Unit Properties for Change Tracking]]). These properties may compliment or provide an alternative to the usage of annotations.
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' Persistence unit properties always override the corresponding annotations' attributes. For more information, see [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]] and [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
|}
+
 
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Transactions (ELUG)#Unit of Work and Change Policy|Unit of Work and Change Policy]].
+
 
+
 
+
 
+
===How to Use the @ChangeTracking Annotation===
+
 
+
Use the <tt>[http://www.eclipse.org/eclipselink/api/1.0/org/eclipse/persistence/annotations/ChangeTracking.html @ChangeTracking]</tt> annotation to set the unit of work's change policy.
+
 
+
@Target({TYPE})
+
@Retention(RUNTIME)
+
public @interface ChangeTracking {
+
    ChangeTrackingType value() default AUTO;
+
}
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' This is an optimization feature that lets you tune the way EclipseLink detects changes. You should choose the strategy based on the usage and data modification patterns of the entity type as different types may have different access patterns and hence different settings, and so on.
+
 
+
For more information, see the following:
+
* [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Optimizing the Unit of Work|Optimizing the Unit of Work]]
+
* [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Read Optimization Examples|Read Optimization Examples]]
+
* [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#Write Optimization Examples|Write Optimization Examples]]
+
|}
+
 
+
 
+
This table lists attributes of the <tt>@ChangeTracking</tt> annotation.
+
 
+
 
+
<span id="Table 19-27"></span>
+
''''' Attributes of the @ChangeTracking Annotation'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @ChangeTracking Annotation" summary="This table lists the attributes of EclipseLink JPA @ChangeTracking annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t42" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t42" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t42" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t42" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t42" headers="r1c1-t42" align="left" |
+
<tt>value</tt>
+
| headers="r2c1-t42 r1c2-t42" align="left" |
+
Set this attribute to the type of the change tracking (<tt>org.eclipse.persistence.annotations.ChangeTrackingType</tt> enumerated type) to use.
+
 
+
The following are the valid values for the <tt>ChangeTrackingType</tt><nowiki>:</nowiki>
+
* <tt>ATTRIBUTE</tt> – This option uses weaving to detect which fields or properties of the object change. This is the most efficient option, but you must enable weaving to use it.<br><br>For more information, see [[Introduction%20to%20EclipseLink%20Transactions%20(ELUG)#Attribute Change Tracking Policy|Attribute Change Tracking Policy]].
+
* <tt>OBJECT</tt> – This option uses weaving to detect if the object has been changed, but uses a backup copy of the object to determine what fields or properties changed. This is more efficient than the <tt>DEFERRED</tt> option, but less efficient than the <tt>ATTRIBUTE</tt> option. You must enable weaving to use this option. This option supports additional mapping configuration to attribute.<br><br>For more information, see [[Introduction%20to%20EclipseLink%20Transactions%20(ELUG)#Object-Level Change Tracking Policy|Object-Level Change Tracking Policy]].
+
* <tt>DEFERRED</tt> – This option defers all change detection to the <tt>UnitOfWork</tt>'s change detection process. This option uses a backup copy of the object to determine which fields or properties changed. This is the least efficient option, but does not require weaving and supports additional mapping configurations to attribute and object.<br><br>For more information, see [[Introduction%20to%20EclipseLink%20Transactions%20(ELUG)#Deferred Change Detection Policy|Deferred Change Detection Policy]].
+
* <tt>AUTO</tt> – This option does not set any change tracking policy. The policy is determined by the EclipseLink agent: if the class can be weaved for change tracking the <tt>ATTRIBUTE</tt> option is used; otherwise, the <tt>DEFERRED</tt> option is used.<br><tt>AUTO</tt> is the only change tracking value where EclipseLink chooses the value; any other value will explicitly cause EclipseLink to use that value, so if you decide to explicitly set it, you must set it correctly and use your model correctly to ensure the change tracking detects your changes.
+
 
+
Note: For every option, objects with changed attributes will be processed at the commit time to include any changes in the results of the commit. Unchanged objects will be ignored.
+
 
+
Note: The weaving of change tracking is the same for attribute and object change tracking.
+
 
+
For information about the relationship between the <tt>value</tt> attribute and <tt>eclipselink.weaving.changetracking</tt> property, see [[#What You May Need to Know About the Relationship Between the Change Tracking Annotation and Persistence Unit Property|What You May Need to Know About the Relationship Between the Change Tracking Annotation and Persistence Unit Property]]
+
| headers="r2c1-t42 r1c3-t42" align="left" |
+
<tt>ChangeTrackingType.AUTO</tt>
+
| headers="r2c1-t42 r1c4-t42" align="left" |
+
optional
+
|}
+
 
+
 
+
This example shows how to use the <tt>@ChangeTracking</tt> annotation.
+
 
+
<span id="Example 19-23"></span>
+
''''' Usage of @ChangeTracking Annotation'''''
+
@Entity
+
@Table(name="EMPLOYEE")
+
@ChangeTracking(OBJECT) (
+
public class Employee implements Serializable {
+
    ...
+
}
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' You cannot use the attribute change tracking in conjunction with the following:
+
* optimistic field-level locking (see [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Optimistic Locking|Optimistic Locking]]);
+
* mutable types (such as mutable temporals or mutable serialized mappings);
+
* non-lazy collection mappings.
+
 
+
The attribute change tracking will not detect object changes made through reflection or direct field access to fields mapped as properties.
+
|}
+
 
+
===How to Use the Persistence Unit Properties for Change Tracking===
+
 
+
This table lists the persistence unit properties that you can define in a <tt>persistence.xml</tt> file to configure EclipseLink change tracking.
+
 
+
 
+
<span id="Table 19-28"></span>
+
''''' EclipseLink JPA Persistence Unit Properties for Change Tracking'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Persistence Unit Properties for Change Tracking" summary="This table lists the persistence unit properties for change tracking." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t44" align="left" valign="bottom" | '''Property'''
+
! id="r1c2-t44" align="left" valign="bottom" | '''Usage'''
+
! id="r1c3-t44" align="left" valign="bottom" | '''Default'''
+
|- align="left" valign="top"
+
| id="r2c1-t44" headers="r1c1-t44" align="left" |
+
<tt>eclipselink.weaving.changetracking</tt>
+
| headers="r2c1-t44 r1c2-t44" align="left" |
+
Enable or disable the <tt>AttributeLevelChangeTracking</tt> through weaving.
+
 
+
The following are the valid values:
+
* <tt>true</tt> – enable the <tt>AttributeLevelChangeTracking</tt> through weaving. When enabled, only classes with all mappings allowing change tracking have change tracking enabled.
+
* <tt>false</tt> – disable the <tt>AttributeLevelChangeTracking</tt> through weaving. Use this setting if the following applies:
+
** you cannot weave at all;
+
** you do not want your classes to be changed during weaving (for example, for debugging purposes);
+
** you wish to disable this feature for configurations that do not support it (for example, you are mutating the <tt>java.util.Date</tt> or <tt>java.util.Calendar</tt>, you are using property access but modifying the underlying instance variables).
+
 
+
Note: you may set this option only if the <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> option is set to <tt>true</tt>. The purpose of the <tt>eclipselink.weaving.changetracking</tt> option is to provide more granular control over weaving.
+
 
+
For more information, see the following:
+
* [[#Using EclipseLink JPA Weaving|Using EclipseLink JPA Weaving]]
+
* [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Change Policy|Configuring Change Policy]]
+
 
+
 
+
'''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
+
<property name="eclipselink.weaving.changetracking" value="false"/>
+
 
+
'''Example'''<nowiki>: property </nowiki><tt>Map</tt>
+
import org.eclipse.persistence.config.PersistenceUnitProperties;
+
propertiesMap.put(PersistenceUnitProperties.WEAVING_CHANGE_TRACKING, "false");
+
| headers="r2c1-t44 r1c3-t44" align="left" |
+
<tt>true</tt>
+
|}
+
 
+
 
+
For information about the relationship between the <tt>value</tt> attribute of the <tt>[[#How to Use the @ChangeTracking Annotation|@ChangeTracking]]</tt> annotation and <tt>eclipselink.weaving.changetracking</tt> property, see [[#What You May Need to Know About the Relationship Between the Change Tracking Annotation and Persistence Unit Property|What You May Need to Know About the Relationship Between the Change Tracking Annotation and Persistence Unit Property]].
+
 
+
For information about the use of annotations as opposed to persistence unit properties and vice versa, see the following:
+
* [[#What You May Need to Know About Overriding Annotations in JPA|What You May Need to Know About Overriding Annotations in JPA]]
+
* [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
For more information about persistence unit properties, see [[#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]].
+
 
+
 
+
 
+
===What You May Need to Know About the Relationship Between the Change Tracking Annotation and Persistence Unit Property===
+
 
+
The following table shows the dependency between the <tt>value</tt> attribute of the <tt>[[#How to Use the @ChangeTracking Annotation|@ChangeTracking]]</tt> annotation and the <tt>eclipselink.weaving.changetracking</tt> property (see [[#How to Use the Persistence Unit Properties for Change Tracking|How to Use the Persistence Unit Properties for Change Tracking]]).
+
 
+
 
+
<span id="Table 19-29"></span>
+
''''' Relationship Between the Change Tracking Annotation and Property'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="Relationship Between the Change Tracking Annotation and Property" summary="This table shows the dependency between @ChangeTracking and eclipselink.weaving.changetracking" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t45" align="left" valign="bottom" | '''@ChangeTracking(value=)'''
+
! id="r1c2-t45" align="left" valign="bottom" | '''eclipselink.weaving.changetracking='''
+
! id="r1c3-t45" align="left" valign="bottom" | '''Description'''
+
|- align="left" valign="top"
+
| id="r2c1-t45" headers="r1c1-t45" align="left" |
+
<tt>ATTRIBUTE</tt>
+
| headers="r2c1-t45 r1c2-t45" align="left" |
+
<tt>true</tt>
+
| headers="r2c1-t45 r1c3-t45" align="left" |
+
Weave and enable attribute change tracking.
+
 
+
Even if the descriptors contain mappings that are not directly supported by change tracking weaving, EclipseLink assumes that you will either use your set methods to ensure that your changes are captured, or raise the events for these mappings.
+
|- align="left" valign="top"
+
| id="r3c1-t45" headers="r1c1-t45" align="left" |
+
<tt>ATTRIBUTE</tt>
+
| headers="r3c1-t45 r1c2-t45" align="left" |
+
<tt>false</tt>
+
| headers="r3c1-t45 r1c3-t45" align="left" |
+
Do not weave change tracking.
+
 
+
You must implement the <tt>org.eclipse.persistence.annotations.ChangeTracking</tt> interface and raise the change events. Otherwise, an error will occur on descriptor initialization.
+
|- align="left" valign="top"
+
| id="r4c1-t45" headers="r1c1-t45" align="left" |
+
<tt>OBJECT</tt>
+
| headers="r4c1-t45 r1c2-t45" align="left" |
+
<tt>true</tt>
+
| headers="r4c1-t45 r1c3-t45" align="left" |
+
Object change tracking is used and change tracking is woven.
+
 
+
Note: Weaving is identical for object and attribute change tracking.
+
|- align="left" valign="top"
+
| id="r5c1-t45" headers="r1c1-t45" align="left" |
+
<tt>OBJECT</tt>
+
| headers="r5c1-t45 r1c2-t45" align="left" |
+
<tt>false</tt>
+
| headers="r5c1-t45 r1c3-t45" align="left" |
+
Do not weave change tracking.
+
 
+
You must implement the <tt>org.eclipse.persistence.annotations.ChangeTracking</tt> interface and raise the change events. Otherwise, an error will occur on descriptor initialization.
+
|- align="left" valign="top"
+
| id="r6c1-t45" headers="r1c1-t45" align="left" |
+
<tt>DEFERRED</tt>
+
| headers="r6c1-t45 r1c2-t45" align="left" |
+
<tt>true</tt>
+
| headers="r6c1-t45 r1c3-t45" align="left" |
+
Do not weave change cracking.
+
 
+
Deferred change cracking is used.
+
|- align="left" valign="top"
+
| id="r7c1-t45" headers="r1c1-t45" align="left" |
+
<tt>DEFERRED</tt>
+
| headers="r7c1-t45 r1c2-t45" align="left" |
+
<tt>false</tt>
+
| headers="r7c1-t45 r1c3-t45" align="left" |
+
Do not weave change cracking.
+
 
+
Deferred change cracking is used.
+
|- align="left" valign="top"
+
| id="r8c1-t45" headers="r1c1-t45" align="left" |
+
<tt>AUTO</tt>
+
| headers="r8c1-t45 r1c2-t45" align="left" |
+
<tt>true</tt>
+
| headers="r8c1-t45 r1c3-t45" align="left" |
+
Weave change tracking if the descriptor does not use any mappings that do not support change tracking.
+
|- align="left" valign="top"
+
| id="r9c1-t45" headers="r1c1-t45" align="left" |
+
<tt>AUTO</tt>
+
| headers="r9c1-t45 r1c2-t45" align="left" |
+
<tt>false</tt>
+
| headers="r9c1-t45 r1c3-t45" align="left" |
+
Do not weave change cracking.
+
 
+
Deferred change cracking is used.
+
|}
+
 
+
 
+
 
+
 
+
==Using EclipseLink JPA Query Customization Extensions==
+
 
+
This section describes the following:
+
* [[#How to Use EclipseLink JPA Query Hints|How to Use EclipseLink JPA Query Hints]]
+
* [[#How to Use EclipseLink Query API in JPA Queries|How to Use EclipseLink Query API in JPA Queries]]
+
 
+
 
+
 
+
===How to Use EclipseLink JPA Query Hints===
+
 
+
The [[#Table 19-30|EclipseLink JPA Query Hints]] table lists the EclipseLink JPA query hints that you can specify when you construct a JPA query, as the [[#Example 19-24|Specifying an EclipseLink JPA Query Hint]] example shows, or when you specify a JPA query using the <tt>@QueryHint</tt> annotation (see Section 8.3.1 "NamedQuery Annotation" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]), as the [[#Example 19-25|Specifying an EclipseLink JPA Query Hint with @QueryHint]] example shows.
+
 
+
All EclipseLink query hints are defined in the <tt>QueryHints</tt> class in the <tt>org.eclipse.persistence.config</tt> package.
+
 
+
The EclipseLink query hints include:
+
* [[#Cache Usage|eclipselink.cache-usage]]
+
* [[#Query Type|eclipselink.query-type]]
+
* [[#Bind Parameters|eclipselink.jdbc.bind-parameters]]
+
* [[#Pessimistic Lock|eclipselink.pessimistic-lock]]
+
* [[#Refresh|eclipselink.refresh]]
+
* [[#Refresh|eclipselink.refresh.cascade]]
+
* [[#Batch|eclipselink.batch]]
+
* [[#Join Fetch|eclipselink.join-fetch]]
+
* [[#Read Only|eclipselink.read-only]]
+
* [[#Timeout|eclipselink.jdbc.timeout]]
+
* [[#Fetch Size|eclipselink.jdbc.fetch-size]]
+
* [[#Max Rows|eclipselink.jdbc.max-rows]]
+
* [[#Result Collection Type|eclipselink.result-collection-type]]
+
 
+
 
+
When you set a hint, you can set the value using the public static final field in the appropriate configuration class in <tt>org.eclipse.persistence.config</tt> package, including the following:
+
* <tt>HintValues</tt>
+
* <tt>CacheUsage</tt>
+
* <tt>PessimisticLock</tt>
+
* <tt>QueryType</tt>
+
 
+
The [[#Example 19-24|Specifying an EclipseLink JPA Query Hint]] and [[#Example 19-25|Specifying an EclipseLink JPA Query Hint with @QueryHint]] examples show how to set the value of hint <tt>eclipselink.jdbc.bind-parameters</tt> using the <tt>QueryHints</tt> configuration class to set the name of the hint, and the <tt>HintValues</tt> configuration class to set the value.
+
 
+
<span id="Example 19-24"></span>
+
''''' Specifying an EclipseLink JPA Query Hint'''''
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
+
Customer customer = (Customer)entityMgr.createNamedQuery("findCustomerBySSN").
+
    setParameter("SSN", "123-12-1234").
+
    setHint(QueryHints.BIND_PARAMETERS, HintValues.PERSISTENCE_UNIT_DEFAULT).
+
    getSingleResult();
+
 
+
 
+
<span id="Example 19-25"></span>
+
''''' Specifying an EclipseLink JPA Query Hint with @QueryHint'''''
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
+
@Entity
+
@NamedQuery(
+
    name="findEmployeeByDept",
+
    query="SELECT e FROM Employee e WHERE e.dept=:deptNum"
+
    hints={@QueryHint=
+
        {name=QueryHints.BIND_PARAMETERS, value=HintValues.TRUE}
+
    }
+
)
+
public class Employee implements Serializable {
+
    ...
+
}
+
 
+
====Cache Usage====
+
The <tt>eclipselink.cache-usage</tt> hint specifies how the query should interact with the EclipseLink cache.
+
 
+
EclipseLink JPA uses a shared cache mechanism that is scoped to the entire persistence unit. When operations are completed in a particular persistence context, the results are merged back into the shared cache so that other persistence contexts can use them. This happens regardless of whether the entity manager and persistence context are created in Java SE or Java EE. Any entity persisted or removed using the entity manager will always be kept consistent with the cache.
+
 
+
For more information, see the following:
+
* [[Introduction%20to%20Cache%20(ELUG)#Session Cache|Session Cache]]
+
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#How to Use In-Memory Queries|How to Use In-Memory Queries]]
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.CacheUsage</tt><nowiki>:</nowiki>
+
* <tt>DoNotCheckCache</tt> – Always go to the database.
+
* <tt>CheckCacheByExactPrimaryKey</tt> – If a read-object query contains an expression where the primary key is the only comparison, you can obtain a cache hit if you process the expression against the object in memory
+
* <tt>CheckCacheByPrimaryKey</tt> – If a read-object query contains an expression that compares at least the primary key, you can obtain a cache hit if you process the expression against the objects in memory.
+
* <tt>CheckCacheThenDatabase</tt> – You can configure any read-object query to check the cache completely before you resort to accessing the database.
+
* <tt>CheckCacheOnly</tt> – You can configure any read-all query to check only the parent session cache (shared cache) and return the result from it without accessing the database.
+
* <tt>ConformResultsInUnitOfWork</tt> – You can configure any read-object or read-all query within the context of a unit of work to conform the results with the changes to the object made within that unit of work. This includes new objects, deleted objects and changed objects.<br><br>For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Using Conforming Queries and Descriptors|Using Conforming Queries and Descriptors]].
+
* <tt>UseEntityDefault</tt> – Use the cache configuration as specified by the EclipseLink descriptor API for this entity.<br><br>Note: the entity default value is to not check the cache (<tt>DoNotCheckCache</tt>). The query will access the database and synchronize with the cache. Unless refresh has been set on the query, the cached objects will be returned without being refreshed from the database. EclipseLink does not support the cache usage for native queries or queries that have complex result sets such as returning data or multiple objects.
+
 
+
Default:
+
<tt>CacheUsage.UseEntityDefault</tt>
+
Note: this default is <tt>DoNotCheckCache</tt>.
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Configuring Cache Usage for In-Memory Queries|Configuring Cache Usage for In-Memory Queries]].
+
 
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.CacheUsage;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint(QueryHints.CACHE_USAGE, CacheUsage.CheckCacheOnly);
+
 
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.CacheUsage;
+
import org.eclipse.persistence.config.TargetDatabase;
+
@QueryHint(name=QueryHints.CACHE_USAGE, value=CacheUsage.CheckCacheOnly);
+
 
+
====Query Type====
+
The <tt>eclipselink.query-type</tt> hint specifies the EclipseLink query type to use for the query.
+
 
+
For most JP QL queries, the <tt>org.eclipse.persistence.queries.ReportQuery</tt> or <tt>org.eclipse.persistence.queries.ReadAllQuery</tt> are used. The <tt>eclipselink.query-type</tt> hint lets you use other query types, such as <tt>org.eclipse.persistence.queries.ReadObjectQuery</tt> for queries that are know to return a single object.
+
 
+
For more information, see the following:
+
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Object-Level Read Query|Object-Level Read Query]]
+
* [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Data-Level Modify Query|Data-Level Modify Query]]
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.QueryType</tt><nowiki>:</nowiki>
+
* <tt>Auto</tt> – EclipseLink chooses the type of query to use.
+
* <tt>ReadAll</tt> – Use the [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#ReadAllQuery|ReadAllQuery]] type for the query.
+
* <tt>ReadObject</tt> – Use the [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#|ReadObjectQuery]] type for the query.
+
* <tt>Report</tt> – Use the [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Report Query|Report Query]] type for the query.
+
 
+
Default: <tt>QueryType.Auto</tt>
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.QueryType;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint(QueryHints.QUERY_TYPE, QueryType.ReadObject);
+
 
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.QueryType;
+
import org.eclipse.persistence.config.TargetDatabase;
+
@QueryHint(name=QueryHints.QUERY_TYPE, value=QueryType.ReadObject);
+
 
+
====Bind Parameters====
+
The <tt>eclipselink.jdbc.bind-parameters</tt> hint controls whether or not the query uses parameter binding.
+
 
+
For more information, see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)#How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization|How to Use Parameterized SQL (Parameter Binding) and Prepared Statement Caching for Optimization]].
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.HintValues</tt><nowiki>:</nowiki>
+
* <tt>TRUE</tt> – bind all parameters.
+
* <tt>FALSE</tt> – do not bind all parameters.
+
* <tt>PERSISTENCE_UNIT_DEFAULT</tt> – use the parameter binding setting made in your EclipseLink session's database login, which is <tt>true</tt> by default.<br><br>For more information, see [[Configuring%20a%20Database%20Login%20(ELUG)#Configuring JDBC Options|Configuring JDBC Options]].
+
 
+
Default: <tt>HintValues.PERSISTENCE_UNIT_DEFAULT</tt>
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint(QueryHints.BIND_PARAMETERS, HintValues.TRUE);
+
 
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.TargetDatabase;
+
@QueryHint(name=QueryHints.BIND_PARAMETERS, value=HintValues.TRUE);
+
 
+
====Fetch Size====
+
The <tt>eclipselink.jdbc.fetch-size</tt> hint specifies the number of rows that should be fetched from the database when more rows are needed<sup>1</sup>
+
 
+
For large queries that return a large number of objects you can configure the row fetch size used in the query to improve performance by reducing the number database hits required to satisfy the selection criteria. Most JDBC drivers default to a fetch size of 10, so if you are reading 1000 objects, increasing the fetch size to 256 can significantly reduce the time required to fetch the query's results. The optimal fetch size is not always obvious. Usually, a fetch size of one half or one quarter of the total expected result size is optimal. Note that if you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.
+
 
+
A value of 0 means the JDBC driver default will be used.
+
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
 
+
Default: 0
+
 
+
Note: this value indicates that the JDBC driver default will be used.
+
 
+
<br><sup>1</sup> This property is dependent on the JDBC driver support.
+
 
+
====Timeout====
+
The <tt>eclipselink.jdbc.timeout</tt> hint specifies the number of seconds EclipseLink will wait on a query before throwing a <tt>DatabaseException</tt><sup>1</sup>
+
 
+
A value of 0 means EclipseLink will never time-out a query.
+
 
+
Valid values: 0 to <tt>Integer.MAX_VALUE</tt> (depending on your JDBC driver) as a <tt>String</tt>.
+
 
+
Default: 0
+
 
+
<br><sup>1</sup> This property is dependent on the JDBC driver support.
+
 
+
====Pessimistic Lock====
+
The <tt>eclipselink.pessimistic-lock</tt> hint controls whether or not pessimistic locking is used.
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.PessimisticLock</tt><nowiki>:</nowiki>
+
* <tt>NoLock</tt> – pessimistic locking is not used.
+
* <tt>Lock</tt> – EclipseLink issues a <tt>SELECT .... FOR UPDATE</tt>.
+
* <tt>LockNoWait</tt> – EclipseLink issues a <tt>SELECT .... FOR UPDATE NO WAIT</tt>.
+
 
+
Default: <tt>NoLock</tt>
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.PessimisticLock;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint(QueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);
+
 
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.PessimisticLock;
+
import org.eclipse.persistence.config.QueryHints;
+
@QueryHint(name=QueryHints.PESSIMISTIC_LOCK, value=PessimisticLock.LockNoWait);
+
 
+
====Batch====
+
The <tt>eclipselink.batch</tt> hint supplies EclipseLink with batching information so subsequent queries of related objects can be optimized in batches instead of being retrieved one-by-one or in one large joined read. Batch reading is more efficient than joining because it avoids reading duplicate data.
+
 
+
Batching is only allowed on queries that have a single object in their select clause.
+
 
+
Valid values: a single-valued relationship path expression.
+
 
+
Note: use dot notation to access nested attributes. For example, to batch-read an employee's manager's address, specify <tt>e.manager.address</tt>
+
 
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint("eclipselink.batch", "e.address");
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
@QueryHint(name=QueryHints.BATCH, value="e.address");
+
 
+
====Join Fetch====
+
The <tt>eclipselink.join-fetch</tt> hint allows joining of the attributes.
+
 
+
This is similar to <tt>eclipselink.batch</tt><nowiki>: subsequent queries of related objects can be optimized in batches instead of being retrieved in one large joined read.</nowiki>
+
 
+
This is different from JP QL joining because it allows multilevel fetch joins.
+
 
+
For more information, see Section 4.4.5.3 "Fetch Joins" of JPA specification.
+
 
+
Valid values: a relationship path expression.
+
 
+
Note: use dot notation to access nested attributes.
+
 
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint("eclipselink.join-fetch", "e.address");
+
 
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
@QueryHint(name=QueryHints.FETCH, value="e.address");
+
 
+
====Refresh====
+
The <tt>eclipselink.refresh</tt> hint controls whether or not to update the EclipseLink session cache with objects that the query returns.
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.HintValues</tt><nowiki>:</nowiki>
+
* <tt>TRUE</tt> – refresh cache.
+
* <tt>FALSE</tt> – do not refresh cache.
+
+
Default: <tt>FALSE</tt>
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint(QueryHints.REFRESH, HintValues.TRUE);
+
 
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
@QueryHint(name=QueryHints.REFRESH, value=HintValues.TRUE);
+
 
+
====Read Only====
+
The <tt>eclipselink.read-only</tt> hint retrieves read-only results back from the query: on nontransactional read operations, where the requested entity types are stored in the shared cache, you can request that the shared instance be returned instead of a detached copy.
+
 
+
Note: you should never modify objects returned from the shared cache.
+
 
+
The following are the valid values for the <tt>org.eclipse.persistence.config.HintValues</tt><nowiki>:</nowiki>
+
* <tt>TRUE</tt> – retrieve read-only results back from the query;
+
* <tt>FALSE</tt> – do not retrieve read-only results back from the query.
+
 
+
Default: <tt>FALSE</tt>
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint(QueryHints.READ_ONLY, HintValues.TRUE);
+
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
@QueryHint(name=QueryHints.READ_ONLY, value=HintValues.TRUE);
+
 
+
====Result Collection Type====
+
The <tt>eclipselink.result-collection-type</tt> hint configures the concrete class that EclipseLink should use to return its query result.
+
 
+
This lets you specify the type of collection in which the result will be returned.
+
 
+
Valid values: Java <tt>Class</tt> that implements the <tt>Collection</tt> interface.
+
 
+
Note: typically, you would execute these queries by calling the <tt>getResultsList</tt> method, which returns the java.util.List, on the <tt>Query</tt>. This means that the class specified in this hint must implement the <tt>List</tt> interface, if you are invoking it using the <tt>getResultsList</tt> method.
+
 
+
Note: specify the class without the <tt>".class"</tt> notation. For example, <tt>java.util.Vector</tt> would work, not <tt>java.util.Vector.class</tt>EclipseLink will throw an exception, if you use this hint with a class that does not implement the <tt>Collection</tt> interface.
+
 
+
Default:<tt>java.util.Vector</tt>
+
 
+
'''Example'''<nowiki>: JPA Query API</nowiki>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
query.setHint("eclipselink.result-collection-type", java.util.ArrayList.class);
+
 
+
'''Example'''<nowiki>: </nowiki><tt>@QueryHint</tt>
+
import org.eclipse.persistence.config.HintValues;
+
import org.eclipse.persistence.config.QueryHints;
+
@QueryHint(name=QueryHints.RESULT_COLLECTION_TYPE, value="java.util.ArrayList");
+
 
+
===How to Use EclipseLink Query API in JPA Queries===
+
EclipseLink JPA provides an EclipseLink implementation class for each JPA persistence interface. By casting to the EclipseLink implementation class, you have full access to EclipseLink functionality.
+
 
+
This section provides the following examples:
+
* [[#Creating a JPA Query Using the EclipseLink Expressions Framework|Creating a JPA Query Using the EclipseLink Expressions Framework]]
+
* [[#Creating a JPA Query Using an EclipseLink DatabaseQuery|Creating a JPA Query Using an EclipseLink DatabaseQuery]]
+
* [[#Creating a JPA Query Using an EclipseLink Call Object|Creating a JPA Query Using an EclipseLink Call Object]]
+
* [[#Using Named Parameters in a Native Query|Using Named Parameters in a Native Query]]
+
* [[#Using Java Persistence Query Language Positional Parameters in a Native Query|Using Java Persistence Query Language Positional Parameters in a Native Query]]
+
* [[#Using JDBC-Style Positional Parameters in a Native Query|Using JDBC-Style Positional Parameters in a Native Query]]
+
 
+
For more information, see [[EclipseLink/UserGuide/Queries (ELUG)|Queries]].
+
 
+
 
+
 
+
====Creating a JPA Query Using the EclipseLink Expressions Framework====
+
 
+
EclipseLink provides an expression framework with which you can express queries in a database-neutral fashion as an alternative to raw SQL.
+
 
+
This example shows how to cast an entity manager to access an EclipseLink persistence provider <tt>createQuery</tt> method that takes an EclipseLink <tt>Expression</tt>.
+
 
+
<span id="Example 19-26"></span>
+
''''' Creating a Query with the EclipseLink Expressions Framework'''''
+
((org.eclipse.persistence.jpa.JpaEntityManager)entityManager.getDelegate()).
+
                      createQuery(Expression expression, Class resultType);
+
 
+
 
+
EclipseLink expressions offer the following advantages over SQL when you access a database:
+
* Expressions are easier to maintain because the database is abstracted.
+
* Changes to descriptors or database tables do not affect the querying structures in the application.
+
* Expressions enhance readability by standardizing the <tt>Query</tt> interface so that it looks similar to traditional Java calling conventions.<br>For example, the Java code required to get the street name from the <tt>Address</tt> object of the <tt>Employee</tt> class looks like this:
+
emp.getAddress().getStreet().equals("Meadowlands");
+
+
The expression to get the same information is similar:
+
emp.get("address").get("street").equal("Meadowlands");
+
* Expressions allow read queries to transparently query between two classes that share a relationship. If these classes are stored in multiple tables in the database, EclipseLink automatically generates the appropriate join statements to return information from both tables.
+
* Expressions simplify complex operations.<br>For example, the following Java code retrieves all employees that live on "Meadowlands" whose salary is greater than 10,000:
+
ExpressionBuilder emp = new ExpressionBuilder();
+
Expression exp = emp.get("address").get("street").equal("Meadowlands");
+
Vector employees = session.readAllObjects(Employee.class,
+
exp.and(emp.get("salary").greaterThan(10000)));
+
+
EclipseLink automatically generates the appropriate SQL from the preceding code:
+
SELECT t0.VERSION, t0.ADDR_ID, t0.EMP_ID, t0.SALARY FROM EMPLOYEE t0, ADDRESS t1 WHERE (((t1.STREET = 'Meadowlands')AND (t0.SALARY > 10000)) AND (t1.ADDRESS_ID = t0.ADDR_ID))
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Expressions%20(ELUG)|Introduction to EclipseLink Expressions]].
+
 
+
 
+
 
+
====Creating a JPA Query Using an EclipseLink DatabaseQuery====
+
 
+
An EclipseLink <tt>[[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#DatabaseQuery|DatabaseQuery]]</tt> is a query object that provides a rich API for handling a variety of database query requirements, including reading and writing at the object level and at the data level.
+
 
+
This example shows how to cast a JPA query from an entity manager to access an EclipseLink persistence provider <tt>setDatabaseQuery</tt> method that takes an EclipseLink <tt>DatabaseQuery</tt>.
+
 
+
<span id="Example 19-27"></span>
+
''''' DatabaseQuery'''''
+
((org.eclipse.persistence.jpa.JpaQuery)query).setDatabaseQuery(DatabaseQuery query);
+
 
+
 
+
The following example shows how to cast a JPA query from an entity manager to access an EclipseLink persistence provider <tt>setDatabaseQuery</tt> method that takes an EclipseLink <tt>DataReadQuery</tt> initialized with an EclipseLink <tt>SQLCall</tt> object that specifies a <tt>SELECT</tt>. This query will return one or more objects.
+
 
+
<span id="Example 19-28"></span>
+
''''' DatabaseQuery with Selecting Call'''''
+
((org.eclipse.persistence.jpa.JpaQuery)query).
+
    setDatabaseQuery(new DataReadQuery(new SQLCall("SELECT...")));
+
 
+
 
+
The following example shows how to cast a JPA query from an entity manager to access an EclipseLink persistence provider <tt>setDatabaseQuery</tt> method that takes an EclipseLink <tt>DataModifyQuery</tt> initialized with an EclipseLink <tt>SQLCall</tt> object that specifies an <tt>UPDATE</tt>. This query will modify one or more objects; however, this query will not update the managed objects within the persistence context.
+
 
+
<span id="Example 19-29"></span>
+
''''' DatabaseQuery with Non-Selecting Call'''''
+
((org.eclipse.persistence.jpa.JpaQuery)query).
+
        setDatabaseQuery(new DataModifyQuery(new SQLCall("UPDATE...")));
+
 
+
 
+
 
+
====Creating a JPA Query Using an EclipseLink Call Object====
+
 
+
Using <tt>[[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#DatabaseQuery|DatabaseQuery]]</tt> method <tt>setCall</tt>, you can define your own EclipseLink <tt>Call</tt> to accommodate a variety of data source options, such as SQL stored procedures and stored functions, EJB QL queries, and EIS interactions.
+
 
+
This example shows how to cast a JPA query from an entity manager to access an EclipseLink persistence provider <tt>getDatabaseQuery</tt> method to set a new <tt>SQLCall</tt>.
+
 
+
<span id="Example 19-30"></span>
+
''''' Call'''''
+
((org.eclipse.persistence.jpa.JpaQuery)query).
+
                  getDatabaseQuery().setCall(new SQLCall("..."));
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Queries%20(ELUG)#Call Queries|Call Queries]].
+
 
+
 
+
 
+
====Using Named Parameters in a Native Query====
+
 
+
Using EclipseLink, you can specify a named parameter in a native query using the EclipseLink <tt><nowiki>#</nowiki></tt> convention (see the [[#Example 19-31|Specifying a Named Parameter with #]] example).
+
 
+
Support for the EclipseLink <tt><nowiki>#</nowiki></tt> convention is helpful if you are already familiar with EclipseLink queries or if you are migrating EclipseLink queries to a JPA application.
+
 
+
<span id="Example 19-31"></span>
+
''''' Specifying a Named Parameter with #'''''
+
Query queryEmployees = entityManager.createNativeQuery(
+
    "SELECT * FROM EMPLOYEE emp WHERE emp.fname LIKE #firstname");
+
queryEmployees.setParameter("firstName", "Joan");
+
Collection employees = queryEmployees.getResultList();
+
 
+
 
+
====Using JP QL Positional Parameters in a Native Query====
+
 
+
Using EclipseLink, you can specify positional parameters in a native query using the Java Persistence query language (JP QL) positional parameter convention <tt>?n</tt> to specify a parameter by number. For more information on JP QL, see [[Developing%20Applications%20Using%20EclipseLink%20JPA%20(ELUG)#What You May Need to Know About Querying with Java Persistence Query Language|What You May Need to Know About Querying with Java Persistence Query Language]].
+
 
+
This example shows how to specify positional parameters using the <tt>?n</tt> convention. In this example, the query string will be <tt>SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "C%"</tt>.
+
 
+
<span id="Example 19-32"></span>
+
''''' Specifying Positional Parameters Using ?'''''
+
Query queryEmployees = entityManager.createNativeQuery(
+
    "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ?1 AND L_NAME LIKE ?2", Employee.class);
+
queryEmployees.setParameter(1, "D%");
+
queryEmployees.setParameter(2, "C%");
+
Collection employees = queryEmployees.getResultList();
+
 
+
 
+
You can easily re-use the same parameter in more than one place in the query, as the following example shows. In this example, the query string will be <tt>SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "D%"</tt>.
+
 
+
<span id="Example 19-33"></span>
+
''''' Specifying Positional Parameters Using ?n'''''
+
Query queryEmployees = entityManager.createNativeQuery(
+
    "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ?1 AND L_NAME LIKE ?1", Employee.class);
+
queryEmployees.setParameter(1, "D%");
+
Collection employees = queryEmployees.getResultList();
+
 
+
 
+
 
+
====Using JDBC-Style Positional Parameters in a Native Query====
+
 
+
Using EclipseLink, you can specify positional parameters in a native query using the JDBC-style positional parameter <tt>?</tt> convention.
+
 
+
This example shows how to specify positional parameters using the <tt>?</tt> convention. Each occurrence of <tt>?</tt> must be matched by a corresponding <tt>setParameter</tt> call. In this example, the query string will be <tt>SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "C%"</tt>.
+
 
+
<span id="Example 19-34">
+
''''' Specifying Positional Parameters with ?'''''
+
Query queryEmployees = entityManager.createNativeQuery(
+
    "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ? AND L_NAME LIKE ?", Employee.class);
+
queryEmployees.setParameter(1, "D%");
+
queryEmployees.setParameter(2, "C%");
+
Collection employees = queryEmployees.getResultList();
+
 
+
 
+
If you want to re-use the same parameter in more than one place in the query, you must repeat the same parameter, as this example shows. In this example, the query string will be <tt>SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "D%"</tt>.
+
 
+
<span id="Example 19-35 "></span>
+
'''''Re-Using Positional Parameters with ?'''''
+
Query queryEmployees = entityManager.createNativeQuery(
+
    "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ? AND L_NAME LIKE ?", Employee.class);
+
queryEmployees.setParameter(1, "D%");
+
queryEmployees.setParameter(2, "D%");
+
Collection employees = queryEmployees.getResultList();
+
 
+
 
+
 
+
==Using EclipseLink JPA Weaving==
+
 
+
Weaving is a technique of manipulating the byte-code of compiled Java classes. The EclipseLink JPA persistence provider uses weaving to enhance JPA entities for such things as lazy loading, change tracking, fetch groups, and internal optimizations.
+
 
+
This section describes the following:
+
* [[#How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent|How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent]]
+
* [[#How to Configure Static Weaving for JPA Entities|How to Configure Static Weaving for JPA Entities]]
+
* [[#How to Disable Weaving Using EclipseLink Persistence Unit Propertie|How to Disable Weaving Using EclipseLink Persistence Unit Properties]]
+
* [[#What You May Need to Know About Weaving JPA Entities|What You May Need to Know About Weaving JPA Entities]]
+
 
+
 
+
 
+
===How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent===
+
 
+
Use this option to weave applicable class files one at a time, as they are loaded at run time. Consider this option when the number of classes to weave is few or the time taken to weave the classes is short.
+
 
+
If the number of classes to weave is large or the time required to weave the classes is long, consider using static weaving. For more information, see [[#How to Configure Static Weaving for JPA Entities|How to Configure Static Weaving for JPA Entities]].
+
 
+
 
+
'''To Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent'''
+
 
+
<ol>
+
<li> Configure your <tt>persistence.xml</tt> file with a <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> extension set to <tt>true</tt>, as this example shows.<br>
+
 
+
<span id="Example 19-36"></span>
+
''''' Setting eclipselink.weaving in the persistence.xml File'''''
+
 
+
<div class="pre">
+
<persistence>
+
    <persistence-unit name="HumanResources">
+
        <class>com.acme.Employee</class>
+
        ...
+
        <properties>
+
+
            <property
+
                name="eclipselink.weaving"
+
                value="true"
+
            >
+
        </properties>
+
    </persistence-unit>
+
</persistence>
+
</div><br>
+
For more information, see the [[#Table 19-16|EclipseLink JPA Persistence Unit Properties for Customization and Validation]] table.</li>
+
<li> Modify your application JVM command line to include the following:
+
<div class="pre">
+
-javaagent:eclipselink.jar
+
</div></li>
+
<li> Ensure that the <tt>eclipselink.jar</tt> is in your application classpath.
+
<li> Package and deploy your application.<br>For more information, see [[Packaging%20and%20Deploying%20EclipseLink%20JPA%20Applications%20(ELUG)#Packaging an EclipseLink JPA Application|Packaging an EclipseLink JPA Application]].
+
</li>
+
</ol>
+
EclipseLink weaves applicable class files one at a time, as they are loaded at run time.
+
 
+
 
+
 
+
===How to Configure Static Weaving for JPA Entities===
+
 
+
Use this option to weave all applicable class files at build time so that you can deliver pre-woven class files. Consider this option to weave all applicable class files at build time so that you can deliver prewoven class files. By doing so, you can improve application performance by eliminating the runtime weaving step required by dynamic weaving (see [[#How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent|How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent]]).
+
 
+
In addition, consider using this option to weave in Java environments where you cannot configure an agent.
+
 
+
 
+
====To Configure Static Weaving for JPA Entities====
+
 
+
<ol>
+
<li>Execute the static static weaver in one of the following ways:
+
<ol>
+
<li>Use the <tt>weave</tt> Ant task as follows:
+
<ul>
+
<li> Configure the <tt>weave</tt> Ant task in your build script, as this example shows. The [[#Table 19-31|EclipseLink weave Ant Task Attributes]] table lists the attributes of this task.<br>
+
<span id="Example 19-37"></span>
+
''''' EclipseLink weave Ant Task'''''
+
<div class="pre">
+
<target name="define.task" description="New task definition for EclipseLInk static weaving"/>
+
+
    <taskdef name="weave" classname="org.eclipse.persistence.tools.weaving.StaticWeaveAntTask"/>
+
</target>
+
<target name="weaving" description="perform weaving" depends="define.task">
+
    <weave  source="c:\myjar.jar"
+
            target="c:\wovenmyjar.jar"
+
            persistenceinfo="c:\myjar-containing-persistenceinfo.jar">
+
        <classpath>
+
            <pathelement path="c:\myjar-dependent.jar"/>
+
        </classpath>
+
+
    </weave>
+
</target>
+
</div>
+
<br>
+
<span id="Table 19-31"></span>
+
''''' EclipseLink <tt>weave</tt> Ant Task Attributes'''''
+
{| class="RuleFormalMax" dir="ltr" title="EclipseLink weave Ant Task Attributes" summary="This table lists the attributes of the EclipseLink JPA weave Ant task." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t47" align="left" valign="bottom" | '''Attribute'''
+
! id="r1c2-t47" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t47" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t47" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t47" headers="r1c1-t47" align="left" |
+
<tt>source</tt>
+
| headers="r2c1-t47 r1c2-t47" align="left" |
+
Specifies the location of the Java source files to weave: either a directory or a JAR file.
+
 
+
If the <tt>persistence.xml</tt> file is not in this location, you must specify the location of the <tt>persistence.xml</tt> using the <tt>persistenceinfo</tt> attribute.
+
| headers="r2c1-t47 r1c3-t47" align="left" | <br>
+
| headers="r2c1-t47 r1c4-t47" align="left" |
+
Required
+
|- align="left" valign="top"
+
| id="r3c1-t47" headers="r1c1-t47" align="left" |
+
<tt>target</tt>
+
| headers="r3c1-t47 r1c2-t47" align="left" |
+
Specifies the output location: either a directory or a JAR file.
+
| headers="r3c1-t47 r1c3-t47" align="left" | <br>
+
| headers="r3c1-t47 r1c4-t47" align="left" |
+
Required
+
|- align="left" valign="top"
+
| id="r4c1-t47" headers="r1c1-t47" align="left" |
+
<tt>persistenceinfo</tt>
+
| headers="r4c1-t47 r1c2-t47" align="left" |
+
Specifies the location of the <tt>persistence.xml</tt> file if it is not in the same location as the source.
+
| headers="r4c1-t47 r1c3-t47" align="left" | <br>
+
| headers="r4c1-t47 r1c4-t47" align="left" |
+
Optional
+
|- align="left" valign="top"
+
| id="r5c1-t47" headers="r1c1-t47" align="left" |
+
<tt>log</tt>
+
| headers="r5c1-t47 r1c2-t47" align="left" |
+
Specifies a logging file.
+
| headers="r5c1-t47 r1c3-t47" align="left" |
+
See [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+
| headers="r5c1-t47 r1c4-t47" align="left" |
+
Optional
+
|- align="left" valign="top"
+
| id="r6c1-t47" headers="r1c1-t47" align="left" |
+
<tt>loglevel</tt>
+
| headers="r6c1-t47 r1c2-t47" align="left" |
+
Specifies the amount and detail of log output.
+
 
+
Valid <tt>java.util.logging.Level</tt> values are the following:
+
* <tt>OFF</tt>
+
* <tt>SEVERE</tt>
+
* <tt>WARNING</tt>
+
* <tt>INFO</tt>
+
* <tt>CONFIG</tt>
+
* <tt>FINE</tt>
+
* <tt>FINER</tt>
+
* <tt>FINEST</tt>
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+
| headers="r6c1-t47 r1c3-t47" align="left" |
+
<tt>Level.OFF</tt>
+
| headers="r6c1-t47 r1c4-t47" align="left" |
+
Optional
+
|}
+
<br><br>
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' If <tt>source</tt> and <tt>target</tt> point to the same location and, if the <tt>source</tt> is a directory (not a JAR file), EclipseLink will weave in place. If <tt>source</tt> and <tt>target</tt> point to different locations, or if the <tt>source</tt> is a JAR file (as the [[#Example 19-37|EclipseLink weave Ant Task]] example shows), EclipseLink cannot weave in place.
+
|}
+
<br></li>
+
<li> Configure the <tt>weave</tt> task with an appropriate <tt><classpath></tt> element, as the [[#Example 19-37|EclipseLink weave Ant Task]] example shows, so that EclipseLink can load all required source classes.</li>
+
<li> Execute the Ant task using the command line that this example shows.<br>In this example, the <tt>weave</tt> Ant task is in the <tt>build.xml</tt> file:<br>
+
 
+
<span id="Example 19-38"></span>
+
''''' EclipseLink weave Ant Task Command Line'''''
+
<div class="pre">
+
ant -lib C:\eclipselink.jar -f build.xml weave
+
</div>
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' You must specify the <tt>eclipselink.jar</tt> file (the JAR that contains the EclipseLink <tt>weave</tt> Ant task) using the Ant command line <tt>-lib</tt> option instead of using the <tt>taskdef</tt> attribute <tt>classpath</tt>.
+
|}
+
 
+
<br>
+
</li></ul>
+
</li>
+
<li>Use the command line as follows: <br>
+
<div class="pre">
+
<tt><nowiki> java org.eclipse.persistence.tools.weaving.StaticWeave [arguments] <source> <target></nowiki></tt>
+
</div>
+
<br>The following example shows how to use the <tt>StaticWeave</tt> class on Windows systems. The [[#Table 19-32|EclipseLink StaticWeave Class Command Line Arguments]] table lists the arguments of this class.<br>
+
<span id="Example 19-39"></span>
+
''''' Executing StaticWeave on the Command Line'''''
+
<div class="pre">
+
java org.eclipse.persistence.tools.weaving.StaticWeave  -persistenceinfo c:\myjar-containing-persistencexml.jar
+
-classpath c:\classpath1;c:\classpath2 c:\myjar-source.jar c:\myjar-target.jar
+
</div>
+
<br>
+
 
+
<span id="Table 19-32"></span>
+
''''' EclipseLink StaticWeave Class Command Line Arguments'''''
+
 
+
{| class="RuleFormalMax" dir="ltr" title="EclipseLink StaticWeave Class Command Line Arguments" summary="This table lists the arguments of the EclipseLink JPA StaticWeave class." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t50" align="left" valign="bottom" | '''Argument'''
+
! id="r1c2-t50" align="left" valign="bottom" | '''Description'''
+
! id="r1c3-t50" align="left" valign="bottom" | '''Default'''
+
! id="r1c4-t50" align="left" valign="bottom" | '''Required or Optional'''
+
|- align="left" valign="top"
+
| id="r2c1-t50" headers="r1c1-t50" align="left" |
+
<tt>-persistenceinfo</tt>
+
| headers="r2c1-t50 r1c2-t50" align="left" |
+
Specifies the location of the <tt>persistence.xml</tt> file if it is not in the same location as the source (see <tt>-classpath</tt>).
+
| headers="r2c1-t50 r1c3-t50" align="left" | <br>
+
| headers="r2c1-t50 r1c4-t50" align="left" |
+
Optional
+
|- align="left" valign="top"
+
| id="r3c1-t50" headers="r1c1-t50" align="left" |
+
<tt>-classpath</tt>
+
| headers="r3c1-t50 r1c2-t50" align="left" |
+
Specifies the location of the Java source files to weave: either a directory or a JAR file. For Windows systems, use delimiter <tt>" ; "</tt>, and for Unix, use delimiter <tt>" : "</tt>.
+
 
+
If the <tt>persistence.xml</tt> file is not in this location, you must specify the location of the <tt>persistence.xml</tt> using the <tt>-persistenceinfo</tt> attribute.
+
| headers="r3c1-t50 r1c3-t50" align="left" | <br>
+
| headers="r3c1-t50 r1c4-t50" align="left" |
+
Required
+
|- align="left" valign="top"
+
| id="r4c1-t50" headers="r1c1-t50" align="left" |
+
<tt>-log</tt>
+
| headers="r4c1-t50 r1c2-t50" align="left" |
+
Specifies a logging file.
+
| headers="r4c1-t50 r1c3-t50" align="left" |
+
See [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+
| headers="r4c1-t50 r1c4-t50" align="left" |
+
Optional
+
|- align="left" valign="top"
+
| id="r5c1-t50" headers="r1c1-t50" align="left" |
+
<tt>-loglevel</tt>
+
| headers="r5c1-t50 r1c2-t50" align="left" |
+
Specifies the amount and detail of log output.
+
 
+
Valid <tt>java.util.logging.Level</tt> values are as follows:
+
* <tt>OFF</tt>
+
* <tt>SEVERE</tt>
+
* <tt>WARNING</tt>
+
* <tt>INFO</tt>
+
* <tt>CONFIG</tt>
+
* <tt>FINE</tt>
+
* <tt>FINER</tt>
+
* <tt>FINEST</tt>
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+
| headers="r5c1-t50 r1c3-t50" align="left" |
+
<tt>Level.OFF</tt>
+
| headers="r5c1-t50 r1c4-t50" align="left" |
+
Optional
+
|- align="left" valign="top"
+
| id="r6c1-t50" headers="r1c1-t50" align="left" |
+
<tt><nowiki><source></nowiki></tt>
+
| headers="r6c1-t50 r1c2-t50" align="left" |
+
Specifies the location of the Java source files to weave: either a directory or a JAR file.
+
 
+
If the <tt>persistence.xml</tt> file is not in this location, you must specify the location of the <tt>persistence.xml</tt> using the [[#-persistenceinfo|<tt>-persistenceinfo</tt>]] attribute.
+
| headers="r6c1-t50 r1c3-t50" align="left" | <br>
+
| headers="r6c1-t50 r1c4-t50" align="left" |
+
Required
+
|- align="left" valign="top"
+
| id="r7c1-t50" headers="r1c1-t50" align="left" |
+
<tt><target></tt>
+
| headers="r7c1-t50 r1c2-t50" align="left" |
+
Specifies the output location: either a directory or a JAR file.
+
| headers="r7c1-t50 r1c3-t50" align="left" | <br>
+
| headers="r7c1-t50 r1c4-t50" align="left" |
+
Required
+
|}
+
<br><br>
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' If <tt><nowiki><source></nowiki></tt> and <tt><target></tt> point to the same location and if the <tt><nowiki><source></nowiki></tt> is a directory (not a JAR file), EclipseLink will weave in place. If <tt><nowiki><source></nowiki></tt> and <tt><target></tt> point to different locations, or if the <tt>source</tt> is a JAR file (as the [[#Example 19-39| Executing StaticWeave on the Command Line]] example shows), EclipseLink cannot weave in place.
+
|}
+
<br>
+
</li></ol>
+
</li>
+
<li> Configure your <tt>persistence.xml</tt> file with a <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> extension set to <tt>static</tt>, as this example shows:<br>
+
 
+
<span id="Example 19-40"></span>
+
 
+
''''' Setting eclipselink.weaving in the persistence.xml File'''''
+
<div class="pre">
+
<persistence>
+
    <persistence-unit name="HumanResources">
+
        <class>com.acme.Employee</class>
+
        ...
+
        <properties>
+
+
            <property
+
                name="eclipselink.weaving"
+
                value="static"
+
            >
+
        </properties>
+
    </persistence-unit>
+
</persistence>
+
</div>
+
<br>
+
For more information, see the [[#Table 19-16|EclipseLink JPA Persistence Unit Properties for Customization and Validation]] table.
+
</li>
+
<li>Package and deploy your application.<br>For more information, see [[Packaging%20and%20Deploying%20EclipseLink%20JPA%20Applications%20(ELUG)#Packaging and Deploying EclipseLink JPA Applications|Packaging and Deploying EclipseLink JPA Applications]].
+
</li>
+
</ol>
+
 
+
 
+
 
+
===How to Disable Weaving Using EclipseLink Persistence Unit Properties===
+
 
+
To disable weaving, you use persistence unit properties.
+
 
+
 
+
====To Disable Weaving Using EclipseLink Persistence Unit Properties====
+
 
+
<ol>
+
<li>Configure your <tt>persistence.xml</tt> file with one or more of the following properties set to <tt>false</tt><nowiki>:</nowiki>
+
* <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> – disables all weaving;
+
* <tt>[[#eclipselink.weaving.lazy|eclipselink.weaving.lazy]]</tt> – disables weaving for lazy loading (indirection);
+
* <tt>[[#eclipselink.weaving.changetracking|eclipselink.weaving.changetracking]]</tt> –  disables weaving for change tracking;
+
* <tt>[[#eclipselink.weaving.fetchgroups|eclipselink.weaving.fetchgroups]]</tt> – disables weaving for fetch groups.
+
* <tt>[[#eclipselink.weaving.internal|eclipselink.weaving.internal]]</tt> – disables weaving for internal optimization.
+
* <tt>[[#eclipselink.weaving.eager|eclipselink.weaving.eager]]</tt> – disables weaving for indirection on eager relationships.<br><br>
+
This example shows how to disable weaving for change tracking only.
+
<br>
+
<span id="Example 19-41"></span>
+
''''' Disabling Weaving for Change Tracking in the persistence.xml File'''''
+
<div class="pre">
+
<persistence>
+
    <persistence-unit name="HumanResources">
+
        <class>com.acme.Employee</class>
+
+
        ...
+
        <properties>
+
            <property
+
                name="eclipselink.weaving.changetracking"
+
                value="false"
+
            >
+
        </properties>
+
    </persistence-unit>
+
</persistence>
+
</div>
+
 
+
The following example shows how to disable all weaving: in this example, EclipseLink does not weave for lazy loading (indirection), change tracking, or internal optimization.
+
 
+
<span id="Example 19-42"></span>
+
''''' Disabling All Weaving in the persistence.xml File'''''
+
<div class="pre">
+
<persistence>
+
    <persistence-unit name="HumanResources">
+
        <class>com.acme.Employee</class>
+
+
        ...
+
        <properties>
+
            <property
+
                name="eclipselink.weaving"
+
                value="false"
+
            >
+
        </properties>
+
    </persistence-unit>
+
</persistence>
+
</div>
+
 
+
For more information, see the [[#Table 19-16|EclipseLink JPA Persistence Unit Properties for Customization and Validation]] table.
+
</li>
+
<li>Package and and deploy your application. For more information, see [[Packaging%20and%20Deploying EclipseLink%20JPA%20Applications%20(ELUG)#Packaging and Deploying EclipseLink JPA Applications|Packaging and Deploying EclipseLink JPA Applications]].
+
</li>
+
</ol>
+
 
+
 
+
 
+
===What You May Need to Know About Weaving JPA Entities===
+
 
+
The EclipseLink JPA persistence provider uses weaving to enable the following features for JPA entities:
+
 
+
* lazy loading (indirection): see [[Developing%20Applications%20Using%20EclipseLink%20JPA%20(ELUG)#How to Configure Lazy Loading|How to Configure Lazy Loading]]<nowiki>;</nowiki>
+
* change tracking: see [[Developing%20Applications%20Using%20EclipseLink%20JPA%20(ELUG)#How to Configure Change Tracking|How to Configure Change Tracking]]<nowiki>;</nowiki>
+
* fetch groups: see [[Developing%20Applications%20Using%20EclipseLink%20JPA%20(ELUG)#How to Configure Fetch Groups|How to Configure Fetch Groups]]<nowiki>;</nowiki>
+
* internal optimizations: see [[Optimizing%20the%20EclipseLink%20Application%20(ELUG)|Optimizing the EclipseLink Application]].
+
 
+
EclipseLink weaves all the JPA entities in a given persistence unit. That is the following:
+
 
+
* all classes you list in <tt>persistence.xml</tt> file;
+
* if element <tt><exclude-unlisted-classes></tt> is <tt>false</tt>, or deployed in Java EE, all classes in the JAR file containing the <tt>persistence.xml</tt> file;
+
* all classes you list in the <tt>orm.xml</tt> file.
+
 
+
For more information, see [[Introduction%20to%20EclipseLink%20Application%20Development%20(ELUG)#What You May Need to Know About Weaving and Java EE Application Servers|What You May Need to Know About Weaving and Java EE Application Servers]].
+
 
+
 
+
 
+
==What You May Need to Know About EclipseLink JPA Lazy Loading==
+
 
+
JPA specifies that lazy loading is a hint to the persistence provider that data should be fetched lazily when it is first accessed, if possible.
+
 
+
If you are developing your application in a Java EE environment, you only have to set fetch to <tt>javax.persistence.FetchType.LAZY</tt>, and EclipseLink persistence provider will supply all the necessary functionality.
+
 
+
When using a [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|one-to-one]] or [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToOne|many-to-one]] mapping in a Java SE environment, to configure EclipseLink JPA to perform lazy loading when the <tt>fetch</tt> attribute is set to <tt>FetchType.LAZY</tt>, configure either dynamic or static weaving.
+
 
+
When using a [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|one-to-one]] or [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToOne|many-to-one]] mapping in a Java SE environment that does not permit the use of <tt>-javaagent</tt> on the JVM command line, to configure EclipseLink JPA to perform lazy loading when annotation attribute <tt>fetch</tt> is set to <tt>javax.persistence.FetchType.LAZY</tt>, you can use static weaving.
+
 
+
The [[#Table 19-33|EclipseLink JPA Support for Lazy Loading by Mapping Type]] table lists EclipseLink JPA support for lazy loading by mapping type.
+
 
+
For more information, see the following:
+
* [[#How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent|How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent]]
+
* [[#How to Configure Static Weaving for JPA Entities|How to Configure Static Weaving for JPA Entities]]
+
* [[#How to Disable Weaving Using EclipseLink Persistence Unit Properties|How to Disable Weaving Using EclipseLink Persistence Unit Properties]]
+
* [[#What You May Need to Know About Weaving JPA Entities|What You May Need to Know About Weaving JPA Entities]]
+
* [[Configuring%20a%20Mapping%20(ELUG)#Configuring Indirection (Lazy Loading)|Configuring Indirection (Lazy Loading)]]
+
 
+
 
+
<span id="Table 19-33"></span>
+
''''' EclipseLink JPA Support for Lazy Loading by Mapping Type'''''
+
 
+
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink JPA Support for Lazy Loading by Mapping Type" summary="This table lists EclipseLink JPA mapping support for lazy loading by mapping type for Java EE (in container) and Java SE (outside of container) applications." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|- align="left" valign="top"
+
! id="r1c1-t52" align="left" valign="bottom" | '''Mapping'''
+
! id="r1c2-t52" align="left" valign="bottom" | '''Java EE''' <sup> 1 </sup>
+
! id="r1c3-t52" align="left" valign="bottom" | '''Java SE'''
+
|- align="left" valign="top"
+
| id="r2c1-t52" headers="r1c1-t52" align="left" |
+
[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToMany|many-to-many]]
+
| headers="r2c1-t52 r1c2-t52" align="left" |
+
EclipseLink JPA performs lazy loading when the <tt>fetch</tt> attribute is set to <tt>javax.persistence.FetchType.LAZY</tt> (default).
+
| headers="r2c1-t52 r1c3-t52" align="left" |
+
EclipseLink JPA performs lazy loading when the <tt>fetch</tt> attribute is set to <tt>javax.persistence.FetchType.LAZY</tt> (default).
+
|- align="left" valign="top"
+
| id="r3c1-t52" headers="r1c1-t52" align="left" |
+
[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToMany|one-to-many]]
+
| headers="r3c1-t52 r1c2-t52" align="left" |
+
EclipseLink JPA performs lazy loading when the <tt>fetch</tt> attribute is set to <tt>javax.persistence.FetchType.LAZY</tt> (default).
+
| headers="r3c1-t52 r1c3-t52" align="left" |
+
EclipseLink JPA performs lazy loading when the <tt>fetch</tt> attribute is set to <tt>javax.persistence.FetchType.LAZY</tt> (default).
+
|- align="left" valign="top"
+
| id="r4c1-t52" headers="r1c1-t52" align="left" |
+
[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@OneToOne|one-to-one]]
+
| headers="r4c1-t52 r1c2-t52" align="left" |
+
EclipseLink JPA performs lazy loading when the <tt>fetch</tt> attribute is set to <tt>javax.persistence.FetchType.LAZY</tt>.
+
| headers="r4c1-t52 r1c3-t52" align="left" |
+
By default, EclipseLink JPA ignores the <tt>fetch</tt> attribute and default javax.persistence.<tt>FetchType.EAGER</tt> applies.
+
 
+
To configure EclipseLink JPA to perform lazy loading when the <tt>fetch</tt> attribute set to <tt>FetchType.LAZY</tt>, consider one of the following:
+
* [[#How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent|How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent]]
+
* [[#How to Configure Static Weaving for JPA Entities|How to Configure Static Weaving for JPA Entities]]
+
|- align="left" valign="top"
+
| id="r5c1-t52" headers="r1c1-t52" align="left" |
+
[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToOne|many-to-one]]
+
| headers="r5c1-t52 r1c2-t52" align="left" |
+
EclipseLink JPA performs lazy loading when the <tt>fetch</tt> attribute is set to <tt>javax.persistence.FetchType.LAZY</tt>.
+
| headers="r5c1-t52 r1c3-t52" align="left" |
+
By default, EclipseLink JPA ignores the <tt>fetch</tt> attribute and default <tt>javax.persistence.FetchType.EAGER</tt> applies.
+
 
+
To configure EclipseLink JPA to perform lazy loading when the <tt>fetch</tt> attribute set to <tt>FetchType.LAZY</tt>, configure one of the following:
+
* [[#How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent|How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent]]
+
* [[#How to Configure Static Weaving for JPA Entities|How to Configure Static Weaving for JPA Entities]]
+
|- align="left" valign="top"
+
| id="r6c1-t52" headers="r1c1-t52" align="left" |
+
[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|basic]]
+
| headers="r6c1-t52 r1c2-t52" align="left" |
+
EclipseLink JPA performs lazy loading when the <tt>fetch</tt> attribute is set to <tt>javax.persistence.FetchType.LAZY</tt>.
+
| headers="r6c1-t52 r1c3-t52" align="left" |
+
By default, EclipseLink JPA ignores the <tt>fetch</tt> attribute and default javax.persistence.<tt>FetchType.EAGER</tt> applies.
+
 
+
To configure EclipseLink JPA to perform lazy loading when the <tt>fetch</tt> attribute set to <tt>FetchType.LAZY</tt>, consider one of the following:
+
* [[#How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent|How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent]]
+
* [[#How to Configure Static Weaving for JPA Entities|How to Configure Static Weaving for JPA Entities]]
+
|}
+
<br><sup> 1 </sup>Fully supported in any container that implements the appropriate container contracts in the EJB 3.0 specification.<br>
+
 
+
 
+
 
+
 
+
==What You May Need to Know About Overriding Annotations in JPA==
+
 
+
In JPA, you override any annotation with XML in your object relational mapping files (see [[#Overriding Annotations with XML|Overriding Annotations with XML]]).
+
 
+
In EclipseLink JPA, you either use JPA processing, or you specify the <tt>sessions.xml</tt> file resulting in creation of the <tt>project.xml</tt> file. For more information, see [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]].
+
 
+
 
+
 
+
===Overriding Annotations with XML===
+
 
+
In JPA, you can use XML mapping metadata on its own, or in combination with annotation metadata, or you can use it to override the annotation metadata.
+
 
+
If you choose to include one or more mapping XML files in your persistence unit, each file must conform and be valid against the <tt>orm_1_0.xsd</tt> schema located at <tt>http://java.sun.com/xml/ns/persistence/orm_1_0.xsd</tt>. This schema defines a namespace called <tt>http://java.sun.com/xml/ns/persistence/orm</tt> that includes all of the ORM elements that you can use in your mapping file.
+
 
+
All object relational XML metadata is contained within the <tt>entity-mappings</tt> root element of the mapping file. The subelements of <tt>entity-mappings</tt> can be categorized into four main scoping and functional groups: persistence unit defaults, mapping file defaults, queries and generators, and managed classes and mappings. There is also a special setting that determines whether annotations should be considered in the metadata for the persistence unit (see [[#Disabling Annotations|Disabling Annotations]]).
+
 
+
For more information and examples, see Section 10.1 "XML Overriding Rules" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].
+
 
+
 
+
 
+
====Disabling Annotations====
+
 
+
JPA provides a mechanism that you can use to disable annotations. If you do not feel the need for annotations in your application, you can use the <tt>xml-mapping-metadata-complete</tt> and <tt>metadata-complete</tt> mapping file elements to disable any existing annotations. Setting this options causes the processor to completely ignore annotations.
+
 
+
When you specify the <tt>xml-mapping-metadata-complete</tt> element, all annotations in the persistence unit will be ignored, and only mapping files in the persistence unit will be considered as the total set of provided metadata. Only entities (see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]), mapped superclasses (see [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@MappedSuperclass|@MappedSuperclass]]), and embedded objects (see [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Embedded|@Embedded]]) that have entries in a mapping file will be added to the persistence unit. The <tt>xml-mapping-metadata-complete</tt> element has to be in only one of the mapping files in the persistence unit. You specify it as an empty subelement of the <tt>persistence-unit-metadata</tt> element, as this example shows:
+
 
+
<span id="Example 19-43"></span>
+
''''' Disabling Annotations for the Persistence Unit in the Mapping File'''''
+
<entity-mappings>
+
    <persistence-unit-metadata>
+
        <xml-mapping-metadata-complete/>
+
    </persistence-unit-metadata>
+
    ...
+
+
</entity-mappings>
+
 
+
 
+
You can also use the <tt>metadata-complete</tt> attribute of the <tt>entity</tt>, <tt>mapped-superclass</tt>, and <tt>embeddable</tt> elements. If you specify this attribute, all annotations on the specified class and on any fields or properties in the class will be ignored – only metadata in the mapping file will be considered as the set of metadata for the class. However, even though the annotations are ignored, the default mapping still applies, so any fields or properties that should not be mapped must still be marked as transient in the XML file, as this example demonstrates.
+
 
+
<span id="Example 19-44"></span>
+
''''' Disabling Annotations for a Managed Class in the Mapping File'''''
+
+
@Entity
+
public class Employee {
+
+
    @Id
+
    private int id;
+
+
    @Column(name="EMP_NAME")
+
    private String name;
+
+
    @Column(name="SALARY")
+
    private long salary;
+
+
    ...
+
}
+
+
<entity-mappings>
+
    ...
+
    <entity class="mypackage.Employee" '''metadata-complete="true"'''>
+
        <attributes>
+
            <id name="id"/>
+
+
        </attributes>
+
    </entity>
+
    ...
+
</entity-mappings>
+
 
+
 
+
In the preceding example, the entity mappings in the annotated class are disabled by the <tt>metadata-complete</tt> attribute, and because the fields are not mapped in the mapping file, the default mapping values will be used. The <tt>name</tt> and <tt>salary</tt> fields will be mapped to the <tt>NAME</tt> and <tt>SALARY</tt> columns, respectively.
+
 
+
For more information, see Section 10.1 "XML Overriding Rules" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].
+
 
+
 
+
 
+
====Advantages and Disadvantages of Using Annotations====
+
 
+
Metadata annotations are relatively simple to use and understand. They provide in-line metadata located with the code that this metadata is describing – you do not need to replicate the source code context of where the metadata applies.
+
 
+
On the other hand, annotations unnecessarily couple the metadata to the code. Thus, changes to metadata require changing the source code.
+
 
+
 
+
 
+
====Advantages and Disadvantages of Using XML====
+
 
+
The following are the advantages of using XML:
+
* no coupling between the metadata and the source code;
+
* compliance with the existing, pre-EJB 3.0 development process;
+
* support in IDEs and source control systems.
+
 
+
The main disadvantages of mapping with XML are the complexity and the need for replication of the code context.
+
 
+
 
+
 
+
==What You May Need to Know About EclipseLink JPA Overriding Mechanisms==
+
 
+
EclipseLink JPA provides a set of persistence unit properties (see [[#What you May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What you May Need to Know About Using EclipseLink JPA Persistence Unit Properties]]) that you can specify in your <tt>persistence.xml</tt> file. The persistence unit properties always override the corresponding annotations' attributes.
+
 
+
Similar to EclipseLink annotations, properties expose some features of EclipseLink that are currently not available through the use of JPA metadata.
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' If multiple instances of the same property are set, then EclipseLink will use the values from the last entry in the list. However, the properties Map provided in the <tt>createEntityManagerFactory</tt> method will always have precedence.
+
|}
+
 
+
 
+
You can also specify the persistence information in the EclipseLink session configuration file – <tt>sessions.xml</tt> (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Session Configuration and the sessions.xml File]]). By setting the <tt>[[#eclipselink.sessions-xml|eclipselink.sessions-xml]]</tt> persistence unit property you enable EclipseLink to replace all class annotations and object relational mappings that you defined in the <tt>persistence.xml</tt> file, as well as mapping files (if present). Through the <tt>sessions.xml</tt> file the <tt>eclipselink.sessions-xml</tt> property lets you provide session-level configurations that are not supported by persistence unit properties (for example, cache coordination).
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' You can use the <tt>eclipselink.sessions-xml</tt> property as an alternative to annotations and deployment XML.
+
|}
+
 
+
 
+
For more information on creating and configuring the <tt>sessions.xml</tt> file, see the following:
+
* [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)|Acquiring a Session at Run Time with the Session Manager]]
+
* [[Introduction to EclipseLink%20Application%20Development%20(ELUG)|Building and Using the Persistence Layer]]
+
* [[Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)|Loading project.xml or sessions.xml Files]]
+
* [[Introduction%20to%20EclipseLink%20Development%20Tools%20(ELUG)|Development Environment]]
+
* [[Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)|Introduction to the EclipseLink Deployment File Creation]]
+
* [[Packaging%20a%20EclipseLink%20Application%20(ELUG)|Packaging an EclipseLink Application]]
+
* [[Introduction%20to%20XML%20Projects%20(ELUG)|EclipseLink Sessions XML File]]
+
* [[Creating%20a%20Session%20(ELUG)|Introduction to the Session Creation]]
+
* [[Creating%20a%20Session%20(ELUG)|Creating a Sessions Configuration]]
+
* [[Creating%20a%20Session%20(ELUG)|Configuring a Sessions Configuration]]
+
* [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Introduction to Session Acquisition]]
+
 
+
In summary, EclipseLink JPA possesses an overriding mechanism that you can use in the following ways:
+
 
+
* You can combine the use of JPA annotations, object relational mapping files (such as <tt>orm.xml</tt>) and persistence unit properties.In this case, EclipseLink persistence provider builds metadata starting with applying defaults, then JPA annotations, and then overrides that with elements of the object relational mapping file. This results in creation of an in-memory EclipseLink session and project. Then EclipseLink persistence provider applies persistence unit properties specified in <tt>persistence.xml</tt> file, as the following illustration shows.<br>
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' The [[#eclipselink.sessions-xml|eclipselink.sessions-xml]] property represents a special case discussed further.
+
|}
+
 
+
<span id="Figure 19-1"></span><br>''''' Combining the Use of Annotations, orm.xml File and Persistence Unit Properties'''''<br>[[Image:override_spec.gif|Combining the Use of Annotations, orm.xml File and Persistence Unit Properties]]<br><br>
+
 
+
* You can use the <tt>[[#eclipselink.sessions-xml|eclipselink.sessions-xml]]</tt> persistence unit property. This defines a <tt>sessions.xml</tt> file, which references a <tt>project.xml</tt> file. In this case, EclipseLink persistence provider builds an in-memory EclipseLink session and project based on this metadata, as the following illustration shows. You can acquire a persistence manager and use it as per the JPA specification, having defined all entities and so on using only EclipseLink <tt>sessions.xml</tt> (see [[Introduction to EclipseLink%20Application%20Development%20(ELUG)#Creating Session Metadata|Creating Session Metadata]]) and <tt>project.xml</tt> files that you created Workbench (see [[Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)|Creating the project.xml File with Workbench|Creating the project.xml File with Workbench]]).
+
 
+
<span id="Figure 19-2"></span>
+
''''' Using eclipselink.sessions-xml Persistence Unit Property'''''
+
 
+
[[Image:override_tl.gif|Using eclipselink.sessions-xml Persistence Unit Property]]<br><br>
+
 
+
 
+
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+
| align="left" |
+
'''Note:''' You cannot combine the use of JPA annotations, object relational mapping files, persistence unit properties and the <tt>[[#eclipselink.sessions-xml|eclipselink.sessions-xml]]</tt> persistence unit property.
+
|}
+
 
+
 
+
 
+
 
+
==What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties==
+
 
+
A persistence unit configures various details that are required when you acquire an entity manager. You specify a persistence unit by name when you acquire an entity manager factory.
+
 
+
You configure persistence units in JPA persistence descriptor file <tt>persistence.xml</tt>.
+
 
+
In this file, you can specify the vendor extensions that this reference describes by using a <tt><properties></tt> element. The [[#Example 19-45|Configuring a Vendor Extension in the persistence.xml File (Java EE)]] example shows how to set an EclipseLink JPA persistence unit extension in a <tt>persistence.xml</tt> file for a Java EE application. The [[#Example 19-46|Configuring a Vendor Extension in the persistence.xml File (Java SE)]] example shows how to do the same for a Java SE application.
+
 
+
<span id="Example 19-45"></span>
+
''''' Configuring a Vendor Extension in the persistence.xml File (Java EE)'''''
+
<persistence-unit name="default" transaction-type="JTA">
+
    <provider>
+
        org.eclipse.persistence.jpa.PersistenceProvider
+
    </provider>
+
    <jta-data-source>
+
        jdbc/MyDataSource
+
    </jta-data-source>
+
+
    <properties>
+
        <property name="eclipselink.logging.level" value="INFO"/>
+
    </properties>
+
</persistence-unit>
+
 
+
 
+
<span id="Example 19-46"></span>
+
''''' Configuring a Vendor Extension in the persistence.xml File (Java SE)'''''
+
<persistence-unit name="default" transaction-type="RESOURCE_LOCAL">
+
    <provider>
+
        org.eclipse.persistence.jpa.PersistenceProvider
+
    </provider>
+
    <exclude-unlisted-classes>false</exclude-unlisted-classes>
+
    <properties>
+
+
        <property name="eclipselink.logging.level" value="INFO"/>
+
        <property name="eclipselink.jdbc.driver" value="oracle.jdbc.OracleDriver"/>
+
        <property name="eclipselink.jdbc.url" value="jdbc:oracle:thin:@myhost:1521:MYSID"/>
+
        <property name="eclipselink.jdbc.password" value="tiger"/>
+
        <property name="eclipselink.jdbc.user" value="scott"/>
+
    </properties>
+
+
</persistence-unit>
+
 
+
 
+
Alternatively, you can set a vendor extensions in the <tt>Map</tt> of properties you pass into a call to <tt>javax.persistence.Persistence</tt> method <tt>createEntityManagerFactory</tt>, as the  [[#Example 19-47|Configuring a Vendor Extension when Creating an EntityManagerFactory]] example shows. You can override extensions set in the <tt>persistence.xml</tt> file in this way. When you set an extension in a map of properties, you can set the value using the public static final field in the appropriate configuration class in <tt>org.eclipse.persistence.config</tt>, including the following:
+
* <tt>CacheType</tt>
+
* <tt>TargetDatabase</tt>
+
* <tt>TargetServer</tt>
+
* <tt>PersistenceUnitProperties</tt>
+
 
+
The following example shows how to set the value of extension <tt>eclipselink.cache.type.default</tt> using the <tt>CacheType</tt> configuration class.
+
 
+
<span id="Example 19-47"></span>
+
''''' Configuring a Vendor Extension when Creating an EntityManagerFactory'''''
+
import org.eclipse.persistence.config.CacheType;
+
+
Map properties = new HashMap();
+
properties.put(PersistenceUnitProperties.CACHE_TYPE_DEFAULT, CacheType.Full);
+
EntityManagerFactory emf = Persistence.createEntityManagerFactory("default", properties);
+
 
+
 
+
You may specify any EclipseLink JPA extension in a <tt>persistence.xml</tt> file and you may pass any EclipseLink JPA extension into <tt>Persistence</tt> method <tt>createEntityManagerFactory</tt>.
+
 
+
Currently, no EclipseLink JPA extensions are applicable to <tt>EntityManagerFactory</tt> method <tt>createEntityManager</tt>.
+
 
+
For more information, see the following:
+
* Section 2.1 "Requirements on the Entity Class" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification];
+
* Chapter 5 "Entity Managers and Persistence Contexts" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].
+
 
+
 
+
 
+
 
+
----
+
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''
+
 
+
 
+
[[Category: EclipseLink User's Guide]]
+
[[Category: Draft]]
+
[[Category: Task]]
+
[[Category: JPA]]
+

Latest revision as of 11:18, 13 July 2012

This page is now obsolete. Please see the EclipseLink JPA Extensions Guide for the current information.

Back to the top