|
|
| (2 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | <h1 class="chapter"> Using TopLink JPA Extensions</h1>
| |
| | | | |
| − | <p><span class="bold">Version</span>: 5/18/2007</p>
| |
| − | <p>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.</p>
| |
| − | <p>TopLink JPA provides extensions to what is defined in the JPA specification. These extensions come in persistence unit properties, query hints, annotations, TopLink own XML metadata, and custom API.</p>
| |
| − | <p>This document is intended for Oracle TopLink 11g preview. For documentation on TopLink Essentials, refer to <code><a href="http://www.oracle.com/technology/products/ias/toplink/JPA/essentials/toplink-jpa-extensions.html">http://www.oracle.com/technology/products/ias/toplink/JPA/essentials/toplink-jpa-extensions.html</a></code></p>
| |
| − | <p>This document explains where and how you use the extensions to customize JPA behavior to meet your application requirements.</p>
| |
| − | <p>This document includes the following sections:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="#BABFEBAH">Using TopLink JPA Extensions for Mapping</a></p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#BABDFDIG">Using TopLink JPA Converters</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#BABGDJBC">Using TopLink JPA Extensions for Entity Caching</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#BABHBEDD">Using TopLink JPA Extensions for Customization</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#BABDDFGA">Using TopLink JPA Extensions for Returning Policy</a></p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><a href="#BABHAEGH">Using TopLink JPA Extensions for Optimistic Locking</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#BABBIJAC">Using TopLink JPA Extensions for Stored Procedure Query</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACDJBDH">Using TopLink JPA Extensions for JDBC</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACBJEEH">Using TopLink JPA Extensions for Logging</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><a href="#CACFFJFD">Using TopLink JPA Extensions for Session, Target Database and Target Application Server</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACIJBBA">Using TopLink JPA Extensions for Schema Generation</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#BABIDJEG">Using TopLink JPA Extensions for Tracking Changes</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACEGCFG">Using TopLink JPA Query Customization Extensions</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACEDCAF">Using TopLink JPA Lazy Loading</a></p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>For more information, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><span class="italic">Oracle TopLink API Reference</span> at <code><a href="http://www.oracle.com/technology/products/ias/toplink/doc/11110/javadoc/index.html">http://www.oracle.com/technology/products/ias/toplink/doc/11110/javadoc/index.html</a></code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://jcp.org/aboutJava/communityprocess/pfd/jsr220/index.html"><span class="italic">JSR-220 Enterprise JavaBeans v.3.0</span></a> <span class="italic">Java Persistence API specification</span></p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://java.sun.com/javaee/5/docs/api/index.html?javax/persistence/package-summary.html"><span class="italic">Java EE 5 SDK JPA Javadoc</span></a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <a id="BABFEBAH" name="BABFEBAH"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Mapping</h2>
| |
| − | <p>TopLink defines the following mapping metadata annotations (in addition to JPA-defined ones):</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@BasicMap</code> (see <a href="#BABJCFGC">"How to Use the @BasicMap Annotation"</a>)</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@BasicCollection</code> (see <a href="#BABDCAFF">"How to Use the @BasicCollection Annotation"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@CollectionTable</code> (see <a href="#BABFHAHH">"How to Use the @CollectionTable Annotation"</a>)</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>@PrivateOwned</code> (see <a href="#BABGGFIB">"How to Use the @PrivateOwned Annotation"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@JoinFetch</code> (see <a href="#CACCFACF">"How to Use the @JoinFetch Annotation"</a>)</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − |
| |
| − | <p>TopLink persistence provider searches mapping annotations in the following order:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@BasicCollection</code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@BasicMap</code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@EmbeddedId</code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@Embedded</code></p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@ManyToMany</code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@ManyToOne</code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@OneToMany</code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@OneToOne</code></p>
| |
| − | </li>
| |
| − |
| |
| − | </ul>
| |
| − | <p>TopLink persistence provider applies the first annotation that it finds; it ignores other mapping annotations, if specified. In most cases, TopLink does not log warnings or throw exceptions.</p>
| |
| − | <p>If TopLink 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 <code>@Basic</code> annotation (see Section 9.1.18 "Basic Annotation" of the JPA specification)).</p>
| |
| − | <a id="BABJCFGC" name="BABJCFGC"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @BasicMap Annotation</h3>
| |
| − | <p>You can use the <code>@BasicMap</code> annotation to map an <code>oracle.toplink.mappings.DirectMapMapping</code>, which stores a collection of key-value pairs of simple types, such as <code>String</code>, <code>Number</code>, <code>Date</code>, and so on, in a single table. The table must store the value and the foreign key to the source object.</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface BasicMap { ... }
| |
| − | </pre>
| |
| − | <p>Use the <code>@BasicMap</code> annotation in conjunction with a <code>@CollectionTable</code> annotation (see <a href="#BABFHAHH">"How to Use the @CollectionTable Annotation"</a>).</p>
| |
| − | <p><a href="#BABHHCFB">Table 1-1</a> lists attributes of the <code>@BasicMap</code> annotation.</p>
| |
| − |
| |
| − | <div class="tblruleformalwidemax"><a id="sthref1" name="sthref1"></a><a id="BABHHCFB" name="BABHHCFB"></a>
| |
| − | <p class="titleintable">Table 1-1 Attributes of the @BasicMap Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @BasicMap Annotation" summary="This table lists the attributes of TopLink JPA @BasicMap annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t2">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t2">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t2">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t2">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t2" headers="r1c1-t2">
| |
| − | <p><code>fetch</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t2 r1c2-t2">
| |
| − | <p>Set this attribute to the <code>javax.persistence.FetchType</code> enumerated type to define whether TopLink persistence provider has to lazily load or eagerly fetch the value of the field or property.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t2 r1c3-t2">
| |
| − | <p><code>FetchType.LAZY</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t2 r1c4-t2">
| |
| − |
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t2" headers="r1c1-t2">
| |
| − | <p><code>keyColumn</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t2 r1c2-t2">
| |
| − | <p>Set this attribute to the name of the data column (<code>javax.persistence.Column</code>) that holds the direct map key.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t2 r1c3-t2">
| |
| − | <p>no default</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t2 r1c4-t2">
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t2" headers="r1c1-t2">
| |
| − | <p><code>keyConverter</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t2 r1c2-t2">
| |
| − | <p>Set this attribute to the key converter (<code>java.toplink.annotations.Convert</code>)</p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r4c1-t2 r1c3-t2">
| |
| − | <p><code>@Convert</code>–an equivalent of specifying <code>@Convert("none")</code> resulting in no converter added to the direct map key.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t2 r1c4-t2">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t2" headers="r1c1-t2">
| |
| − | <p><code>valueColumn</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t2 r1c2-t2">
| |
| − | <p>Set this attribute to the name of the value column (<code>javax.persistence.Column</code>) that holds the direct collection data.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t2 r1c3-t2">
| |
| − | <p><code>@Column</code></p>
| |
| − | <p>Note: TopLink persistence provider sets the default to the name of the field or property.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t2 r1c4-t2">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − |
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t2" headers="r1c1-t2">
| |
| − | <p><code>valueConverter</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t2 r1c2-t2">
| |
| − | <p>Set this attribute to the value converter (<code>java.toplink.annotations.Convert</code>).</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t2 r1c3-t2">
| |
| − | <p><code>@Convert</code>–an equivalent of specifying <code>@Convert("none")</code> resulting in no converter added to the direct map key.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t2 r1c4-t2">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − |
| |
| − | If you specify <code>@BasicMap</code> on an attribute of type <code>Collection</code>, TopLink will throw an exception.</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <p><a href="#BABFDCCJ">Example 1-1</a> shows how to use the <code>@BasicMap</code> annotation to specify <code>Employee</code> field <code>licenses</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="BABFDCCJ" name="BABFDCCJ"></a>
| |
| − | <p class="titleinexample">Example 1-1 Usage of the @BasicMap Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @Table(name="CMP3_EMPLOYEE")
| |
| − | @TypeConverter(
| |
| − | name="Integer2String",
| |
| − | dataType=Integer.class,
| |
| − | objectType=String.class
| |
| − | )
| |
| − | public class Employee implements Serializable{
| |
| − | ...
| |
| − | @BasicMap (
| |
| − | fetch="EAGER",
| |
| − | keyColumn=@Column(name="LICENSE"),
| |
| − | keyConverter=@Convert("licenseConverter"),
| |
| − | valueColumn=@Column(name="STATUS")),
| |
| − | valueConverter=@Convert("Integer2String")
| |
| − | )
| |
| − | @ObjectConverter(
| |
| − | 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> getLicenses() {
| |
| − | return licenses;
| |
| − | }
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABDCAFF" name="BABDCAFF"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @BasicCollection Annotation</h3>
| |
| − | <p>You can use the <code>@BasicCollection</code> annotation to map an <code>oracle.toplink.mappings.DirectCollectionMapping</code>, which stores a collection of simple types, such as <code>String</code>, <code>Number</code>, <code>Date</code>, and so on, in a single table. The table must store the value and the foreign key to the source object.</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface BasicCollection { ... }
| |
| − | </pre>
| |
| − | <p>Use the <code>@BasicCollection</code> annotation in conjunction with a <code>@CollectionTable</code> annotation (see <a href="#BABFHAHH">"How to Use the @CollectionTable Annotation"</a>). You can also use it in conjunction with <code>@Convert</code> (see <a href="#BABCHBGG">"How to Use the @Convert Annotation"</a>) to modify the data value(s) during reading and writing of the collection.</p>
| |
| − |
| |
| − | <p><a href="#BABEIFAC">Table 1-2</a> lists attributes of the <code>@BasicCollection</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref2" name="sthref2"></a><a id="BABEIFAC" name="BABEIFAC"></a>
| |
| − | <p class="titleintable">Table 1-2 Attributes of the @BasicCollection Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @BasicCollection Annotation" summary="This table lists the attributes of TopLink JPA @BasicCollection annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t4">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t4">Description</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c3-t4">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t4">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t4" headers="r1c1-t4">
| |
| − | <p><code>fetch</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t4 r1c2-t4">
| |
| − | <p>The <code>javax.persistence.FetchType</code> enumerated type that defines whether TopLink should lazily load or eagerly fetch the value of the field or property.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t4 r1c3-t4">
| |
| − | <p><code>FetchType.LAZY</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t4 r1c4-t4">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t4" headers="r1c1-t4">
| |
| − | <p><code>valueColumn</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t4 r1c2-t4">
| |
| − | <p>The name of the value column (<code>javax.persistence.Column</code>) that holds the direct collection data.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t4 r1c3-t4">
| |
| − | <p><code>@Column</code></p>
| |
| − | <p>Note: TopLink persistence provider sets the default to the name of the field or property.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t4 r1c4-t4">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <div align="center">
| |
| − |
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | If you specify <code>@BasicCollection</code> on an attribute of type <code>Map</code>, TopLink will throw an exception.</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − |
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <p><a href="#BABEBJDI">Example 1-2</a> shows how to use the <code>@BasicCollection</code> annotation to specify <code>Employee</code> field <code>responsibilities</code>.</p>
| |
| − | <div class="example"><a id="BABEBJDI" name="BABEBJDI"></a>
| |
| − | <p class="titleinexample">Example 1-2 Usage of the @BasicCollection Annotation</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | public class Employee implements Serializable{
| |
| − | ...
| |
| − | @BasicCollection (
| |
| − | fetch="EAGER",
| |
| − | valueColumn=@Column(name="DESCRIPTION")
| |
| − | )
| |
| − | @CollectionTable (
| |
| − | name="RESPONS",
| |
| − | primaryKeyJoinColumns=
| |
| − | {@PrimaryKeyJoinColumn(name="EMPLOYEE_ID", referencedColumnName="EMP_ID")}
| |
| − | )
| |
| − | public Collection getResponsibilities() {
| |
| − | return responsibilities;
| |
| − | }
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABFHAHH" name="BABFHAHH"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @CollectionTable Annotation</h3>
| |
| − | <p>You can use the <code>@CollectionTable</code> annotation in conjunction with a <code>@BasicCollection</code> annotation (see <a href="#BABDCAFF">"How to Use the @BasicCollection Annotation"</a>) or the <code>@BasicMap</code> annotation (see <a href="#BABJCFGC">"How to Use the @BasicMap Annotation"</a>). If you do not specify the <code>@CollectionTable</code>, TopLink persistence provider will use the defaults.</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface CollectionTable { ... }
| |
| − | </pre>
| |
| − | <p><a href="#BABFJECG">Table 1-3</a> lists attributes of the <code>@CollectionTable</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref3" name="sthref3"></a><a id="BABFJECG" name="BABFJECG"></a>
| |
| − | <p class="titleintable">Table 1-3 Attributes of the @CollectionTable Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @CollectionTable Annotation" summary="This table lists the attributes of TopLink JPA @CollectionTable annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t6">Attribute</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c2-t6">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t6">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t6">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t6" headers="r1c1-t6">
| |
| − | <p><code>name</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t6 r1c2-t6">
| |
| − | <p>Set this attribute to the <code>String</code> name for your collection table.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t6 r1c3-t6">
| |
| − | <p>empty <code>String</code></p>
| |
| − | <p>Note: TopLink persistence provider applies the following concatenated <code>String</code> as a default: the name of the source entity + "_" + the name of the relationship property or field of the source entity.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t6 r1c4-t6">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r3c1-t6" headers="r1c1-t6">
| |
| − | <p><code>catalog</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t6 r1c2-t6">
| |
| − | <p>Set this attribute to the <code>String</code> name of the table's catalog.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t6 r1c3-t6">
| |
| − | <p>empty <code>String</code></p>
| |
| − | <p>Note: TopLink persistence provider sets the default to the persistence unit's default catalog.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t6 r1c4-t6">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t6" headers="r1c1-t6">
| |
| − | <p><code>schema</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t6 r1c2-t6">
| |
| − | <p>Set this attribute to the <code>String</code> name of the table's schema.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t6 r1c3-t6">
| |
| − | <p>empty <code>String</code></p>
| |
| − | <p>Note: TopLink persistence provider sets the default to the persistence unit's default schema.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t6 r1c4-t6">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t6" headers="r1c1-t6">
| |
| − | <p><code>primaryKeyJoinColumns</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t6 r1c2-t6">
| |
| − | <p>Set this attribute to an array of <code>javax.persistence.PrimaryKeyJoinColumn</code> 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, TopLink persistence provider will apply the following defaults:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>javax.persistence.PrimaryKeyJoinColumn</code> <code>name</code>–the same name as the primary key column of the primary table of the source entity;</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>javax.persistence.PrimaryKeyJoinColumn referencedColumnName</code>–the same name of the primary key column of the primary table of the source entity.</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>If the source entity uses a composite primary key and you failed to specify the primary key join columns, TopLink will throw an exception.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t6 r1c3-t6">
| |
| − | <p>empty <code>PrimaryKeyJoinColumn</code> array</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t6 r1c4-t6">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t6" headers="r1c1-t6">
| |
| − | <p><code>uniqueConstraints</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t6 r1c2-t6">
| |
| − | <p>Set this attribute to an array of <code>javax.persistence.UniqueConstraint</code> instances that you want to place on the table. These constraints are only used if table generation is in effect.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t6 r1c3-t6">
| |
| − | <p>empty <code>UniqueConstraint</code> array</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t6 r1c4-t6">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#CJAGDAFA">Example 1-3</a> shows how to use the <code>@CollectionTable</code> annotation to specify <code>Employee</code> field <code>responsibilities</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAGDAFA" name="CJAGDAFA"></a>
| |
| − | <p class="titleinexample">Example 1-3 Usage of the @CollectionTable Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @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;
| |
| − | }
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABGGFIB" name="BABGGFIB"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @PrivateOwned Annotation</h3>
| |
| − | <p>Use the <code>@PrivateOwned</code> annotation in conjunction with a <code>@OneToOne</code> annotation (see Section 9.1.23 "OneToOne Annotation" of the JPA specification), or a <code>@OneToMany</code> annotation (see Section 9.1.24 "OneToMany Annotation" of the JPA specification).</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface PrivateOwned { ... }
| |
| − | </pre>
| |
| − | <p>The <code>@PrivateOwned</code> annotation does not have attributes.</p>
| |
| − | <p><a href="#BABFADHG">Example 1-4</a> shows how to use the <code>@PrivateOwned</code> annotation to specify <code>Employee</code> field <code>managedEmployees</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="BABFADHG" name="BABFADHG"></a>
| |
| − | <p class="titleinexample">Example 1-4 Usage of the @PrivateOwned Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | public class Employee implements Serializable {
| |
| − | ...
| |
| − | @OneToMany(cascade=ALL, mappedBy="owner")
| |
| − | @PrivateOwned
| |
| − | public Collection getPhoneNumbers() {
| |
| − | return phoneNumbers;
| |
| − | }
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref4" name="sthref4"></a>
| |
| − | <h4 class="sect3">What You May Need to Know About Private Ownership of Objects</h4>
| |
| − | <p>When the referenced object is privately owned the referenced child object cannot exist without the parent object.</p>
| |
| − | <p>When you tell TopLink that a relationship is privately owned, you are specifying the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p>If the source of a privately owned relationship is deleted, then delete the target. Note that this is equivalent of setting a cascade delete. For more information, see the following:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="circle">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descun.htm#CHECICGH">Optimistic Version Locking Policies and Cascading</a></p>
| |
| − | </li>
| |
| − | <li type="circle">
| |
| − | <p>Section 3.2.2 "Removal" of the JPA specification;</p>
| |
| − | </li>
| |
| − | <li type="circle">
| |
| − | <p>Section 3.5.2 "Semantics of the Life Cycle Callback Methods for Entities" of the JPA specification;</p>
| |
| − | </li>
| |
| − | <li type="circle">
| |
| − | <p>Section 4.10 "Bulk Update and Delete Operations" of the JPA specification;</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="circle">
| |
| − | <p>Section 9.1.23 "OneToOne Annotation" of the JPA specification;</p>
| |
| − | </li>
| |
| − | <li type="circle">
| |
| − | <p>Section 9.1.22 "ManyToOne Annotation" of the JPA specification;</p>
| |
| − | </li>
| |
| − | <li type="circle">
| |
| − | <p>Section 9.1.24 "OneToMany Annotation" of the JPA specification;</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>If you remove the reference to a target from a source, then delete the target.</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>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.</p>
| |
| − | <p>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.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowbas.htm#i1134011">Using the privateOwnedRelationship Attribute</a>".</p>
| |
| − | </div>
| |
| − | <!-- class="sect3" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="CACCFACF" name="CACCFACF"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @JoinFetch Annotation</h3>
| |
| − |
| |
| − | <p>You can specify the <code>@JoinFetch</code> annotation for the following mappings:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@OneToOne</code> (see Section 9.1.23 "OneToOne Annotation" of the JPA specification);</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@OneToMany</code> (see Section 9.1.24 "OneToMany Annotation" of the JPA specification);</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@ManyToOne</code> (see Section 9.1.22 "ManyToOne Annotation" of the JPA specification);</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@ManyToMany</code> (see Section 9.1.26 "ManyToMany Annotation" of the JPA specification);</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@BasicCollection</code> (see <a href="#BABDCAFF">"How to Use the @BasicCollection Annotation"</a>);</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@BasicMap</code> (see <a href="#BABJCFGC">"How to Use the @BasicMap Annotation"</a>).</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface JoinFetch { ... }
| |
| − | </pre>
| |
| − | <p>Using the <code>@JoinFetch</code> annotation, you can enable the joining and reading of the related objects in the same query as the source object.</p>
| |
| − |
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | Oracle recommends setting join fetching at the query level, as not all queries require joining. For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qrybas.htm#a1158158">Using Join Reading</a>".</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − |
| |
| − | <p>Alternatively, you can use batch reading, especially for collection relationships. For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qrybas.htm#i1165217">Using Batch Reading</a>".</p>
| |
| − | <p><a href="#BABFHHEH">Table 1-4</a> lists attributes of the <code>@JoinFetch</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref5" name="sthref5"></a><a id="BABFHHEH" name="BABFHHEH"></a>
| |
| − | <p class="titleintable">Table 1-4 Attributes of the @JoinFetch Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @JoinFetch Annotation" summary="This table lists the attributes of TopLink JPA @BasicCollection annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c1-t8">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t8">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t8">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t8">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t8" headers="r1c1-t8">
| |
| − | <p><code>value</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t8 r1c2-t8">
| |
| − |
| |
| − | <p>Set this attribute to the <code>oracle.toplink.annotations.JoinFetchType</code> enumerated type of the fetch that you will be using.</p>
| |
| − | <p>The following are the valid values for the <code>JoinFetchType</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>INNER</code>–This option provides the inner join fetching of the related object.</p>
| |
| − | <p>Note: inner joining does not allow for null or empty values.</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>OUTER</code>–This option provides the outer join fetching of the related object.</p>
| |
| − | <p>Note: outer joining allows for null or empty values.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>For more information, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/expres.htm#CJABCJII">Understanding Joins</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qrybas.htm#a1158158">Using Join Reading</a></p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/oomapcfg.htm#CHDHGFGG">Configuring Joining at the Mapping Level</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t8 r1c3-t8">
| |
| − | <p><code>JoinFetchType.INNER</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t8 r1c4-t8">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − |
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="BABDFDIG" name="BABDFDIG"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Converters</h2>
| |
| − | <p>TopLink defines the following converter annotations (in addition to JPA-defined ones):</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@Converter</code> (see <a href="#BABDBCIA">"How to Use the @Converter Annotation"</a>)</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@TypeConverter</code> (see <a href="#BABHEDEE">"How to Use the @TypeConverter Annotation"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@ObjectTypeConverter</code> (see <a href="#BABGCAEA">"How to Use the @ObjectTypeConverter Annotation"</a>)</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>@Convert</code> (see <a href="#BABCHBGG">"How to Use the @Convert Annotation"</a>)</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>TopLink persistence provider searches the converter annotations in the following order:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@Converter</code> (see <a href="#BABDBCIA">"How to Use the @Converter Annotation"</a>)</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@Enumerated</code> (see Section 9.1.21 "Enumerated Annotation" of the JPA specification)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@Lob</code> (see Section 9.1.19 "Lob Annotation" of the JPA specification)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@Temporal</code> (see Section 9.1.20 "Temporal Annotation" of the JPA specification)</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Serialized (automatic)</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>You can define converters at the class, field and property level. You can specify TopLink converters on the following classes:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@Entity</code> (see Section 8.1 "Entity" of the JPA specification);</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@MappedSuperclass</code> (see Section 9.1.36 "MappedSuperclass Annotation" of the JPA specification);</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@Embeddable</code> (see Section 9.1.34 "Embeddable Annotation" of the JPA specification).</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>TopLink supports the use of converters with the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@Basic</code> (see Section 9.1.18 "Basic Annotation" of the JPA specification)</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>@BasicMap</code> (see <a href="#BABJCFGC">"How to Use the @BasicMap Annotation"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@BasicCollection</code> (see <a href="#BABDCAFF">"How to Use the @BasicCollection Annotation"</a>)</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − |
| |
| − | <p>If you specify a converter with any other type of mapping annotation, TopLink will throw an exception.</p>
| |
| − | <a id="BABDBCIA" name="BABDBCIA"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @Converter Annotation</h3>
| |
| − | <p>You can use <code>@Converter</code> annotation to specify a custom converter for modification of the data value(s) during the reading and writing of a mapped attribute.</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE, METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface Converter { ... }
| |
| − | </pre>
| |
| − | <p><a href="#BABJCFIG">Table 1-5</a> lists attributes of the <code>@Converter</code> annotation.</p>
| |
| − |
| |
| − | <div class="tblruleformalwidemax"><a id="sthref6" name="sthref6"></a><a id="BABJCFIG" name="BABJCFIG"></a>
| |
| − | <p class="titleintable">Table 1-5 Attributes of the @Converter Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @Converter Annotation" summary="This table lists the attributes of TopLink JPA @Converter annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t9">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t9">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t9">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t9">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t9" headers="r1c1-t9">
| |
| − | <p><code>name</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t9 r1c2-t9">
| |
| − | <p>Set this attribute to the <code>String</code> name for your converter. Ensure that this name is unique across the persistence unit</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t9 r1c3-t9">
| |
| − | <p>no default</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t9 r1c4-t9">
| |
| − |
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t9" headers="r1c1-t9">
| |
| − | <p><code>converterClass</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t9 r1c2-t9">
| |
| − | <p>Set this attribute to the <code>Class</code> of your converter. This class must implement the TopLink <code>oracle.toplink.mappings.converters.Converter</code> interface.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t9 r1c3-t9">
| |
| − | <p>no default</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t9 r1c4-t9">
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#BABFHCDB">Example 1-5</a> shows how to use the <code>@Converter</code> annotation to specify <code>Employee</code> field <code>gender</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="BABFHCDB" name="BABFHCDB"></a>
| |
| − | <p class="titleinexample">Example 1-5 Usage of the @Converter Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | public class Employee implements Serializable{
| |
| − | ...
| |
| − | @Basic
| |
| − | @Converter (
| |
| − | name="genderConverter",
| |
| − | converterClass=org.myorg.converters.GenderConverter.class
| |
| − | )
| |
| − | @Convert("genderConverter")
| |
| − | public String getGender() {
| |
| − | return gender;
| |
| − | }
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABHEDEE" name="BABHEDEE"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @TypeConverter Annotation</h3>
| |
| − | <p>The <code>@TypeConverter</code> is a TopLink-specific annotation. You can use it to specify a TopLink <code>oracle.toplink.mappings.converters.TypeConversionConverter</code> for modification of the data value(s) during the reading and writing of a mapped attribute.</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE, METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface TypeConverter { ... }
| |
| − | </pre>
| |
| − | <p><a href="#BABEAFDC">Table 1-6</a> lists attributes of the <code>@TypeConverter</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref7" name="sthref7"></a><a id="BABEAFDC" name="BABEAFDC"></a>
| |
| − | <p class="titleintable">Table 1-6 Attributes of the @TypeConverter Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @TypeConverter Annotation" summary="This table lists the attributes of TopLink JPA @TypeConverter annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t10">Attribute</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c2-t10">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t10">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t10">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t10" headers="r1c1-t10">
| |
| − | <p><code>name</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t10 r1c2-t10">
| |
| − | <p>Set this attribute to the <code>String</code> name for your converter. Ensure that this name is unique across the persistence unit</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t10 r1c3-t10">
| |
| − | <p>no default</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t10 r1c4-t10">
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t10" headers="r1c1-t10">
| |
| − | <p><code>dataType</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t10 r1c2-t10">
| |
| − | <p>Set this attribute to the type stored in the database.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t10 r1c3-t10">
| |
| − | <p><code>void.class</code></p>
| |
| − | <p>Note: The default is inferred from the type of the persistence field or property.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t10 r1c4-t10">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t10" headers="r1c1-t10">
| |
| − | <p><code>objectType</code></p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r4c1-t10 r1c2-t10">
| |
| − | <p>Set the value of this attribute to the type stored on the entity.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t10 r1c3-t10">
| |
| − | <p><code>void.class</code></p>
| |
| − | <p>Note: The default is inferred from the type of the persistence field or property.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t10 r1c4-t10">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − |
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#BABECICJ">Example 1-6</a> shows how to use the <code>@TypeConverter</code> annotation to convert the <code>Double</code> value stored in the database to a <code>Float</code> value stored in the entity.</p>
| |
| − | <div class="example"><a id="BABECICJ" name="BABECICJ"></a>
| |
| − | <p class="titleinexample">Example 1-6 Usage of the @TypeConverter Annotation</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | public class Employee implements Serializable{
| |
| − | ...
| |
| − | @TypeConverter (
| |
| − | name="doubleToFloat",
| |
| − | dataType=Double.class,
| |
| − | objectType=Float.class,
| |
| − | )
| |
| − | @Convert("doubleToFloat")
| |
| − | public Number getGradePointAverage() {
| |
| − | return gradePointAverage;
| |
| − | }
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABGCAEA" name="BABGCAEA"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @ObjectTypeConverter Annotation</h3>
| |
| − | <p>You can use the <code>@ObjectTypeConverter</code> annotation to specify a TopLink <code>oracle.toplink.mappings.converters.ObjectTypeConverter</code> that converts a fixed number of database data value(s) to Java object value(s) during the reading and writing of a mapped attribute.</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE, METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface ObjectTypeConverter { ... }
| |
| − | </pre>
| |
| − | <p><a href="#BABFCGJF">Table 1-7</a> lists attributes of the <code>@ObjectTypeConverter</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref8" name="sthref8"></a><a id="BABFCGJF" name="BABFCGJF"></a>
| |
| − | <p class="titleintable">Table 1-7 Attributes of the @ObjectTypeConverter Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @ObjectTypeConverter Annotation" summary="This table lists the attributes of TopLink JPA @ObjectTypeConverter annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t11">Attribute</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c2-t11">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t11">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t11">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t11" headers="r1c1-t11">
| |
| − | <p><code>name</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t11 r1c2-t11">
| |
| − | <p>Set this attribute to the <code>String</code> name for your converter. Ensure that this name is unique across the persistence unit</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t11 r1c3-t11">
| |
| − | <p>no default</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t11 r1c4-t11">
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t11" headers="r1c1-t11">
| |
| − | <p><code>dataType</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t11 r1c2-t11">
| |
| − | <p>Set this attribute to the type stored in the database.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t11 r1c3-t11">
| |
| − | <p><code>void.class</code></p>
| |
| − | <p>Note: The default is inferred from the type of the persistence field or property.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t11 r1c4-t11">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t11" headers="r1c1-t11">
| |
| − | <p><code>objectType</code></p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r4c1-t11 r1c2-t11">
| |
| − | <p>Set the value of this attribute to the type stored on the entity.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t11 r1c3-t11">
| |
| − | <p><code>void.class</code></p>
| |
| − | <p>Note: The default is inferred from the type of the persistence field or property.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t11 r1c4-t11">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t11" headers="r1c1-t11">
| |
| − |
| |
| − | <p><code>conversionValues</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t11 r1c2-t11">
| |
| − | <p>Set the value of this attribute to the array of conversion values (instances of <code>ConversionValue</code>: <code>String objectValue</code> and <code>String dataValue</code>. See <a href="#BABJEBJA">Example 1-7</a>) to be used with the object converter.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t11 r1c3-t11">
| |
| − |
| |
| − | <p>no default</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t11 r1c4-t11">
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t11" headers="r1c1-t11">
| |
| − | <p><code>defaultObjectValue</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t11 r1c2-t11">
| |
| − | <p>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.</p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r6c1-t11 r1c3-t11">
| |
| − | <p>empty <code>String</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t11 r1c4-t11">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#BABJEBJA">Example 1-7</a> shows how to use the <code>@ObjectTypeConverter</code> annotation to specify the <code>Employee</code> field <code>gender</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="BABJEBJA" name="BABJEBJA"></a>
| |
| − | <p class="titleinexample">Example 1-7 Usage of the @ObjectTypeConverter Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | 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;
| |
| − | }
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABCHBGG" name="BABCHBGG"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @Convert Annotation</h3>
| |
| − | <p>The <code>@Convert</code> annotation specifies that a named converter should be used with the corresponding mapped attribute.</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface Convert { ... }
| |
| − | </pre>
| |
| − | <p>The <code>@Convert</code> has the following reserved names:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>serialized</code>–places the <code>oracle.toplink.mappings.converters.SerializedObjectConverter</code> on the associated mapping.</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>none</code>–does not place a converter on the associated mapping.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><a href="#BABBJEIF">Table 1-8</a> lists attributes of the <code>@Convert</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref9" name="sthref9"></a><a id="BABBJEIF" name="BABBJEIF"></a>
| |
| − | <p class="titleintable">Table 1-8 Attributes of the @Convert Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @Convert Annotation" summary="This table lists the attributes of TopLink JPA @Convert annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − |
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t12">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t12">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t12">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t12">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t12" headers="r1c1-t12">
| |
| − | <p><code>value</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t12 r1c2-t12">
| |
| − | <p>Set this attribute to the <code>String</code> name for your converter.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t12 r1c3-t12">
| |
| − | <p><code>"none" String</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t12 r1c4-t12">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − |
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#BABHHCCH">Example 1-8</a> shows how to use the <code>@Convert</code> annotation to define the <code>Employee</code> field <code>gender</code>.</p>
| |
| − | <div class="example"><a id="BABHHCCH" name="BABHHCCH"></a>
| |
| − |
| |
| − | <p class="titleinexample">Example 1-8 Usage of the @Convert Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @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;
| |
| − | }
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="BABGDJBC" name="BABGDJBC"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Entity Caching</h2>
| |
| − | <p>The TopLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. TopLink uses the cache to do the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p>Improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Manage locking and isolation level.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Manage object identity.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>For more information about the TopLink cache and its default behavior, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#CHEJAEBH">Understanding the Cache</a>".</p>
| |
| − | <p>TopLink defines the following entity caching annotations:</p>
| |
| − | <ul>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>@Cache</code> (see <a href="#BABFCJJB">"How to Use the @Cache Annotation"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@TimeOfDay</code> (see <a href="#BABCIHBD">"How to Use the @TimeOfDay Annotation"</a>)</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − |
| |
| − | <p>TopLink also provides a number of persistence unit properties that you can specify to configure the TopLink cache (see <a href="#CACCFEAG">"How to Use the Persistence Unit Properties for Caching"</a>). These properties may compliment or provide an alternative to the usage of annotations. For more information, see <a href="#CJAFAHEJ">"What You May Need to Know About Overriding Annotations"</a>.</p>
| |
| − | <a id="BABFCJJB" name="BABFCJJB"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @Cache Annotation</h3>
| |
| − | <p>TopLink 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 <code>@Cache</code> annotation.</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface Cache { ... }
| |
| − |
| |
| − | </pre>
| |
| − | <p>You may define the <code>@Cache</code> annotation on the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@Entity</code> (see Section 8.1 "Entity" of the JPA specification);</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@MappedSuperclass</code> (see Section 9.1.36 "MappedSuperclass Annotation" of the JPA specification);</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>the root of the inheritance hierarchy (if applicable).</p>
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | If you define the <code>@Cache</code> annotation on an inheritance subclass, the annotation will be ignored.</td>
| |
| − |
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><a href="#BABHBIJE">Table 1-9</a> lists attributes of the <code>@Cache</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref10" name="sthref10"></a><a id="BABHBIJE" name="BABHBIJE"></a>
| |
| − | <p class="titleintable">Table 1-9 Attributes of the @Cache Annotation</p>
| |
| − |
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @Cache Annotation" summary="This table lists the attributes of TopLink JPA Cache annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t14">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t14">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t14">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t14">Required or Optional</th>
| |
| − | <th align="left" valign="bottom" id="r1c5-t14">Override with Persistence Unit Property</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r2c1-t14" headers="r1c1-t14">
| |
| − | <p><a id="CACDJFCF" name="CACDJFCF"></a><code>type</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t14 r1c2-t14">
| |
| − | <p>Set this attribute to the type (<code>oracle.toplink.annotations.CacheType</code> enumerated type) of the cache that you will be using.</p>
| |
| − | <p>The following are the valid values for the <code>CacheType</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>FULL</code>–This option provides full caching and guaranteed identity: all objects are cached and not removed.</p>
| |
| − |
| |
| − | <p>Note: this process may be memory-intensive when many objects are read.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>WEAK</code>–This option is similar to <code>FULL</code>, except that objects are referenced using weak references. This option uses less memory than <code>FULL</code>, allows complete garbage collection and provides full caching and guaranteed identity.</p>
| |
| − | <p>Oracle recommends using this identity map for transactions that, once started, stay on the server side.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SOFT_WEAK</code>–This option is similar to <code>WEAK</code> 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.</p>
| |
| − |
| |
| − | <p>Oracle recommends using this identity map in most circumstances as a means to control memory used by the cache.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>HARD_WEAK</code>–This option is similar to <code>SOFT_WEAK</code> 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.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CACHE</code>–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.</p>
| |
| − | <p>Note: this option furnishes caching and identity, but does not guarantee identity.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>NONE</code>–This option does not preserve object identity and does not cache objects. Oracle does not recommend using this option.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t14 r1c3-t14">
| |
| − | <p><code>CacheType.SOFT_WEAK</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t14 r1c4-t14">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t14 r1c5-t14">
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACGFGJE">toplink.cache.type.<ENTITY></a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACCAEFH">toplink.cache.type.default</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t14" headers="r1c1-t14">
| |
| − | <p><code>isolated</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t14 r1c2-t14">
| |
| − | <p>Set this attribute to a <code>boolean</code> value to indicate whether cached instances should be in the shared cache or in a client isolated cache (see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowadv.htm#CACCGBHG">Isolated Client Session Cache</a>").</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t14 r1c3-t14">
| |
| − | <p><code>false</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t14 r1c4-t14">
| |
| − | <p>optional</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t14 r1c5-t14"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t14" headers="r1c1-t14">
| |
| − | <p><code>expiry</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t14 r1c2-t14">
| |
| − | <p>Set this attribute to the <code>int</code> 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.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t14 r1c3-t14">
| |
| − | <p>-1 (no expiry)</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t14 r1c4-t14">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t14 r1c5-t14"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t14" headers="r1c1-t14">
| |
| − | <p><code>expiryTimeOfDay</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t14 r1c2-t14">
| |
| − | <p>Set this attribute to a specific time of day (<code>oracle.toplink.annotations.TimeOfDay</code>) when the cached instance will expire. Queries executed against the cache after this will be forced back to the database for a refreshed copy.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t14 r1c3-t14">
| |
| − | <p><code>@TimeOfDay(specified=false)</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t14 r1c4-t14">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t14 r1c5-t14"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t14" headers="r1c1-t14">
| |
| − | <p><code>alwaysRefresh</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t14 r1c2-t14">
| |
| − |
| |
| − | <p>Set this attribute to a <code>boolean</code> value of <code>true</code> to force all queries that go to the database to always refresh the cache.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t14 r1c3-t14">
| |
| − | <p><code>false</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t14 r1c4-t14">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r6c1-t14 r1c5-t14"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r7c1-t14" headers="r1c1-t14">
| |
| − | <p><code>refreshOnlyIfNewer</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t14 r1c2-t14">
| |
| − | <p>Set this attribute to a <code>boolean</code> value of <code>true</code> 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).</p>
| |
| − | <p>Note: this option only applies if one of the other refreshing options, such as <code>alwaysRefresh</code>, is already enabled.</p>
| |
| − |
| |
| − | <p>Note: a version field is necessary to apply this feature.</p>
| |
| − | <p>For more information, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CJAEHCDC">What You May Need to Know About Version Fields</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descun.htm#CIHJCGBA">Optimistic Version Locking Policies</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Section 3.4 "Optimistic Locking and Concurrency" of the JPA specification</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p>Section 9.1.17 "Version Annotation" of the JSR 220 EJB 3.0 JPA specification</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t14 r1c3-t14">
| |
| − | <p><code>false</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t14 r1c4-t14">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t14 r1c5-t14"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r8c1-t14" headers="r1c1-t14">
| |
| − | <p><code>disableHits</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t14 r1c2-t14">
| |
| − | <p>Set this attribute to a <code>boolean</code> value of <code>true</code> 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.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t14 r1c3-t14">
| |
| − | <p><code>false</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t14 r1c4-t14">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t14 r1c5-t14"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r9c1-t14" headers="r1c1-t14">
| |
| − | <p><code>coordinationType</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r9c1-t14 r1c2-t14">
| |
| − | <p>Set this attribute to the cache coordination mode (<code>oracle.toplink.annotations.CacheCoordinationType</code> enumerated type).</p>
| |
| − |
| |
| − | <p>The following are the valid values for the <code>CacheCoordinationType</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>SEND_OBJECT_CHANGES</code>–This option sends a list of changed objects (including information about the changes). This data is merged into the receiving cache.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>INVALIDATE_CHANGED_OBJECTS</code>–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).</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SEND_NEW_OBJECTS_WITH_CHANGES</code>–This option is similar to <code>SEND_OBJECT_CHANGES</code> except it also includes any newly created objects from the transaction.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>NONE</code>–This option does not coordinate cache.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#CHEDFBFB">Understanding Cache Coordination</a>".</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r9c1-t14 r1c3-t14">
| |
| − | <p><code>CacheCoordinationType.SEND_OBJECT_CHANGES</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r9c1-t14 r1c4-t14">
| |
| − |
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r9c1-t14 r1c5-t14"><br /></td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − |
| |
| − | If you define the <code>@Cache</code> annotation on <code>@Embeddable</code>, TopLink will throw an exception.</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <p><a href="#BABIHGBG">Example 1-9</a> shows how to achieve the desired behavior of the TopLink cache by defining the attributes of the <code>@Cache</code> annotation.</p>
| |
| − |
| |
| − | <div class="example"><a id="BABIHGBG" name="BABIHGBG"></a>
| |
| − | <p class="titleinexample">Example 1-9 Usage of @Cache Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @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 {
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <a id="CJAEHCDC" name="CJAEHCDC"></a>
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" -->
| |
| − | <h4 class="sect3">What You May Need to Know About Version Fields</h4>
| |
| − | <p>By default, TopLink persistence provider assumes that the application is responsible for data consistency.</p>
| |
| − | <p>Use the <code>@Version</code> annotation (see Section 9.1.17 "Version Annotation" of theJPA specification) 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).</p>
| |
| − |
| |
| − | <p>When choosing a version field or property, ensure that the following is <code>true</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p>there is only one version field or property per entity;</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>you choose a property or field persisted to the primary table (see Section 9.1.1 "Table Annotation" of the JPA specification);</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>your application does not modify the version property or field.</p>
| |
| − | </li>
| |
| − |
| |
| − | </ul>
| |
| − | </div>
| |
| − | <!-- class="sect3" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="CACCFEAG" name="CACCFEAG"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the Persistence Unit Properties for Caching</h3>
| |
| − | <p><a href="#CJAFFDEG">Table 1-10</a> lists the persistence unit properties that you can define in a <code>persistence.xml</code> file to configure the TopLink cache.</p>
| |
| − | <p>For more information, see the following:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#CHEJAEBH">Understanding the TopLink Cache</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CJAFAHEJ">What You May Need to Know About Overriding Annotations</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref11" name="sthref11"></a><a id="CJAFFDEG" name="CJAFFDEG"></a>
| |
| − | <p class="titleintable">Table 1-10 TopLink JPA Properties for Caching</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Properties for Caching" summary="This table lists TopLink JPA persistence.xml extensions for the TopLink cache." dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t16">Property</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c2-t16">Usage</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t16">Default</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t16" headers="r1c1-t16"><a id="toplink.cache.type.default" name="toplink.cache.type.default"></a>
| |
| − | <p><a id="CACCAEFH" name="CACCAEFH"></a><code>toplink.cache.type.default</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t16 r1c2-t16">
| |
| − | <p>The default type of session cache.</p>
| |
| − | <p>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, TopLink 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 <code>EntityManagerFactory</code> wraps an <code>oracle.toplink.threetier.ServerSession</code>; entity managers wrap an <code>oracle.toplink.sessions.UnitOfWork</code> and <code>oracle.toplink.threetier.ClientSession</code>. For more information about sessions, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/sesun.htm#CACJAFDF">Understanding TopLink Sessions</a>".</p>
| |
| − |
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.config.CacheType</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc"><a id="CacheType.Full" name="CacheType.Full"></a>
| |
| − | <p><code>Full</code>–This option provides full caching and guaranteed identity: objects are never flushed from memory unless they are deleted.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#CHEHGEEB">Full Identity Map</a>".</p>
| |
| − | </li>
| |
| − | <li type="disc"><a id="CacheType.HardWeak" name="CacheType.HardWeak"></a>
| |
| − | <p><code>HardWeak</code>–This option is similar to <code>Weak</code> except that it maintains a most frequently used subcache that uses hard references.</p>
| |
| − |
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#CHEJDCBH">Hard Cache Weak Identity Maps</a>".</p>
| |
| − | </li>
| |
| − | <li type="disc"><a id="CacheType.NONE" name="CacheType.NONE"></a>
| |
| − | <p><code>NONE</code>–This option does not preserve object identity and does not cache objects. Oracle does not recommend using this option.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#CHEEBFCI">No Identity Map</a>".</p>
| |
| − | </li>
| |
| − | <li type="disc"><a id="CacheType.SoftWeak" name="CacheType.SoftWeak"></a>
| |
| − | <p><code>SoftWeak</code>–This option is similar to <code>Weak</code> except that it maintains a most frequently used subcache that uses soft references. Oracle recommends using this identity map in most circumstances as a means to control memory used by the cache.</p>
| |
| − |
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#CHEJDCBH">Soft Cache Weak Identity Maps</a>".</p>
| |
| − | </li>
| |
| − | <li type="disc"><a id="CacheType.Weak" name="CacheType.Weak"></a>
| |
| − | <p><code>Weak</code>–This option is similar to <code>Full</code>, except that objects are referenced using weak references. This option uses less memory than <code>Full</code>, but does not provide a durable caching strategy across client/server transactions. Oracle recommends using this identity map for transactions that, once started, stay on the server side.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#CHEGIBAC">Weak Identity Map</a>".</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>Note: the values are case-sensitive.</p>
| |
| − | <p>Note: using this property, you can override the <code>@Cache</code> annotation (see <a href="#BABFCJJB">"How to Use the @Cache Annotation"</a>) attribute <a href="#CACDJFCF">type</a>.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.cache.type.default" value="Full"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.CacheType;
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.CACHE_TYPE_DEFAULT, CacheType.Full);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r2c1-t16 r1c3-t16">
| |
| − | <p><code>CacheType.SoftWeak</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r3c1-t16" headers="r1c1-t16"><a id="toplink.cache.size.default" name="toplink.cache.size.default"></a>
| |
| − | <p><code>toplink.cache.size.default</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t16 r1c2-t16">
| |
| − | <p>The default maximum number of objects allowed in a TopLink cache.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> as a <code>String</code>.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.cache.size.default" value="5000"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.CACHE_SIZE_DEFAULT, 5000);
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r3c1-t16 r1c3-t16">
| |
| − | <p>1000</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t16" headers="r1c1-t16"><a id="toplink.cache.shared.default" name="toplink.cache.shared.default"></a>
| |
| − | <p><code>toplink.cache.shared.default</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t16 r1c2-t16">
| |
| − | <p>The default for whether or not the TopLink session cache is shared by multiple client sessions.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><code>true</code>–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, TopLink saves a copy of the objects in the parent server session's cache and makes them accessible to all other processes in the session.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–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.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − |
| |
| − | <property name="toplink.cache.shared.default" value="true"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.CACHE_SHARED_DEFAULT, "true");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r4c1-t16 r1c3-t16">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t16" headers="r1c1-t16"><a id="toplink.cache.type.ENTITY" name="toplink.cache.type.ENTITY"></a>
| |
| − |
| |
| − | <p><a id="CACGFGJE" name="CACGFGJE"></a><code>toplink.cache.type.<ENTITY></code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t16 r1c2-t16">
| |
| − | <p>The type of session cache for the JPA entity named <code><ENTITY></code> or with the class name <ENTITY>.</p>
| |
| − | <p>For more information on entity names, see Section 8.1 "Entity" of the JPA specification.</p>
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.config.CacheType</code>:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>Full</code>–see <a href="#CACCAEFH">toplink.cache.type.default</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>HardWeak</code>–see <a href="#CACCAEFH">toplink.cache.type.default</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>NONE</code>–see <a href="#CACCAEFH">toplink.cache.type.default</a></p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SoftWeak</code>–see <a href="#CACCAEFH">toplink.cache.type.default</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>Weak</code>–see <a href="#CACCAEFH">toplink.cache.type.default</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>Note: using this property, you can override the <code>@Cache</code> annotation (see <a href="#BABFCJJB">"How to Use the @Cache Annotation"</a>) attribute <a href="#CACDJFCF">type</a>.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.cache.type.Order" value="Full"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.CacheType;
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.CACHE_TYPE+".Order", CacheType.Full);
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r5c1-t16 r1c3-t16">
| |
| − | <p><code>CacheType.SoftWeak</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t16" headers="r1c1-t16"><a id="toplink.cache.size.ENTITY" name="toplink.cache.size.ENTITY"></a>
| |
| − | <p><code>toplink.cache.size.<ENTITY></code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t16 r1c2-t16">
| |
| − | <p>The maximum number of JPA entities of the type denoted by JPA entity name <code><ENTITY></code> allowed in a TopLink cache.</p>
| |
| − |
| |
| − | <p>For more information on entity names, see Section 8.1 "Entity" of the JPA specification.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> as a <code>String</code>.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.cache.size.Order" value="5000"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.CACHE_SIZE+".Order", 1000);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r6c1-t16 r1c3-t16">
| |
| − | <p>1000</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r7c1-t16" headers="r1c1-t16"><a id="toplink.cache.shared.ENTITY" name="toplink.cache.shared.ENTITY"></a>
| |
| − | <p><code>toplink.cache.shared.<ENTITY></code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t16 r1c2-t16">
| |
| − | <p>Whether or not the TopLink session cache is shared by multiple client sessions for JPA entities of the type denoted by JPA entity name <code><ENTITY></code>.</p>
| |
| − | <p>For more information on entity names, see Section 8.1 "Entity" of the JPA specification.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–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, TopLink saves a copy of the objects in the parent server session's cache and makes them accessible to all other processes in the session.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–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.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.cache.shared.Order" value="true"/>
| |
| − | </pre>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.CACHE_SHARED+".Order", "true");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r7c1-t16 r1c3-t16">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − |
| |
| − | <a id="BABCIHBD" name="BABCIHBD"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @TimeOfDay Annotation</h3>
| |
| − | <p>You can use the <code>@TimeOfDay</code> annotation to specify a time of day using a <code>Calendar</code> instance. By doing so, you configure cache expiry on an entity class.</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface TimeOfDay { ... }
| |
| − | </pre>
| |
| − | <p><a href="#BABEJDEB">Table 1-11</a> lists attributes of the <code>@TimeOfDay</code> annotation.</p>
| |
| − |
| |
| − | <div class="tblruleformalwidemax"><a id="sthref12" name="sthref12"></a><a id="BABEJDEB" name="BABEJDEB"></a>
| |
| − | <p class="titleintable">Table 1-11 Attributes of the @TimeOfDay Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @TimeOfDay Annotation" summary="This table lists the attributes of TopLink JPA @TimeOfDay annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t17">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t17">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t17">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t17">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t17" headers="r1c1-t17">
| |
| − | <p><code>hour</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t17 r1c2-t17">
| |
| − | <p>Set this attribute to the <code>int</code> value representing an hour of the day.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t17 r1c3-t17">
| |
| − | <p>0</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t17 r1c4-t17">
| |
| − |
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t17" headers="r1c1-t17">
| |
| − | <p><code>minute</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t17 r1c2-t17">
| |
| − | <p>Set this attribute to the <code>int</code> value representing a minute of the day.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t17 r1c3-t17">
| |
| − |
| |
| − | <p>0</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t17 r1c4-t17">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t17" headers="r1c1-t17">
| |
| − | <p><code>second</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t17 r1c2-t17">
| |
| − | <p>Set this attribute to the <code>int</code> value representing a second of the day.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t17 r1c3-t17">
| |
| − | <p>0</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t17 r1c4-t17">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t17" headers="r1c1-t17">
| |
| − | <p><code>millisecond</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t17 r1c2-t17">
| |
| − | <p>Set this attribute to the <code>int</code> value representing a millisecond of the day.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t17 r1c3-t17">
| |
| − | <p>0</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t17 r1c4-t17">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="BABHBEDD" name="BABHBEDD"></a>
| |
| − |
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Customization</h2>
| |
| − | <p>TopLink defines the following descriptor customizer annotations:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@Customizer</code> (see <a href="#BABHIJJA">"How to Use the @Customizer Annotation"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@ReadOnly</code> (see <a href="#BABBAAHB">"How to Use the @ReadOnly Annotation"</a>)</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>TopLink also provides a number of persistence unit properties that you can specify to configure TopLink customization and validation (see <a href="#CACDAFAG">"How to Use the Persistence Unit Properties for Customization and Validation"</a>). These properties may compliment or provide an alternative to the usage of annotations.</p>
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | Persistence unit properties always override the corresponding annotations' attributes. For more information, see <a href="#CJAFAHEJ">"What You May Need to Know About Overriding Annotations"</a>.</td>
| |
| − |
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <a id="BABHIJJA" name="BABHIJJA"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @Customizer Annotation</h3>
| |
| − | <p>Use the <code>@Customizer</code> annotation to specify a class that implements the <code>oracle.toplink.tools.sessionconfiguration.DescriptorCustomizer</code> interface and that is to be run against a class' descriptor after all metadata processing has been completed. See <a href="#CJAIHBBG">toplink.descriptor.customizer.<ENTITY></a> for more information.</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface Customizer { ... }
| |
| − | </pre>
| |
| − | <p>You can define the <code>@Customizer</code> annotation on the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@Entity</code> (see Section 8.1 "Entity" of the JPA specification);</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@MappedSuperclass</code> (see Section 9.1.36 "MappedSuperclass Annotation" of the JPA specification);</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@Embeddable</code> (see Section 9.1.34 "Embeddable Annotation" of the JPA specification).</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | A <code>@Customizer</code> is not inherited from its parent classes.</td>
| |
| − |
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <p><a href="#BABFBIEA">Table 1-12</a> lists attributes of the <code>@Customizer</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref13" name="sthref13"></a><a id="BABFBIEA" name="BABFBIEA"></a>
| |
| − | <p class="titleintable">Table 1-12 Attributes of the @Customizer Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @Customizer Annotation" summary="This table lists the attributes of TopLink JPA @Customizer annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t20">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t20">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t20">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t20">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t20" headers="r1c1-t20">
| |
| − | <p><code>value</code></p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r2c1-t20 r1c2-t20">
| |
| − | <p>Set this attribute to the <code>Class</code> of the descriptor customizer that you want to apply to your entity's descriptor.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t20 r1c3-t20">
| |
| − | <p>no default</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t20 r1c4-t20">
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − |
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#BABIGIAH">Example 1-10</a> shows how to use the <code>@Customizer</code> annotation.</p>
| |
| − | <div class="example"><a id="BABIGIAH" name="BABIGIAH"></a>
| |
| − | <p class="titleinexample">Example 1-10 Usage of the @Customizer Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @Table(name="EMPLOYEE")
| |
| − | @Customizer(mypackage.MyCustomizer.class)
| |
| − | public class Employee implements Serializable {
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − |
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="CACDAFAG" name="CACDAFAG"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the Persistence Unit Properties for Customization and Validation</h3>
| |
| − | <p><a href="#CJADHEEB">Table 1-13</a> lists the persistence unit properties that you can define in a <code>persistence.xml</code> file to configure TopLink customization and validation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref14" name="sthref14"></a><a id="CJADHEEB" name="CJADHEEB"></a>
| |
| − | <p class="titleintable">Table 1-13 TopLink JPA Persistence Unit Properties for Customization and Validation</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Persistence Unit Properties for Customization and Validation" summary="This table lists TopLink JPA persistence.xml extensions for TopLink customization and validation." dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t21">Property</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t21">Usage</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t21">Default</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t21" headers="r1c1-t21"><a id="toplink.orm.throw.exceptions" name="toplink.orm.throw.exceptions"></a>
| |
| − | <p><code>toplink.orm.throw.exceptions</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t21 r1c2-t21">
| |
| − | <p>Specify whether or not TopLink JPA should throw an exception or log a warning when it encounters a problem with any of the files listed in a <code>persistence.xml</code> file <code><mapping-file></code> element.</p>
| |
| − |
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–throw exceptions.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–log warning only.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="oracle.orm.throw.exceptions" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider;
| |
| − | propertiesMap.put(EntityManagerFactoryProvider.TOPLINK_ORM_THROW_EXCEPTIONS, "false");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r2c1-t21 r1c3-t21">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r3c1-t21" headers="r1c1-t21"><a id="toplink.weaving" name="toplink.weaving"></a>
| |
| − | <p><a id="CJAFECEI" name="CJAFECEI"></a><code>toplink.weaving</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t21 r1c2-t21">
| |
| − | <p>Control whether or not the weaving of the entity classes is performed. Weaving is required in order to use lazy fetching of <code>@OneToOne</code> (see Section 9.1.23 "OneToOne Annotation" of the JPA specification) and <code>@ManyToOne</code> (see Section 9.1.22 "ManyToOne Annotation" of the JPA specification) relationships.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><code>true</code>–weave entity classes.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–do not weave entity classes.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>static</code>–weave entity classes statically.</p>
| |
| − | <p>Use this option if you plan to execute your application outside of a Java EE 5 container in an environment that does not permit the use of <code>-javaagent:toplink-agent.jar</code> on the JVM command line.</p>
| |
| − |
| |
| − | <p>This assumes that classes have already been statically woven. Run the Static weaver tool on the classes before deploying them.</p>
| |
| − | <p>For more information on static weaving, see <a href="#StaticWeaving">"How to Configure Static Weaving Using the StaticWeave Class on the Command Line"</a> and <a href="#CJAGHHFH">"How to Use Static Weaving with the weave Ant Task"</a>.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>For more information, including the option of using the TopLink JPA <code>weave</code> Ant task, see <a href="#CACEDCAF">"Using TopLink JPA Lazy Loading"</a>.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.weaving" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.WEAVING, "false");
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r3c1-t21 r1c3-t21">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t21" headers="r1c1-t21">
| |
| − | <p><code>toplink.weaving.lazy</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t21 r1c2-t21">
| |
| − | <p>Enable or disable the lazy one-to-one (see Section 9.1.23 "OneToOne Annotation" of the JPA specification) mapping through weaving.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><code>true</code>–enable lazy one-to-one mapping through weaving.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–disable lazy one-to-one mapping through weaving.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>Note: you may set this option only if the <a href="#CJAFECEI">toplink.weaving</a> option is set to <code>true</code>. The purpose of the toplink.weaving.lazy option is to provide more granular control over weaving.</p>
| |
| − |
| |
| − | <p>For more information, see <a href="#CACEDCAF">"Using TopLink JPA Lazy Loading"</a>.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.weaving.lazy" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.WEAVING_LAZY, "false");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r4c1-t21 r1c3-t21">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t21" headers="r1c1-t21">
| |
| − | <p><code>toplink.weaving.changetracking</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t21 r1c2-t21">
| |
| − | <p>Enable or disable the <code>AttributeLevelChangeTracking</code> through weaving.</p>
| |
| − |
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–enable the <code>AttributeLevelChangeTracking</code> through weaving. When enabled, only classes with all mappings allowing change tracking have change tracking enabled.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–disable the <code>AttributeLevelChangeTracking</code> through weaving. Use this setting if the following applies:</p>
| |
| − |
| |
| − | <p>- you cannot weave at all;</p>
| |
| − | <p>- you do not want your classes to be changed during weaving (for example, for debugging purposes);</p>
| |
| − | <p>- you wish to disable this feature for configurations that do not support it (for example, you are mutating the <code>java.util.Date</code> or <code>java.util.Calendar</code>, you are using property access but modifying the underlying instance variables).</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>Note: you may set this option only if the <a href="#CJAFECEI">toplink.weaving</a> option is set to <code>true</code>. The purpose of the toplink.weaving.lazy option is to provide more granular control over weaving.</p>
| |
| − |
| |
| − | <p>For more information, see <a href="#CACEDCAF">"Using TopLink JPA Lazy Loading"</a>.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.weaving.changetracking" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.WEAVING_CHANGE_TRACKING, "false");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r5c1-t21 r1c3-t21">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t21" headers="r1c1-t21"><a id="toplink.session.customizer" name="toplink.session.customizer"></a>
| |
| − | <p><code>toplink.session.customizer</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t21 r1c2-t21">
| |
| − | <p>Specify a TopLink session customizer class: a Java class that implements the <code>oracle.toplink.tools.sessionconfiguration.SessionCustomizer</code> interface and provides a default (zero-argument) constructor. Use this class' <code>customize</code> method, which takes an <code>oracle.toplink.sessions.Session</code>, to programmatically access advanced TopLink session API.</p>
| |
| − |
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/sesun.htm#CACGEBJF">Session Customization</a>".</p>
| |
| − | <p>Valid values: class name of a <code>SessionCustomizer</code> class fully qualified by its package name.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.session.customizer" value="acme.sessions.MySessionCustomizer"/>
| |
| − |
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.SESSION_CUSTOMIZER, "acme.sessions.MySessionCustomizer");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r6c1-t21 r1c3-t21"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r7c1-t21" headers="r1c1-t21"><a id="toplink.descriptor.customizer.ENTITY" name="toplink.descriptor.customizer.ENTITY"></a>
| |
| − | <p><a id="CJAIHBBG" name="CJAIHBBG"></a><code>toplink.descriptor.customizer.<ENTITY></code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t21 r1c2-t21">
| |
| − |
| |
| − | <p>Specify a TopLink descriptor customizer class–a Java class that implements the <code>oracle.toplink.tools.sessionconfiguration.DescriptorCustomizer</code> interface and provides a default (zero-argument) constructor. Use this class's <code>customize</code> method, which takes an <code>oracle.toplink.descriptors.ClassDescriptor</code>, to programmatically access advanced TopLink descriptor and mapping API for the descriptor associated with the JPA entity named <code><ENTITY></code>.</p>
| |
| − | <p>For more information on entity names, see Section 8.1 "Entity" of the JPA specification</p>
| |
| − | <p>For more information on TopLink descriptors, see the following:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descun.htm#CHECEAAE">Understanding Descriptors</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descun.htm#CHEIGIHG">Descriptor Customization</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>Note: TopLink does not support multiple descriptor customizers.</p>
| |
| − | <p>Valid values: class name of a <code>DescriptorCustomizer</code> class fully qualified by its package name.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.descriptor.customizer.Order" value="acme.sessions.MyDescriptorCustomizer"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.DESCRIPTOR_CUSTOMIZER+".Order", "acme.sessions.MyDescriptorCustomizer");
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r7c1-t21 r1c3-t21"><br /></td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABBAAHB" name="BABBAAHB"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @ReadOnly Annotation</h3>
| |
| − | <p>Use the <code>@ReadOnly</code> annotation to specify that a class is read-only (see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowadv.htm#CACCDEFJ">Read-Only Classes</a>").</p>
| |
| − |
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | 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.</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface ReadOnly { ... }
| |
| − |
| |
| − | </pre>
| |
| − | <p>You can define the <code>@ReadOnly</code> annotation on the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@Entity</code> (see Section 8.1 "Entity" of the JPA specification);</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@MappedSuperclass</code> (see Section 9.1.36 "MappedSuperclass Annotation" of the JPA specification);</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>the root of the inheritance hierarchy (if applicable).</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>The <code>@ReadOnly</code> annotation does not have attributes.</p>
| |
| − | <p><a href="#BABGIGFG">Example 1-11</a> shows how to use the <code>@ReadOnly</code> annotation.</p>
| |
| − |
| |
| − | <div class="example"><a id="BABGIGFG" name="BABGIGFG"></a>
| |
| − | <p class="titleinexample">Example 1-11 Usage of the @ReadOnly Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @ReadOnly
| |
| − | public class Employee implements Serializable {
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="BABDDFGA" name="BABDDFGA"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Returning Policy</h2>
| |
| − | <p>The returning policy enables <code>INSERT</code> or <code>UPDATE</code> 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 "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descfg.htm#CHDHCCIG">Configuring Returning Policy</a>".</p>
| |
| − |
| |
| − | <p>TopLink defines the following returning policy annotations:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@ReturnInsert</code> (see <a href="#BABEACGB">"How to Use the @ReturnInsert Annotation"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@ReturnUpdate</code> (see <a href="#BABFFGJA">"How to Use the @ReturnUpdate Annotation"</a>)</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <a id="BABEACGB" name="BABEACGB"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @ReturnInsert Annotation</h3>
| |
| − | <p>You can only specify the <code>@ReturnInsert</code> for a <code>@Basic</code> mapping (see Section 9.1.18 "Basic Annotation" of the JPA specification).</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface ReturnInsert { ... }
| |
| − | </pre>
| |
| − |
| |
| − | <p><a href="#BABIAAEG">Table 1-14</a> lists attributes of the <code>@ReturnInsert</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref15" name="sthref15"></a><a id="BABIAAEG" name="BABIAAEG"></a>
| |
| − | <p class="titleintable">Table 1-14 Attributes of the @ReturnInsert Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @ReturnInsert Annotation" summary="This table lists the attributes of TopLink JPA @ReturnInsert annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t23">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t23">Description</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c3-t23">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t23">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t23" headers="r1c1-t23">
| |
| − | <p><code>returnOnly</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t23 r1c2-t23">
| |
| − | <p>Set this attribute to the <code>boolean</code> value of <code>true</code> if you want a return of a value for this field, without including the field in the insert.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t23 r1c3-t23">
| |
| − | <p><code>false</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t23 r1c4-t23">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#BABBBHIH">Example 1-12</a> shows how to use the <code>@ReturnInsert</code> annotation without specifying the value for the <code>returnOnly</code> argument, therefore accepting the default value of <code>false</code>. <a href="#BABEHAHA">Example 1-13</a> shows how to set the value of the <code>returnOnly</code> argument to <code>true</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="BABBBHIH" name="BABBBHIH"></a>
| |
| − | <p class="titleinexample">Example 1-12 Usage of the @ReturnInsert Annotation Without Arguments</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @ReturnInsert
| |
| − | public String getFirstName() {
| |
| − | return firstName;
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <div class="example"><a id="BABEHAHA" name="BABEHAHA"></a>
| |
| − | <p class="titleinexample">Example 1-13 Usage of the @ReturnInsert Annotation with Arguments</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @ReturnInsert(returnOnly=true)
| |
| − | public String getFirstName() {
| |
| − | return firstName;
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABFFGJA" name="BABFFGJA"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − |
| |
| − | <h3 class="sect2">How to Use the @ReturnUpdate Annotation</h3>
| |
| − | <p>You can only specify the <code>@ReturnUpdate</code> for a <code>@Basic</code> mapping.</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface ReturnUpdate { ... }
| |
| − | </pre>
| |
| − | <p>The <code>@ReturnUpdate</code> annotation does not have attributes.</p>
| |
| − |
| |
| − | <p><a href="#BABGGADH">Example 1-14</a> shows how to use the <code>@ReturnUpdate</code> annotation.</p>
| |
| − | <div class="example"><a id="BABGGADH" name="BABGGADH"></a>
| |
| − | <p class="titleinexample">Example 1-14 Usage of the @ReturnUpdate Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @ReturnUpdate
| |
| − | public String getFirstName() {
| |
| − | return firstName;
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="BABHAEGH" name="BABHAEGH"></a>
| |
| − |
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Optimistic Locking</h2>
| |
| − | <p>TopLink defines one annotation for optimistic locking–<code>@OptimisticLocking</code> (see <a href="#BABFFBJJ">"How to Use the @OptimisticLocking Annotation"</a>).</p>
| |
| − | <p>For more information, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/undtldev.htm#BABDIIJF">Optimistic Locking</a></p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descfg.htm#BCGGBAJE">Configuring an Optimistic Locking Policy</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <a id="BABFFBJJ" name="BABFFBJJ"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @OptimisticLocking Annotation</h3>
| |
| − | <p>You can use the <code>@OptimisticLocking</code> annotation to specify the type of optimistic locking that TopLink should use when updating or deleting entities.</p>
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − |
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | TopLink supports additional optimistic locking policies beyond what is supported through the JPA specification (such as <code>@Version</code>). When mapping to a database schema where a version column does not exist and cannot be added, these locking policies enable the concurrency protection.</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface OptimisticLocking { ... }
| |
| − | </pre>
| |
| − |
| |
| − | <p><a href="#BABGIDIC">Table 1-15</a> lists attributes of the <code>@OptimisticLocking</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref16" name="sthref16"></a><a id="BABGIDIC" name="BABGIDIC"></a>
| |
| − | <p class="titleintable">Table 1-15 Attributes of the @OptimisticLocking Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @OptimisticLocking Annotation" summary="This table lists the attributes of TopLink JPA @OptimisticLocking annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t25">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t25">Description</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c3-t25">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t25">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t25" headers="r1c1-t25">
| |
| − | <p><code>type</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t25 r1c2-t25">
| |
| − | <p>Set this attribute to the type (<code>oracle.toplink.annotations.OptimisticLockingType</code> enumerated type) of the optimistic locking policy that you will be using.</p>
| |
| − |
| |
| − | <p>The following are the valid values for the <code>OptimisticLockingType</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>ALL_COLUMNS</code>–Use this type of locking policy to compare every field in the table in the <code>WHERE</code> clause during an update or a delete operation. If any field has been changed, TopLink will throw an optimistic locking exception.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CHANGED_COLUMNS</code>–Use this type of locking policy to compare changed fields in the table in the <code>WHERE</code> clause during an update operation. If any field has been changed, TopLink will throw an optimistic locking exception.</p>
| |
| − |
| |
| − | <p>Note: performing the same during a delete operation will only compare primary keys.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a id="CJAHGDGE" name="CJAHGDGE"></a><code>SELECTED_COLUMNS</code>–Use this type of locking policy to compare selected fields in the table in the <code>WHERE</code> clause during an update or a delete operation. If any field has been changed, TopLink will throw an optimistic locking exception.</p>
| |
| − | <p>Note: specified fields must be mapped and must not be primary keys.</p>
| |
| − | <p>Note: TopLink will throw an exception if you set the <code>SELECTED_COLUMNS</code> type, but fail to specify the <code>selectedColumns</code>. You must also specify the <code>name</code> attribute of <code>Column</code>.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a id="CJACFHAD" name="CJACFHAD"></a><code>VERSION_COLUMN</code>–Use this type of locking policy to compare a single version number in the <code>WHERE</code> clause during an update operation in each <code>@Column</code> annotaion.</p>
| |
| − | <p>Note: the version field must be mapped and must not be the primary key.</p>
| |
| − | <p>Note: this functionality is equivalent to the functionality of the <code>@Version</code> annotation (see Section 9.1.17 "Version Annotation" of the JPA specification) in JPA.</p>
| |
| − |
| |
| − | <p>For more information, see <a href="#CJAEHCDC">"What You May Need to Know About Version Fields"</a>.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t25 r1c3-t25">
| |
| − | <p><code>OptimisticLockingType.VERSION_COLUMN</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t25 r1c4-t25">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r3c1-t25" headers="r1c1-t25">
| |
| − | <p><code>selectedColumns</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t25 r1c2-t25">
| |
| − | <p>Set this attribute to an array of <code>javax.persistence.Column</code> instances.</p>
| |
| − | <p>For an optimistic locking policy of type <a href="#CJAHGDGE">SELECTED_COLUMNS</a>, this annotation member becomes a required field.</p>
| |
| − | <p>Note: TopLink will throw an exception if you set the <a href="#CJAHGDGE">SELECTED_COLUMNS</a> type, but fail to specify the <code>selectedColumns</code>. You must also specify the <code>name</code> attribute of <code>Column</code>.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t25 r1c3-t25">
| |
| − | <p>empty <code>Column</code> array</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t25 r1c4-t25">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t25" headers="r1c1-t25">
| |
| − | <p><code>cascade</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t25 r1c2-t25">
| |
| − | <p>Set the value of this attribute to a <code>boolean</code> value of <code>true</code> to specify that the optimistic locking policy should cascade the lock.</p>
| |
| − | <p>By enabling cascading you configure TopLink to automatically force a version field update on a parent object when its privately owned child object's version field changes.</p>
| |
| − | <p>Note: in the current release, only supported with <a href="#CJACFHAD">VERSION_COLUMN</a> locking.</p>
| |
| − |
| |
| − | <p>For more information, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descun.htm#CHECICGH">Optimistic Version Locking Policies and Cascading</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descfg.htm#BCGJCCIG">Configuring Optimistic Locking Policy Cascading</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t25 r1c3-t25">
| |
| − | <p><code>false</code></p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r4c1-t25 r1c4-t25">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − |
| |
| − | Setting an <code>@OptimisticLocking</code> may override any <code>@Version</code> specification (see Section 9.1.17 "Version Annotation" of the JPA specification) on the entity: TopLink will not throw an exception, but will log a warning.
| |
| − | <p>You can specify <code>@Version</code> without any <code>@OptimisticLocking</code> specification to define a version locking policy (<code>oracle.toplink.descriptors.VersionLockingPolicy</code>) on the source entity..</p>
| |
| − |
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <p><a href="#BABCDJHJ">Example 1-15</a> shows how to use the <code>@OptimisticLocking</code> annotation with the <code>ALL_COLUMNS</code> type.</p>
| |
| − | <div class="example"><a id="BABCDJHJ" name="BABCDJHJ"></a>
| |
| − |
| |
| − | <p class="titleinexample">Example 1-15 Usage of the @OptimisticLocking Annotation - ALL_COLUMNS</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @Table(name="EMPLOYEE")
| |
| − | @OptimisticLocking(type=ALL_COLUMNS)
| |
| − | public class Employee implements Serializable{
| |
| − |
| |
| − | private Integer id;
| |
| − | private String firstName;
| |
| − | private String lastName;
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p><a href="#BABGABBB">Example 1-16</a> shows how to use the <code>@OptimisticLocking</code> annotation with the <code>CHANGED_COLUMNS</code> type.</p>
| |
| − | <div class="example"><a id="BABGABBB" name="BABGABBB"></a>
| |
| − |
| |
| − | <p class="titleinexample">Example 1-16 Usage of the @OptimisticLocking Annotation - CHANGED_COLUMNS</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @Table(name="EMPLOYEE")
| |
| − | @OptimisticLocking(type=CHANGED_COLUMNS)
| |
| − | public class Employee implements Serializable{
| |
| − |
| |
| − | private Integer id;
| |
| − | private String firstName;
| |
| − | private String lastName;
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p><a href="#BABBCHDH">Example 1-17</a> shows how to use the <code>@OptimisticLocking</code> annotation with the <code>SELECTED_COLUMNS</code> type.</p>
| |
| − | <div class="example"><a id="BABBCHDH" name="BABBCHDH"></a>
| |
| − |
| |
| − | <p class="titleinexample">Example 1-17 Usage of the @OptimisticLocking Annotation - SELECTED_COLUMNS</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @Table(name="EMPLOYEE")
| |
| − | @OptimisticLocking(
| |
| − | type=SELECTED_COLUMNS,
| |
| − | selectedColumns={@Column(name="id"), @Column(name="lastName")}
| |
| − | )
| |
| − | public class Employee implements Serializable{
| |
| − |
| |
| − | @Id
| |
| − | private Integer id;
| |
| − | private String lastName;
| |
| − | private String lastName;
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p><a href="#BABBAIGH">Example 1-18</a> shows how to use the <code>@OptimisticLocking</code> annotation with the <code>VERSION_COLUMN</code> type.</p>
| |
| − | <div class="example"><a id="BABBAIGH" name="BABBAIGH"></a>
| |
| − |
| |
| − | <p class="titleinexample">Example 1-18 Usage of the @OptimisticLocking Annotation - VERSION_COLUMN</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @Table(name="EMPLOYEE")
| |
| − | @OptimisticLocking(type=VERSION_COLUMN, cascade=true)
| |
| − | public class Employee implements Serializable{
| |
| − |
| |
| − | private String firstName;
| |
| − | private String lastName;
| |
| − | @Version private int version;
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="BABBIJAC" name="BABBIJAC"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Stored Procedure Query</h2>
| |
| − | <p>TopLink defines the following stored procedure query annotations:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>@NamedStoredProcedureQuery</code> (see <a href="#BABCEAEH">"How to Use the @NamedStoredProcedureQuery Annotation"</a>);</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>@NamedStoredProcedureQueries</code> (see <a href="#BABGDBCA">"How to Use the @NamedStoredProcedureQueries Annotation"</a>).</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>You can execute a stored procedure query like any other named query (see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qryun.htm#CACFBJCI">Named Queries</a>"). For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/prt_qur.htm#BABCBADI">Queries</a>".</p>
| |
| − | <a id="BABCEAEH" name="BABCEAEH"></a>
| |
| − |
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @NamedStoredProcedureQuery Annotation</h3>
| |
| − | <p>Use the <code>@NamedStoredProcedureQuery</code> to define queries that call stored procedures as named queries.</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface NamedStoredProcedureQuery { ... }
| |
| − | </pre>
| |
| − | <p><a href="#BABHCIJD">Table 1-16</a> lists attributes of the <code>@NamedStoredProcedureQuery</code> annotation.</p>
| |
| − |
| |
| − | <div class="tblruleformalwidemax"><a id="sthref17" name="sthref17"></a><a id="BABHCIJD" name="BABHCIJD"></a>
| |
| − | <p class="titleintable">Table 1-16 Attributes of the @NamedStoredProcedureQuery Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @NamedStoredProcedureQuery Annotation" summary="This table lists the attributes of TopLink JPA @NamedStoredProcedureQuery annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t27">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t27">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t27">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t27">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t27" headers="r1c1-t27">
| |
| − | <p><code>name</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t27 r1c2-t27">
| |
| − | <p>Set this attribute to the unique <code>String</code> name that references this stored procedure query.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t27 r1c3-t27">
| |
| − | <p>no default</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t27 r1c4-t27">
| |
| − |
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t27" headers="r1c1-t27">
| |
| − | <p><code>hints</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t27 r1c2-t27">
| |
| − | <p>Set this attribute to an array of <code>javax.persistence.QueryHint</code> instances.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t27 r1c3-t27">
| |
| − |
| |
| − | <p>empty <code>QueryHint</code> array</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t27 r1c4-t27">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t27" headers="r1c1-t27">
| |
| − | <p><code>resultClass</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t27 r1c2-t27">
| |
| − |
| |
| − | <p>Set this attribute to the <code>Class</code> of the query result.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t27 r1c3-t27">
| |
| − | <p><code>void.class</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t27 r1c4-t27">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t27" headers="r1c1-t27">
| |
| − |
| |
| − | <p><code>resultSetMapping</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t27 r1c2-t27">
| |
| − | <p>Set this attribute to the <code>String</code> name of the <code>javax.persistence.SQLResultSetMapping</code> instance.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t27 r1c3-t27">
| |
| − | <p>empty <code>String</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t27 r1c4-t27">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t27" headers="r1c1-t27">
| |
| − | <p><code>procedureName</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t27 r1c2-t27">
| |
| − | <p>Set this attribute to the <code>String</code> name of the stored procedure.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t27 r1c3-t27">
| |
| − | <p>no default</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t27 r1c4-t27">
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r7c1-t27" headers="r1c1-t27">
| |
| − | <p><code>returnsResultSet</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t27 r1c2-t27">
| |
| − | <p>Set this attribute to the <code>boolean</code> value of <code>false</code> to disable the return of the result set.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t27 r1c3-t27">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t27 r1c4-t27">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r8c1-t27" headers="r1c1-t27">
| |
| − | <p><code>procedureParameters</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t27 r1c2-t27">
| |
| − | <p>Set the value of this attribute to an array of <code>oracle.toplink.annotations.StoredProcedureParameter</code> instances to define arguments to the stored procedure.</p>
| |
| − |
| |
| − | <p>The following are attributes of the <code>StoredProcedureParameter</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>procedureParameterDirection</code>–Set the value of this attribute to define the direction (<code>oracle.toplink.annotations.Direction</code> enumerated type) of the stored procedure parameter.</p>
| |
| − | <p>The default value is an empty <code>Direction.IN</code>.</p>
| |
| − | <p>The following are valid values for <code>Direction.IN</code>:</p>
| |
| − |
| |
| − | <p>- <code>IN</code>–Input parameter</p>
| |
| − | <p>- <code>OUT</code>–Output parameter</p>
| |
| − | <p>- <code>IN_OUT</code>–Input and output parameter</p>
| |
| − | <p>- <code>OUT_CURSOR</code>–Output cursor</p>
| |
| − | <p>You are not required to set the value of this attribute.</p>
| |
| − |
| |
| − | <p>Note: TopLink will throw an exception if you set more than one parameter to the <code>OUT_CURSOR</code> type.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>name</code>–Set this attribute to the <code>String</code> name of the stored procedure parameter.</p>
| |
| − | <p>The default value is an empty <code>String</code>.</p>
| |
| − |
| |
| − | <p>You are not required to set the value of this attribute.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>queryParameter</code>–Set this attribute to the <code>String</code> name of the query parameter.</p>
| |
| − | <p>You are required to set the value of this attribute.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>type</code>–Set this attribute to the type of Java <code>Class</code> that you want to receive back from the procedure. This depends on the type returned from the procedure.</p>
| |
| − |
| |
| − | <p>The default value is <code>void.class</code>.</p>
| |
| − | <p>You are not required to set the value of this attribute.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>jdbcType</code>–Set this attribute to the <code>int</code> value of JDBC type code. This depends on the type returned from the procedure.</p>
| |
| − | <p>The default value is -1.</p>
| |
| − | <p>You are not required to set the value of this attribute.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>jdbcTypeName</code>–Set this attribute to the <code>String</code> value of the JDBC type name.</p>
| |
| − | <p>The default value is an empty <code>String</code>.</p>
| |
| − | <p>You are not required to set the value of this attribute.</p>
| |
| − | <p>Note: Setting of this attribute may be required for <code>ARRAY</code> or <code>STRUCT</code> types.</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>For more information, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qryun.htm#CACCEHIH">StoredProcedureCall</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qrybas.htm#BCFIJIIH">Using a StoredProcedureCall</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qryun.htm#CACJHDCJ">Call Queries</a></p>
| |
| − | </li>
| |
| − |
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t27 r1c3-t27">
| |
| − | <p>empty <code>StoredProcedureParameter</code> array</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t27 r1c4-t27">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − |
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#BABCFFIJ">Example 1-19</a> shows how to use the <code>@NamedStoredProcedureQuery</code> annotation.</p>
| |
| − | <div class="example"><a id="BABCFFIJ" name="BABCFFIJ"></a>
| |
| − | <p class="titleinexample">Example 1-19 Usage of the @NamedStoredProcedureQuery Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @Table(name="EMPLOYEE")
| |
| − | @NamedStoredProcedureQuery(
| |
| − | name="ReadEmployee",
| |
| − | procedureName="Read_Employee",
| |
| − | resultClass="Employee.class",
| |
| − | storedProcedureParameters={
| |
| − | @StoredProcedureParameter(queryParamater="EMP_ID")}
| |
| − | )
| |
| − | public class Employee implements Serializable{
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="BABGDBCA" name="BABGDBCA"></a>
| |
| − |
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @NamedStoredProcedureQueries Annotation</h3>
| |
| − | <p>Use the <code>@NamedStoredProcedureQueries</code> to define queries that call stored procedures as named queries.</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface NamedStoredProcedureQueries { ... }
| |
| − | </pre>
| |
| − | <p><a href="#BABCECFE">Table 1-17</a> lists attributes of the <code>@NamedStoredProcedureQueries</code> annotation.</p>
| |
| − |
| |
| − | <div class="tblruleformalwidemax"><a id="sthref18" name="sthref18"></a><a id="BABCECFE" name="BABCECFE"></a>
| |
| − | <p class="titleintable">Table 1-17 Attributes of the @NamedStoredProcedureQueries Annotation</p>
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @NamedStoredProcedureQueries Annotation" summary="This table lists the attributes of TopLink JPA @NamedStoredProcedureQuery annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t28">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t28">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t28">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t28">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t28" headers="r1c1-t28">
| |
| − | <p><code>value</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t28 r1c2-t28">
| |
| − | <p>Set this attribute to the array of <code>@NamedStoredProcedureQuery</code>.</p>
| |
| − | <p>For more information, see <a href="#BABCEAEH">"How to Use the @NamedStoredProcedureQuery Annotation"</a></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t28 r1c3-t28">
| |
| − | <p>no default</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t28 r1c4-t28">
| |
| − | <p>required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="CACDJBDH" name="CACDJBDH"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for JDBC</h2>
| |
| − | <p>TopLink JPA provides persistence unit properties that you can define in a <code>persistence.xml</code> file to configure how TopLink will use the connections returned from the data source used. These properties are devided into the two following categories:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p>Options that you can use to configure how TopLink communicates with the JDBC connection (see <a href="#CJAIFDGD">"How to Use TopLink JPA Extensions for JDBC Connection Communication"</a>).</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Options that you can use to configure TopLink own connection pooling (see <a href="#CJADIGAF">"How to Use TopLink JPA Extensions for JDBC Connection Pooling"</a>).</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <a id="CJAIFDGD" name="CJAIFDGD"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use TopLink JPA Extensions for JDBC Connection Communication</h3>
| |
| − |
| |
| − | <p><a href="#CJAJGAEC">Table 1-18</a> lists the TopLink JPA persistence unit properties that you can define in a <code>persistence.xml</code> file to configure how TopLink communicates with the JDBC connection.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref19" name="sthref19"></a><a id="CJAJGAEC" name="CJAJGAEC"></a>
| |
| − | <p class="titleintable">Table 1-18 TopLink JPA Persistence Unit Properties for JDBC Connection Communication</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Persistence Unit Properties for JDBC Connection Communication" summary="This table lists TopLink JPA persistence.xml extensions for TopLink JDBC (JSE)" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t29">Property</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t29">Usage</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c3-t29">Default</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t29" headers="r1c1-t29"><a id="toplink.jdbc.bind-parameters_persistence.xml" name="toplink.jdbc.bind-parameters_persistence.xml"></a>
| |
| − | <p><code>toplink.jdbc.bind-parameters</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t29 r1c2-t29">
| |
| − | <p>Control whether or not the query uses parameter binding.</p>
| |
| − | <p>Note: this property applies when used in a Java SE environment.</p>
| |
| − | <p>For more information, see "<a href="http://download-west.oracle.com/docs/cd/B32110_01/web.1013/b28218/optimiz.htm#i1124456">Parameterized SQL (Binding) and Prepared Statement Caching</a>".</p>
| |
| − |
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–bind all parameters.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–do not bind parameters.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.bind-parameters" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_BIND_PARAMETERS, "false");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r2c1-t29 r1c3-t29">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r3c1-t29" headers="r1c1-t29">
| |
| − | <p><code>toplink.jdbc.native-sql</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t29 r1c2-t29">
| |
| − | <p>Enable or disable TopLink's generation of database platform-specific SQL (as opposed to generic SQL).</p>
| |
| − | <p>Note: this property applies when used both in a Java SE and Java EE environment.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–enable TopLink's generation of database platform-specific SQL.</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–disable generation of database platform-specific SQL by TopLink.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.native-sql" value="true"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.NATIVE_SQL, "true");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r3c1-t29 r1c3-t29">
| |
| − | <p><code>false</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t29" headers="r1c1-t29">
| |
| − | <p><code>toplink.jdbc.batch-writing</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t29 r1c2-t29">
| |
| − | <p>Specify the use of batch writing to optimize transactions with multiple write operations.</p>
| |
| − | <p>Set the value of this property into the session at deployment time.</p>
| |
| − |
| |
| − | <p>Note: This property applies when used both in a Java SE and Java EE environment.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>JDBC</code>–use JDBC batch writing instead of native platform batch writing.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>BUFFERED</code>–do not use either JDBC batch writing nor native platform batch writing.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>ORACLE_JDBC</code>–use both JDBC batch writing and native platform batch writing.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>NONE</code>–do not use batch writing (turn it off).</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>Note: if you set any other value, TopLink will throw an exception.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.batch-writing" value="BUFFERED"/>
| |
| − |
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.BATCH_WRITING, "BUFFERED");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r4c1-t29 r1c3-t29">
| |
| − | <p><code>NONE</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t29" headers="r1c1-t29">
| |
| − | <p><code>toplink.jdbc.cache-statements.size</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t29 r1c2-t29">
| |
| − | <p>The number of statements held when using internal statement caching.</p>
| |
| − | <p>Set the value at the deployment time.</p>
| |
| − | <p>Note: this property applies when used both in a Java SE and Java EE environment.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> (depending on your JDBC driver) as a <code>String</code>.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.cache-statements.size" value="2"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.CACHE_STATEMENTS_SIZE, "2");
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r5c1-t29 r1c3-t29">
| |
| − | <p>50</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t29" headers="r1c1-t29"><a id="toplink.jdbc.driver" name="toplink.jdbc.driver"></a>
| |
| − | <p><code>toplink.jdbc.driver</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t29 r1c2-t29">
| |
| − | <p>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.</p>
| |
| − | <p>Note: 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 JPA specification ).</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_DRIVER, "oracle.jdbc.driver.OracleDriver");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r6c1-t29 r1c3-t29"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r7c1-t29" headers="r1c1-t29"><a id="toplink.jdbc.password" name="toplink.jdbc.password"></a>
| |
| − | <p><code>toplink.jdbc.password</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t29 r1c2-t29">
| |
| − | <p>The password for your JDBC user.</p>
| |
| − | <p>Note: 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 JPA specification ).</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.password" value="tiger"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_PASSWORD, "tiger");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r7c1-t29 r1c3-t29"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r8c1-t29" headers="r1c1-t29"><a id="toplink.jdbc.url" name="toplink.jdbc.url"></a>
| |
| − | <p><code>toplink.jdbc.url</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t29 r1c2-t29">
| |
| − | <p>The JDBC connection URL required by your JDBC driver.</p>
| |
| − | <p>Note: 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 JPA specification )</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.url" value="jdbc:oracle:thin:@MYHOST:1521:MYSID"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_URL, "jdbc:oracle:thin:@MYHOST:1521:MYSID");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r8c1-t29 r1c3-t29"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r9c1-t29" headers="r1c1-t29"><a id="toplink.jdbc.user" name="toplink.jdbc.user"></a>
| |
| − | <p><code>toplink.jdbc.user</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r9c1-t29 r1c2-t29">
| |
| − | <p>The user name for your JDBC user.</p>
| |
| − | <p>Note: 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 JPA specification )</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.url" value="scott"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_USER, "scott");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r9c1-t29 r1c3-t29"><br /></td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p>For information about the use of annotations as opposed to persistence unit properties and vice versa, see <a href="#CJAFAHEJ">"What You May Need to Know About Overriding Annotations"</a>.</p>
| |
| − | </div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="CJADIGAF" name="CJADIGAF"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − |
| |
| − | <h3 class="sect2">How to Use TopLink JPA Extensions for JDBC Connection Pooling</h3>
| |
| − | <p><a href="#CJACCJFI">Table 1-19</a> lists the TopLink JPA persistence unit properties that you can define in a <code>persistence.xml</code> file to configure TopLink internal connection pooling (see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/daun.htm#CHDHEIJE">Internal Connection Pools</a>").</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref20" name="sthref20"></a><a id="CJACCJFI" name="CJACCJFI"></a>
| |
| − | <p class="titleintable">Table 1-19 TopLink JPA Persistence Unit Properties for JDBC Connection Pooling</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Persistence Unit Properties for JDBC Connection Pooling" summary="This table lists TopLink JPA persistence.xml extensions for TopLink JDBC (JSE)" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c1-t30">Property</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t30">Usage</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t30">Default</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t30" headers="r1c1-t30">
| |
| − | <p><code>toplink.jdbc.read-connections.max</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t30 r1c2-t30">
| |
| − | <p>The maximum number of connections allowed in the JDBC read connection pool.</p>
| |
| − |
| |
| − | <p>Note: this property applies when used in a Java SE environment.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> (depending on your JDBC driver) as a <code>String</code>.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.read-connections.max" value="3"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_READ_CONNECTIONS_MAX, "3");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r2c1-t30 r1c3-t30">
| |
| − | <p>2</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r3c1-t30" headers="r1c1-t30">
| |
| − | <p><code>toplink.jdbc.read-connections.min</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t30 r1c2-t30">
| |
| − | <p>The minimum number of connections allowed in the JDBC read connection pool.</p>
| |
| − | <p>Note: this property applies when used in a Java SE environment.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> (depending on your JDBC driver) as a <code>String</code>.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.read-connections.min" value="1"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_READ_CONNECTIONS_MIN, "1");
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r3c1-t30 r1c3-t30">
| |
| − | <p>2</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t30" headers="r1c1-t30">
| |
| − | <p><code>toplink.jdbc.read-connections.shared</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t30 r1c2-t30">
| |
| − | <p>Specify whether or not to allow concurrent use of shared read connections.</p>
| |
| − | <p>Note: this property applies when used in a Java SE environment.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–allow concurrent use of shared read connections.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–do not allow the concurrent use of shared read connections; concurrent readers are each allocated their own read connection.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.read-connections.shared" value="true"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_READ_CONNECTIONS_SHARED, "true");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r4c1-t30 r1c3-t30">
| |
| − | <p><code>false</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r5c1-t30" headers="r1c1-t30">
| |
| − | <p><code>toplink.jdbc.write-connections.max</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t30 r1c2-t30">
| |
| − | <p>The maximum number of connections allowed in the JDBC write connection pool.</p>
| |
| − | <p>Note: this property applies when used in a Java SE environment.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> (depending on your JDBC driver) as a <code>String</code>.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.write-connections.max" value="5"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_WRITE_CONNECTIONS_MAX, "5");
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r5c1-t30 r1c3-t30">
| |
| − | <p>10</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t30" headers="r1c1-t30">
| |
| − | <p><code>toplink.jdbc.write-connections.min</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t30 r1c2-t30">
| |
| − | <p>The maximum number of connections allowed in the JDBC write connection pool.</p>
| |
| − | <p>Note: this property applies when used in a Java SE environment.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> (depending on your JDBC driver) as a <code>String</code>.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.jdbc.write-connections.min" value="2"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(ToplinkProperties.JDBC_WRITE_CONNECTIONS_MIN, "2");
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r6c1-t30 r1c3-t30">
| |
| − | <p>5</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p>For information about the use of annotations as opposed to persistence unit properties and vice versa, see <a href="#CJAFAHEJ">"What You May Need to Know About Overriding Annotations"</a>.</p>
| |
| − | </div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="CACBJEEH" name="CACBJEEH"></a>
| |
| − |
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Logging</h2>
| |
| − | <p><a href="#CJAHJIJH">Table 1-20</a> lists the TopLink JPA persistence unit properties that you can define in a <code>persistence.xml</code> file to configure TopLink logging.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/sesun.htm#i1122078">Logging</a>".</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref21" name="sthref21"></a><a id="CJAHJIJH" name="CJAHJIJH"></a>
| |
| − | <p class="titleintable">Table 1-20 TopLink JPA Persistence Unit Properties for Logging</p>
| |
| − |
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Persistence Unit Properties for Logging" summary="This table lists TopLink JPA persistence.xml extensions for TopLink logging." dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t31">Property</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t31">Usage</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t31">Default</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t31" headers="r1c1-t31">
| |
| − | <p><code>toplink.logging.logger</code></p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r2c1-t31 r1c2-t31">
| |
| − | <p>Select the type of logger to use:</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>DefaultLogger</code>–the TopLink native logger <code>oracle.toplink.logging.DefaultSessionLog</code>.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>JavaLogger</code>–the <code>java.util.logging</code> logger <code>oracle.toplink.logging.JavaLog</code>.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Fully qualified class name of a custom logger. The custom logger must implement the <code>oracle.toplink.logging.SessionLog</code> interface.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.logging.logger" value="acme.loggers.MyCustomLogger" />
| |
| − |
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.LOGGING_LOGGER, "acme.loggers.MyCustomLogger" />
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r2c1-t31 r1c3-t31">
| |
| − | <p><code>DefaultLogger</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t31" headers="r1c1-t31"><a id="toplink.logging.level" name="toplink.logging.level"></a>
| |
| − | <p><code>toplink.logging.level</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t31 r1c2-t31">
| |
| − | <p>Control the amount and detail of log output by configuring the log level (in ascending order of information):</p>
| |
| − | <p>The following are the valid values for the <code>java.util.logging.Level</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>OFF</code>–disables logging</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SEVERE</code>–logs exceptions indicating TopLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>WARNING</code>–logs exceptions that do not force TopLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>INFO</code>–logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CONFIG</code>–logs only login, JDBC connection, and database information.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><code>FINE</code>–logs SQL.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FINER</code>–similar to warning. Includes stack trace.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FINEST</code>–includes additional low level information.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.logging.level" value="INFO"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import java.util.logging.Level;
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.LOGGING_LEVEL, Level.INFO);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r3c1-t31 r1c3-t31">
| |
| − | <p><code>CONFIG</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r4c1-t31" headers="r1c1-t31"><a id="toplink.logging.timestamp" name="toplink.logging.timestamp"></a>
| |
| − | <p><code>toplink.logging.timestamp</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t31 r1c2-t31">
| |
| − | <p>Control whether the timestamp is logged in each log entry.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–log a timestamp.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–do not log a timestamp.</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.logging.timestamp" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − |
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.LOGGING_TIMESTAMP, "false");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r4c1-t31 r1c3-t31">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t31" headers="r1c1-t31"><a id="toplink.logging.thread" name="toplink.logging.thread"></a>
| |
| − | <p><code>toplink.logging.thread</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t31 r1c2-t31">
| |
| − | <p>Control whether a thread identifier is logged in each log entry.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–log a thread identifier.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–do not log a thread identifier.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.logging.thread" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.LOGGING_THREAD, "false");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r5c1-t31 r1c3-t31">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r6c1-t31" headers="r1c1-t31"><a id="toplink.logging.session" name="toplink.logging.session"></a>
| |
| − | <p><code>toplink.logging.session</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t31 r1c2-t31">
| |
| − | <p>Control whether a TopLink session identifier is logged in each log entry.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–log a TopLink session identifier.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–do not log a TopLink session identifier.</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.logging.session" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − |
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.LOGGING_SESSION, "false");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r6c1-t31 r1c3-t31">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r7c1-t31" headers="r1c1-t31"><a id="toplink.logging.exceptions" name="toplink.logging.exceptions"></a>
| |
| − | <p><code>toplink.logging.exceptions</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t31 r1c2-t31">
| |
| − | <p>Control whether the exceptions thrown from within the TopLink 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.</p>
| |
| − | <p>The following are the valid values:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–log all exceptions.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–do not log exceptions.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.logging.exceptions" value="true"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.LOGGING_EXCEPTIONS, "true");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r7c1-t31 r1c3-t31">
| |
| − | <p><code>false</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r8c1-t31" headers="r1c1-t31">
| |
| − | <p><code>toplink.logging.file</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t31 r1c2-t31">
| |
| − | <p>Specify a file location for the log output (instead of the standard out).</p>
| |
| − | <p>Note: this property applies when used in a Java SE environment.</p>
| |
| − | <p>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.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.logging.file" value="C:\myout\"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.LOGGING_FILE, "C:\myout\");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r8c1-t31 r1c3-t31"><br /></td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − |
| |
| − | <p>For information about the use of annotations as opposed to persistence unit properties and vice versa, see <a href="#CJAFAHEJ">"What You May Need to Know About Overriding Annotations"</a>.</p>
| |
| − | </div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="CACFFJFD" name="CACFFJFD"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Session, Target Database and Target Application Server</h2>
| |
| − | <p><a href="#CJAEBIJC">Table 1-21</a> lists the TopLink JPA persistence unit properties that you can define in a <code>persistence.xml</code> file to configure TopLink extensions for session, as well as the target database and application server.</p>
| |
| − |
| |
| − | <div class="tblruleformalwidemax"><a id="sthref22" name="sthref22"></a><a id="CJAEBIJC" name="CJAEBIJC"></a>
| |
| − | <p class="titleintable">Table 1-21 TopLink JPA Persistence Unit Properties for Database, Session, and Application Server</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Persistence Unit Properties for Database, Session, and Application Server" summary="This table lists TopLink JPA persistence.xml extensions for TopLink database, session, and pplication server." dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t32">Property</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t32">Usage</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t32">Default</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t32" headers="r1c1-t32"><a id="toplink.session-name" name="toplink.session-name"></a>
| |
| − |
| |
| − | <p><code>toplink.session-name</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t32 r1c2-t32">
| |
| − | <p>Specify the name by which the TopLink session is stored in the static session manager. Use this option if you need to access the TopLink shared session outside of the context of the JPA or to use a pre-existing TopLink session configured through a TopLink <code>sessions.xml</code> file</p>
| |
| − | <p>Valid values: a valid TopLink session name that is unique in a server deployment.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.session-name" value="MySession"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.SESSION_NAME, "MySession");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r2c1-t32 r1c3-t32">
| |
| − | <p>TopLink generated unique name.</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r3c1-t32" headers="r1c1-t32">
| |
| − | <p><a id="CJACBJGJ" name="CJACBJGJ"></a><code>toplink.session-xml</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t32 r1c2-t32">
| |
| − | <p>Specify persistence information loaded from the TopLink session configuration file (<code>sessions.xml</code>).</p>
| |
| − | <p>You can use this option as an alternative to annotations and deployment XML. If you specify this property, TopLink will override all class annotation and the object-relational mapping from the <code>persistence.xml</code>, as well as <code>ORM.xml</code> and other mapping files, if present. For more information, see <a href="#CJABFEFC">"Overriding Annotations in TopLink JPA"</a>.</p>
| |
| − |
| |
| − | <p>Indicate the session by setting the <code>toplink.session-name</code> property.</p>
| |
| − | <p>Note: if you do not specify the value for this property, sessions.xml file will not be used.</p>
| |
| − | <p>Valid values: the resource name of the sessions XML file.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.session-xml" value="mysession.xml"/>
| |
| − |
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.SESSION_XML, "mysession.xml");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r3c1-t32 r1c3-t32"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t32" headers="r1c1-t32">
| |
| − | <p><code>toplink.session-event-listener</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t32 r1c2-t32">
| |
| − | <p>Specify a descriptor event listener to be added during bootstrapping.</p>
| |
| − |
| |
| − | <p>Valid values: qualified class name for a class that implements the <code>oracle.toplink.sessions.SessionEventListener</code> interface.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.session-event-listener" value="mypackage.MyClass.class"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.SESSION_EVENT_LISTENER_CLASS, "mypackage.MyClass.class");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r4c1-t32 r1c3-t32"><br /></td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t32" headers="r1c1-t32">
| |
| − | <p><code>toplink.session.include.descriptor.queries</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t32 r1c2-t32">
| |
| − | <p>Enable or disable the default copying of all named queries (see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qryun.htm#CACFBJCI">Named Queries</a>") from the descriptors to the session. These queries include the ones defined using TopLink API, descriptor amendment methods (see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/descun.htm#CHEIGIHG">Amendment Methods</a>"), and so on.</p>
| |
| − |
| |
| − | <p>The following are the valid values:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>true</code>–enable the default copying of all named queries from the descriptors to the session.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>false</code>–disable the default copying of all named queries from the descriptors to the session.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.session.include.descriptor.queries" value="false"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.INCLUDE_DESCRIPTOR_QUERIES, "false");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r5c1-t32 r1c3-t32">
| |
| − | <p><code>true</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r6c1-t32" headers="r1c1-t32"><a id="toplink.target-database" name="toplink.target-database"></a>
| |
| − | <p><code>toplink.target-database</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t32 r1c2-t32">
| |
| − | <p>Specify the type of database that your JPA application uses. The <code>oracle.toplink.config.TargetDatabase</code> enumerated type contains an entry for many of the more common database types supported.</p>
| |
| − | <p>The following are the valid values for the <code>TargetDatabase</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>Attunity</code>–configure the persistence provider to use an Attunity database.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>Auto</code>–TopLink accesses the database and uses the metadata that JDBC provides to determine the target database. Applicable to JDBC drives that support this metadata.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>Cloudscape</code>–configure the persistence provider to use a Cloudscape database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>Database</code>–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 <code>Auto</code> option requires.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>DB2</code>–configure the persistence provider to use a DB2 database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>DB2Mainframe</code>–configure the persistence provider to use a DB2Mainframe database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>DBase</code>–configure the persistence provider to use a DBase database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><code>Derby</code>–configure the persistence provider to use a Derby database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>HSQL</code>–configure the persistence provider to use an HSQL database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>Informix</code>–configure the persistence provider to use an Informix database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>JavaDB</code>–configure the persistence provider to use a JavaDB database.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>MySQL4</code>–configure the persistence provider to use a MySQL4 database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>Oracle</code>–configure the persistence provider to use an Oracle database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>PointBase</code>–configure the persistence provider to use a PointBase database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><code>PostgreSQL</code>–configure the persistence provider to use a PostgreSQL database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SQLAnyWhere</code>–configure the persistence provider to use an SQLAnyWhere database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SQLServer</code>–configure the persistence provider to use an SQLServer database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>Sybase</code>–configure the persistence provider to use a Sybase database.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>TimesTen</code>–configure the persistence provider to use a TimesTen database.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>You can also set the value to the fully qualified classname of a subclass of the <code>oracle.toplink.platform.DatabasePlatform</code> class.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.target-database" value="Oracle"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TargetDatabase;
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.TARGET_DATABASE, TargetDatabase.Oracle);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r6c1-t32 r1c3-t32">
| |
| − | <p><code>TargetDatabase.Auto</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r7c1-t32" headers="r1c1-t32"><a id="toplink.target-server" name="toplink.target-server"></a>
| |
| − | <p><code>toplink.target-server</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t32 r1c2-t32">
| |
| − | <p>Specify the type of application server that your JPA application uses:</p>
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.config.TargetServer</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>None</code>–configure the persistence provider to use no application server.</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>OC4J_10_1_3</code>–configure the persistence provider to use OC4J 10.1.3.0.</p>
| |
| − | <p>Note: this server sets this property automatically, so you do not need to set it, unless it is disabled.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SunAS9</code>–configure the persistence provider to use Sun Application Server version 9.</p>
| |
| − | <p>Note: this server sets this property automatically, so you do not need to set it, unless it is disabled.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.target-server" value="OC4J_10_1_3"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.TargetServer;
| |
| − | import oracle.toplink.config.TopLinkProperties;
| |
| − | propertiesMap.put(TopLinkProperties.TARGET_SERVER, TargetServer.OC4J_10_1_3);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r7c1-t32 r1c3-t32">
| |
| − | <p><code>None</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − |
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p>For information about the configuration of platforms, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/undtldev.htm#BABGCJBJ">Understanding Target Platforms</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/asinteg.htm#BABCJCGB">Integrating TopLink with an Application Server</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/prjdaun.htm#BABHABII">Projects and Platforms</a></p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/daun.htm#CACBHFGE">Database Platforms</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>For information about the use of annotations as opposed to persistence unit properties and vice versa, see <a href="#CJAFAHEJ">"What You May Need to Know About Overriding Annotations"</a>.</p>
| |
| − | </div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="CACIJBBA" name="CACIJBBA"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Schema Generation</h2>
| |
| − | <p><a href="#CJAJIIIA">Table 1-22</a> lists the TopLink JPA persistence unit properties that you can define in a <code>persistence.xml</code> file to configure schema generation.</p>
| |
| − |
| |
| − | <div class="tblruleformalwidemax"><a id="sthref23" name="sthref23"></a><a id="CJAJIIIA" name="CJAJIIIA"></a>
| |
| − | <p class="titleintable">Table 1-22 TopLink JPA Persistence Unit Properties for Schema Generation</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Persistence Unit Properties for Schema Generation" summary="This table lists TopLink JPA persistence.xml extensions for Java2DB schema generation." dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t33">Property</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t33">Usage</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t33">Default</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t33" headers="r1c1-t33"><a id="toplink.ddl-generation" name="toplink.ddl-generation"></a>
| |
| − |
| |
| − | <p><a id="CJAGHFGI" name="CJAGHFGI"></a><code>toplink.ddl-generation</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t33 r1c2-t33">
| |
| − | <p>Specify what Data Definition Language (DDL) generation action you want for your JPA entities. To specify the DDL generation target, see <a href="#CJAHICAC">toplink.ddl-generation.output-mode</a>.</p>
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>none</code>–do not generate DDL; no schema is generated.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>create-tables</code>–create DDL for non-existent tables; leave existing tables unchanged (see also <a href="#CJAIIDIB">toplink.create-ddl-jdbc-file-name</a>).</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>drop-and-create-tables</code>–create DDL for all tables; drop all existing tables (see also <a href="#CJAIIDIB">toplink.create-ddl-jdbc-file-name</a> and <a href="#CJAEEFBE">toplink.drop-ddl-jdbc-file-name</a>).</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>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 <code>INTERACT_WITH_DB</code> and set its value to <code>false</code>.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.ddl-generation" value="create-tables"/>
| |
| − |
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider;
| |
| − | propertiesMap.put(EntityManagerFactoryProvider.DDL_GENERATION, EntityManagerFactoryProvider.CREATE_ONLY);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r2c1-t33 r1c3-t33">
| |
| − | <p><code>none</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t33" headers="r1c1-t33"><a id="toplink.application-location" name="toplink.application-location"></a>
| |
| − | <p><a id="CJAFGEBH" name="CJAFGEBH"></a><code>toplink.application-location</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t33 r1c2-t33">
| |
| − | <p>Specify where TopLink should write generated DDL files (see <a href="#CJAIIDIB">toplink.create-ddl-jdbc-file-name</a> and <a href="#CJAEEFBE">toplink.drop-ddl-jdbc-file-name</a>). Files are written if <a href="#CJAGHFGI">toplink.ddl-generation</a> is set to anything other than <code>none</code>.</p>
| |
| − | <p>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, TopLink will append one valid for your operating system.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.application-location" value="C:\ddl\"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider;
| |
| − | propertiesMap.put(EntityManagerFactoryProvider.APP_LOCATION, "C:\ddl\");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r3c1-t33 r1c3-t33">
| |
| − | <p><code>"."+File.separator</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − |
| |
| − | <td align="left" id="r4c1-t33" headers="r1c1-t33"><a id="toplink.create-ddl-jdbc-file-name" name="toplink.create-ddl-jdbc-file-name"></a>
| |
| − | <p><a id="CJAIIDIB" name="CJAIIDIB"></a><code>toplink.create-ddl-jdbc-file-name</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t33 r1c2-t33">
| |
| − | <p>Specify the file name of the DDL file that TopLink generates containing SQL statements to create tables for JPA entities. This file is written to the location specified by <a href="#CJAFGEBH">toplink.application-location</a> when <a href="#CJAGHFGI">toplink.ddl-generation</a> is set to <code>create-tables</code> or <code>drop-and-create-tables</code>.</p>
| |
| − |
| |
| − | <p>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 <a href="#CJAFGEBH">toplink.application-location</a> + <a href="#CJAIIDIB">toplink.create-ddl-jdbc-file-name</a> is a valid file specification for your operating system.</p>
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.create-ddl-jdbc-file-name" value="create.sql"/>
| |
| − |
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider;
| |
| − | propertiesMap.put(EntityManagerFactoryProvider.CREATE_JDBC_DDL_FILE, "create.sql");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r4c1-t33 r1c3-t33">
| |
| − | <p><code>createDDL.jdbc</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t33" headers="r1c1-t33"><a id="toplink.drop-ddl-jdbc-file-name" name="toplink.drop-ddl-jdbc-file-name"></a>
| |
| − | <p><a id="CJAEEFBE" name="CJAEEFBE"></a><code>toplink.drop-ddl-jdbc-file-name</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t33 r1c2-t33">
| |
| − | <p>Specify the file name of the DDL file that TopLink generates containing the SQL statements to drop tables for JPA entities. This file is written to the location specified by <a href="#CJAFGEBH">toplink.application-location</a> when <a href="#CJAGHFGI">toplink.ddl-generation</a> is set to <code>drop-and-create-tables</code></p>
| |
| − | <p>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 <a href="#CJAFGEBH">toplink.application-location</a> + <a href="#CJAEEFBE">toplink.drop-ddl-jdbc-file-name</a> is a valid file specification for your operating system.</p>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.drop-ddl-jdbc-file-name" value="drop.sql"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider;
| |
| − | propertiesMap.put(EntityManagerFactoryProvider.DROP_JDBC_DDL_FILE, "drop.sql");
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r5c1-t33 r1c3-t33">
| |
| − | <p><code>dropDDL.jdbc</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t33" headers="r1c1-t33"><a id="toplink.ddl-generation.output-mode" name="toplink.ddl-generation.output-mode"></a>
| |
| − | <p><a id="CJAHICAC" name="CJAHICAC"></a><code>toplink.ddl-generation.output-mode</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t33 r1c2-t33">
| |
| − | <p>Use this property to specify the DDL generation target.</p>
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider</code>:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>both</code>–generate SQL files and execute them on the database.</p>
| |
| − | <p>If <a href="#CJAGHFGI">toplink.ddl-generation</a> is set to <code>create-tables</code>, then <a href="#CJAIIDIB">toplink.create-ddl-jdbc-file-name</a> is written to <a href="#CJAFGEBH">toplink.application-location</a> and executed on the database.</p>
| |
| − |
| |
| − | <p>If <a href="#CJAGHFGI">toplink.ddl-generation</a> is set to <code>drop-and-create-tables</code>, then both <a href="#CJAIIDIB">toplink.create-ddl-jdbc-file-name</a> and <a href="#CJAEEFBE">toplink.drop-ddl-jdbc-file-name</a> are written to <a href="#CJAFGEBH">toplink.application-location</a> and both SQL files are executed on the database.</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>database</code>–execute SQL on the database only (do not generate SQL files).</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>sql-script</code>–generate SQL files only (do not execute them on the database).</p>
| |
| − | <p>If <a href="#CJAGHFGI">toplink.ddl-generation</a> is set to <code>create-tables</code>, then <a href="#CJAIIDIB">toplink.create-ddl-jdbc-file-name</a> is written to <a href="#CJAFGEBH">toplink.application-location</a>. It is not executed on the database.</p>
| |
| − |
| |
| − | <p>If <a href="#CJAGHFGI">toplink.ddl-generation</a> is set to <code>drop-and-create-tables</code>, then both <a href="#CJAIIDIB">toplink.create-ddl-jdbc-file-name</a> and <a href="#CJAEEFBE">toplink.drop-ddl-jdbc-file-name</a> are written to <a href="#CJAFGEBH">toplink.application-location</a>. Neither is executed on the database.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − |
| |
| − | <p><span class="bold">Example</span>: <code>persistence.xml</code> file</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <property name="toplink.ddl-generation.output-mode" value="database"/>
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: property <code>Map</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.ejb.cmp3.EntityManagerFactoryProvider;
| |
| − | propertiesMap.put(EntityManagerFactoryProvider.DDL_GENERATION_MODE, EntityManagerFactoryProvider.DDL_DATABASE_GENERATION);
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r6c1-t33 r1c3-t33">
| |
| − | <p>Container or Java EE mode: EntityManagerFactoryProvider.<code>sql-script</code></p>
| |
| − | <p>Bootstrap or Java SE mode: EntityManagerFactoryProvider.<code>both</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p>For information about the use of annotations as opposed to persistence unit properties and vice versa, see <a href="#CJAFAHEJ">"What You May Need to Know About Overriding Annotations"</a>.</p>
| |
| − |
| |
| − | </div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="BABIDJEG" name="BABIDJEG"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Extensions for Tracking Changes</h2>
| |
| − | <p>Within a transaction, TopLink automatically tracks entity changes.</p>
| |
| − | <p>TopLink defines one annotation for tracking changes–<code>@ChangeTracking</code> (see <a href="#BABGGBIJ">"How to Use the @ChangeTracking Annotation"</a>).</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowund.htm#CIHJJAGI">Unit of Work and Change Policy</a>".</p>
| |
| − |
| |
| − | <a id="BABGGBIJ" name="BABGGBIJ"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use the @ChangeTracking Annotation</h3>
| |
| − | <p>Use the <code>@ChangeTracking</code> annotation to set the unit of work's change policy.</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Target({TYPE})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface ChangeTracking { ... }
| |
| − | </pre>
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − |
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | This is an optimization feature that lets you tune the way TopLink detects changes. You should choose the strategy based on the usage and data modification patterns of the entity type as different types may have different access patterns and hence different settings, and so on.
| |
| − | <p>For more information, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/optimiz.htm#BEEGAGCE">Optimizing the Unit of Work</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/optimiz.htm#BEEGGDDB">Read Optimization Examples</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/optimiz.htm#BEEFFIIA">Write Optimization Examples</a>.</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <p><a href="#BABCBEBA">Table 1-23</a> lists attributes of the <code>@ChangeTracking</code> annotation.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref24" name="sthref24"></a><a id="BABCBEBA" name="BABCBEBA"></a>
| |
| − | <p class="titleintable">Table 1-23 Attributes of the @ChangeTracking Annotation</p>
| |
| − |
| |
| − | <table class="RuleFormalWideMax" title="Attributes of the @ChangeTracking Annotation" summary="This table lists the attributes of TopLink JPA @ChangeTracking annotation" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t35">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t35">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t35">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t35">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t35" headers="r1c1-t35">
| |
| − | <p><code>value</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t35 r1c2-t35">
| |
| − | <p>Set this attribute to the type of the change tracking (<code>oracle.toplink.annotations.ChangeTrackingType</code> enumerated type) to use.</p>
| |
| − | <p>The following are the valid values for the <code>ChangeTrackingType</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>ATTRIBUTE</code>–This option allows change tracking at the attribute level of an object. Objects with changed attributes will be processed at the commit time to include any changes in the results of the commit. Unchanged objects will be ignored.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowund.htm#CIHBBGBB">Attribute Change Tracking Policy</a>".</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>OBJECT</code>–This option allows an object to calculate for itself whether or not it has changed. Changed objects will be processed at the commit time to include any changes in the results of the commit. Unchanged objects will be ignored.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowund.htm#CIHDJFIC">Object-Level Change Tracking Policy</a>".</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>DEFERRED</code>–This option defers all change detection to the <code>UnitOfWork</code>'s change detection process.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowund.htm#CIHBIEDF">Deferred Change Tracking Policy</a>".</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>AUTO</code>–This option does not set any change tracking policy. The policy is determined by the TopLink agent: if the class can be weaved for change tracking the <code>ATTRIBUTE</code> option is used; otherwise, the <code>DEFERRED</code> option is used.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t35 r1c3-t35">
| |
| − | <p><code>ChangeTrackingType.AUTO</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t35 r1c4-t35">
| |
| − | <p>optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p><a href="#BABJHDGJ">Example 1-20</a> shows how to use the <code>@ChangeTracking</code> annotation.</p>
| |
| − |
| |
| − | <div class="example"><a id="BABJHDGJ" name="BABJHDGJ"></a>
| |
| − | <p class="titleinexample">Example 1-20 Usage of @ChangeTracking Annotation</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | @Table(name="EMPLOYEE")
| |
| − | @ChangeTracking(OBJECT) (
| |
| − | public class Employee implements Serializable {
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="CACEGCFG" name="CACEGCFG"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Query Customization Extensions</h2>
| |
| − | <p>This section describes the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><a href="#CACJJADJ">How to Use TopLink JPA Query Hints</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACIJDHJ">How to Use TopLink Query API in JPA Queries</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <a id="CACJJADJ" name="CACJJADJ"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use TopLink JPA Query Hints</h3>
| |
| − | <p><a href="#CJADBHCE">Table 1-24</a> lists the TopLink JPA query hints that you can specify when you construct a JPA query, as <a href="#CJAGAFIC">Example 1-21</a> shows, or when you specify a JPA query using the <code>@QueryHint</code> annotation (see Section 8.3.1 "NamedQuery Annotation" of the JPA specification), as <a href="#CJADBIHF">Example 1-22</a> shows.</p>
| |
| − |
| |
| − | <p>When you set a hint, you can set the value using the public static final field in the appropriate configuration class in <code>oracle.toplink.config</code> package, including the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>PessimisticLock</code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>TopLinkQueryHints</code></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>HintValues</code></p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><a href="#CJAGAFIC">Example 1-21</a> and <a href="#CJADBIHF">Example 1-22</a> show how to set the value of hint <code>toplink.jdbc.bind-parameters</code> using the <code>TopLinkQueryHints</code> configuration class to set the name of the hint, and the <code>HintValues</code> configuration class to set the value.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAGAFIC" name="CJAGAFIC"></a>
| |
| − | <p class="titleinexample">Example 1-21 Specifying a TopLink JPA Query Hint</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − |
| |
| − | Customer customer = (Customer)entityMgr.createNamedQuery("findCustomerBySSN").
| |
| − | setParameter("SSN", "123-12-1234").
| |
| − | setHint(TopLinkQueryHints.BIND_PARAMETERS, HintValues.PERSISTENCE_UNIT_DEFAULT).
| |
| − | getSingleResult();
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <div class="example"><a id="CJADBIHF" name="CJADBIHF"></a>
| |
| − | <p class="titleinexample">Example 1-22 Specifying a TopLink JPA Query Hint with @QueryHint</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − |
| |
| − | @Entity
| |
| − | @NamedQuery(
| |
| − | name="findEmployeeByDept",
| |
| − | query="SELECT e FROM Employee e WHERE e.dept=:deptNum"
| |
| − | hints={@QueryHint=
| |
| − | {name=TopLinkQueryHints.BIND_PARAMETERS, value=HintValues.TRUE}
| |
| − | }
| |
| − | )
| |
| − | public class Employee implements Serializable {
| |
| − | ...
| |
| − | }
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <div class="tblruleformalwidemax"><a id="sthref25" name="sthref25"></a><a id="CJADBHCE" name="CJADBHCE"></a>
| |
| − | <p class="titleintable">Table 1-24 TopLink JPA Query Hints</p>
| |
| − |
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Query Hints" summary="This table lists TopLink JPA persistence.xml extensions for TopLink JDBC (JSE)" dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t36">Hint</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t36">Usage</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t36">Default</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t36" headers="r1c1-t36">
| |
| − | <p><code>toplink.cache-usage</code></p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r2c1-t36 r1c2-t36">
| |
| − | <p>Specify how the query should interact with the TopLink cache.</p>
| |
| − | <p>TopLink JPA uses a shared cache mechanism that is scoped to the entire persistence unit. When operations are completed in a particular persistence context, the results are merged back into the shared cache so that other persistence contexts can use them. This happens regardless of whether the entity manager and persistence context are created in Java SE or Java EE. Any entity persisted or removed using the entity manager will always be kept consistent with the cache.Cache invalidation is another strategy that you can use. Consider the following example, that clears the current persistence context as well as invalidates the cache:</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | public static void clearCache(EntityManager em){
| |
| − | em.clear();
| |
| − | oracle.toplink.ejb.cmp3.EntityManager tlem =
| |
| − | (oracle.toplink.ejb.cmp3.EntityManager)em;
| |
| − | tlem.getActiveSession()
| |
| − | .getIdentityMapAccessor()
| |
| − | .initializeAllIdentityMaps();
| |
| − | }
| |
| − | </pre>
| |
| − | <p>For more information, see the following:</p>
| |
| − | <p>- <a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/cachun.htm#sthref4981">Session Cache</a></p>
| |
| − | <p>- <a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qryun.htm#i1165073">Using In-Memory Queries</a></p>
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.config.CacheUsage</code>:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>DoNotCheckCache</code>–Always go to the database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CheckCacheByExactPrimaryKey</code>–If a read-object query contains an expression where the primary key is the only comparison, you can obtain a cache hit if you process the expression against the object in memory</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qrybas.htm#BCFCEAJG">Reading Objects Using Query-By-Example</a>".</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CheckCacheByPrimaryKey</code>–If a read-object query contains an expression that compares at least the primary key, you can obtain a cache hit if you process the expression against the objects in memory.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CheckCacheThenDatabase</code>–You can configure any read-object query to check the cache completely before you resort to accessing the database.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CheckCacheOnly</code>–You can configure any read-all query to check only the parent session cache (shared cache) and return the result from it without accessing the database.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qrybas.htm#BCFCEAJG">Reading Objects Using Query-By-Example</a>".</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>ConformResultsInUnitOfWork</code>–You can configure any read-object or read-all query within the context of a unit of work to conform the results with the changes to the object made within that unit of work. This includes new objects, deleted objects and changed objects.</p>
| |
| − |
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowadv.htm#CACIJJBF">Using Conforming Queries and Descriptors</a>".</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>UseEntityDefault</code>–Use the cache configuration as specified by the TopLink descriptor API for this entity.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>Note: the default value is related to the value that you defined in the descriptor for the <code>disableCacheHits</code> method (see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/uowadv.htm#CACEDDEC">Descriptor Method disableCacheHits</a>"), which defaults to <code>false</code> in the descriptor. This amounts to <code>CheckCacheByPrimaryKey</code> value by default, but how TopLink interprets this depends on the query: if <code>disableCacheHits</code> were set to <code>true</code>, <code>DoNotCheckCache</code> would be the default. For a read-all query, <code>CheckCacheByPrimaryKey</code> means the same as <code>DoNotCheckCache</code>. For a read-object query, this means the cache is first checked for a primary key query. For a report query, <code>toplink.cache-usage</code> hint is not supported. Currently, in TopLink JPA read-all queries are used for any "simple" queries, and report queries are used for "complex" queries (for example, selecting non-objects or multiple objects); read-object queries are never used making the <code>toplink.cache-usage</code> somewhat limited.</p>
| |
| − |
| |
| − | <p>For more information, see " <a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qryun.htm#CACDAJCC">Configuring Cache Usage for In-Memory Queries</a>".</p>
| |
| − | <p><span class="bold">Example</span>: JPA Query API</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.CacheUsage;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | query.setHint(TopLinkQueryHints.CACHE_USAGE, CacheUsage.CheckCacheOnly);
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: <code>@QueryHint</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.CacheUsage;
| |
| − | import oracle.toplink.config.TargetDatabase;
| |
| − | @QueryHint(name=TopLinkQueryHints.CACHE_USAGE, value=CacheUsage.CheckCacheOnly);
| |
| − | </pre></td>
| |
| − |
| |
| − | <td align="left" headers="r2c1-t36 r1c3-t36">
| |
| − | <p><code>CacheUsage.UseEntityDefault</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t36" headers="r1c1-t36"><a id="toplink.jdbc.bind-parameters_query.hint" name="toplink.jdbc.bind-parameters_query.hint"></a>
| |
| − | <p><code>toplink.jdbc.bind-parameters</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t36 r1c2-t36">
| |
| − | <p>Control whether or not the query uses parameter binding.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/optimiz.htm#i1124456">Parameterized SQL (Binding) and Prepared Statement Caching</a>".</p>
| |
| − |
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.config.HintValues</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>TRUE</code>–bind all parameters.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FALSE</code>–do not bind all parameters.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>PERSISTENCE_UNIT_DEFAULT</code>–use the parameter binding setting made in your TopLink session's database login, which is <code>true</code> by default.</p>
| |
| − |
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/dblgcfg.htm#BABIGEJG">Configuring JDBC Options</a>".</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: JPA Query API</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | query.setHint(TopLinkQueryHints.BIND_PARAMETERS, HintValues.TRUE);
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: <code>@QueryHint</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − |
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TargetDatabase;
| |
| − | @QueryHint(name=TopLinkQueryHints.BIND_PARAMETERS, value=HintValues.TRUE);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r3c1-t36 r1c3-t36">
| |
| − | <p><code>HintValues.PERSISTENCE_UNIT_DEFAULT</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t36" headers="r1c1-t36">
| |
| − | <p><code>toplink.jdbc.fetch-size</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t36 r1c2-t36">
| |
| − | <p>Specify the number of rows that should be fetched from the database when more rows are needed.</p>
| |
| − | <p>For large queries that return a large number of objects you can configure the row fetch size used in the query to improve performance by reducing the number database hits required to satisfy the selection criteria. Most JDBC drivers default to a fetch size of 10, so if you are reading 1000 objects, increasing the fetch size to 256 can significantly reduce the time required to fetch the query's results. The optimal fetch size is not always obvious. Usually, a fetch size of one half or one quarter of the total expected result size is optimal. Note that if you are unsure of the result set size, incorrectly setting a fetch size too large or too small can decrease performance.</p>
| |
| − |
| |
| − | <p>A value of 0 means the JDBC driver returns results one row at a time.</p>
| |
| − | <p>Note: this property is dependent on the JDBC driver support.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> (depending on your JDBC driver) as a <code>String</code>.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t36 r1c3-t36">
| |
| − | <p>0</p>
| |
| − |
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t36" headers="r1c1-t36">
| |
| − | <p><code>toplink.jdbc.timeout</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t36 r1c2-t36">
| |
| − | <p>Specify the number of seconds TopLink will wait on a query before throwing a <code>DatabaseException</code>.</p>
| |
| − | <p>A value of 0 means TopLink will never time-out a query.</p>
| |
| − | <p>Note: this property is dependent on the JDBC driver support.</p>
| |
| − | <p>Valid values: <code>0</code> to <code>Integer.MAX_VALUE</code> (depending on your JDBC driver) as a <code>String</code>.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t36 r1c3-t36">
| |
| − | <p>0</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t36" headers="r1c1-t36"><a id="toplink.pessimistic-lock" name="toplink.pessimistic-lock"></a>
| |
| − | <p><code>toplink.pessimistic-lock</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t36 r1c2-t36">
| |
| − | <p>Control whether or not pessimistic locking is used.</p>
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.config.PessimisticLock</code>:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>NoLock</code>–pessimistic locking is not used.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>Lock</code>–TopLink issues a <code>SELECT .... FOR UPDATE</code>.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>LockNoWait</code>–TopLink issues a <code>SELECT .... FOR UPDATE NO WAIT</code>.</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: JPA Query API</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.PessimisticLock;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | query.setHint(TopLinkQueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: <code>@QueryHint</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.PessimisticLock;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | @QueryHint(name=TopLinkQueryHints.PESSIMISTIC_LOCK, value=PessimisticLock.LockNoWait);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r6c1-t36 r1c3-t36">
| |
| − | <p><code>NoLock</code></p>
| |
| − |
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r7c1-t36" headers="r1c1-t36">
| |
| − | <p><code>toplink.batch</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t36 r1c2-t36">
| |
| − | <p>Supply TopLink with batching information so subsequent queries of related objects can be optimized in batches instead of being retrieved in one large joined read.</p>
| |
| − | <p>Batching is only allowed on queries that have a single object in their select clause.</p>
| |
| − | <p>Allow joining of the attributes.</p>
| |
| − | <p>This is different from JP QL joining because it allows multilevel fetch joins.</p>
| |
| − | <p>Valid values: a single-valued relationship path expression.</p>
| |
| − |
| |
| − | <p>Note: use dot notation to access nested attributes. For example, to batch-read an employee's manager's address, specify <code>e.manager.address</code></p>
| |
| − | <p><span class="bold">Example</span>: JPA Query API</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | query.setHint("toplink.batch", "e.address");
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: <code>@QueryHint</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | @QueryHint(name=TopLinkQueryHints.BATCH, value="e.address");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r7c1-t36 r1c3-t36">
| |
| − |
| |
| − | <p><code>""</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r8c1-t36" headers="r1c1-t36">
| |
| − | <p><code>toplink.join-fetch</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r8c1-t36 r1c2-t36">
| |
| − | <p>Allow joining of the attributes.</p>
| |
| − | <p>This is similar to <code>toplink.batch</code>, except that you can use it for queries that select multiple items in the <code>SELECT</code> clause.</p>
| |
| − |
| |
| − | <p>For more information, see Section 4.4.5.3 "Fetch Joins" of JPA specification.</p>
| |
| − | <p>Valid values: a relationship path expression.</p>
| |
| − | <p>Note: use dot notation to access nested attributes.</p>
| |
| − | <p><span class="bold">Example</span>: JPA Query API</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | query.setHint("toplink.join-fetch", "e.address");
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: <code>@QueryHint</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − |
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | @QueryHint(name=TopLinkQueryHints.FETCH, value="e.address");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r8c1-t36 r1c3-t36">
| |
| − | <p><code>""</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r9c1-t36" headers="r1c1-t36"><a id="toplink.refresh" name="toplink.refresh"></a>
| |
| − | <p><code>toplink.refresh</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r9c1-t36 r1c2-t36">
| |
| − | <p>Control whether or not to update the TopLink session cache with objects that the query returns.</p>
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.config.HintValues</code>:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>TRUE</code>–refresh cache.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FALSE</code>–do not refresh cache.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: JPA Query API</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | query.setHint(TopLinkQueryHints.REFRESH, HintValues.TRUE);
| |
| − |
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: <code>@QueryHint</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | @QueryHint(name=TopLinkQueryHints.REFRESH, value=HintValues.TRUE);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r9c1-t36 r1c3-t36">
| |
| − | <p><code>FALSE</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r10c1-t36" headers="r1c1-t36">
| |
| − | <p><code>toplink.return-shared</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r10c1-t36 r1c2-t36">
| |
| − | <p>Retrieve read-only results back from the query: on nontransactional read operations, where the requested entity types are stored in the shared cache, you can request that the shared instance be returned instead of a detached copy.</p>
| |
| − | <p>You must set the read-only flag for the report query to <code>true</code>.</p>
| |
| − | <p>Note: You should never modify objects returned from the shared cache.</p>
| |
| − | <p>The following are the valid values for the <code>oracle.toplink.config.HintValues</code>:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>TRUE</code>–retrieve read-only results back from the query;</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FALSE</code>–do not retrieve read-only results back from the query.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p><span class="bold">Example</span>: JPA Query API</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | query.setHint(TopLinkQueryHints.RETURN_SHARED, HintValues.TRUE);
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: <code>@QueryHint</code></p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | @QueryHint(name=TopLinkQueryHints.RETURN_SHARED, value=HintValues.TRUE);
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r10c1-t36 r1c3-t36">
| |
| − | <p><code>FALSE</code></p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r11c1-t36" headers="r1c1-t36">
| |
| − | <p><code>toplink.result-collection-type</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r11c1-t36 r1c2-t36">
| |
| − | <p>Configure the concrete class that TopLink should use to return its query result.</p>
| |
| − | <p>This lets you specify the type of collection in which the result will be returned.</p>
| |
| − |
| |
| − | <p>Valid values: Java <code>Class</code> that implements the <code>Collection</code> interface.</p>
| |
| − | <p>Note: Typically, you would execute these queries by calling the <code>getResultsList</code> method, which returns the java.util.List, on the <code>Query</code>. This means that the class specified in this hint must implement the <code>List</code> interface, if you are invoking it using the <code>getResultsList</code> method.</p>
| |
| − |
| |
| − | <p>Note: Specify the class without the <code>".class"</code> notation. For example, <code>java.util.Vector</code> would work, not <code>java.util.Vector.class</code></p>
| |
| − | <p>TopLink will throw an exception, if you use this hint with a class that does not implement the <code>Collection</code> interface.</p>
| |
| − | <p><span class="bold">Example</span>: JPA Query API</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | query.setHint("toplink.result-collection-type", "java.util.ArrayList.class");
| |
| − | </pre>
| |
| − | <p><span class="bold">Example</span>: <code>@QueryHint</code></p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | import oracle.toplink.config.HintValues;
| |
| − | import oracle.toplink.config.TopLinkQueryHints;
| |
| − | @QueryHint(name=TopLinkQueryHints.RESULT_COLLECTION_TYPE, value="java.util.ArrayList");
| |
| − | </pre></td>
| |
| − | <td align="left" headers="r11c1-t36 r1c3-t36">
| |
| − | <p>java.util.Vector</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − |
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="CACIJDHJ" name="CACIJDHJ"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use TopLink Query API in JPA Queries</h3>
| |
| − | <p>TopLink JPA provides a TopLink implementation class for each JPA persistence interface. By casting to the TopLink implementation class, you have full access to TopLink functionality.</p>
| |
| − | <p>This section provides the following examples:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CJAFGFEJ">Creating a JPA Query Using the TopLink Expressions Framework</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><a href="#CJACFIGB">Creating a JPA Query Using a TopLink DatabaseQuery</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CJABCFBJ">Creating a JPA Query Using a TopLink Call Object</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CJAFCACJ">Using Named Parameters in a Native Query</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CJADDHGG">Using Java Persistence Query Language Positional Parameters in a Native Query</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CJABHABE">Using JDBC-Style Positional Parameters in a Native Query</a></p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/prt_qur.htm#BABCBADI">Understanding TopLink Queries</a>".</p>
| |
| − | <a id="CJAFGFEJ" name="CJAFGFEJ"></a>
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" -->
| |
| − | <h4 class="sect3">Creating a JPA Query Using the TopLink Expressions Framework</h4>
| |
| − | <p>TopLink provides an expression framework with which you can express queries in a database-neutral fashion as an alternative to raw SQL.</p>
| |
| − | <p><a href="#CJAFDHAG">Example 1-23</a> shows how to cast an entity manager to access a TopLink persistence provider <code>createQuery</code> method that takes a TopLink <code>Expression</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAFDHAG" name="CJAFDHAG"></a>
| |
| − | <p class="titleinexample">Example 1-23 Creating a Query with the TopLink Expressions Framework</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | ((oracle.toplink.ejb.cmp3.EntityManager)entityManager.getDelegate()).
| |
| − | createQuery(Expression expression, Class resultType);
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p>TopLink expressions offer the following advantages over SQL when you access a database:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p>Expressions are easier to maintain because the database is abstracted.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Changes to descriptors or database tables do not affect the querying structures in the application.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Expressions enhance readability by standardizing the <code>Query</code> interface so that it looks similar to traditional Java calling conventions.</p>
| |
| − | <p>For example, the Java code required to get the street name from the <code>Address</code> object of the <code>Employee</code> class looks like this:</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | emp.getAddress().getStreet().equals("Meadowlands");
| |
| − |
| |
| − | </pre>
| |
| − | <p>The expression to get the same information is similar:</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | emp.get("address").get("street").equal("Meadowlands");
| |
| − | </pre></li>
| |
| − | <li type="disc">
| |
| − | <p>Expressions allow read queries to transparently query between two classes that share a relationship. If these classes are stored in multiple tables in the database, TopLink automatically generates the appropriate join statements to return information from both tables.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Expressions simplify complex operations.</p>
| |
| − | <p>For example, the following Java code retrieves all employees that live on "Meadowlands" whose salary is greater than 10,000:</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | ExpressionBuilder emp = new ExpressionBuilder();
| |
| − | Expression exp = emp.get("address").get("street").equal("Meadowlands");
| |
| − | Vector employees = session.readAllObjects(Employee.class,
| |
| − | exp.and(emp.get("salary").greaterThan(10000)));
| |
| − |
| |
| − | </pre>
| |
| − | <p>TopLink automatically generates the appropriate SQL from the preceding code:</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | SELECT t0.VERSION, t0.ADDR_ID, t0.EMP_ID, t0.SALARY FROM EMPLOYEE t0, ADDRESS t1 WHERE (((t1.STREET = 'Meadowlands')AND (t0.SALARY > 10000)) AND (t1.ADDRESS_ID = t0.ADDR_ID))
| |
| − | </pre></li>
| |
| − | </ul>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/expres.htm#CJAGGAGJ">Understanding the TopLink Expressions</a>".</p>
| |
| − | </div>
| |
| − | <!-- class="sect3" -->
| |
| − | <a id="CJACFIGB" name="CJACFIGB"></a>
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" -->
| |
| − |
| |
| − | <h4 class="sect3">Creating a JPA Query Using a TopLink DatabaseQuery</h4>
| |
| − | <p>A TopLink <code>DatabaseQuery</code> is a query object that provides a rich API for handling a variety of database query requirements, including reading and writing at the object level and at the data level.</p>
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qryun.htm#CACFEDJD">Understanding the TopLink DatabaseQuery</a>".</p>
| |
| − | <p><a href="#CJAEGECE">Example 1-24</a> shows how to cast a JPA query from an entity manager to access a TopLink persistence provider <code>setDatabaseQuery</code> method that takes a TopLink <code>DatabaseQuery</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAEGECE" name="CJAEGECE"></a>
| |
| − | <p class="titleinexample">Example 1-24 DatabaseQuery</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | ((oracle.toplink.ejb.cmp3.EJBQuery)query).setDatabaseQuery(DatabaseQuery query);
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p><a href="#CJAGEAAB">Example 1-25</a> shows how to cast a JPA query from an entity manager to access a TopLink persistence provider <code>setDatabaseQuery</code> method that takes a TopLink <code>DataReadQuery</code> initialized with a TopLink <code>SQLCall</code> object that specifies a <code>SELECT</code>. This query will return one or more objects.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAGEAAB" name="CJAGEAAB"></a>
| |
| − | <p class="titleinexample">Example 1-25 DatabaseQuery with Selecting Call</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | ((oracle.toplink.ejb.cmp3.EJBQuery)query).
| |
| − | setDatabaseQuery(new DataReadQuery(new SQLCall("SELECT...")));
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p><a href="#CJAFCADG">Example 1-26</a> shows how to cast a JPA query from an entity manager to access a TopLink persistence provider <code>setDatabaseQuery</code> method that takes a TopLink <code>DataModifyQuery</code> initialized with a TopLink <code>SQLCall</code> object that specifies an <code>UPDATE</code>. This query will modify one or more objects; however, this query will not update the managed objects within the persistence context.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAFCADG" name="CJAFCADG"></a>
| |
| − | <p class="titleinexample">Example 1-26 DatabaseQuery with Non-Selecting Call</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | ((oracle.toplink.ejb.cmp3.EJBQuery)query).
| |
| − | setDatabaseQuery(new DataModifyQuery(new SQLCall("UPDATE...")));
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect3" -->
| |
| − | <a id="CJABCFBJ" name="CJABCFBJ"></a>
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" -->
| |
| − | <h4 class="sect3">Creating a JPA Query Using a TopLink Call Object</h4>
| |
| − | <p>Using <code>DatabaseQuery</code> method <code>setCall</code>, you can define your own TopLink <code>Call</code> to accommodate a variety of data source options such as SQL stored procedures and stored functions, EJB QL queries, and EIS interactions.</p>
| |
| − |
| |
| − | <p><a href="#CJABJHIH">Example 1-27</a> shows how to cast a JPA query from an entity manager to access a TopLink persistence provider <code>getDatabaseQuery</code> method to set a new <code>SQLCall</code>.</p>
| |
| − | <div class="example"><a id="CJABJHIH" name="CJABJHIH"></a>
| |
| − | <p class="titleinexample">Example 1-27 Call</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | ((oracle.toplink.ejb.cmp3.EJBQuery)query).
| |
| − | getDatabaseQuery().setCall(new SQLCall("..."));
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p>For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/qryun.htm#CACJHDCJ">Understanding TopLink Call Queries</a>".</p>
| |
| − |
| |
| − | </div>
| |
| − | <!-- class="sect3" -->
| |
| − | <a id="CJAFCACJ" name="CJAFCACJ"></a>
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" -->
| |
| − | <h4 class="sect3">Using Named Parameters in a Native Query</h4>
| |
| − | <p>Using TopLink, you can specify a named parameter in a native query using the TopLink <code>#</code> convention (see <a href="#CJAFCADE">Example 1-28</a>).</p>
| |
| − | <p>Support for the TopLink <code>#</code> convention is helpful if you are already familiar with TopLink queries or if you are migrating TopLink queries to a JPA application.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAFCADE" name="CJAFCADE"></a>
| |
| − | <p class="titleinexample">Example 1-28 Specifying a Named Parameter with #</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | Query queryEmployees = entityManager.createNativeQuery(
| |
| − | "SELECT * FROM EMPLOYEE emp WHERE emp.fname LIKE #firstname");
| |
| − | queryEmployees.setParameter("firstName", "Joan");
| |
| − | Collection employees = queryEmployees.getResultList();
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect3" -->
| |
| − | <a id="CJADDHGG" name="CJADDHGG"></a>
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" -->
| |
| − | <h4 class="sect3">Using Java Persistence Query Language Positional Parameters in a Native Query</h4>
| |
| − | <p>Using TopLink, you can specify positional parameters in a native query using the Java Persistence Query Language positional parameter convention <code>?n</code> to specify a parameter by number.</p>
| |
| − |
| |
| − | <p><a href="#CJAIFGEH">Example 1-29</a> shows how to specify positional parameters using the <code>?n</code> convention. In this example, the query string will be <code>SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "C%"</code>.</p>
| |
| − | <div class="example"><a id="CJAIFGEH" name="CJAIFGEH"></a>
| |
| − | <p class="titleinexample">Example 1-29 Specifying Positional Parameters Using ?</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | Query queryEmployees = entityManager.createNativeQuery(
| |
| − | "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ?1 AND L_NAME LIKE ?2", Employee.class);
| |
| − | queryEmployees.setParameter(1, "D%");
| |
| − | queryEmployees.setParameter(2, "C%");
| |
| − | Collection employees = queryEmployees.getResultList();
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p>You can easily re-use the same parameter in more than one place in the query, as <a href="#CJAJACFB">Example 1-30</a> shows. In this example, the query string will be <code>SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "D%"</code>.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAJACFB" name="CJAJACFB"></a>
| |
| − | <p class="titleinexample">Example 1-30 Specifying Positional Parameters Using ?n</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | Query queryEmployees = entityManager.createNativeQuery(
| |
| − | "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ?1 AND L_NAME LIKE ?1", Employee.class);
| |
| − | queryEmployees.setParameter(1, "D%");
| |
| − | Collection employees = queryEmployees.getResultList();
| |
| − | </pre></div>
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect3" -->
| |
| − | <a id="CJABHABE" name="CJABHABE"></a>
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" -->
| |
| − | <h4 class="sect3">Using JDBC-Style Positional Parameters in a Native Query</h4>
| |
| − | <p>Using TopLink, you can specify positional parameters in a native query using the JDBC-style positional parameter <code>?</code> convention.</p>
| |
| − |
| |
| − | <p><a href="#CJAJJIGD">Example 1-31</a> shows how to specify positional parameters using the <code>?</code> convention. Each occurrence of <code>?</code> must be matched by a corresponding <code>setParameter</code> call. In this example, the query string will be <code>SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "C%"</code>.</p>
| |
| − | <div class="example"><a id="CJAJJIGD" name="CJAJJIGD"></a>
| |
| − | <p class="titleinexample">Example 1-31 Specifying Positional Parameters with ?</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | Query queryEmployees = entityManager.createNativeQuery(
| |
| − | "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ? AND L_NAME LIKE ?", Employee.class);
| |
| − | queryEmployees.setParameter(1, "D%");
| |
| − | queryEmployees.setParameter(2, "C%");
| |
| − | Collection employees = queryEmployees.getResultList();
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p>If you want to re-use the same parameter in more than one place in the query, you must repeat the same parameter as <a href="#CJACJIAB">Example 1-32</a> shows. In this example, the query string will be <code>SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "D%"</code>.</p>
| |
| − | <div class="example"><a id="CJACJIAB" name="CJACJIAB"></a>
| |
| − | <p class="titleinexample">Example 1-32 Re-Using Positional Parameters with ?</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | Query queryEmployees = entityManager.createNativeQuery(
| |
| − | "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ? AND L_NAME LIKE ?", Employee.class);
| |
| − | queryEmployees.setParameter(1, "D%");
| |
| − | queryEmployees.setParameter(2, "D%");
| |
| − | Collection employees = queryEmployees.getResultList();
| |
| − | </pre></div>
| |
| − |
| |
| − | <!-- class="example" --></div>
| |
| − | <!-- class="sect3" --></div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="CACEDCAF" name="CACEDCAF"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">Using TopLink JPA Lazy Loading</h2>
| |
| − | <p>JPA specifies that lazy loading is a hint to the persistence provider that data should be fetched lazily when it is first accessed, if possible.</p>
| |
| − | <p>If you are developing your application in a Java EE environment, you only have to set fetch to <code>FetchType.LAZY</code>, and TopLink persistence provider will supply all the necessary functionality.</p>
| |
| − | <p>If you are developing your application in a Java SE environment, to configure TopLink JPA to perform lazy loading when the <code>fetch</code> attribute is set to <code>FetchType.LAZY</code>, configure either dynamic (see <a href="#DynamicWeaving">"How to Configure Dynamic Weaving"</a>) or static (see <a href="#StaticWeaving">"How to Configure Static Weaving Using the StaticWeave Class on the Command Line"</a>) weaving.</p>
| |
| − |
| |
| − | <p><a href="#CJAJCGDA">Table 1-25</a> lists TopLink JPA support for lazy loading by mapping type.</p>
| |
| − | <div class="tblruleformalwidemax"><a id="sthref26" name="sthref26"></a><a id="CJAJCGDA" name="CJAJCGDA"></a>
| |
| − | <p class="titleintable">Table 1-25 TopLink JPA Support for Lazy Loading by Mapping Type</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink JPA Support for Lazy Loading by Mapping Type" summary="This table lists TopLink JPA mapping support for lazy loading by mapping type for Java EE (in container) and Java SE (outside of container) applications." dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t37">Mapping</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t37">Java EE<a id="sthref27" name="sthref27" href="#sthref27" onclick='footdisplay(1,"Fully supported in any container that implements the appropriate container contracts in the EJB 3.0 specification.")'><sup class="tablefootnote">Foot 1 </sup></a></th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t37">Java SE</th>
| |
| − |
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t37" headers="r1c1-t37">
| |
| − | <p><code>@ManyToMany</code> (see Section 9.1.26 "ManyToMany Annotation" of the JPA specification)</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t37 r1c2-t37">
| |
| − | <p>TopLink JPA performs lazy loading when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code> (the default).</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t37 r1c3-t37">
| |
| − | <p>TopLink JPA performs lazy loading when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code> (the default).</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t37" headers="r1c1-t37">
| |
| − | <p><code>@OneToMany</code> (see Section 9.1.24 "OneToMany Annotation" of the JPA specification)</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t37 r1c2-t37">
| |
| − | <p>TopLink JPA performs lazy loading when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code> (the default).</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t37 r1c3-t37">
| |
| − | <p>TopLink JPA performs lazy loading when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code> (the default).</p>
| |
| − |
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t37" headers="r1c1-t37">
| |
| − | <p><code>@OneToOne</code> (see Section 9.1.23 "OneToOne Annotation" of the JPA specification)</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t37 r1c2-t37">
| |
| − | <p>TopLink JPA performs lazy loading when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code>.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t37 r1c3-t37">
| |
| − | <p>By default, TopLink JPA ignores the <code>fetch</code> attribute and default javax.persistence.<code>FetchType.EAGER</code> applies.</p>
| |
| − | <p>To configure TopLink JPA to perform lazy loading when the <code>fetch</code> attribute set to <code>FetchType.LAZY</code>, configure one of the following:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p>Dynamic weaving (see <a href="#DynamicWeaving">"How to Configure Dynamic Weaving"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Static weaving with the StaticWeave class on the command line (see <a href="#StaticWeaving">"How to Configure Static Weaving Using the StaticWeave Class on the Command Line"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Static weaving with the weave Ant task (see <a href="#CJAGHHFH">"How to Use Static Weaving with the weave Ant Task"</a>)</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t37" headers="r1c1-t37">
| |
| − | <p><code>@ManyToOne</code> (see Section 9.1.22 "ManyToOne Annotation" of the JPA specification)</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t37 r1c2-t37">
| |
| − | <p>TopLink JPA performs lazy loading when the <code>fetch</code> attribute is set to <code>javax.persistence.FetchType.LAZY</code>.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t37 r1c3-t37">
| |
| − | <p>By default, TopLink JPA ignores the <code>fetch</code> attribute and default <code>javax.persistence.FetchType.EAGER</code> applies.</p>
| |
| − | <p>To configure TopLink JPA to perform lazy loading when the <code>fetch</code> attribute set to <code>FetchType.LAZY</code>, configure one of the following:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p>Dynamic weaving (see <a href="#DynamicWeaving">"How to Configure Dynamic Weaving"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Static weaving with the StaticWeave class on the command line (see <a href="#StaticWeaving">"How to Configure Static Weaving Using the StaticWeave Class on the Command Line"</a>)</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>Static weaving with the weave Ant task (see <a href="#CJAGHHFH">"How to Use Static Weaving with the weave Ant Task"</a>)</p>
| |
| − |
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t37" headers="r1c1-t37">
| |
| − | <p><code>@Basic</code> (see Section 9.1.18 "Basic Annotation" of the JPA specification)</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t37 r1c2-t37">
| |
| − | <p>TopLink JPA ignores the <code>fetch</code> attribute. Default <code>javax.persistence.FetchType.EAGER</code> always applies.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t37 r1c3-t37">
| |
| − | <p>TopLink JPA ignores the <code>fetch</code> attribute. Default <code>javax.persistence.FetchType.EAGER</code> always applies.</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <p class="tablefootnote"><sup class="tablefootnote">Footnote 1 </sup>Fully supported in any container that implements the appropriate container contracts in the EJB 3.0 specification.</p>
| |
| − |
| |
| − | <p>For more information, see the following:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><a href="#CACDIDAH">What You May Need to Know About Weaving</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/optimiz.htm#BEEGGDDB">Read Optimization Examples</a></p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/mapcfg.htm#CEGDDEEA">Configuring Indirection</a></p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <a id="DynamicWeaving" name="DynamicWeaving"></a>
| |
| − |
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Configure Dynamic Weaving</h3>
| |
| − | <p>When using a one-to-one (see Section 9.1.23 "OneToOne Annotation" of the JPA specification) or many-to-one (see Section 9.1.22 "ManyToOne Annotation" of the JPA specification) mapping in a Java SE environment that permits the use of <code>-javaagent</code> on the JVM command line, to configure TopLink JPA to perform lazy loading when the annotation attribute <code>fetch</code> is set to <code>javax.persistence.FetchType.LAZY</code>, you can use the <code>toplink-agent.jar</code> file, as follows:</p>
| |
| − | <ol type="1" start="1">
| |
| − |
| |
| − | <li>
| |
| − | <p>Configure your persistence unit with a <a href="#toplink.weaving"><code>toplink.weaving</code></a> extension set to <code>true</code>.</p>
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>Modify your application JVM command line to include the following:</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | -javaagent:toplink-agent.jar
| |
| − | </pre></li>
| |
| − | <li>
| |
| − | <p>Ensure that the <code>toplink-agent.jar</code> is in your application classpath.</p>
| |
| − |
| |
| − | </li>
| |
| − | </ol>
| |
| − | <p>Use this option to weave applicable class files one at a time, as they are loaded at run time, when the number of classes is few or the time taken to weave the classes is short. If the number of class files is large or the time required to weave the classes is long, consider using static weaving (see <a href="#StaticWeaving">"How to Configure Static Weaving Using the StaticWeave Class on the Command Line"</a> or <a href="#CJAGHHFH">"How to Use Static Weaving with the weave Ant Task"</a>).</p>
| |
| − | </div>
| |
| − | <!-- class="sect2" -->
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref28" name="sthref28"></a>
| |
| − | <h3 class="sect2">How to Configure Static Weaving Using the Persistence Unit Property</h3>
| |
| − | <p>Configure your persistence unit with a <a href="#CJAFECEI">toplink.weaving</a> property set to <code>static</code>.</p>
| |
| − |
| |
| − | </div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="StaticWeaving" name="StaticWeaving"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Configure Static Weaving Using the StaticWeave Class on the Command Line</h3>
| |
| − | <p>When using a one-to-one (see Section 9.1.23 "OneToOne Annotation" of the JPA specification) or many-to-one (see Section 9.1.22 "ManyToOne Annotation" of the JPA specification) mapping in a Java SE environment that does not permit the use of <code>-javaagent</code> on the JVM command line, to configure TopLink JPA to perform lazy loading when annotation attribute <code>fetch</code> is set to <code>javax.persistence.FetchType.LAZY</code>, you can use the <code>StaticWeave</code> class on the command line.</p>
| |
| − |
| |
| − | <p>Use this option to weave all applicable class files at buildtime so that you can deliver pre-woven class files. By doing so, you can improve application performance by eliminating the runtime weaving step required by dynamic weaving (see <a href="#DynamicWeaving">"How to Configure Dynamic Weaving"</a>).</p>
| |
| − | <p>Alternatively, you can do this using Ant (see <a href="#CJAGHHFH">"How to Use Static Weaving with the weave Ant Task"</a>).</p>
| |
| − | <p>To use the <code>StaticWeave</code> class, do the following:</p>
| |
| − | <ol type="1" start="1">
| |
| − | <li>
| |
| − | <p>Ensure that the <code>toplink.jar</code> file is in your system classpath.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>Execute the <code>StaticWeave</code> class on the command line as follows:</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | java oracle.toplink.weaving.StaticWeave [arguments] <source> <target>
| |
| − | </pre>
| |
| − | <p><a href="#CJAEGCGC">Example 1-33</a> shows how to use the <code>StaticWeave</code> class on Windows systems. <a href="#CJAEIGGH">Table 1-26</a> lists the arguments of this class.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAEGCGC" name="CJAEGCGC"></a>
| |
| − | <p class="titleinexample">Example 1-33 Executing StaticWeave on the Command Line</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | java oracle.toplink.weaving.StaticWeave -persistenceinfo c:\foo-containing-persistencexml.jar -classpath c:\classpath1;c:\classpath2 c:\foo-source.jar c:\foo-target.jar
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <div class="tblruleformalwidemax"><a id="sthref29" name="sthref29"></a><a id="CJAEIGGH" name="CJAEIGGH"></a>
| |
| − | <p class="titleintable">Table 1-26 TopLink StaticWeave Class Command Line Arguments</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink StaticWeave Class Command Line Arguments" summary="This table lists the arguments of the TopLink JPA StaticWeave class." dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t38">Argument</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t38">Description</th>
| |
| − |
| |
| − | <th align="left" valign="bottom" id="r1c3-t38">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t38">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t38" headers="r1c1-t38"><a id="CJAEFHEI" name="CJAEFHEI"></a>
| |
| − | <p><code>-persistenceinfo</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t38 r1c2-t38">
| |
| − | <p>Specifies the location of the <code>persistence.xml</code> file if it is not in the same location as the source (see <a href="#CJAIHEBF"><code>-classpath</code></a>).</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t38 r1c3-t38"><br /></td>
| |
| − | <td align="left" headers="r2c1-t38 r1c4-t38">
| |
| − | <p>Optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t38" headers="r1c1-t38"><a id="CJAIHEBF" name="CJAIHEBF"></a>
| |
| − | <p><code>-classpath</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t38 r1c2-t38">
| |
| − | <p>Specifies the location of the Java source files to weave: either a directory or a JAR file. For Windows, use delimiter <code>;</code> and for Unix, use delimiter <code>:</code>.</p>
| |
| − |
| |
| − | <p>If the <code>persistence.xml</code> file is not in this location, you must specify the location of the <code>persistence.xml</code> using the <a href="#CJAEFHEI"><code>-persistenceinfo</code></a> attribute.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t38 r1c3-t38"><br /></td>
| |
| − | <td align="left" headers="r3c1-t38 r1c4-t38">
| |
| − | <p>Required</p>
| |
| − | </td>
| |
| − |
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t38" headers="r1c1-t38">
| |
| − | <p><code>-log</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t38 r1c2-t38">
| |
| − | <p>Specifies a logging file.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t38 r1c3-t38">
| |
| − | <p>See "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/sesun.htm#i1122078">Logging</a>".</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t38 r1c4-t38">
| |
| − |
| |
| − | <p>Optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t38" headers="r1c1-t38">
| |
| − | <p><code>-loglevel</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t38 r1c2-t38">
| |
| − | <p>Specifies the amount and detail of log output.</p>
| |
| − | <p>Valid <code>java.util.logging.Level</code> values are as follows:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>OFF</code>–disables logging.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SEVERE</code>–logs exceptions indicating TopLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>WARNING</code> –logs exceptions that do not force TopLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.</p>
| |
| − | </li>
| |
| − |
| |
| − | <li type="disc">
| |
| − | <p><code>INFO</code>–logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CONFIG</code>–logs only login, JDBC connection, and database information.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FINE</code>–logs SQL.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FINER</code>–similar to warning. Includes stack trace.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FINEST</code>–includes additional low level information.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t38 r1c3-t38">
| |
| − | <p><code>Level.OFF</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t38 r1c4-t38">
| |
| − | <p>Optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − |
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t38" headers="r1c1-t38">
| |
| − | <p><code><source></code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t38 r1c2-t38">
| |
| − | <p>Specifies the location of the Java source files to weave: either a directory or a JAR file.</p>
| |
| − | <p>If the <code>persistence.xml</code> file is not in this location, you must specify the location of the <code>persistence.xml</code> using the <a href="#CJAEFHEI"><code>-persistenceinfo</code></a> attribute.</p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t38 r1c3-t38"><br /></td>
| |
| − | <td align="left" headers="r6c1-t38 r1c4-t38">
| |
| − | <p>Required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r7c1-t38" headers="r1c1-t38">
| |
| − | <p><code><target></code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t38 r1c2-t38">
| |
| − | <p>Specifies the output location: either a directory or a JAR file.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r7c1-t38 r1c3-t38"><br /></td>
| |
| − |
| |
| − | <td align="left" headers="r7c1-t38 r1c4-t38">
| |
| − | <p>Required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − |
| |
| − | If <code><source></code> and <code><target></code> point to the same location and if the <code><source></code> is a directory (not a JAR file), TopLink JPA will weave in place. If <code><source></code> and <code><target></code> point to different locations or if the <code>source</code> is a JAR file (as <a href="#CJAEGCGC">Example 1-33</a> shows), TopLink JPA cannot weave in place.</td>
| |
| − |
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | </li>
| |
| − | </ol>
| |
| − | </div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="CJAGHHFH" name="CJAGHHFH"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">How to Use Static Weaving with the weave Ant Task</h3>
| |
| − | <p>When using a one-to-one (see Section 9.1.23 "OneToOne Annotation" of the JPA specification) or many-to-one (see Section 9.1.22 "ManyToOne Annotation" of the JPA specification) mapping in a Java SE environment that does not permit the use of <code>-javaagent</code> on the JVM command line, to configure TopLink JPA to perform lazy loading when annotation attribute <code>fetch</code> is set to <code>javax.persistence.FetchType.LAZY</code>, you can use the TopLink JPA <code>weave</code> Ant task.</p>
| |
| − |
| |
| − | <p>Use this option to weave all applicable class files at build time so that you can deliver prewoven class files. By doing so, you can improve the deployment performance.</p>
| |
| − | <p>To use the TopLink JPA <code>weave</code> Ant task, do the following:</p>
| |
| − | <ol type="1" start="1">
| |
| − | <li>
| |
| − | <p>Configure the <code>weave</code> Ant task in your build script as <a href="#CJABDJCB">Example 1-34</a> shows. <a href="#CJAFDEHH">Table 1-27</a> lists the attributes of this task.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJABDJCB" name="CJABDJCB"></a>
| |
| − | <p class="titleinexample">Example 1-34 TopLink weave Ant Task</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <target name="define.task" description="New task definition for toplink static weaving"/>
| |
| − | <taskdef name="weave" classname="oracle.toplink.weaving.StaticWeaveAntTask"/>
| |
| − | </target>
| |
| − | <target name="weaving" description="perform weaving" depends="define.task">
| |
| − | <weave source="c:\foo.jar"
| |
| − | target="c:\wovenfoo.jar"
| |
| − | persistenceinfo="c:\foo-containing-persistenceinfo.jar">
| |
| − | <classpath>
| |
| − |
| |
| − | <pathelement path="c:\foo-dependent.jar"/>
| |
| − | </classpath>
| |
| − | </weave>
| |
| − | </target>
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <div class="tblruleformalwidemax"><a id="sthref30" name="sthref30"></a><a id="CJAFDEHH" name="CJAFDEHH"></a>
| |
| − | <p class="titleintable">Table 1-27 TopLink weave Ant Task Attributes</p>
| |
| − | <table class="RuleFormalWideMax" title="TopLink weave Ant Task Attributes" summary="This table lists the attributes of the TopLink JPA weave Ant task." dir="ltr" border="1" width="100%" frame="border" rules="all" cellpadding="3" cellspacing="0">
| |
| − |
| |
| − | <thead>
| |
| − | <tr align="left" valign="top">
| |
| − | <th align="left" valign="bottom" id="r1c1-t40">Attribute</th>
| |
| − | <th align="left" valign="bottom" id="r1c2-t40">Description</th>
| |
| − | <th align="left" valign="bottom" id="r1c3-t40">Default</th>
| |
| − | <th align="left" valign="bottom" id="r1c4-t40">Required or Optional</th>
| |
| − | </tr>
| |
| − | </thead>
| |
| − | <tbody>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r2c1-t40" headers="r1c1-t40">
| |
| − | <p><code>source</code></p>
| |
| − |
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t40 r1c2-t40">
| |
| − | <p>Specifies the location of the Java source files to weave: either a directory or a JAR file.</p>
| |
| − | <p>If the <code>persistence.xml</code> file is not in this location, you must specify the location of the <code>persistence.xml</code> using the <code>persistenceinfo</code> attribute.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r2c1-t40 r1c3-t40"><br /></td>
| |
| − |
| |
| − | <td align="left" headers="r2c1-t40 r1c4-t40">
| |
| − | <p>Required</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r3c1-t40" headers="r1c1-t40">
| |
| − | <p><code>target</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t40 r1c2-t40">
| |
| − | <p>Specifies the output location: either a directory or a JAR file.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r3c1-t40 r1c3-t40"><br /></td>
| |
| − | <td align="left" headers="r3c1-t40 r1c4-t40">
| |
| − | <p>Required</p>
| |
| − |
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r4c1-t40" headers="r1c1-t40">
| |
| − | <p><code>persistenceinfo</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t40 r1c2-t40">
| |
| − | <p>Specifies the location of the <code>persistence.xml</code> file if it is not in the same location as the source.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r4c1-t40 r1c3-t40"><br /></td>
| |
| − | <td align="left" headers="r4c1-t40 r1c4-t40">
| |
| − | <p>Optional</p>
| |
| − |
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r5c1-t40" headers="r1c1-t40">
| |
| − | <p><code>log</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t40 r1c2-t40">
| |
| − | <p>Specifies a logging file.</p>
| |
| − | </td>
| |
| − | <td align="left" headers="r5c1-t40 r1c3-t40">
| |
| − | <p>See "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/sesun.htm#i1122078">Logging</a>"</p>
| |
| − | </td>
| |
| − |
| |
| − | <td align="left" headers="r5c1-t40 r1c4-t40">
| |
| − | <p>Optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − | <tr align="left" valign="top">
| |
| − | <td align="left" id="r6c1-t40" headers="r1c1-t40">
| |
| − | <p><code>loglevel</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t40 r1c2-t40">
| |
| − | <p>Specifies the amount and detail of log output.</p>
| |
| − | <p>Valid <code>java.util.logging.Level</code> values are:</p>
| |
| − |
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p><code>OFF</code>–disables logging.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>SEVERE</code>–logs exceptions indicating TopLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>WARNING</code>–logs exceptions that do not force TopLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − |
| |
| − | <p><code>INFO</code>–logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>CONFIG</code>–logs only login, JDBC connection, and database information.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FINE</code>–logs SQL.</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FINER</code>–similar to warning. Includes stack trace.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p><code>FINEST</code>–includes additional low level information.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t40 r1c3-t40">
| |
| − | <p><code>Level.OFF</code></p>
| |
| − | </td>
| |
| − | <td align="left" headers="r6c1-t40 r1c4-t40">
| |
| − | <p>Optional</p>
| |
| − | </td>
| |
| − | </tr>
| |
| − |
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="tblruleformalwidemax" -->
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | If <code>source</code> and <code>target</code> point to the same location and if the <code>source</code> is a directory (not a JAR file), TopLink JPA will weave in place. If <code>source</code> and <code>target</code> point to different locations or if the <code>source</code> is a JAR file (as <a href="#CJABDJCB">Example 1-34</a> shows), TopLink JPA cannot weave in place.</td>
| |
| − |
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>Configure the <code>weave</code> task with an appropriate <code><classpath></code> element, as <a href="#CJABDJCB">Example 1-34</a> shows, so that TopLink JPA can load all required source classes.</p>
| |
| − |
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>Execute the Ant task using the command line that <a href="#CJABGHGH">Example 1-35</a> shows.</p>
| |
| − | <p>In this example, the <code>weave</code> Ant task is in the <code>build.xml</code> file.</p>
| |
| − | <div class="example"><a id="CJABGHGH" name="CJABGHGH"></a>
| |
| − | <p class="titleinexample">Example 1-35 TopLink JPA weave Ant Task Command Line</p>
| |
| − |
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | ant -lib C:\toplink.jar -f build.xml weave
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | You must specify the <code>toplink.jar</code> file (the JAR that contains the TopLink JPA <code>weave</code> Ant task) using the Ant command line <code>-lib</code> option instead of using the <code>taskdef</code> attribute <code>classpath</code>.</td>
| |
| − |
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | </li>
| |
| − | </ol>
| |
| − | </div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="CACDIDAH" name="CACDIDAH"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">What You May Need to Know About Weaving</h3>
| |
| − | <p>Weaving is a technique of manipulating the byte-code of compiled Java classes.</p>
| |
| − | <p>TopLink persistence provider uses weaving for lazy loading (value holder indirection) For more information, see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/mapun.htm#CEGHBHEA">Value Holder Indirection</a>".</p>
| |
| − |
| |
| − | </div>
| |
| − | <!-- class="sect2" --></div>
| |
| − | <!-- class="sect1" -->
| |
| − | <a id="CJAFAHEJ" name="CJAFAHEJ"></a>
| |
| − | <div class="sect1"><!-- infolevel="all" infotype="General" -->
| |
| − | <h2 class="sect1">What You May Need to Know About Overriding Annotations</h2>
| |
| − | <p>In JPA, you override any annotation with XML in your object-relational mapping files (see <a href="#CJAJADEB">"Overriding Annotations with XML in JPA"</a>).</p>
| |
| − | <p>In TopLink JPA, you can override any attribute of a TopLink-extended annotation in a TopLink <code>project.xml</code> file. This overriding mechanism is similar to the JPA's one with the exception that TopLink annotations correspond to a subset of the <code>project.xml</code> file's elements instead of all elements. Also, in addition annotations extensions, TopLink JPA allows you to use persistence unit properties that you specify in the <code>persistence.xml</code> file. In some cases, a persistence unit property, if specified, overrides a corresponding TopLink JPA annotation attribute (see <a href="#CJABFEFC">"Overriding Annotations in TopLink JPA"</a>).</p>
| |
| − |
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | By design, TopLink JPA annotations and persistence unit properties are not analogous to the JPA annotations and elements of mapping XML files.</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <a id="CJAJADEB" name="CJAJADEB"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − |
| |
| − | <h3 class="sect2">Overriding Annotations with XML in JPA</h3>
| |
| − | <p>In JPA, you can use XML mapping metadata on its own, or in combination with annotation metadata, or you can use it to override the annotation metadata.</p>
| |
| − | <p>If you choose to include one or more mapping XML files in your persistence unit, each file must conform and be valid against the <code>orm_1_0.xsd</code> schema located at <code><a href="http://java.sun.com/xml/ns/persistence/orm_1_0.xsd">http://java.sun.com/xml/ns/persistence/orm_1_0.xsd</a></code>. This schema defines a namespace called <code>http://java.sun.com/xml/ns/persistence/orm</code> that includes all of the ORM elements that you can use in your mapping file.</p>
| |
| − | <p>All object-relational XML metadata is contained within the <code>entity-mappings</code> root element of the mapping file. The subelements of <code>entity-mappings</code> can be categorized into four main scoping and functional groups: persistence unit defaults, mapping file defaults, queries and generators, and managed classes and mappings. There is also a special setting that determines whether annotations should be considered in the metadata for the persistence unit (see <a href="#CJACJBHD">"Disabling Annotations"</a>).</p>
| |
| − |
| |
| − | <p>For more information and examples, see Section 10.1 "XML Overriding Rules" of the JPA specification.</p>
| |
| − | <a id="CJACJBHD" name="CJACJBHD"></a>
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" -->
| |
| − | <h4 class="sect3">Disabling Annotations</h4>
| |
| − | <p>JPA provides a mechanism that you can use to disable annotaions. If you do not feel the need for annotations in your application, you can use the <code>xml-mapping-metadata-complete</code> and <code>metadata-complete</code> mapping file elements to disable any existing annotations. Setting this options causes the processor to completely ignore annotations.</p>
| |
| − | <p>When you specify the <code>xml-mapping-metadata-complete</code> element, all annotations in the persistence unit will be ignored, and only mapping files in the persistence unit will be considered as the total set of provided metadata. Only entities (see Section 8.1 "Entity" of the JPA specification), mapped superclasses (see Section 9.1.36 "MappedSuperclass Annotation" of the JPA specification), and embedded objects (see Section 9.1.35 "Embedded Annotation" of the JPA specification) that have entries in a mapping file will be added to the persistence unit. The <code>xml-mapping-metadata-complete</code> element has to be in only one of the mapping files in the persistence unit. You specify it as an empty subelement of the <code>persistence-unit-metadata</code> element, as <a href="#CJABABHJ">Example 1-36</a> shows.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJABABHJ" name="CJABABHJ"></a>
| |
| − | <p class="titleinexample">Example 1-36 Disabling Annotations for the Persistence Unit in the Mapping File</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | <entity-mappings>
| |
| − | <persistence-unit-metadata>
| |
| − | <xml-mapping-metadata-complete/>
| |
| − | </persistence-unit-metadata>
| |
| − | ...
| |
| − |
| |
| − | </entity-mappings>
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p>You can also use the <code>metadata-complete</code> attribute of the <code>entity</code>, <code>mapped-superclass</code>, and <code>embeddable</code> elements. If you specify this attribute, all annotations on the specified class and on any fields or properties in the class will be ignored–only metadata in the mapping file will be considered as the set of metadata for the class. <a href="#CJAEAEJH">Example 1-37</a> shows how to use the <code>metadata-complete</code> attribute.</p>
| |
| − |
| |
| − | <div class="example"><a id="CJAEAEJH" name="CJAEAEJH"></a>
| |
| − | <p class="titleinexample">Example 1-37 Disabling Annotations for a Managed Class in the Mapping File</p>
| |
| − | <pre xml:space="preserve" class="oac_no_warn">
| |
| − | @Entity
| |
| − | public class Employee {
| |
| − |
| |
| − | @Id
| |
| − | private int id;
| |
| − |
| |
| − | @Column(name="EMP_NAME")
| |
| − | private String name;
| |
| − |
| |
| − | @Column(name="SALARY")
| |
| − | private long salary;
| |
| − |
| |
| − | ...
| |
| − | }
| |
| − |
| |
| − | <entity-mappings>
| |
| − | ...
| |
| − | <entity class="mypackage.Employee" <span class="bold">metadata-complete="true"</span>>
| |
| − | <attributes>
| |
| − | <id name="id"/>
| |
| − |
| |
| − | </attributes>
| |
| − | </entity>
| |
| − | ...
| |
| − | </entity-mappings>
| |
| − | </pre></div>
| |
| − | <!-- class="example" -->
| |
| − | <p>In the preceding example, the entity mappings in the annotated class are disabled by the <code>metadata-complete</code> attribute, and because the fields are not mapped in the mapping file, the default mapping values will be used. The <code>name</code> and <code>salary</code> fields will be mapped to the <code>NAME</code> and <code>SALARY</code> columns, respectively.</p>
| |
| − |
| |
| − | <p>For more information, see Section 10.1 "XML Overriding Rules" of the JPA specification.</p>
| |
| − | </div>
| |
| − | <!-- class="sect3" -->
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref31" name="sthref31"></a>
| |
| − | <h4 class="sect3">Advantages and Disadvantages of Using Annotations</h4>
| |
| − | <p>Metadata annotations are relatively simple to use and understand. They provide in-line metadata located with the code that this metadata is describing–you do not need to replicate the source code context of where the metadata applies.</p>
| |
| − | <p>On the other hand, annotations unnecessarily couple the metadata to the code. Thus, changes to metadata require changing the source code.</p>
| |
| − | </div>
| |
| − | <!-- class="sect3" -->
| |
| − | <div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref32" name="sthref32"></a>
| |
| − | <h4 class="sect3">Advantages and Disadvantages of Using XML</h4>
| |
| − |
| |
| − | <p>The following are the advantages of using XML:</p>
| |
| − | <ul>
| |
| − | <li type="disc">
| |
| − | <p>no coupling between the metadata and the source code;</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>compliance with the existing, pre-EJB 3.0 development process;</p>
| |
| − | </li>
| |
| − | <li type="disc">
| |
| − | <p>support in IDEs and source control systems.</p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>The main disadvantages of mapping with XML are the complexity and the need for replication of the code context.</p>
| |
| − |
| |
| − | </div>
| |
| − | <!-- class="sect3" --></div>
| |
| − | <!-- class="sect2" -->
| |
| − | <a id="CJABFEFC" name="CJABFEFC"></a>
| |
| − | <div class="sect2"><!-- infolevel="all" infotype="General" -->
| |
| − | <h3 class="sect2">Overriding Annotations in TopLink JPA</h3>
| |
| − | <p>TopLink JPA provides a set of persistence unit properties that you can specify in your <code>persistence.xml</code> file, or in a property map file. The persistence unit properties always override the corresponding annotations' attributes.</p>
| |
| − | <p>Similar to TopLink annotations, properties expose some features of TopLink that are currently not available through the use of JPA metadata.</p>
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − |
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | If multiple instances of the same property are set, then TopLink will use the values from the last entry in the list.</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | <br /></div>
| |
| − | <!-- class="inftblnote" --></div>
| |
| − | <p>You can also specify the persistence information in the TopLink session configuration file–<code>sessions.xml</code> (see "<a href="http://download.oracle.com/docs/cd/B32110_01/web.1013/b28218/sesun.htm#CACIGEBC">Session Configuration and the sessions.xml File</a>"). By setting the <a href="#CJACBJGJ">toplink.session-xml</a> persistence unit property you enable TopLink to override all class annotations and object-relational mappings that you defined in the <code>persistence.xml</code> file, as well as mapping files (if present). Through the <code>sessions.xml</code> file the <code>toplink.session-xml</code> property lets provide session-level configurations that are not supported by persistence unit properties (for example, cache coordination).</p>
| |
| − |
| |
| − | <div align="center">
| |
| − | <div class="inftblnote"><br />
| |
| − | <table class="Note oac_no_warn" summary="This is a layout table to format a note" title="This is a layout table to format a note" dir="ltr" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
| |
| − | <tbody>
| |
| − | <tr>
| |
| − | <td align="left">
| |
| − | <p class="notep1">Note:</p>
| |
| − | You can use tthe <code>toplink.session-xml</code> property as an alternative to annotations and deployment XML.</td>
| |
| − | </tr>
| |
| − | </tbody>
| |
| − | </table>
| |
| − | </div>
| |
| − |
| |
| − | </body>
| |
| − | </html>
| |
