blob: c0c2809dc8f4cf0dfbcb69e9879214e8e3286fee [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>Performance Features | EclipseLink 2.7 Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
<meta name="date" content="2014-06-10T10:35:15Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Performance Features" />
<meta name="relnum" content="Release 2.7" />
<link rel="stylesheet" type="text/css" href="../../dcommon/style.css" media="screen" />
<link rel="copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="start" href="../../index.htm" title="Home" type="text/html" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="prev" href="performance.htm" title="Previous" type="text/html" />
<link rel="next" href="performance002.htm" title="Next" type="text/html" />
<!-- START: Disqus --><script type="text/javascript"> var disqus_developer = 0; </script><!-- END: Disqus --><!-- START: Sharethis --><script type="text/javascript">var switchTo5x=true;</script><script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script><script type="text/javascript" src="http://s.sharethis.com/loader.js"></script> <!-- END: Sharethis --></head>
<body bgcolor="#FFFFFF"><iframe id="docheader" frameborder="0" framemargin="0" scrolling="no" src="../../dcommon/header.html"></iframe><script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> google.load('search', '1', {language : 'en'}); google.setOnLoadCallback(function() { var customSearchOptions = {}; var googleAnalyticsOptions = {}; googleAnalyticsOptions['queryParameter'] = 'q'; googleAnalyticsOptions['categoryParameter'] = ''; customSearchOptions['googleAnalyticsOptions'] = googleAnalyticsOptions; var customSearchControl = new google.search.CustomSearchControl( '016171230611334810008:enkkfjmsqju', customSearchOptions); customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET); var options = new google.search.DrawOptions(); options.setSearchFormRoot('cse-search-form'); customSearchControl.draw('cse', options); }, true);</script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" /><div id="cse" style="width:100%;"></div>
<div class="header"><a id="top" name="top"></a>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><font face="helvetica, arial, sans-serif"><b>EclipseLink Solutions Guide for EclipseLink</b><br />
Release 2.7</div></td>
<td valign="bottom" align="right" width="144">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<tr>
<td align="center"><a href="performance.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="performance002.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
<td>&nbsp;</td>
</tr>
</table>
</div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="CHDIIAFD" name="CHDIIAFD"></a><a id="TLADG414" name="TLADG414"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Performance Features</font></h1>
<p>EclipseLink includes a number of performance features that make it the industry's best performing and most scalable JPA implementation. These features include:</p>
<ul>
<li>
<p><a href="#CHDCGIHF">Object Caching</a></p>
</li>
<li>
<p><a href="#CHDJFFEJ">Querying</a></p>
</li>
<li>
<p><a href="#CHDDGGFI">Mapping</a></p>
</li>
<li>
<p><a href="#CHDBIBAI">Transactions</a></p>
</li>
<li>
<p><a href="#CHDHFDEJ">Database</a></p>
</li>
<li>
<p><a href="#BBAFFHDD">Automated Tuning</a></p>
</li>
<li>
<p><a href="#CHDIICEJ">Tools</a></p>
</li>
</ul>
<a id="CHDCGIHF" name="CHDCGIHF"></a><a id="TLADG415" name="TLADG415"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Object Caching</font></h2>
<p>The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. The cache helps improve performance by holding recently read or written objects and accessing them in-memory to minimize database access.</p>
<p>Caching allows you to:</p>
<ul>
<li>
<p>Set how long the cache lives and the time of day, a process called cache invalidation.</p>
</li>
<li>
<p>Configure cache types (Weak, Soft, SoftCache, HardCache, Full) on a per entity basis.</p>
</li>
<li>
<p>Configure cache size on a per entity basis.</p>
</li>
<li>
<p>Coordinate clustered caches.</p>
</li>
</ul>
<a id="TLADG416" name="TLADG416"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref144" name="sthref144"></a>
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Caching Annotations</font></h3>
<p>EclipseLink defines these entity caching annotations:</p>
<ul>
<li>
<p><code>@Cache</code></p>
</li>
<li>
<p><code>@TimeOfDay</code></p>
</li>
<li>
<p><code>@ExistenceChecking</code></p>
</li>
</ul>
<p>EclipseLink also provides a number of persistence unit properties that you can specify to configure the EclipseLink cache (see "Persistence Property Extensions Reference" in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>). These properties might compliment or provide an alternative to the usage of annotations.</p>
</div>
<!-- class="sect3" -->
<a id="TLADG417" name="TLADG417"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref145" name="sthref145"></a>
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using the @Cache Annotation</font></h3>
<p>EclipseLink uses identity maps to cache objects in order to enhance performance, as well as maintain object identity. You can control the cache and its behavior by using the <code>@Cache</code> annotation in your entity classes. <a href="#CHDBDCBC">Example 18-1</a> shows how to implement this annotation.</p>
<div class="example"><a id="CHDBDCBC" name="CHDBDCBC"></a><a id="TLADG418" name="TLADG418"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 18-1 Using the @Cache Annotation</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
@Entity
@Table(name="EMPLOYEE")
<strong>@Cache (</strong>
<strong>type=CacheType.WEAK,</strong>
<strong>isolated=false,</strong>
<strong>expiry=600000,</strong>
<strong>alwaysRefresh=true,</strong>
<strong>disableHits=true,</strong>
<strong>coordinationType=INVALIDATE_CHANGED_OBJECTS</strong>
<strong>)</strong>
public class Employee implements Serializable {
...
}
</pre></div>
<!-- class="example" -->
<p>For more information about object caching and using the <code>@Cache</code> annotation, see "@Cache" in the <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDJFFEJ" name="CHDJFFEJ"></a><a id="TLADG419" name="TLADG419"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Querying</font></h2>
<p>The scope of a query, the amount of data returned, and how that data is returned can all affect the performance of a EclipseLink-enabled application. EclipseLink query mechanisms enhance query performance by providing these features:</p>
<ul>
<li>
<p><a href="#CHDEHHHD">Read-only Queries</a></p>
</li>
<li>
<p><a href="#CHDEGCHH">Join Fetching</a></p>
</li>
<li>
<p><a href="#CHDFHFEB">Batch Reading</a></p>
</li>
<li>
<p><a href="#CHDDJCAC">Fetch Size</a></p>
</li>
<li>
<p><a href="#CHDIEBJE">Pagination</a></p>
</li>
<li>
<p><a href="#CHDBGFAI">Cache Usage</a></p>
</li>
</ul>
<p>This section describes how these features improve performance.</p>
<a id="CHDEHHHD" name="CHDEHHHD"></a><a id="TLADG420" name="TLADG420"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Read-only Queries</font></h3>
<p>EclipseLink uses the <code>eclipselink.read-only</code> hint, <code>QueryHint</code> (<code>@QueryHint</code>) to retrieve read-only results back from a 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>For more information about read-only queries, see the documentation for the read-only hint in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" -->
<a id="CHDEGCHH" name="CHDEGCHH"></a><a id="TLADG421" name="TLADG421"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Join Fetching</font></h3>
<p>Join Fetching enhances performance by enabling the joining and reading of the related objects in the same query as the source object. Enable Join Fetching by using the <code>@JoinFetch</code> annotation, as shown in <a href="#CHDBICAF">Example 18-2</a>. This example shows how the <code>@JoinFetch</code> annotation specifies the <code>Employee</code> field <code>managedEmployees</code>.</p>
<div class="example"><a id="CHDBICAF" name="CHDBICAF"></a><a id="TLADG422" name="TLADG422"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 18-2 Enabling JoinFetching</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
@Entity
public class Employee implements Serializable {
...
@OneToMany(cascade=ALL, mappedBy="owner")
<strong> @JoinFetch(value=OUTER)</strong>
public Collection&lt;Employee&gt; getManagedEmployees() {
return managedEmployees;
}
...
}
</pre></div>
<!-- class="example" -->
<p>For more details on Join Fetching, see "@JoinFetch" in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" -->
<a id="CHDFHFEB" name="CHDFHFEB"></a><a id="TLADG423" name="TLADG423"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Batch Reading</font></h3>
<p>The <code>eclipselink.batch</code> hint supplies EclipseLink with batching information so subsequent queries of related objects can be optimized in batches instead of being retrieved one-by-one or in one large joined read. Batch reading is more efficient than joining because it avoids reading duplicate data. Batching is only allowed on queries that have a single object in their select clause.</p>
</div>
<!-- class="sect3" -->
<a id="CHDDJCAC" name="CHDDJCAC"></a><a id="TLADG424" name="TLADG424"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Fetch Size</font></h3>
<p>If you have large queries that return a large number of objects you can improve performance by reducing the number database hits required to satisfy the selection criteria. To do this, use the The <code>eclipselink.jdbc.fetch-size</code> hint. This hint specifies the number of rows that should be fetched from the database when more rows are required (depending on the JDBC driver support level). 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>
</div>
<!-- class="sect3" -->
<a id="CHDIEBJE" name="CHDIEBJE"></a><a id="TLADG425" name="TLADG425"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Pagination</font></h3>
<p>Slow paging can result in significant application overhead; however, EclipseLink includes a variety of solutions for improving paging results; for example, you can:</p>
<ul>
<li>
<p>Configure the first and maximum number of rows to retrieve when executing a query.</p>
</li>
<li>
<p>Perform a query on the database for all of the ID values that match the criteria and then use these values to retrieve specific sets.</p>
</li>
<li>
<p>Configure EclipseLink to return a <code>ScrollableCursor</code> object from a query by using query hints. This returns a database cursor on the query's result set and allows the client to scroll through the results page by page.</p>
</li>
</ul>
<p>For details on improving paging performance, see "How to use EclipseLink Pagination" in the EclipseLink online documentation, at:</p>
<p><code><a href="http://wiki.eclipse.org/EclipseLink/Examples/JPA/Pagination#How_to_use_EclipseLink_Pagination">http://wiki.eclipse.org/EclipseLink/Examples/JPA/Pagination#How_to_use_EclipseLink_Pagination</a></code></p>
</div>
<!-- class="sect3" -->
<a id="CHDBGFAI" name="CHDBGFAI"></a><a id="TLADG426" name="TLADG426"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Cache Usage</font></h3>
<p>EclipseLink 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.</p>
<p>You can specify how the query should interact with the EclipseLink cache by using the <code>eclipselink.cache-usage</code> hint. For more information, see "cache usage" in t<em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDDGGFI" name="CHDDGGFI"></a><a id="TLADG427" name="TLADG427"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Mapping</font></h2>
<p>Mapping performance is enhanced by these features:</p>
<ul>
<li>
<p><a href="#CHDDJHCG">Read-Only Objects</a></p>
</li>
<li>
<p><a href="#CHDIJAAH">Weaving</a></p>
</li>
</ul>
<p>This section describes these features.</p>
<a id="CHDDJHCG" name="CHDDJHCG"></a><a id="TLADG429" name="TLADG429"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Read-Only Objects</font></h3>
<p>When you declare a class read-only, clones of that class are neither created nor merged greatly improving performance. You can declare a class as read-only within the context of a unit of work by using the <code>addReadOnlyClass()</code> method.</p>
<ul>
<li>
<p>To configure a read-only class for a single unit of work, specify that class as the argument to <code>addReadOnlyClass()</code>:</p>
<pre xml:space="preserve" class="oac_no_warn">
myUnitofWork.<strong>addReadOnlyClass(B.class)</strong>;
</pre></li>
<li>
<p>To configure multiple classes as read-only, add them to a vector and specify that vector as the argument to <code>addReadOnlyClass()</code>:</p>
<pre xml:space="preserve" class="oac_no_warn">
myUnitOfWork.<strong>addReadOnlyClasses(myVectorOfClasses)</strong>;
</pre></li>
</ul>
<p>For more information about using read-only objects to enhance performance, see "@ReadOnly" in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" -->
<a id="CHDIJAAH" name="CHDIJAAH"></a><a id="TLADG430" name="TLADG430"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Weaving</font></h3>
<p>Weaving is a technique of manipulating the byte-code of compiled Java classes. The EclipseLink JPA persistence provider uses weaving to enhance both JPA entities and Plain Old Java Object (POJO) classes for such things as lazy loading, change tracking, fetch groups, and internal optimizations.Weaving can be performed either dynamically at runtime, when entities are loaded, or statically at compile time by post-processing the entity <code>.class</code> files. By default, EclipseLink uses dynamic weaving whenever possible. This includes inside an Java EE 5/6 application server and in Java SE when the EclipseLink agent is configured. Dynamic weaving is recommended as it is easy to configure and does not require any changes to a project's build process</p>
<p>For details on how to use weaving to enhance application performance, see "weaving" in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CHDBIBAI" name="CHDBIBAI"></a><a id="TLADG431" name="TLADG431"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Transactions</font></h2>
<p>To optimize performance during data transactions, use change tracking,. Change tracking allows you to tune the way EclipseLink detects changes that occur during a transaction. 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>
<p>Enable change tracking by using the <code>@ChangeTracking</code> annotation, as shown in <a href="#CHDJDDFA">Example 18-3</a>.</p>
<div class="example"><a id="CHDJDDFA" name="CHDJDDFA"></a><a id="TLADG432" name="TLADG432"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 18-3 Enabling Change Tracking</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
@Entity
@Table(name="EMPLOYEE")
<strong>@ChangeTracking(OBJECT)</strong> (
public class Employee implements Serializable {
...
}
</pre></div>
<!-- class="example" -->
<p>For more details on change tracking, see "@ChangeTracking" in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect2" -->
<a id="CHDHFDEJ" name="CHDHFDEJ"></a><a id="TLADG433" name="TLADG433"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Database</font></h2>
<p>Database performance features in EclipseLink include:</p>
<ul>
<li>
<p><a href="#CHDJFFHG">Connection Pooling</a></p>
</li>
<li>
<p><a href="#CHDHECDD">Parameterized SQL and Statement Caching</a></p>
</li>
<li>
<p><a href="#CHDHDFAD">Batch Writing</a></p>
</li>
<li>
<p><a href="#BBAJBHBI">Serialized Object Policy</a></p>
</li>
</ul>
<p>This section describes these features.</p>
<a id="CHDJFFHG" name="CHDJFFHG"></a><a id="TLADG434" name="TLADG434"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Connection Pooling</font></h3>
<p>Establishing a connection to a data source can be time-consuming, so reusing such connections in a connection pool can improve performance. EclipseLink uses connection pools to manage and share the connections used by server and client sessions. This feature reduces the number of connections required and allows your application to support many clients.</p>
<p>By default, EclipseLink sessions use internal connection pools. These pools allow you to optimize the creation of read connections for applications that read data only to display it and only infrequently modify data. The also allow you to use Workbench to configure the default (write) and read connection pools and to create additional connection pools for object identity or any other purpose.</p>
<p>In addition to internal connection pools, you can also configure EclipseLink to use any of these types of connection pools:</p>
<ul>
<li>
<p>External connection pools; you must use this type of connection pool to integrate with external transaction controller (JTA).</p>
</li>
<li>
<p>Default (write) and read connection pools;</p>
</li>
</ul>
<ul>
<li>
<p>Sequence connection pools; Use these types of pools when your application requires table sequencing (that is, non-native sequencing) and you are using an external transaction controller. Application-specific connection pools; These are connection pools that you can create and use for any application purpose, provided you are using internal EclipseLink connection pools in a session.</p>
</li>
</ul>
<p>For more information about using connection pools with EclipseLink, see the following topics in <em>EclipseLink Concepts</em>:</p>
<ul>
<li>
<p>"Understanding Connections"</p>
</li>
<li>
<p>"Understanding Connection Pools"</p>
</li>
</ul>
</div>
<!-- class="sect3" -->
<a id="CHDHECDD" name="CHDHECDD"></a><a id="TLADG435" name="TLADG435"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Parameterized SQL and Statement Caching</font></h3>
<p>Parameterized SQL can prevent the overall length of an SQL query from exceeding the statement length limit that your JDBC driver or database server imposes. Using parameterized SQL along with prepared statement caching can improve performance by reducing the number of times the database SQL engine parses and prepares SQL for a frequently called query</p>
<p>By default, EclipseLink enables parameterized SQL but not prepared statement caching. You should enable statement caching either in EclipseLink when using an internal connection pool or in the data source when using an external connection pool and want to specify a statement cache size appropriate for your application.</p>
<p>To enable parameterized SQL, add this line to the <code>persistence.xml</code> file that is in the same path as your domain classes:</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;property name="eclipselink.jdbc.bind-parameters" value="true"/&gt;
</pre>
<p>To disable parameterized SQL, change <code>value=</code> to <code>false</code>.</p>
<p>For more information about using parameterized SQL and statement caching, see "jdbc.bind-parameters" in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" -->
<a id="CHDHDFAD" name="CHDHDFAD"></a><a id="TLADG436" name="TLADG436"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Batch Writing</font></h3>
<p>Heterogeneous batch writing is an optimization that allows EclipseLink to send multiple heterogeneous dynamic SQL statements to the database to be executed as a single batch. Batch writing is best used for applications that perform multiples writes in each transaction.</p>
<p>To configure batch writing, include the <code>eclipselink.jdbc.batch-writing</code> and <code>eclipselink.jdbc.batch-writing.size</code> properties in the <code>persistence.xml</code> file. The following example enables Oracle's native batch writing feature that is available with the Oracle JDBC driver and configures the batch size to 150 statements:</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;property name="eclipselink.jdbc.batch-writing" value="Oracle-JDBC"/&gt;
&lt;property name="eclipselink.jdbc.batch-writing.size" value="150"/&gt;
</pre>
<p>Different batch options are supported and custom batch implementations can also be used. For a detailed reference of the batch writing properties, see the <code>batch-writing</code> and <code>batch-writing.size</code> documentation in <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect3" -->
<a id="BBAJBHBI" name="BBAJBHBI"></a><a id="TLADG1243" name="TLADG1243"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Serialized Object Policy</font></h3>
<p>Serialized object policy is an optimization that allows EclipseLink to write out the whole entity object with its privately owned (and nested privately owned) entities and element collections into an additional field in the database. Serialized object policy optimizes fetching from the database, provides faster database reads, and reduces middle tier CPU and network access in certain situations.</p>
<p>Serialized object policy is best for read-only or read-mostly applications and should only be used for entities that load all their dependent entities or element collections. When using serialized object policy, database write operations (insert and update) are slower and queries for objects without private-owned data are slower. See <a href="#BBAHIFAF">"A Simple Serialized Object Policy Example"</a> that demonstrates when serialized object policy is best used to increase performance.</p>
<p>Consider using serialized object policy only for complex objects with numerous aggregation as characterized by:</p>
<ul>
<li>
<p>Multiple database rows mapped to a single Java object</p>
</li>
<li>
<p>When the object is read from the database all these rows are read at once (no indirection, or all indirection always triggered). There may be un-triggered indirection for other fields that are not included in the serialized object policy field</p>
</li>
<li>
<p>If versionning is used, then updating or deleting any mapped row (or inserting of a new one) should result in incrementing of the object's version</p>
</li>
<li>
<p>Object deletion causes all the rows to be deleted.</p>
</li>
<li>
<p>Irregular structure of the aggregation makes it less possible to use other common optimizations (such as join fetching and batch reading).</p>
</li>
</ul>
<a id="TLADG1253" name="TLADG1253"></a>
<p><b><font face="arial, helvetica, sans-serif" color="#330099">Serialized Object Policy Configuration</font></b></p>
<p>Serialized object policy is enabled by using the <code>@SerializedObject</code> annotation on an entity or mapped superclass and passing in an implementation of the <code>SerializedObjectPolicy</code> interface. You must provide an implementation of this interface; there is no default implementation. The annotations also includes a field to define the column name for the object in the database. The default column name is <code>SOP</code>.</p>
<p><a href="#BBAHGDFA">Example 18-4</a> enables serialized object policy, overrides the default column name, and sets optimistic locking to <code>cascade</code>, which can increase performance by keeping the serialized object policy field in the database up-to-date.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>If serialized object policy is set on an entity, then policies with the same fields are set on all inheriting entities.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<div class="example"><a id="BBAHGDFA" name="BBAHGDFA"></a><a id="TLADG1250" name="TLADG1250"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 18-4 Enabling Serialized Object Policy Using Annotations</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
@Entity
@SerializedObject(MySerializedObjectPolicy.class)
@OptimisticLocking(cascade = true)
public class Employee implements Serializable {
...
@Entity
@SerializedObject(MySerializedObjectPolicy.class, column = @Column(name="ADDR_SOP"))
@OptimisticLocking(cascade = true)
public class Address implements Serializable {
...
</pre></div>
<!-- class="example" -->
<p><a href="#BBABHJJI">Example 18-5</a> enables serialized object policy in the <code>eclipselink-orm.xml</code> file</p>
<div class="example"><a id="BBABHJJI" name="BBABHJJI"></a><a id="TLADG1251" name="TLADG1251"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 18-5 Enabling Serialized Object Policy Using eclipselink-orm.xml</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;entity class="Employee"&gt;
&lt;optimistic-locking cascade="true"&gt;
&lt;serialized-object class="MySerializedObjectPolicy"&gt;
&lt;/entity&gt;
&lt;entity class="Address"&gt;
&lt;optimistic-locking cascade="true"&gt;
&lt;serialized-object class="MySerializedObjectPolicy"&gt;
&lt;column name="ADDR_SOP"/&gt;
&lt;/serialized-object&gt;
&lt;/entity&gt;
</pre></div>
<!-- class="example" -->
<p><a href="#BBAGBGFB">Example 18-6</a> enables serialized object policy in a customizer (either session or descriptor):</p>
<div class="example"><a id="BBAGBGFB" name="BBAGBGFB"></a><a id="TLADG1254" name="TLADG1254"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 18-6 Enabling Serialized Object Policy in a Customizer</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
if (descriptor.hasSerializedObjectPolicy()) {
MySerializedObjectPolicy sop = (MySerializedObjectPolicy)descriptor.
getSerializedObjectPolicy();
// to compare pk cached in SOP Object with pk read directly from the row from
//pk field(s) (false by default):
sop.setShouldVerifyPrimaryKey(true);
// to NOT compare version cached in SOP Object with version read directly from
// the row from version field (true by default):
sop.setShouldVerifyVersion(false);
// to define recoverable SOP (false by default):
sop.setIsRecoverable(true);
}
</pre></div>
<!-- class="example" -->
<p>To use a descriptor customizer, define the class and specify it using the <code>@Customizer</code> annotation:</p>
<pre xml:space="preserve" class="oac_no_warn">
public class MyDescriptorCustomizer implements
org.eclipse.persistence.config.DescriptorCustomizer {
public void customize(ClassDescriptor descriptor) throws Exception
{
...
}
}
...
@Customizer(MyDescriptorCustomizer.class)
public class Employee implements Serializable {...
</pre>
<p>To use a session customizer to reach all descriptors at once, specify it in a persistence unit property:</p>
<pre xml:space="preserve" class="oac_no_warn">
public class MySessionCustomizer implements
org.eclipse.persistence.config.SessionCustomizer {
public void customize(Session session) throws Exception
{
for (ClassDescriptor descriptor : session.getDescriptors().values()) {
...
}
}
}
&lt;property name="eclipselink.session.customizer" value="MySessionCustomizer"/&gt;
</pre>
<p>Read queries (including find and refresh) automatically use a serialized object if serialized object policy is enabled. If the serialized object column contains <code>null</code>, or an obsolete version of the object, then a query using a serialized object policy would either throw an exception or, if all other fields have been read as well, build the object using these fields (exactly as in the case where a serialized object policy is not used).</p>
<p>To disable querying the serialized object, set the <code>SERIALIZED_OBJECT</code> property to <code>false</code> as part of a query hint. For example:</p>
<pre xml:space="preserve" class="oac_no_warn">
Query query = em.createQuery("SELECT e FROM Employee e")
.setHint(QueryHints.SERIALIZED_OBJECT, "false");
</pre>
<p>The following example demonstrates disabling searching for a serialized object:</p>
<pre xml:space="preserve" class="oac_no_warn">
Map hints = new HashMap();
hints.put("eclipselink.serialized-object", "false");
Employee emp = em.find(Employee.class, id, hints);
</pre>
<p>Applications that use serialized object policy should also consider using the result set access optimization. Use the optimization when querying to avoid the costly reading of the serialized object policy field (which can be large) if it is already cached and the query is not a refresh query. The optimization ensures that only the primary key is retrieved from the result set and only gets additional values if the cached object cannot be used. To enable the result set access optimization, set the <code>eclipselink.jdbc.result-set-access-optimization</code> persistent unit property to <code>true</code> in the <code>persistence.xml</code> file. For example:</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;property name="eclipselink.jdbc.result-set-access-optimization" value="true"/&gt;
</pre>
<a id="BBAHIFAF" name="BBAHIFAF"></a><a id="TLADG1252" name="TLADG1252"></a>
<p><b><font face="arial, helvetica, sans-serif" color="#330099">A Simple Serialized Object Policy Example</font></b></p>
<p>Consider the following example object model:</p>
<pre xml:space="preserve" class="oac_no_warn">
@Entity(name="SOP_PartOrWhole")
@Table(name="SOP_PART_OR_WHOLE")
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@Index(columnNames={"LEFTPART_ID", "RIGHTPART_ID"})
public abstract class PartOrWhole implements Serializable {
@Id
@GeneratedValue(strategy=GenerationType.TABLE)
public long id;
protected String description = "";
@OneToOne(cascade=CascadeType.ALL, orphanRemoval=true)
protected Part leftPart;
@OneToOne(cascade=CascadeType.ALL, orphanRemoval=true)
protected Part rightPart;
}
@Entity(name="SOP_Whole")
@DiscriminatorValue("W")
@SerializedObject(MySerializedObjectPolicy.class)
@NamedQueries({
@NamedQuery(name="findWhole", query="Select w from SOP_Whole w where w.id =
:id", hints= @QueryHint(name="eclipselink.serialized-object", value="false")),
@NamedQuery(name="findWholeSOP", query="Select w from SOP_Whole w where w.id =
:id"),
})
public class Whole extends PartOrWhole {
}
@Entity(name="SOP_Part")
@DiscriminatorValue("P")
public class Part extends PartOrWhole {
}
</pre>
<p>The above data model allows the construction of a <code>Whole</code> object with any number of (nested) <code>Part</code> objects. For example:</p>
<ul>
<li>
<p>1 level &ndash; A <code>Whole</code> object contains left and right <code>Part</code> objects (3 objects all together)</p>
</li>
<li>
<p>2 levels &ndash; A <code>Whole</code> object contains left and right <code>Part</code> objects; each of the <code>Part</code> objects has left and right <code>Part</code> objects (7 objects all together)</p>
</li>
<li>
<p>3 levels &ndash; A <code>Whole</code> object contains left and right <code>Part</code> object; each of the <code>Part</code> objects has a left and right <code>Part</code> objects; which each have a left and right <code>Part</code> objects (15 objects all together)</p>
</li>
<li>
<p><em><code>n</code></em> levels &ndash; (2<em><code>n</code></em>+1 - 1 objects all together)</p>
</li>
</ul>
<p>Performance for the above data model increases as the number of levels in the model increases. For example:</p>
<ul>
<li>
<p>1 level &ndash; performance is slower than without serialized object policy.</p>
</li>
<li>
<p>2 levels &ndash; performance is only slightly faster than without serialized object policy.</p>
</li>
<li>
<p>5 levels &ndash; performance is 7 times faster than without serialized object policy.</p>
</li>
<li>
<p>10 levels &ndash; performance is more than 25 times faster than without serialized object policy.</p>
</li>
</ul>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="BBAFFHDD" name="BBAFFHDD"></a><a id="TLADG1244" name="TLADG1244"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Automated Tuning</font></h2>
<p>Automated tuning is an optimization that allows applications to automatically tune JPA and session configuration for a specific purpose. Multiple configuration options can be configured by a single tuner and different configurations can be specified before and after application deployment and after application metadata has been processed but before connecting the session. Automated tuning simplifies configuration and allows a dynamic single tuning option.</p>
<p>Tuners are created by implementing the <code>org.eclipse.persistence.tools.tuning.SessionTuner</code> interface. Two tuner implementations are provided and custom tuners can be created as required:</p>
<ul>
<li>
<p>Standard (<code>StandardTuner</code>) &ndash; The standard tuner is enabled by default and does not change any of the default configuration settings.</p>
</li>
<li>
<p>Safe (<code>SafeModeTuner</code>) &ndash; The safe tuner configures the persistence unit for debugging. It disables caching and several performance optimizations to provide a simplified debugging and development configuration:</p>
<pre xml:space="preserve" class="oac_no_warn">
WEAVING_INTERNAL = false
WEAVING_CHANGE_TRACKING = false
CACHE_SHARED_DEFAULT = false
JDBC_BIND_PARAMETERS = false
ORM_SCHEMA_VALIDATION = true
TEMPORAL_MUTABLE = true
ORDER_UPDATES = true
</pre></li>
</ul>
<p>To enable a tuner, specify a predefined tuner or enter the fully qualified name of a <code>SessionTuner</code> implementation as the value of the <code>eclipselink.tuning</code> property in the <code>persistence.xml</code> file. The following example enables the safe tuner.</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;property name="eclipselink.tuning" value="Safe"/&gt;
</pre>
<p>For a detailed reference of the <code>tuning</code> property, see <em>Java Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect2" -->
<a id="CHDIICEJ" name="CHDIICEJ"></a><a id="TLADG437" name="TLADG437"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Tools</font></h2>
<p>EclipseLink provides monitoring and optimization tools, as described in <a href="performance002.htm#CHDFIECF">Monitoring and Optimizing EclipseLink-Enabled Applications</a>.</p>
</div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="performance.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="performance002.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
</tr>
</table>
</td>
<td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
<font size="-2">Copyright&nbsp;&copy;&nbsp;2014,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</font> <a href="../../dcommon/html/cpyr.htm"><br />
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
<div id="copyright">Copyright &copy; 2014 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-1608008-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
</html>