|
|
| Line 1: |
Line 1: |
| − | <div style="border:1px solid #999999;background-color:#ffffff;align:center">
| + | This page is now obsolete. Please see the |
| − | [http://www.eclipse.org/eclipselink/documentation/2.4/jpa/extensions/toc.htm New EclipseLink JPA Extensions Guide]
| + | [http://www.eclipse.org/eclipselink/documentation/ EclipseLink JPA Extensions Guide] for the current information. |
| − | </div>
| + | |
| − | | + | |
| − | __TOC__
| + | |
| − | <div style="float:right;border:1px solid #000000;padding:5px">
| + | |
| − | [[Special:Whatlinkshere/Using EclipseLink JPA Extensions (ELUG)|Related Topics]]</div>
| + | |
| − | | + | |
| − | 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>
| + | |
| − | * <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>
| + | |
| − | * <tt>[[#How to Use the @VariableOneToOne Annotation|@VariableOneToOne]]</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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @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;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | 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" |
| + | |
| − | optional
| + | |
| − | |- 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @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;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @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;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | ===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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @Entity
| + | |
| − | public class Employee implements Serializable {
| + | |
| − | ...
| + | |
| − | @OneToMany(cascade=ALL, mappedBy="employee")
| + | |
| − | @PrivateOwned
| + | |
| − | public Collection<PhoneNumber> getPhoneNumbers() {
| + | |
| − | return phoneNumbers;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | ====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 {
| + | |
| − | JoinFetchType value() default JoinFetchType.INNER;
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @Entity
| + | |
| − | public class Employee implements Serializable {
| + | |
| − | ...
| + | |
| − | @OneToMany(cascade=ALL, mappedBy="owner")
| + | |
| − | @JoinFetch(value=OUTER)
| + | |
| − | public Collection<Employee> getManagedEmployees() {
| + | |
| − | return managedEmployees;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | ===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 {
| + | |
| − | boolean value() default true;
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @Entity
| + | |
| − | public class Employee implements Serializable {
| + | |
| − | ...
| + | |
| − | @Temporal(DATE)
| + | |
| − | @Mutable
| + | |
| − | public Calendar getHireDate() {
| + | |
| − | return hireDate;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | ===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.
| + | |
| − | | + | |
| − | @Target({METHOD, FIELD})
| + | |
| − | @Retention(RUNTIME)
| + | |
| − | public @interface Transformation {
| + | |
| − | FetchType fetch() default EAGER;
| + | |
| − | boolean optional() default true;
| + | |
| − | }
| + | |
| − | | + | |
| − | | + | |
| − | {| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| + | |
| − | | align="left" |
| + | |
| − | '''Note:''' The <tt>@Transformation</tt> annotation is optional for transformation mappings: if you specify either a <tt>[[#How to Use the @ReadTransformer Annotation|@ReadTransformer]]</tt>, <tt>[[#How to Use the @WriteTransformer Annotation|@WriteTransformer]]</tt> or <tt>[[#How to Use the @WriteTransformers Annotation|@WriteTransformers]]</tt> annotation,
| + | |
| − | the mapping would become a transformation mapping by default, without you specifying
| + | |
| − | the <tt>@Transformation</tt> annotation.
| + | |
| − | |}
| + | |
| − | | + | |
| − | <!-- 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 @ReadTransformer Annotation===
| + | |
| − | | + | |
| − | Use the <tt>@ReadTransformer</tt> annotation 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. 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 {
| + | |
| − | Class transformerClass() default void.class;
| + | |
| − | String method() default "";
| + | |
| − | }
| + | |
| − | | + | |
| − | 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===
| + | |
| − | | + | |
| − | Use the <tt>@WriteTransformer</tt> annotation with the <tt>[[#How to Use the @Transformation Annotation|@Transformation]]</tt> mapping to 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 {
| + | |
| − | Class transformerClass() default void.class;
| + | |
| − | String method() default "";
| + | |
| − | Column column() default @Column;
| + | |
| − | }
| + | |
| − | | + | |
| − | 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 with the <tt>[[#How to Use the @Transformation Annotation|@Transformation]]</tt> mapping 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 {
| + | |
| − | WriteTransformer[] value();
| + | |
| − | }
| + | |
| − | | + | |
| − | 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
| + | |
| − | |}
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===How to Use the @VariableOneToOne Annotation===
| + | |
| − | | + | |
| − | You can use the <tt>@VariableOneToOne</tt> annotation to map an <tt>[[Introduction%20to%20Relational%20Mappings%20(ELUG)#Variable One-to-One Mapping|org.eclipse.persistence.mappings.VariableOneToOneMapping]]</tt>, which you use to represent a pointer references between a Java object and an implementer of an interface. This mapping is typically represented by a single pointer (stored in an instance variable) between the source and target objects. In the relational database tables, these mappings are usually implemented using a foreign key and a type code.
| + | |
| − | | + | |
| − | @Target({METHOD, FIELD})
| + | |
| − | @Retention(RUNTIME)
| + | |
| − | public @interface VariableOneToOne {
| + | |
| − | Class targetInterface() default void.class;
| + | |
| − | CascadeType[] cascade() default {};
| + | |
| − | FetchType fetch() default EAGER;
| + | |
| − | boolean optional() default true;
| + | |
| − | DiscriminatorColumn discriminatorColumn() default @DiscriminatorColumn;
| + | |
| − | DiscriminatorClass[] discriminatorClasses() default {};
| + | |
| − | }
| + | |
| − | | + | |
| − | Specify the <tt>@VariableOneToOne</tt> annotation within an <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> or <tt>[[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Embeddable|@Embeddable]]</tt> class.
| + | |
| − | | + | |
| − | This table lists attributes of the <tt>@VariableOneToOne</tt> annotation.
| + | |
| − | | + | |
| − | <span id="Table 19-550"></span>
| + | |
| − | ''''' Attributes of the @VariableOneToOneAnnotation'''''
| + | |
| − | | + | |
| − | {| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @VariableOneToOne Annotation" summary="This table lists the attributes of EclipseLink JPA @VariableOneToOne 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>cascade</tt>
| + | |
| − | | headers="r2c1-t10 r1c2-t10" align="left" |
| + | |
| − | Set this attribute to an array of <tt>javax.persistence.CascadeType</tt> objects to indicate operations that must be cascaded to the target of the association.
| + | |
| − | | headers="r2c1-t10 r1c3-t10" align="left" |
| + | |
| − | <tt>{}</tt>
| + | |
| − | | headers="r2c1-t10 r1c4-t10" align="left" |
| + | |
| − | optional
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r2c1-t10" headers="r1c1-t10" align="left" |
| + | |
| − | <tt>discriminatorClasses</tt>
| + | |
| − | | headers="r2c1-t10 r1c2-t10" align="left" |
| + | |
| − | Set this attribute to an array of <tt>org.eclipse.persistence.annotations.DiscriminatorClass</tt> objects to provide a list of discriminator types that can be used with this variable one-to-one mapping.
| + | |
| − | | + | |
| − | If none are specified, then those entities within the persistence unit that implement the target interface will be added to the list of types. In this case, the discriminator type will default as follows:
| + | |
| − | * If the <tt>javax.persistence.DiscriminatorColumn</tt> type is <tt>STRING</tt>, it is <tt>Entity.name()</tt>
| + | |
| − | * If the <tt>DiscriminatorColumn</tt> type is <tt>CHAR</tt>, it is the first letter of the <tt>Entity</tt> class
| + | |
| − | * If the <tt>DiscriminatorColumn</tt> type is <tt>INTEGER</tt> it is the next integer after the highest integer explicitly added.
| + | |
| − | | headers="r2c1-t10 r1c3-t10" align="left" |
| + | |
| − | <tt>{}</tt>
| + | |
| − | | headers="r2c1-t10 r1c4-t10" align="left" |
| + | |
| − | optional
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r2c1-t10" headers="r1c1-t10" align="left" |
| + | |
| − | <tt>discriminatorColumn</tt>
| + | |
| − | | headers="r2c1-t10 r1c2-t10" align="left" |
| + | |
| − | Set this attribute to the <tt>javax.persistence.DiscriminatorColumn</tt> that will hold the type indicators.
| + | |
| − | | + | |
| − | If the discriminator column is not specified, the name of the discriminator column defaults to <tt>"DTYPE"</tt>, and the discriminator type - to <tt>STRING</tt>.
| + | |
| − | | headers="r2c1-t10 r1c3-t10" align="left" |
| + | |
| − | <tt>@javax.persistence.DiscriminatorColumn</tt>
| + | |
| − | | headers="r2c1-t10 r1c4-t10" align="left" |
| + | |
| − | 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 association is optional.
| + | |
| − | | + | |
| − | The following are valid values:
| + | |
| − | * <tt>true</tt> - The association is optional.
| + | |
| − | * <tt>false</tt> - A non-null relationship must always exist.
| + | |
| − | | headers="r2c1-t10 r1c3-t10" align="left" |
| + | |
| − | <tt>true</tt>
| + | |
| − | | headers="r2c1-t10 r1c4-t10" align="left" |
| + | |
| − | optional
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r2c1-t10" headers="r1c1-t10" align="left" |
| + | |
| − | <tt>targetInterface</tt>
| + | |
| − | | headers="r2c1-t10 r1c2-t10" align="left" |
| + | |
| − | Set this attribute to an interface class that is the target of the association.
| + | |
| − | | + | |
| − | If not specified, it will be inferred from the type of the object being referenced.
| + | |
| − | | headers="r2c1-t10 r1c3-t10" align="left" |
| + | |
| − | <tt>void.class</tt>
| + | |
| − | | headers="r2c1-t10 r1c4-t10" align="left" |
| + | |
| − | optional
| + | |
| − | |}
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===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>[[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 @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 {
| + | |
| − | String name();
| + | |
| − | Class converterClass();
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @Entity
| + | |
| − | public class Employee implements Serializable{
| + | |
| − | ...
| + | |
| − | @Basic
| + | |
| − | @Converter (
| + | |
| − | name="genderConverter",
| + | |
| − | converterClass=org.myorg.converters.GenderConverter.class
| + | |
| − | )
| + | |
| − | @Convert("genderConverter")
| + | |
| − | public String getGender() {
| + | |
| − | return gender;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | </source> }
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===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 {
| + | |
| − | String name();
| + | |
| − | Class dataType() default void.class;
| + | |
| − | Class objectType() default void.class;
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @Entity
| + | |
| − | public class Employee implements Serializable{
| + | |
| − | ...
| + | |
| − | @TypeConverter (
| + | |
| − | name="doubleToFloat",
| + | |
| − | dataType=Double.class,
| + | |
| − | objectType=Float.class,
| + | |
| − | )
| + | |
| − | @Convert("doubleToFloat")
| + | |
| − | public Number getGradePointAverage() {
| + | |
| − | return gradePointAverage;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | *Another example of '''TypeConverter''' usage is in the [http://wiki.eclipse.org/EclipseLink/Examples/Distributed#TypeConverter distributed tutorial] - this one is used to enable storage of a near limitless '''BigInteger''' using a String (VARCHAR) field instead of the usual NUMBER type.
| + | |
| − | | + | |
| − | ===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 {
| + | |
| − | String name();
| + | |
| − | Class dataType() default void.class;
| + | |
| − | Class objectType() default void.class;
| + | |
| − | ConversionValue[] conversionValues();
| + | |
| − | String defaultObjectValue() default "";
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | 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;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | ===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 {
| + | |
| − | String name();
| + | |
| − | String converter();
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @StructConverter(name="MyType",
| + | |
| − | converter="myproject.converters.MyStructConverter")
| + | |
| − | </source>
| + | |
| − | | + | |
| − | 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 {
| + | |
| − | String value() default "none";
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @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;
| + | |
| − | }
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | ==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>
| + | |
| − | * <tt>[[#How to Use the @ExistenceChecking Annotation|@ExistenceChecking]]</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.
| + | |
| − | <source lang="java">
| + | |
| − | @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;
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | 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. To disable the shared cache for an Entity set the 'shared' property to false.
| + | |
| − | | 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 (number of objects).
| + | |
| − | | 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" |
| + | |
| − | * <tt>[[#eclipselink.cache.shared.default|eclipselink.cache.shared.default]]</tt>
| + | |
| − | |- 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @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 {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | ====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><span id="eclipselink.cache.type.default">eclipselink.cache.type.default</span></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 use in a <tt>persistence.xml</tt> file and for the <tt>org.eclipse.persistence.config.CacheType</tt>:
| + | |
| − | * <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]] or to turn off the cache - use '''"eclipselink.cache.shared"="false"'''.
| + | |
| − | | + | |
| − | '''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>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" |
| + | |
| − | 100
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r4c1-t21" headers="r1c1-t21" align="left" |
| + | |
| − | <tt><span id="eclipselink.cache.shared.default">eclipselink.cache.shared.default</span></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="false"/>
| + | |
| − | | + | |
| − | | + | |
| − | '''Example'''<nowiki>: property </nowiki><tt>Map</tt>
| + | |
| − | import org.eclipse.persistence.config.PersistenceUnitProperties;
| + | |
| − | propertiesMap.put(PersistenceUnitProperties.CACHE_SHARED_DEFAULT, "false");
| + | |
| − | | headers="r4c1-t21 r1c3-t21" align="left" |
| + | |
| − | <tt>true</tt>
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r5c1-t21" headers="r1c1-t21" align="left" |
| + | |
| − | <tt><span id="eclipselink.cache.type.ENTITY">eclipselink.cache.type.<ENTITY></span></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 use in a <tt>persistence.xml</tt> file and for the <tt>org.eclipse.persistence.config.CacheType</tt>:
| + | |
| − | * "<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" |
| + | |
| − | <tt>eclipselink.cache.size.default</tt>
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r7c1-t21" headers="r1c1-t21" align="left" |
| + | |
| − | <tt><span id="eclipselink.cache.shared.ENTITY">eclipselink.cache.shared.<ENTITY></span></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 use in a <tt>persistence.xml</tt> file and 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.
| + | |
| − | | + | |
| − | | + | |
| − | '''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>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 {
| + | |
| − | int hour() default 0;
| + | |
| − | int minute() default 0;
| + | |
| − | int second() default 0;
| + | |
| − | int millisecond() default 0;
| + | |
| − | }
| + | |
| − | | + | |
| − | 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
| + | |
| − | |}
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===How to Use the @ExistenceChecking Annotation===
| + | |
| − | | + | |
| − | Use the <tt>@ExistenceChecking</tt> annotation to specify the type of checking that EclipseLink should use when determining if an <tt>Entity</tt> is new or already existing.
| + | |
| − | | + | |
| − | On a merge operation, this annotation determines whether or not EclipseLink should only use the cache to check if an object exists, or should read the object (from the database or cache).
| + | |
| − |
| + | |
| − | @Target({TYPE})
| + | |
| − | @Retention(RUNTIME)
| + | |
| − | public @interface ExistenceChecking {
| + | |
| − | ExistenceType value() default CHECK_CACHE;
| + | |
| − | }
| + | |
| − | | + | |
| − | You may define the <tt>@ExistenceChecking</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>;
| + | |
| − | | + | |
| − | This table lists attributes of the <tt>@ExistenceChecking</tt> annotation.
| + | |
| − | | + | |
| − | | + | |
| − | <span id="Table 19-144"></span>
| + | |
| − | ''''' Attributes of the @ExistenceChecking Annotation'''''
| + | |
| − | | + | |
| − | {| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @ExistenceChecking Annotation" summary="This table lists the attributes of EclipseLink JPA @ExistenceChecking 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>value</tt>
| + | |
| − | | headers="r2c1-t22 r1c2-t22" align="left" |
| + | |
| − | Set this attribute to the type (<tt>org.eclipse.persistence.annotations.ExistenceType</tt> enumerated type) of the existence checking that you will be using to determine if an insert or an update operation should occur for an object.
| + | |
| − | | + | |
| − | The following are the valid values for the <tt>ExistenceType</tt><nowiki>:</nowiki>
| + | |
| − | * <tt>CHECK_CACHE</tt> – This option assumes that if the object's primary key does not include <tt>null</tt> and it is in the cache, then this object must exist.
| + | |
| − | * <tt>CHECK_DATABASE</tt> – This option triggers the object existence check on a database.
| + | |
| − | * <tt>ASSUME_EXISTENCE</tt> – This option assumes that if the object's primary key does not include <tt>null</tt>, then the object must exist.<br>You may choose this option if your application guarantees the existence checking, or is not concerned about it.
| + | |
| − | * <tt>ASSUME_NON_EXISTENCE</tt> – This option assumes that the object does not exist.<br>You may choose this option if your application guarantees the existence checking, or is not concerned about it.<br>If you specify this option, EclipseLink will force the call of an insert operation.
| + | |
| − | | |
| + | |
| − | One of the following default values applies:
| + | |
| − | * <tt>ExistenceType.CHECK_CACHE</tt> - If either an <tt>@ExistenceChecking</tt> annotation or an XML element exists, but the <tt>value</tt> attribute is not set.
| + | |
| − | * <tt>ExistenceType.CHECK_DATABASE</tt> - If neither the <tt>@ExistenceChecking</tt> annotation nor an XML element exists.
| + | |
| − | | headers="r2c1-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.config.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 {
| + | |
| − | Class value();
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @Entity
| + | |
| − | @Table(name="EMPLOYEE")
| + | |
| − | @Customizer(mypackage.MyCustomizer.class)
| + | |
| − | public class Employee implements Serializable {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | ===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]]) and many-to-one (see [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@ManyToOne|@ManyToOne]]) mapping through weaving.
| + | |
| − | | + | |
| − | The following are the valid values:
| + | |
| − | * <tt>true</tt> – enable lazy one-to-one/many-to-one mapping through weaving (default).
| + | |
| − | * <tt>false</tt> – disable lazy one-to-one/many-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> or <tt>static</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 (default). 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> or <tt>static</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 (default).
| + | |
| − | * <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> or <tt>static</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 (default).
| + | |
| − | * <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> or <tt>static</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.weaving.eager"></span>
| + | |
| − | <tt>eclipselink.weaving.eager</tt>
| + | |
| − | | headers="r8c1-t26 r1c2-t26" align="left" |
| + | |
| − | Enable or disable indirection on eager relationships through weaving. (Even one-to-one and many-to-one relations with FetchType.EAGER become effectively "lazy".)
| + | |
| − | | + | |
| − | 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 (default).
| + | |
| − | | + | |
| − | '''Note''': you may set this option only if the <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> option is set to <tt>true</tt> or <tt>static</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.config.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.config.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>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.
| + | |
| − | * <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>
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r2c1-t27" headers="r1c1-t27" align="left" |
| + | |
| − | <tt>eclipselink.persistence.context.reference-mode</tt>
| + | |
| − | | headers="r2c1-t27 r1c2-t27" align="left" |
| + | |
| − | Specify whether or not the Java VM is allowed to manage the number of objects within the persistence context using Java’s weak references.
| + | |
| − | | + | |
| − | In cases where your application cannot use the <tt>EntityManager</tt> <tt>clear</tt> method to clear an extended persistence context, use this setting to enable the VM to remove unreferenced and unchanged objects from the persistence context, resulting in making resources available for other uses.
| + | |
| − | | + | |
| − | You can set this property either during the <tt>EntityManagerFactory</tt> <tt>createEntityManager(Map)</tt> call, or globally in the <tt>persistence.xml</tt> file.
| + | |
| − | | + | |
| − | The following are the valid values for the use in a <tt>persistence.xml</tt> file and for the <tt>org.eclipse.persistence.sessions.factories.ReferenceMode</tt>:
| + | |
| − | * <tt>HARD</tt> - Use this option to specify that all references to all objects will be through hard references. These objects will not be available for garbage collection until the referencing artifact (such as persistence context or unit of work) is released/cleared or closed.
| + | |
| − | * <tt>WEAK</tt> - Use this option to specify that references to objects supporting active attribute change tracking (see [[Introduction%20to%20EclipseLink%20Transactions%20(ELUG)#Attribute Change Tracking Policy|Attribute Change Tracking Policy]]) will be held by weak references. That is, any object no longer referenced directly or indirectly will be available for garbage collection. When a change is made to a change-tracked object, that object is moved to a hard reference and will not be available for garbage collection until flushed.<br>New and removed objects, as well as objects that do not support active attribute change tracking, will also be held by hard references and will not be available for garbage collection.
| + | |
| − | * <tt>FORCE_WEAK</tt> - Use this option to specify that all objects, including non-change-tracked objects, are to be held by weak references. When a change is made to a change-tracked object, that object is moved to a hard reference and will not be available for garbage collection until flushed. However, any objects that do not support active attribute change tracking may be garbage collected before their changes are flushed to a database, which can potentially result in a loss of changes.<br>New and removed objects will be held by hard references and will not be available for garbage collection.
| + | |
| − | | + | |
| − | Using Java, you can configure reference mode through the EclipseLink <tt>Session</tt>'s <tt>acquireUnitOfWork(ReferenceMode mode)</tt> method. To specify a persistence unit- or session-wide default, use the <tt>Session</tt>'s <tt>setDefaultReferenceMode</tt> method.
| + | |
| − | | + | |
| − | For more information, see the following:
| + | |
| − | * [[#Using EclipseLink JPA Extensions for Tracking Changes|Using EclipseLink JPA Extensions for Tracking Changes]]
| + | |
| − | * [[Introduction%20to%20Cache%20(ELUG)#Cache Type and Object Identity|Cache Type and Object Identity]]
| + | |
| − | | + | |
| − | | + | |
| − | '''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
| + | |
| − | <property name="eclipselink.persistence-context.reference-mode" value="FORCE_WEAK"/>
| + | |
| − | | + | |
| − | '''Example'''<nowiki>: property </nowiki><tt>Map</tt>
| + | |
| − | import org.eclipse.persistence.config.PersistenceUnitProperties;
| + | |
| − | propertiesMap.put(PersistenceUnitProperties.PERSISTENCE_CONTEXT_REFERENCE_MODE, ReferenceMode.FORCE_WEAK);
| + | |
| − | | headers="r2c1-t38 r1c3-t38" align="left" |
| + | |
| − | <tt>WEAK</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 Copy Policy==
| + | |
| − | | + | |
| − | The copy policy enables EclipseLink to produce exact copies of persistent objects. For more information, see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Copy Policy|Configuring Copy Policy]].
| + | |
| − | | + | |
| − | EclipseLink defines the following copy policy annotations:
| + | |
| − | * <tt>[[#How to Use the @CopyPolicy Annotation|@CopyPolicy]]</tt>
| + | |
| − | * <tt>[[#How to Use the @CloneCopyPolicy Annotation|@CloneCopyPolicy]]</tt>
| + | |
| − | * <tt>[[#How to Use the @InstantitationCopyPolicy Annotation|@InstantitationCopyPolicy]]</tt>
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===How to Use the @CopyPolicy Annotation===
| + | |
| − | Use the <tt>@CopyPolicy</tt> annotation to specify a class that implements the <tt>org.eclipse.persistence.descriptors.copying.CopyPolicy</tt> interface to set the copy policy on an <tt>Entity</tt>.
| + | |
| − | | + | |
| − | @Target({TYPE})
| + | |
| − | @Retention(RUNTIME)
| + | |
| − | public @interface CopyPolicy {
| + | |
| − | Class value();
| + | |
| − | }
| + | |
| − | | + | |
| − | You can define the <tt>@CopyPolicy</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>
| + | |
| − | | + | |
| − | This table lists attributes of the <tt>@CopyPolicy</tt> annotation.
| + | |
| − | | + | |
| − | | + | |
| − | <span id='Table 19-155'></span>
| + | |
| − | ''''' Attributes of the @CopyPolicy Annotation'''''
| + | |
| − | | + | |
| − | {| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @CopyPolicy Annotation" summary="This table lists the attributes of EclipseLink JPA @CopyPolicy 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 copy policy that you want to apply to your entity's descriptor.<br>The class must implement <tt>org.eclipse.persistence.descriptors.copying.CopyPolicy</tt>
| + | |
| − | | 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>@CopyPolicy</tt> annotation.
| + | |
| − | | + | |
| − | <span id="Example 19-133"></span>
| + | |
| − | ''''' Usage of the @CopyPolicy Annotation'''''
| + | |
| − | <source lang="java">
| + | |
| − | @Entity
| + | |
| − | @Table(name="EMPLOYEE")
| + | |
| − | @CopyPolicy(mypackage.MyCopyPolicy.class)
| + | |
| − | public class Employee implements Serializable {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | ===How to Use the @CloneCopyPolicy Annotation===
| + | |
| − | Use the <tt>@CloneCopyPolicy</tt> annotation to set the clone copy policy (<tt>org.eclipse.persistence.descriptors.copying.CloneCopyPolicy</tt>) on an <tt>Entity</tt>.
| + | |
| − | | + | |
| − | @Target({TYPE})
| + | |
| − | @Retention(RUNTIME)
| + | |
| − | public @interface CloneCopyPolicy {
| + | |
| − | Sting method();
| + | |
| − | Sting workingCopyMethod();
| + | |
| − | }
| + | |
| − | | + | |
| − | The <tt>@CloneCopyPolicy</tt> must specify one or both of the <tt>method</tt> or <tt>workingCopyMethod</tt> attributes based on the following:
| + | |
| − | * Use the <tt>method</tt> for the clone whose function is comparison in conjunction with EclipseLink's <tt>DeferredChangeDetectionPolicy</tt> (see [[Introduction%20to%20EclipseLink%20Transactions%20(ELUG)#Deferred Change Detection Policy|Deferred Change Detection Policy]]).
| + | |
| − | * Use the <tt>workingCopyMethod</tt> to clone objects that will be returned, as they are registered in EclipseLink's transactional mechanism (the unit of work).
| + | |
| − | | + | |
| − | You can define the <tt>@CloneCopyPolicy</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>
| + | |
| − | | + | |
| − | This table lists attributes of the <tt>@CloneCopyPolicy</tt> annotation.
| + | |
| − | | + | |
| − | | + | |
| − | <span id='Table 19-156'></span>
| + | |
| − | ''''' Attributes of the @CloneCopyPolicy Annotation'''''
| + | |
| − | | + | |
| − | {| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @CloneCopyPolicy Annotation" summary="This table lists the attributes of EclipseLink JPA @CloneCopyPolicy 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>method</tt>
| + | |
| − | | headers="r2c1-t25 r1c2-t25" align="left" |
| + | |
| − | Set this attribute to the <tt>String</tt> method name that EclipseLink will use to create a clone to enable comparison by EclipseLink's [[Introduction%20to%20EclipseLink%20Transactions%20(ELUG)#Deferred Change Detection Policy|deferred change detection policy]]) that you want to apply to your entity's descriptor.
| + | |
| − | | + | |
| − | Note: you have to set either this attribute, or the <tt>workingCopyMethod</tt>, or both.
| + | |
| − | | headers="r2c1-t25 r1c3-t25" align="left" |
| + | |
| − | no default
| + | |
| − | | headers="r2c1-t25 r1c4-t25" align="left" |
| + | |
| − | optional/required
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r2c1-t25" headers="r1c1-t25" align="left" |
| + | |
| − | <tt>workingCopyMethod</tt>
| + | |
| − | | headers="r2c1-t25 r1c2-t25" align="left" |
| + | |
| − | Set this attribute to the <tt>String</tt> method name that EclipseLink will use to create the object returned when registering an <tt>Object</tt> in an EclipseLink [[Introduction%20to%20EclipseLink%20Transactions%20(ELUG)|unit of work]].
| + | |
| − | | + | |
| − | Note: you have to set either this attribute, or the <tt>method</tt>, or both.
| + | |
| − | | headers="r2c1-t25 r1c3-t25" align="left" |
| + | |
| − | no default
| + | |
| − | | headers="r2c1-t25 r1c4-t25" align="left" |
| + | |
| − | optional/required
| + | |
| − | |}
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===How to Use the @InstantiationCopyPolicy Annotation===
| + | |
| − | | + | |
| − | Instantiation copy policy is the default copy policy in EclipseLink. Use the <tt>@InstantiationCopyPolicy</tt> annotation to override other types of copy policies for an <tt>Entity</tt>.
| + | |
| − | | + | |
| − | @Target({TYPE})
| + | |
| − | @Retention(RUNTIME)
| + | |
| − | public @interface CloneCopyPolicy {
| + | |
| − | }
| + | |
| − | | + | |
| − | You can define the <tt>@InstantiationCopyPolicy</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 <tt>@InstantiationCopyPolicy</tt> annotation does not have attributes.
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ==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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @Entity
| + | |
| − | @ReadOnly
| + | |
| − | public class Employee implements Serializable {
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ==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 {
| + | |
| − | boolean returnOnly() default false;
| + | |
| − | }
| + | |
| − | | + | |
| − | 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'''''
| + | |
| − | <source lang="java">
| + | |
| − | @ReturnInsert
| + | |
| − | public String getFirstName() {
| + | |
| − | return firstName;
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | <span id="Example 19-16"></span>
| + | |
| − | ''''' Usage of the @ReturnInsert Annotation with Arguments'''''
| + | |
| − | <source lang="java">
| + | |
| − | @ReturnInsert(returnOnly=true)
| + | |
| − | public String getFirstName() {
| + | |
| − | return firstName;
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | ===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 {
| + | |
| − | OptimisticLockingType type() default VERSION_COLUMN;
| + | |
| − | Column[] selectedColumns() default {};
| + | |
| − | boolean cascade() default false;
| + | |
| − | }
| + | |
| − |
| + | |
| − | 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 @StoredProcedureParameter Annotation|@StoredProcedureParameter]]</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 {
| + | |
| − | String name();
| + | |
| − | String procedureName();
| + | |
| − | QueryHint[] hints() default {};
| + | |
| − | Class resultClass() default void.class;
| + | |
| − | String resultSetMapping() default "";
| + | |
| − | boolean returnsResultSet() default false;
| + | |
| − | StoredProcedureParameter[] parameters() default {};
| + | |
| − | }
| + | |
| − | | + | |
| − | 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>[[#How to Use the StoredProcedureParameter Annotation|@StoredProcedureParameter]]</tt> instances to define arguments to the stored procedure.
| + | |
| − | | 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 @StoredProcedureParameter Annotation===
| + | |
| − | | + | |
| − | Use the <tt>@StoredProcedureParameter</tt> annotation within a [[#How to Use the NamedStoredProcedureQuery Annotation|@NamedStoredProcedureQuery]] annotation to define arguments to the stored procedure.
| + | |
| − | | + | |
| − | @Target({})
| + | |
| − | @Retention(RUNTIME)
| + | |
| − | public @interface StoredProcedureParameter {
| + | |
| − | String queryParameter();
| + | |
| − | Direction direction() default IN;
| + | |
| − | int jdbcType() default -1;
| + | |
| − | String jdbcTypeName() default "";
| + | |
| − | String name() default "";
| + | |
| − | Class type() default void.class;
| + | |
| − | }
| + | |
| − | | + | |
| − | This table lists attributes of the <tt>@StoredProcedureParameter</tt> annotation.
| + | |
| − | | + | |
| − | | + | |
| − | <span id="Table 19-200"></span>
| + | |
| − | ''''' Attributes of the @StoredProcedureParameter Annotation'''''
| + | |
| − | | + | |
| − | {| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @StoredProcedureParameter Annotation" summary="This table lists the attributes of EclipseLink JPA @StoredProcedureParameter 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>queryParameter</tt>
| + | |
| − | | headers="r2c1-t33 r1c2-t33" align="left" |
| + | |
| − | Set this attribute to the <tt>String</tt> query parameter name.
| + | |
| − | | 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>direction</tt>
| + | |
| − | | headers="r3c1-t33 r1c2-t33" align="left" |
| + | |
| − | Set the value of this attribute to define the direction(<tt>org.eclipse.persistence.annotations.Direction</tt> enumerated type) of the stored procedure parameter.
| + | |
| − | | + | |
| − | The following are valid values for <tt>Direction.IN</tt>:
| + | |
| − | * <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>Note: EclipseLink will throw an exception if you set more than one parameter to the <tt>OUT_CURSOR</tt> type.
| + | |
| − | | headers="r3c1-t33 r1c3-t33" align="left" |
| + | |
| − | empty <tt>Direction.IN</tt>
| + | |
| − | | headers="r3c1-t33 r1c4-t33" align="left" |
| + | |
| − | optional
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r4c1-t33" headers="r1c1-t33" align="left" |
| + | |
| − | <tt>name</tt>
| + | |
| − | | headers="r4c1-t33 r1c2-t33" align="left" |
| + | |
| − | Set this attribute to the <tt>String</tt> name of the stored procedure parameter.
| + | |
| − | | headers="r4c1-t33 r1c3-t33" align="left" |
| + | |
| − | <tt>""</tt>
| + | |
| − | | headers="r4c1-t33 r1c4-t33" align="left" |
| + | |
| − | optional
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r5c1-t33" headers="r1c1-t33" align="left" |
| + | |
| − | <tt>type</tt>
| + | |
| − | | headers="r5c1-t33 r1c2-t33" align="left" |
| + | |
| − | 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.
| + | |
| − | | headers="r5c1-t33 r1c3-t33" align="left" |
| + | |
| − | <tt>void.class</tt>
| + | |
| − | | headers="r5c1-t33 r1c4-t33" align="left" |
| + | |
| − | optional
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r6c1-t33" headers="r1c1-t33" align="left" |
| + | |
| − | <tt>jdbcType</tt>
| + | |
| − | | headers="r6c1-t33 r1c2-t33" align="left" |
| + | |
| − | Set this attribute to the int value of JDBC type code. This depends on the type returned from the procedure.
| + | |
| − | | headers="r6c1-t33 r1c3-t33" align="left" |
| + | |
| − | -1
| + | |
| − | | headers="r6c1-t33 r1c4-t33" align="left" |
| + | |
| − | optional
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r7c1-t33" headers="r1c1-t33" align="left" |
| + | |
| − | <tt>jdbcTypeName </tt>
| + | |
| − | | headers="r7c1-t33 r1c2-t33" align="left" |
| + | |
| − | Set this attribute to the <tt>String</tt> value of the JDBC type name.<br>Note: setting of this attribute may be required for <tt>ARRAY</tt> or <tt>STRUCT</tt> types.
| + | |
| − | | headers="r7c1-t33 r1c3-t33" align="left" |
| + | |
| − | <tt>""</tt>
| + | |
| − | | headers="r7c1-t33 r1c4-t33" align="left" |
| + | |
| − | optional
| + | |
| − | |}
| + | |
| − | | + | |
| − | The [[#Example 19-25|Usage of the @NamedStoredProcedureQuery Annotation]] example shows how to use the <tt>@StoredProcedureParameter</tt> annotation.
| + | |
| − | | + | |
| − | 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]]
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===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 {
| + | |
| − | NamedStoredProcedureQuery[] value();
| + | |
| − | }
| + | |
| − | | + | |
| − | 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 the use in a <tt>persistence.xml</tt> file and for the <tt>org.eclipse.persistence.config.BatchWriting</tt>:
| + | |
| − | * <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="r4c1-t35" headers="r1c1-t35" align="left" |
| + | |
| − | <tt>eclipselink.jdbc.connection-policy</tt>
| + | |
| − | | headers="r4c1-t35 r1c2-t35" align="left" |
| + | |
| − | Specify an entire connection policy(<tt>org.eclipse.persistence.sessions.server.ConnectionPolicy</tt>) to control how an EclipseLink session acquires and uses read and write connections. For more information, see [[Configuring%20a%20Session%20(ELUG)#Configuring Connection Policy|Configuring Connection Policy]].
| + | |
| − | | + | |
| − | The following are the valid values for the use in a <tt>persistence.xml</tt> file and for the <tt>org.eclipse.persistence.config.EntityManagerProperties</tt>:
| + | |
| − | * information pending
| + | |
| − | | + | |
| − | '''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
| + | |
| − | <property name="eclipselink.jdbc.connection-policy" value="information pending"/>
| + | |
| − |
| + | |
| − | '''Example'''<nowiki>: property </nowiki><tt>Map</tt>
| + | |
| − | import org.eclipse.persistence.config.EntityManagerProperties;
| + | |
| − | propertiesMap.put(EntityManagerProperties.CONNECTION_POLICY, information pending);
| + | |
| − | | headers="r4c1-t35 r1c3-t35" align="left" |
| + | |
| − | <tt>information pending</tt>
| + | |
| − | -->
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r7c1-t35" headers="r1c1-t35" align="left" |
| + | |
| − | <tt>eclipselink.jdbc.exclusive-connection.is-lazy</tt>
| + | |
| − | | headers="r4c1-t35 r1c2-t35" align="left" |
| + | |
| − | Specify when a write connection is acquired lazily. For more information, see [[Configuring%20a%20Session%20(ELUG)#Lazy Connection Acquisition|Lazy Connection Acquisition]].
| + | |
| − | | + | |
| − | The following are the valid values:
| + | |
| − | * <tt>true</tt> - aquire the write connection lazily.
| + | |
| − | * <tt>false</tt> - do not aquire the write connection lazily.
| + | |
| − | | + | |
| − | For more information, see [[Configuring%20a%20Session%20(ELUG)#Configuring Connection Policy|Configuring Connection Policy]].
| + | |
| − | | + | |
| − | | + | |
| − | '''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
| + | |
| − | <property name="eclipselink.jdbc.exclusive-connection.is-lazy" value="false"/>
| + | |
| − |
| + | |
| − | '''Example'''<nowiki>: property </nowiki><tt>Map</tt>
| + | |
| − | import org.eclipse.persistence.config.PersistenceUnitProperties;
| + | |
| − | propertiesMap.put(PersistenceUnitProperties.EXCLUSIVE_CONNECTION_IS_LAZY, "false");
| + | |
| − | | headers="r4c1-t35 r1c3-t35" align="left" |
| + | |
| − | <tt>true</tt>
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r7c1-t35" headers="r1c1-t35" align="left" |
| + | |
| − | <tt>eclipselink.jdbc.exclusive-connection.mode</tt>
| + | |
| − | | headers="r4c1-t35 r1c2-t35" align="left" |
| + | |
| − | Specify when EclipseLink should perform reads through a write connection. For more information, see [[Configuring%20a%20Session%20(ELUG)#Exclusive Write Connections|Exclusive Write Connections]].
| + | |
| − | | + | |
| − | You can set this property while creating either an EntityManagerFactory (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 use in a <tt>persistence.xml</tt> file and for the <tt>org.eclipse.persistence.config.ExclusiveConnectionMode</tt>:
| + | |
| − | * <tt>Transactional</tt> - Create an isolated client session (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated Client Sessions|Isolated Client Sessions]]) if some or all entities require isolated cache<sup> 4 </sup>; otherwise, create a client session.<br>Note: EclipseLink keeps the connection exclusive for the duration of the transaction. Inside the transaction, EclipseLink performs all writes and reads through the exclusive connection. However, outside the Eclipelink transaction, a new connection is acquired from the connection pool for each read and released back immediately after the query is executed.
| + | |
| − | * <tt>Isolated</tt> - Create an exclusive isolated client session if reading an isolated <tt>Entity</tt>; otherwise, raise an error.<br>Note: EclipseLink keeps the connection exclusive for the lifetime of the owning <tt>EntityManager</tt>. Inside the transaction, EclipseLink performs all writes and reads through the exclusive connection. However, outside the Eclipelink transaction only isolated entities are read through the exclusive connection; for nonisolated entities, a new connection is acquired from the connection pool for each read and released back immediately after the query is executed.
| + | |
| − | * <tt>Always</tt> - Create an exclusive isolated client session (see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Isolated Client Sessions|Isolated Client Sessions]]) if reading an isolated <tt>Entity</tt>; otherwise, create an exclusive client session.<br>Note: EclipseLink keeps the connection exclusive for the lifetime of the owning <tt>EntityManager</tt> and performs all writes and reads through the exclusive connection.
| + | |
| − | | + | |
| − | For more information, see [[Configuring%20a%20Session%20(ELUG)#Configuring Connection Policy|Configuring Connection Policy]].
| + | |
| − | | + | |
| − | | + | |
| − | '''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
| + | |
| − | <property name="eclipselink.jdbc.exclusive-connection.mode" value="Always"/>
| + | |
| − |
| + | |
| − | '''Example'''<nowiki>: property </nowiki><tt>Map</tt>
| + | |
| − | import org.eclipse.persistence.config.PersistenceUnitProperties;
| + | |
| − | propertiesMap.put(PersistenceUnitProperties.EXCLUSIVE_CONNECTION_MODE, "Always");
| + | |
| − | | headers="r4c1-t35 r1c3-t35" align="left" |
| + | |
| − | <tt>Transactional</tt>
| + | |
| − | |- 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.<br>
| + | |
| − | <sup>2</sup> This property applies when used both in a Java SE and Java EE environment.<br>
| + | |
| − | <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]).<br>
| + | |
| − | <sup>4</sup> To do this, set the <tt>[[#eclipselink.cache.shared.ENTITY|eclipselink.cache.shared.<ENTITY>]]</tt> property for one or more entities to <tt>false</tt>; Use the <tt>[[#eclipselink.cache.shared.default|eclipselink.cache.shared.default]]</tt> property if you want to use the isolated cache for all entities.
| + | |
| − | | + | |
| − | | + | |
| − | 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]]. Additional information (including examples) is available in [[EclipseLink/Examples/JPA/CustomLogger|How to configure a custom logger in JPA]].
| + | |
| − | | + | |
| − | <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.<br>You may want to set logging to <tt>OFF</tt> during production to avoid the overhead of logging.
| + | |
| − | * <tt>SEVERE</tt> – logs exceptions indicating that 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.<br>You may want to use the <tt>CONFIG</tt> log level at deployment time.
| + | |
| − | * <tt>FINE</tt> – logs SQL.<br>You may want to use this log level during debugging and testing, but not at production time.
| + | |
| − | * <tt>FINER</tt> – similar to <tt>WARNING</tt>. Includes stack trace.<br>You may want to use this log level during debugging and testing, but not at production time.
| + | |
| − | * <tt>FINEST</tt> – includes additional low level information.<br>You may want to use this log level during debugging and testing, but not at production time.
| + | |
| − | * <tt>ALL</tt> – logs at the same level as <tt>FINEST</tt>.
| + | |
| − | | + | |
| − | | + | |
| − | '''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 following are the valid values for the use in a <tt>persistence.xml</tt> file and 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 drivers 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>MySQL</tt> – configure the persistence provider to use a MySQL 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.database.DatabasePlatform</tt> class.
| + | |
| − | | + | |
| − | | + | |
| − | '''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
| + | |
| − | <property name="eclipselink.target-database" value="Oracle"/>
| + | |
| − | | + | |
| − | '''Example'''<nowiki>: </nowiki><tt>persistence.xml</tt> file
| + | |
| − | <property name="eclipselink.target-database" value="org.eclipse.persistence.platform.database.HSQLPlatform"/>
| + | |
| − | | + | |
| − | '''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>WebLogic</tt> – configure the persistence provider to use Oracle WebLogic Server.<br>Note: this server sets this property automatically, so you do not need to set it, unless it is disabled.
| + | |
| − | * <tt>WebLogic_9</tt> – configure the persistence provider to use Oracle WebLogic Server version 9.
| + | |
| − | * <tt>WebLogic_10</tt> – configure the persistence provider to use Oracle WebLogic Server version 10.
| + | |
| − | * <tt>OC4J</tt> – configure the persistence provider to use OC4J.
| + | |
| − | * <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>JBoss</tt> – configure the persistence provider to use JBoss Application Server.
| + | |
| − | * <tt>NetWeaver_7_1</tt> - configure the persistence provider to use SAP NetWeaver Application Server version 7.1 and higher.
| + | |
| − | * 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> – EclipseLink does not generate DDL; no schema is generated.
| + | |
| − | * <tt>create-tables</tt> – EclipseLink will attempt to execute a <tt>CREATE TABLE</tt> SQL for each table. If the table already exists, EclipseLink will follow the default behavior of your specific database and JDBC driver combination (when a <tt>CREATE TABLE</tt> SQL is issued for an already existing table). In most cases an exception is thrown and the table <i>is not</i> created. EclipseLink will then continue with the next statement. (See also <tt>[[#eclipselink.create-ddl-jdbc-file-name|eclipselink.create-ddl-jdbc-file-name]]</tt>.)
| + | |
| − | * <tt>drop-and-create-tables</tt> – EclipseLink will attempt to <tt>DROP</tt> all tables, then <tt>CREATE</tt> all tables. If any issues are encountered, EclipseLink will follow the default behavior of your specific database and JDBC driver combination, then continue with the next statement. (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>database</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]].
| + | |
| − | |}
|
