You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by kw...@apache.org on 2014/05/15 00:22:26 UTC
svn commit: r908837 [21/37] -
/websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_caching.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_caching.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_caching.html Wed May 14 22:22:23 2014
@@ -0,0 +1,1062 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Chapter 10. Caching</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ref_guide_enterprise_abstractstore.html" title="8. Non-Relational Stores"><link rel="next" href="ref_guide_cache_querycomp.html" title="2. Query Compilation Cache"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10.
+ Caching
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_enterprise_abstractstore.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_cache_querycomp.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 10. Caching" id="ref_guide_caching"><div class="titlepage"><div><div><h2 class="title">Chapter 10.
+ Caching
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache">1.
+ Data Cache
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_conf">1.1.
+ Data Cache Configuration
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_data_cache">1.1.1.
+ openjpa.DataCache Configuration
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_shared_cache_mode_integration">1.1.2.
+ Integration with JPA standard shared cache mode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_distribution">1.1.3. Distributing instances across cache partitions</a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_use">1.2.
+ Data Cache Usage
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_use_JPA">1.2.1. Using the JPA standard Cache interface</a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_use_openJPA">1.2.2. Using the OpenJPA StoreCache extensions</a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_statistics">1.3.
+ Cache Statistics
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_query">1.4.
+ Query Cache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_extension">1.5.
+ Cache Extension
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_notes">1.6.
+ Important Notes
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#datastore_cache_issues">1.7.
+ Known Issues and Limitations
+ </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_cache_querycomp.html">2.
+ Query Compilation Cache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_cache_querysql.html">3. Prepared SQL Cache</a></span></dt></dl></div>
+
+ <p>
+OpenJPA utilizes several configurable caches to maximize performance. This
+chapter explores OpenJPA's data cache, query cache, and query compilation cache.
+ </p>
+ <div class="section" title="1. Data Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_cache">1.
+ Data Cache
+ </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_conf">1.1.
+ Data Cache Configuration
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_data_cache">1.1.1.
+ openjpa.DataCache Configuration
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_shared_cache_mode_integration">1.1.2.
+ Integration with JPA standard shared cache mode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_distribution">1.1.3. Distributing instances across cache partitions</a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_use">1.2.
+ Data Cache Usage
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_use_JPA">1.2.1. Using the JPA standard Cache interface</a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_use_openJPA">1.2.2. Using the OpenJPA StoreCache extensions</a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_statistics">1.3.
+ Cache Statistics
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_query">1.4.
+ Query Cache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_extension">1.5.
+ Cache Extension
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_notes">1.6.
+ Important Notes
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#datastore_cache_issues">1.7.
+ Known Issues and Limitations
+ </a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e15883"></a>
+ <p>
+The OpenJPA data cache is an optional cache of persistent object data that
+operates at the <code class="classname">EntityManagerFactory</code> level. This cache is
+designed to significantly increase performance while remaining in full
+compliance with the JPA standard. This means that turning on the caching option
+can transparently increase the performance of your application, with no changes
+to your code.
+ </p>
+ <p>
+OpenJPA's data cache is not related to the <code class="classname">EntityManager</code>
+cache dictated by the JPA specification. The JPA specification mandates behavior
+for the <code class="classname">EntityManager</code> cache aimed at guaranteeing
+transaction isolation when operating on persistent objects.
+ </p>
+ <p>
+OpenJPA's data cache is designed to provide significant performance increases
+over cacheless operation, while guaranteeing that behavior will be identical in
+both cache-enabled and cacheless operation.
+ </p>
+ <p>
+There are five ways to access data via the OpenJPA APIs: standard relation
+traversal, large result set relation traversal, queries, looking up an object by
+id, and iteration over an <code class="classname">Extent</code>. OpenJPA's cache plugin
+accelerates three of these mechanisms. It does not provide any caching of large
+result set relations or <code class="classname">Extent</code> iterators. If you find
+yourself in need of higher-performance <code class="classname">Extent</code> iteration,
+see <a class="xref" href="ref_guide_caching.html#ref_guide_cache_limits_extent" title="Example 10.25. Query Replaces Extent">Example 10.25, “
+ Query Replaces Extent
+ ”</a>.
+ </p>
+ <div class="table"><a name="d5e15897"></a><p class="title"><b>Table 10.1.
+ Data access methods
+ </b></p><div class="table-contents">
+
+ <table summary="
 Data access methods
 " border="1"><colgroup><col align="left" class="access-method"><col align="left" class="cacheable"></colgroup><thead><tr><th align="left">Access method</th><th align="left">Uses cache</th></tr></thead><tbody><tr><td align="left">
+ Standard relation traversal
+ </td><td align="left">
+ Yes
+ </td></tr><tr><td align="left">
+ Large result set relation traversal
+ </td><td align="left">No</td></tr><tr><td align="left">Query</td><td align="left">Yes</td></tr><tr><td align="left">
+ Lookups by object id
+ </td><td align="left">Yes</td></tr><tr><td align="left">
+ Iteration over an <code class="classname">Extent</code>
+ </td><td align="left">No</td></tr></tbody></table>
+ </div></div><br class="table-break">
+ <p>
+When enabled, the cache is checked before making a trip to the datastore. Data
+is stored in the cache when objects are committed and when persistent objects
+are loaded from the datastore.
+ </p>
+ <p>
+OpenJPA's data cache can operate in both single-JVM and multi-JVM environments.
+Multi-JVM caching is achieved through the use of the distributed event
+notification framework described in <a class="xref" href="ref_guide_event.html" title="2. Remote Event Notification Framework">Section 2, “
+ Remote Event Notification Framework
+ ”</a>, or
+through custom integrations with a third-party distributed cache.
+ </p>
+ <p>
+The single JVM mode of operation maintains and shares a data cache across all
+<code class="classname">EntityManager</code> instances obtained from a particular
+<code class="classname">EntityManagerFactory</code>. This is not appropriate for use in
+a distributed environment, as caches in different JVMs or created from different
+<code class="classname">EntityManagerFactory</code> objects will not be synchronized.
+ </p>
+ <div class="section" title="1.1. Data Cache Configuration"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_cache_conf">1.1.
+ Data Cache Configuration
+ </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_data_cache">1.1.1.
+ openjpa.DataCache Configuration
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_shared_cache_mode_integration">1.1.2.
+ Integration with JPA standard shared cache mode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_distribution">1.1.3. Distributing instances across cache partitions</a></span></dt></dl></div>
+
+ <p>
+There are two ways to enable the basic single-factory cache. One is using
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.DataCache" title="5.26. openjpa.DataCache"><code class="literal">openjpa.DataCache</code></a>
+property, the other is using JPA standard shared-cache-mode element or the
+javax.persistence.sharedCache.mode property.
+ </p>
+ <div class="section" title="1.1.1. openjpa.DataCache Configuration"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_data_cache">1.1.1.
+ openjpa.DataCache Configuration
+ </h4></div></div></div>
+
+ <p>
+To enable the basic single-factory cache set the
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.DataCache" title="5.26. openjpa.DataCache"><code class="literal">openjpa.DataCache</code></a>
+property to <code class="literal">true</code>:
+ </p>
+ <div class="example"><a name="ref_guide_cache_conf_sjvm"></a><p class="title"><b>Example 10.1.
+ Single-JVM Data Cache
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.DataCache" value="true"/>
+</pre>
+ </div></div><br class="example-break">
+ <p>
+To configure the data cache to remain up-to-date in a distributed environment,
+set the <a class="link" href="ref_guide_conf_openjpa.html#openjpa.RemoteCommitProvider" title="5.61. openjpa.RemoteCommitProvider"><code class="literal">
+openjpa.RemoteCommitProvider</code></a> property appropriately, or
+integrate OpenJPA with a third-party caching solution. Remote commit providers
+are described in <a class="xref" href="ref_guide_event.html" title="2. Remote Event Notification Framework">Section 2, “
+ Remote Event Notification Framework
+ ”</a>.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e15949"></a>
+OpenJPA's default implementation maintains a map of object
+ids to cache data. By default, 1000 elements are kept in cache. When the cache
+overflows, random entries are evicted. The maximum cache size can be
+adjusted by setting the <code class="literal">CacheSize</code> property in your plugin
+string - see below for an example. Objects that are pinned into the cache are
+not counted when determining if the cache size exceeds its maximum size.
+ </p>
+ <p>
+Expired objects are moved to a soft reference map, so they may stick around for
+a little while longer. You can control the number of soft references OpenJPA
+keeps with the <code class="literal">SoftReferenceSize</code> property. Soft references
+are unlimited by default. Set to 0 to disable soft references completely.
+ </p>
+ <p>
+Both the QueryCache and DataCache can be configured to use a backing <code class="literal">Lru</code> map rather than the default
+concurrent HashMap. Note that enabling the <code class="literal">Lru</code> cache can hurt performance as this map in not as
+scalable as the default map.
+ </p>
+ <div class="example"><a name="ref_guide_cache_conf_lru"></a><p class="title"><b>Example 10.2.
+ Lru Cache
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.DataCache" value="true(Lru=true)"/>
+<property name="openjpa.QueryCache" value="true(Lru=true)"/>
+</pre>
+ </div></div><br class="example-break">
+ <div class="example"><a name="ref_guide_cache_conf_size"></a><p class="title"><b>Example 10.3.
+ Data Cache Size
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.DataCache" value="true(CacheSize=5000, SoftReferenceSize=0)"/>
+</pre>
+ </div></div><br class="example-break">
+ <p>
+ <a class="indexterm" name="d5e15965"></a>
+You can specify a cache timeout value for a class by setting the timeout
+<a class="link" href="ref_guide_meta_ext.html" title="4. Metadata Extensions">metadata extension</a> to the amount of
+time in milliseconds a class's data is valid. Use a value of -1 for no
+expiration. This is the default value.
+ </p>
+ <div class="example"><a name="ex_timeout_cache"></a><p class="title"><b>Example 10.4.
+ Data Cache Timeout
+ </b></p><div class="example-contents">
+
+ <p>
+Timeout <code class="classname">Employee</code> objects after 10 seconds.
+ </p>
+<pre class="programlisting">
+@Entity
+@DataCache(timeout=10000)
+public class Employee {
+ ...
+}
+</pre>
+ </div></div><br class="example-break">
+
+ <p>
+ <a class="indexterm" name="d5e15975"></a>
+ Entities may be explicitly excluded from the cache by providing a
+ list of fully qualified class names in the <code class="literal">ExcludedTypes</code> argument.
+ The entities provided via <code class="literal">ExcludedTypes</code> will not be cached
+ regardless of the <code class="classname">DataCache</code> annotation.
+ </p>
+ <div class="example"><a name="ex_exclude_types_from_cache"></a><p class="title"><b>Example 10.5.
+ Excluding entities
+ </b></p><div class="example-contents">
+
+ <p>
+ Exclude entities <code class="classname">foo.bar.Person</code> and
+ <code class="classname">foo.bar.Employee</code> from the cache.
+</p><pre class="programlisting">
+<property name="openjpa.DataCache" value="true(ExcludedTypes=foo.bar.Person;foo.bar.Employee)"/>
+</pre><p>
+ </p>
+ </div></div><br class="example-break">
+
+ <p>
+ <a class="indexterm" name="d5e15988"></a>
+ Entities may be explicitly included in the cache by providing a
+ list of fully qualified class names in the <code class="literal">Types</code> argument.
+ Any entities which are not included
+ in this list will not be cached.
+ </p>
+ <div class="example"><a name="ex_include_types_in_cache"></a><p class="title"><b>Example 10.6.
+ Including entities
+ </b></p><div class="example-contents">
+
+ <p>
+ Include only entity <code class="classname">foo.bar.FullTimeEmployee</code> in the cache.
+</p><pre class="programlisting">
+<property name="openjpa.DataCache" value="true(Types=foo.bar.FullTimeEmployee)"/>
+</pre><p>
+ </p>
+ </div></div><br class="example-break">
+ <p>
+See the <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/DataCache.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.DataCache</code></a> Javadoc
+for more information on the <code class="classname">DataCache</code> annotation.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e16002"></a>
+A cache can specify that it should be cleared at certain times rather than using
+data timeouts. The <code class="literal">EvictionSchedule</code> property of OpenJPA's
+cache implementation can be input in two different formats. The first is a <code class="literal">cron</code> style eviction schedule.
+The format of this property is a whitespace-separated list of five tokens, where
+the <code class="literal">*</code> symbol (asterisk), indicates match all. The tokens are,
+in order:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+Minute
+ </p>
+ </li><li class="listitem">
+ <p>
+Hour of Day
+ </p>
+ </li><li class="listitem">
+ <p>
+Day of Month
+ </p>
+ </li><li class="listitem">
+ <p>
+Month
+ </p>
+ </li><li class="listitem">
+ <p>
+Day of Week
+ </p>
+ </li></ul></div>
+ <p>
+For example, the following <code class="literal">openjpa.DataCache</code> setting
+schedules the default cache to evict values from the cache at 15 and 45 minutes
+past 3 PM on Sunday.
+ </p>
+<pre class="programlisting">
+true(EvictionSchedule='15,45 15 * * 1')
+</pre>
+ <p>
+The second format for this property is an interval style eviction schedule. The
+format of this property is a <code class="literal">+</code> followed by the number of minutes
+between each time that the cache should be evicted.
+ </p>
+ <p>
+For example, the following <code class="literal">openjpa.DataCache</code> setting schedules the default cache
+to evict values from the cache every 120 minutes.
+ </p>
+ <p>
+</p><pre class="programlisting">
+true(EvictionSchedule='+120')
+</pre><p>
+ </p>
+ <div class="example"><a name="bulk_update_evict_cache"></a><p class="title"><b>Example 10.7.
+ Bulk updates and cache eviction
+ </b></p><div class="example-contents">
+
+ <p>
+Setting <code class="literal">EvictOnBulkUpdate</code> to <code class="literal">false</code> will tell OpenJPA to not evict from the DataCache when executing
+an UPDATE or DELETE statement. The default for the value is <code class="literal">true</code>.
+ </p>
+ <p>
+</p><pre class="programlisting"><property name="openjpa.DataCache" value="true(EvictOnBulkUpdate=false)"/></pre><p>
+ </p>
+ </div></div><br class="example-break">
+</div>
+<div class="section" title="1.1.2. Integration with JPA standard shared cache mode"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_shared_cache_mode_integration">1.1.2.
+ Integration with JPA standard shared cache mode
+ </h4></div></div></div>
+
+ <p>
+ JPA 2.0 specification introduced the standard data cache configuration through the shared-cache-mode element or javax.persistence.
+sharedCache.mode property.
+ </p>
+ <p>
+ When only the shared cache mode is configured to turn on the caching, the default data cache setting will be used. For example the
+ cache size will be set to default 1000.
+ </p>
+ <p>
+ When the shared cache mode and openjpa.DataCache are both configured, the JPA standard shared cache mode
+ configuration takes the precedence.
+ </p>
+ <p>
+ If the shared cache mode is to turn on the caching, the cache setting configured through openjpa.DataCache
+ , like cacheSize and SoftReferenceSize, will be used to initialize or manage the cache. The Types and ExcludeTypes
+ property in openjpa.DataCache will be ingnored since the shared cache mode in conjunction with the javax.persistence.Cacheable
+ annotation already defines what will be cached.
+ </p>
+ <div class="example"><a name="shared-cache-mode-none"></a><p class="title"><b>Example 10.8. </b></p><div class="example-contents">
+ <p>
+</p><pre class="programlisting">
+<property name="openjpa.DataCache" value="true"/>
+<property name="javax.persistence.sharedCache.mode" value="NONE"/>
+</pre><p>
+ </p>
+ <p>
+ When the shared cache mode is set to NONE, the data cache will be disabled no matter how openjpa.DataCache is configured.
+ </p>
+ </div></div><br class="example-break">
+
+ <div class="example"><a name="shared-cache-mode-all"></a><p class="title"><b>Example 10.9. </b></p><div class="example-contents">
+ <p>
+</p><pre class="programlisting">
+<property name="openjpa.DataCache" value="true(ExcludedTypes=foo.bar.Person;foo.bar.Employee)"/>
+<property name="javax.persistence.sharedCache.mode" value="ALL"/>
+</pre><p>
+ </p>
+ <p>
+ When the shared cache mode is set to ALL, all entities will be cached no matter how openjpa.DataCache is configured.
+ </p>
+ </div></div><br class="example-break">
+
+ <div class="example"><a name="shared-cache-mode-enable-selective"></a><p class="title"><b>Example 10.10. </b></p><div class="example-contents">
+ <p>
+</p><pre class="programlisting">
+<property name="openjpa.DataCache" value="true(ExcludedTypes=foo.bar.Person;foo.bar.Employee)"/>
+<property name="javax.persistence.sharedCache.mode" value="ENABLE_SELECTIVE"/>
+</pre><p>
+ </p>
+ <p>
+ When the shared cache mode set to ENABLE_SELECTIVE, the entities with Cacheable(true) anotation will be cached.
+ ExcludedTypes will be ignored.
+ </p>
+ </div></div><br class="example-break">
+</div>
+<div class="section" title="1.1.3. Distributing instances across cache partitions"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_cache_distribution">1.1.3. Distributing instances across cache partitions</h4></div></div></div>
+
+ <p>
+OpenJPA also supports a partitioned cache configuration where the cached
+instances can be distributed across partitions by an application-defined
+policy. Each partition behaves as a data cache by itself, identified by its name and can
+be configured individually. The distribution policy
+determines the specific partition that stores the state of a managed instance.
+The default distribution policy distributes the instances by their type
+as specified by the <code class="literal">name</code> attribute in <code class="literal">@DataCache</code>
+annotation. Cache distribution policy is a simple interface that can be implemented
+by an application to distribute among the partitions on a per instance basis.
+To enable a partitioned cache set the <code class="literal">openjpa.DataCache</code>
+property to <code class="literal">partitioned</code>, and configure individual partitions
+as follows:
+ </p>
+ <div class="example"><a name="ref_guide_cache_conf_partition"></a><p class="title"><b>Example 10.11.
+ Partitioned Data Cache
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.CacheDistributionPolicy" value="org.acme.foo.DistributionPolicy"/>
+<property name="openjpa.DataCache" value="partitioned(PartitionType=concurrent,partitions=
+ '(name=a,cacheSize=100),(name=b,cacheSize=200)')"/>
+</pre>
+ </div></div><br class="example-break">
+</div>
+ <p>
+The distribution policy is configured by a full-qualified class name that implements
+<code class="literal">org.apache.openjpa.datacahe.CacheDistributionPolicy</code>. The partitions
+are specified as value of the <code class="literal">partitions</code> attribute as a series of
+individually configurable plug-in strings. As the example shows, i) each partition plug-in configuration
+must be enclosed in parentheses, ii) must be separated by comma and iii) the complete
+set be enclosed in single quote. Each individual partition is a Data Cache by itself and
+the class that implements the partition can be configured via <code class="literal">PartitionType</code>
+attribute. The above example configuration will configure a partitioned cache with
+two partitions named <code class="literal">a</code> and <code class="literal">b</code> of cache size 100 and 200,
+respectively. The partitions are of <code class="literal">concurrent</code> type which is a mnemonic or alias
+for <code class="literal">org.apache.openjpa.datacache.ConcurrentDataCache</code>. The <code class="literal">PartitionType</code>
+is defaulted to <code class="literal">concurrent</code> though explicitly mentioned in this example.
+ </p>
+ </div>
+ <div class="section" title="1.2. Data Cache Usage"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_cache_use">1.2.
+ Data Cache Usage
+ </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_use_JPA">1.2.1. Using the JPA standard Cache interface</a></span></dt><dt><span class="section"><a href="ref_guide_caching.html#ref_guide_cache_use_openJPA">1.2.2. Using the OpenJPA StoreCache extensions</a></span></dt></dl></div>
+
+ <p>
+The <code class="literal">org.apache.openjpa.datacache</code> package defines OpenJPA's
+data caching framework. While you may use this framework directly (see its
+<a class="ulink" href="../javadoc/org/apache/openjpa/datacache/package-summary.html" target="_top">
+Javadoc</a> for details), its APIs are meant primarily for service
+providers. In fact, <a class="xref" href="ref_guide_caching.html#ref_guide_cache_extension" title="1.5. Cache Extension">Section 1.5, “
+ Cache Extension
+ ”</a> below has
+tips on how to use this package to extend OpenJPA's caching service yourself.
+ </p>
+ <p>
+Rather than use the low-level <code class="literal">org.apache.openjpa.datacache</code>
+package APIs, JPA users should typically access the data cache through the JPA
+standard <code class="classname">javax.persistence.Cache</code> interface, or OpenJPA's
+high-level
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/StoreCache.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.StoreCache</code></a> facade.
+ </p>
+ <p>
+Both interfaces provide methods to evict data from the cache and detect whether
+an entity is in the cache. The OpenJPA facade adds methods to pin and unpin
+records, additional methods to evict data, and provides basic statistics of
+number of read or write requests and hit ratio of the cache.
+ </p>
+<div class="section" title="1.2.1. Using the JPA standard Cache interface"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_cache_use_JPA">1.2.1. Using the JPA standard Cache interface</h4></div></div></div>
+
+ You may obtain the <code class="classname">javax.persistence.Cache</code> through
+ the EntityManagerFactory.getCache() method.
+ <div class="example"><a name="ref_guide_cache_access_jpa_standard"></a><p class="title"><b>Example 10.12.
+ Accessing the Cache
+ </b></p><div class="example-contents">
+
+ <pre class="programlisting">
+import javax.persistence.Cache;
+import javax.persistence.EntityManagerFactory;
+import javax.persistence.Persistence;
+. . .
+EntityManagerFactory emf =
+ Persistence.createEntityManagerFactory("myPersistenceUnit");
+Cache cache = emf.getCache();
+. . .
+ </pre>
+ </div></div><br class="example-break">
+
+ <div class="example"><a name="ref_guide_cache_use_jpa_standard"></a><p class="title"><b>Example 10.13. Using the javax.persistence.Cache interface</b></p><div class="example-contents">
+
+ <pre class="programlisting">
+// Check whether the cache contains an entity with a provided ID
+Cache cache = emf.getCache();
+boolean contains = cache.contains(MyEntity.class, entityID);
+
+// evict a specific entity from the cache
+cache.evict(MyEntity.class, entityID);
+
+// evict all instances of an entity class from the cache
+cache.evict(AnotherEntity.class);
+
+// evict everything from the cache
+cache.evictAll();
+ </pre>
+ </div></div><br class="example-break">
+</div>
+<div class="section" title="1.2.2. Using the OpenJPA StoreCache extensions"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_cache_use_openJPA">1.2.2. Using the OpenJPA StoreCache extensions</h4></div></div></div>
+
+ <p>
+You obtain the <code class="classname">StoreCache</code> through the <code class="methodname">
+OpenJPAEntityManagerFactory.getStoreCache</code> method.
+ </p>
+ <div class="example"><a name="ref_guide_cache_access_jpa"></a><p class="title"><b>Example 10.14.
+ Accessing the StoreCache
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+...
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+StoreCache cache = oemf.getStoreCache();
+...
+</pre>
+Alternatively you can just cast the same object returned from
+the EntityManager.getCache() method.
+<pre class="programlisting">
+import org.apache.openjpa.persistence.StoreCache;
+...
+StoreCache cache = (StoreCache) emf.getCache();
+</pre>
+ </div></div><br class="example-break">
+<pre class="programlisting">
+public void evict(Class cls, Object oid);
+public void evictAll();
+public void evictAll(Class cls, Object... oids);
+public void evictAll(Class cls, Collection oids);
+</pre>
+ <p>
+The <code class="methodname">evict</code> methods tell the cache to release data. Each
+method takes an entity class and one or more identity values, and releases the
+cached data for the corresponding persistent instances. The <code class="methodname">
+evictAll</code> method with no arguments clears the cache. Eviction is
+useful when the datastore is changed by a separate process outside OpenJPA's
+control. In this scenario, you typically have to manually evict the data from
+the datastore cache; otherwise the OpenJPA runtime, oblivious to the changes,
+will maintain its stale copy.
+ </p>
+<pre class="programlisting">
+public void pin(Class cls, Object oid);
+public void pinAll(Class cls, Object... oids);
+public void pinAll(Class cls, Collection oids);
+public void unpin(Class cls, Object oid);
+public void unpinAll(Class cls, Object... oids);
+public void unpinAll(Class cls, Collection oids);
+</pre>
+ <p>
+Most caches are of limited size. Pinning an identity to the cache ensures that
+the cache will not kick the data for the corresponding instance out of the
+cache, unless you manually evict it. Note that even after manual eviction, the
+data will get pinned again the next time it is fetched from the store. You can
+only remove a pin and make the data once again available for normal cache
+overflow eviction through the <code class="methodname">unpin</code> methods. Use
+pinning when you want a guarantee that a certain object will always be available
+from cache, rather than requiring a datastore trip.
+ </p>
+
+
+ <div class="example"><a name="ref_guide_cache_use_jpa"></a><p class="title"><b>Example 10.15.
+ StoreCache Usage
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+...
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+StoreCache cache = oemf.getStoreCache();
+cache.pin(Magazine.class, popularMag.getId());
+cache.evict(Magazine.class, changedMag.getId());
+</pre>
+ </div></div><br class="example-break">
+ <p>
+See the <code class="classname">StoreCache</code>
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/StoreCache.html" target="_top">
+Javadoc</a> for information on additional functionality it provides. Also,
+<a class="xref" href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions">Chapter 9, <i>
+ Runtime Extensions
+ </i></a> discusses OpenJPA's other extensions
+to the standard set of JPA runtime interfaces.
+ </p>
+</div>
+ <p>
+The examples above include calls to <code class="methodname">evict</code> to manually
+remove data from the data cache. Rather than evicting objects from the data
+cache directly, you can also configure OpenJPA to automatically evict objects
+from the data cache when you use the <code class="classname">
+OpenJPAEntityManager</code>'s eviction APIs.
+ </p>
+ <div class="example"><a name="ref_guide_cache_pmevict"></a><p class="title"><b>Example 10.16.
+ Automatic Data Cache Eviction
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.BrokerImpl" value="EvictFromDataCache=true"/>
+</pre>
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
+oem.evict(changedMag); // will evict from data cache also
+</pre>
+ </div></div><br class="example-break">
+ </div>
+
+ <div class="section" title="1.3. Cache Statistics"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_cache_statistics">1.3.
+ Cache Statistics
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e16127"></a>
+
+ <p>
+ Number of requests to read and write requests and hit ratio of the
+data cache is available via
+<a class="ulink" href="../javadoc/org/apache/openjpa/datacache/CacheStatistics.html" target="_top">
+<code class="classname">org.apache.openjpa.datacache.CacheStatistics</code></a>
+interface. The collection of cache statistics is disabled by default and needs to be enabled on a per cache basis. By default
+all counts returned from the CacheStatistics interface will return 0.
+ </p><div class="example"><a name="ref_guide_cache_enablestats"></a><p class="title"><b>Example 10.17.
+ Configuring CacheStatistics
+ </b></p><div class="example-contents">
+
+ <pre class="programlisting">
+<property name="openjpa.DataCache" value="true(EnableStatistics=true)"/>
+</pre>
+ </div></div><p><br class="example-break">
+Once cache statistics are enabled you can access them via StoreCache
+</p><pre class="programlisting">
+import org.apache.openjpa.datacache.CacheStatistics;
+...
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+CacheStatistics statistics = oemf.getStoreCache().getCacheStatistics();
+</pre><p>
+The statistics includes number of read and write requests made to the cache
+since start and last reset. The statistics can be obtained also per class basis.
+</p><pre class="programlisting">
+public interface org.apache.openjpa.datacache.CacheStatistics extends java.io.Serializable{
+ // Statistics since last reset
+ public long getReadCount();
+ public long getHitCount();
+ public long getWriteCount();
+
+ // Statistics since start
+ public long getTotalReadCount();
+ public long getTotalHitCount();
+ public long getTotalWriteCount();
+
+ // Per-Class statistics since last reset
+ public long getReadCount(java.lang.Class);
+ public long getHitCount(java.lang.Class);
+ public long getWriteCount(java.lang.Class);
+
+ // Per-Class statistics since start
+ public long getTotalReadCount(java.lang.Class);
+ public long getTotalHitCount(java.lang.Class);
+ public long getTotalWriteCount(java.lang.Class);
+
+ // Starting and last reset time
+ public java.util.Date since();
+ public java.util.Date start();
+
+ // Resets the statistics.
+ public void reset();
+
+ // Returns whether or not statistics will be collected.
+ public boolean isEnabled();
+}
+</pre><p>
+Collecting per-class statistics depends on determining the runtime type of a
+cached data element, when the given context does not permit determination of
+exact runtime type, the statistics is registered against generic
+<code class="classname">java.lang.Object</code>. Also each method that accepts Class
+argument, treats null argument as <code class="classname">java.lang.Object</code>
+</p>
+
+ </div>
+
+ <div class="section" title="1.4. Query Cache"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_cache_query">1.4.
+ Query Cache
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e16142"></a>
+ <a class="indexterm" name="d5e16145"></a>
+ <p>
+In addition to the data cache, the <code class="literal">org.apache.openjpa.datacache
+</code> package defines service provider interfaces for a query cache. The
+query cache is disabled by default and needs to be enabled separately from the data cache.
+The query cache stores the object ids returned by query executions. When you run a query,
+OpenJPA assembles a key based on the query properties and the parameters used at
+execution time, and checks for a cached query result. If one is found, the
+object ids in the cached result are looked up, and the resultant
+persistence-capable objects are returned. Otherwise, the query is executed
+against the database, and the object ids loaded by the query are put into the
+cache. The object id list is not cached until the list returned at query
+execution time is fully traversed.
+ </p>
+ <p>
+OpenJPA exposes a high-level interface to the query cache through the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/QueryResultCache.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.QueryResultCache</code></a>
+class. You can access this class through the <code class="classname">
+OpenJPAEntityManagerFactory</code>.
+ </p>
+ <div class="example"><a name="ref_guide_cache_queryaccess"></a><p class="title"><b>Example 10.18.
+ Accessing the QueryResultCache
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+QueryResultCache qcache = oemf.getQueryResultCache();
+</pre>
+ </div></div><br class="example-break">
+ <p>
+The default query cache implementation caches 100 query executions in a
+least-recently-used cache. This can be changed by setting the cache size in the
+<code class="literal">CacheSize</code> plugin property. Like the data cache, the query
+cache also has a backing soft reference map. The <code class="literal">SoftReferenceSize
+</code> property controls the size of this map. It is disabled by default.
+ </p>
+ <div class="example"><a name="ref_guide_cache_cachesize"></a><p class="title"><b>Example 10.19.
+ Query Cache Size
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.QueryCache" value="true(CacheSize=1000, SoftReferenceSize=100)"/>
+</pre>
+ </div></div><br class="example-break">
+ <p>
+To disable the query cache (default), set the <code class="literal">openjpa.QueryCache
+</code> property to <code class="literal">false</code>:
+ </p>
+ <div class="example"><a name="ref_guide_cache_disablequery"></a><p class="title"><b>Example 10.20.
+ Disabling the Query Cache
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.QueryCache" value="false"/>
+</pre>
+ </div></div><br class="example-break">
+ <p>
+Query Cache's default behaviour on eviction is to evict all the queries from
+the cache if any of the entities that are in the access path of the query are
+modified. Scanning through the whole query cache to evict the queries upon an
+entity update slows down the entity update action.
+
+The configurable eviction policy "timestamp" is to track the timestamp of the
+query and the timestamp of last update for each entity class and compare the
+timestamps when retrieving the query for reuse. If the timestamp of the query
+result is older than the last update time of any entity in the access path of
+the query, the query result would not be reused and the query result would be
+evicted from the query cache.
+To configure the <code class="literal">EvictPolicy</code> to timestamp,
+here is an example:
+ </p>
+ <div class="example"><a name="ref_guide_cache_evictionPolicy"></a><p class="title"><b>Example 10.21.
+ Query Cache Eviction Policy
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.QueryCache" value="true(EvictPolicy='timestamp')"/>
+</pre>
+ </div></div><br class="example-break">
+ <p>
+There are certain situations in which the query cache is bypassed:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+Caching is not used for in-memory queries (queries in which the candidates are a
+collection instead of a class or <code class="classname">Extent</code>).
+ </p>
+ </li><li class="listitem">
+ <p>
+Caching is not used in transactions that have <code class="literal">IgnoreChanges</code>
+set to <code class="literal">false</code> and in which modifications to classes in the
+query's access path have occurred. If none of the classes in the access path
+have been touched, then cached results are still valid and are used.
+ </p>
+ </li><li class="listitem">
+ <p>
+Caching is not used in pessimistic transactions, since OpenJPA must go to the
+database to lock the appropriate rows.
+ </p>
+ </li><li class="listitem">
+ <p>
+Caching is not used when the data cache does not have any cached data for an
+id in a query result.
+ </p>
+ </li><li class="listitem">
+ <p>
+Queries that use persistence-capable objects as parameters are only cached if
+the parameter is directly compared to field, as in:
+ </p>
+<pre class="programlisting">
+select e from Employee e where e.company.address = :addr
+</pre>
+ <p>
+If you extract field values from the parameter in your query string, or if the
+parameter is used in collection element comparisons, the query is not cached.
+ </p>
+ </li><li class="listitem">
+ <p>
+Queries that result in projections of custom field types or <code class="classname">
+BigDecimal</code> or <code class="classname">BigInteger</code> fields are not
+cached.
+ </p>
+ </li></ul></div>
+ <p>
+Cache results are removed from the cache when instances of classes in a cached
+query's access path are touched. That is, if a query accesses data in class
+<code class="classname">A</code>, and instances of class <code class="classname">A</code> are
+modified, deleted, or inserted, then the cached query result is dropped from the
+cache.
+ </p>
+ <p>
+It is possible to tell the query cache that a class has been altered. This is
+only necessary when the changes occur via direct modification of the database
+outside of OpenJPA's control. You can also evict individual queries, or clear
+the entire cache.
+ </p>
+<pre class="programlisting">
+public void evict(Query q);
+public void evictAll(Class cls);
+public void evictAll();
+</pre>
+ <p>
+For JPA queries with parameters, set the desired parameter values into the
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/Query.html" target="_top">
+<code class="classname">Query</code></a> instance before calling the above methods.
+ </p>
+ <div class="example"><a name="ref_guide_cache_query_classchange"></a><p class="title"><b>Example 10.22.
+ Evicting Queries
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+QueryResultCache qcache = oemf.getQueryResultCache();
+
+// evict all queries that can be affected by changes to Magazines
+qcache.evictAll(Magazine.class);
+
+// evict an individual query with parameters
+EntityManager em = emf.createEntityManager();
+Query q = em.createQuery(...).
+ setParameter(0, paramVal0).
+ setParameter(1, paramVal1);
+qcache.evict(q);
+</pre>
+ </div></div><br class="example-break">
+ <p>
+When using one of OpenJPA's distributed cache implementations, it is necessary
+to perform this in every JVM - the change notification is not propagated
+automatically. When using a third-party coherent caching solution,
+it is not necessary to do this in every JVM (although it won't hurt to do so),
+as the cache results are stored directly in the coherent cache.
+ </p>
+ <p>
+Queries can also be pinned and unpinned through the <code class="classname">
+QueryResultCache</code>. The semantics of these operations are the same
+as pinning and unpinning data from the data cache.
+ </p>
+<pre class="programlisting">
+public void pin(Query q);
+public void unpin(Query q);
+</pre>
+ <p>
+For JPA queries with parameters, set the desired parameter values into the
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/Query.html" target="_top">
+<code class="classname">Query</code></a> instance before calling the above methods.
+ </p>
+ <p>
+The following example shows these APIs in action.
+ </p>
+ <div class="example"><a name="ref_guide_cache_query_pin"></a><p class="title"><b>Example 10.23.
+ Pinning, and Unpinning Query Results
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+QueryResultCache qcache = oemf.getQueryResultCache();
+EntityManager em = emf.createEntityManager();
+
+Query pinQuery = em.createQuery(...).
+ setParameter(0, paramVal0).
+ setParameter(1, paramVal1);
+qcache.pin(pinQuery);
+Query unpinQuery = em.createQuery(...).
+ setParameter(0, paramVal0).
+ setParameter(1, paramVal1);
+qcache.unpin(unpinQuery);
+</pre>
+ </div></div><br class="example-break">
+ <p>
+Pinning data into the cache instructs the cache to not expire the pinned results
+when cache flushing occurs. However, pinned results will be removed from the
+cache if an event occurs that invalidates the results.
+ </p>
+ <p>
+You can disable caching on a per-<code class="classname">EntityManager</code> or
+per-<code class="classname">Query</code> basis:
+ </p>
+ <div class="example"><a name="ref_guide_cache_query_disable"></a><p class="title"><b>Example 10.24.
+ Disabling and Enabling Query Caching
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+// temporarily disable query caching for all queries created from em
+OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
+oem.getFetchPlan().setQueryResultCacheEnabled(false);
+
+// re-enable caching for a particular query
+OpenJPAQuery oq = oem.createQuery(...);
+oq.getFetchPlan().setQueryResultCacheEnabled(true);
+</pre>
+ </div></div><br class="example-break">
+ </div>
+ <div class="section" title="1.5. Cache Extension"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_cache_extension">1.5.
+ Cache Extension
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e16226"></a>
+ <a class="indexterm" name="d5e16230"></a>
+ <p>
+The provided data cache classes can be easily extended to add additional
+functionality. If you are adding new behavior, you should extend <code class="classname">
+org.apache.openjpa.datacache.ConcurrentDataCache</code>. To use your own storage
+mechanism, extend <code class="classname">org.apache.openjpa.datacache.AbstractDataCache
+</code> (preferred), or implement <code class="classname">org.apache.openjpa.datacache.DataCache
+</code> directly. If you want to implement a distributed cache that uses an
+unsupported method for communications, create an implementation of <code class="classname">
+org.apache.openjpa.event.RemoteCommitProvider</code>. This process is
+described in greater detail in
+<a class="xref" href="ref_guide_event.html#ref_guide_event_customization" title="2.2. Customization">Section 2.2, “
+ Customization
+ ”</a>.
+ </p>
+ <p>
+The query cache is just as easy to extend. Add functionality by extending the
+default <code class="classname">org.apache.openjpa.datacache.ConcurrentQueryCache</code>.
+Implement your own storage mechanism for query results by extending <code class="classname">
+org.apache.openjpa.datacache.AbstractQueryCache</code> (preferred) or implementing the
+<code class="classname">org.apache.openjpa.datacache.QueryCache</code> interface
+directly.
+ </p>
+ </div>
+ <div class="section" title="1.6. Important Notes"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_cache_notes">1.6.
+ Important Notes
+ </h3></div></div></div>
+
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+The default cache implementations <span class="emphasis"><em>do not</em></span> automatically
+refresh objects in other <code class="classname">EntityManager</code>s when the cache
+is updated or invalidated. This behavior would not be compliant with the JPA
+specification.
+ </p>
+ </li><li class="listitem">
+ <p>
+Invoking <code class="methodname">OpenJPAEntityManager.evict</code><span class="emphasis"><em> does not
+</em></span> result in the corresponding data being dropped from the data cache,
+unless you have set the proper configuration options as explained above (see
+<a class="xref" href="ref_guide_caching.html#ref_guide_cache_pmevict" title="Example 10.16. Automatic Data Cache Eviction">Example 10.16, “
+ Automatic Data Cache Eviction
+ ”</a>). Other methods related to the
+<code class="classname">EntityManager</code> cache also do not affect the data cache.
+ </p>
+ <p>
+The data cache assumes that it is up-to-date with respect to the datastore, so
+it is effectively an in-memory extension of the database. To manipulate the data
+cache, you should generally use the data cache facades presented in this
+chapter.
+ </p>
+ </li></ul></div>
+ </div>
+ <div class="section" title="1.7. Known Issues and Limitations"><div class="titlepage"><div><div><h3 class="title" id="datastore_cache_issues">1.7.
+ Known Issues and Limitations
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e16260"></a>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+When using datastore (pessimistic) transactions in concert with the distributed
+caching implementations, it is possible to read stale data when reading data
+outside a transaction.
+ </p>
+ <p>
+For example, if you have two JVMs (JVM A and JVM B) both communicating with each
+other, and JVM A obtains a data store lock on a particular object's underlying
+data, it is possible for JVM B to load the data from the cache without going to
+the datastore, and therefore load data that should be locked. This will only
+happen if JVM B attempts to read data that is already in its cache during the
+period between when JVM A locked the data and JVM B received and processed the
+invalidation notification.
+ </p>
+ <p>
+This problem is impossible to solve without putting together a two-phase commit
+system for cache notifications, which would add significant overhead to the
+caching implementation. As a result, we recommend that people use optimistic
+locking when using data caching. If you do not, then understand that some of
+your non-transactional data may not be consistent with the datastore.
+ </p>
+ <p>
+Note that when loading objects in a transaction, the appropriate datastore
+transactions will be obtained. So, transactional code will maintain its
+integrity.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">Extent</code>s are not cached. So, if you plan on iterating
+over a list of all the objects in an <code class="classname">Extent</code> on a regular
+basis, you will only benefit from caching if you do so with a <code class="classname">Query
+</code> instead:
+ </p>
+ <div class="example"><a name="ref_guide_cache_limits_extent"></a><p class="title"><b>Example 10.25.
+ Query Replaces Extent
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
+Extent extent = oem.createExtent(Magazine.class, false);
+
+// This iterator does not benefit from caching...
+Iterator uncachedIterator = extent.iterator();
+
+// ... but this one does.
+OpenJPAQuery extentQuery = oem.createQuery(...);
+extentQuery.setSubclasses(false);
+Iterator cachedIterator = extentQuery.getResultList().iterator();
+</pre>
+ </div></div><br class="example-break">
+ </li></ul></div>
+ </div>
+ </div>
+
+
+
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_enterprise_abstractstore.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_cache_querycomp.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.
+ Non-Relational Stores
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2.
+ Query Compilation Cache
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_caching.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_conf.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_conf.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_conf.html Wed May 14 22:22:23 2014
@@ -0,0 +1,215 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Chapter 2. Configuration</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ref_guide_intro.html" title="Chapter 1. Introduction"><link rel="next" href="ref_guide_conf_specify.html" title="2. Runtime Configuration"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2.
+ Configuration
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_intro.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_conf_specify.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 2. Configuration" id="ref_guide_conf"><div class="titlepage"><div><div><h2 class="title">Chapter 2.
+ Configuration
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ref_guide_conf.html#ref_guide_conf_intro">1.
+ Introduction
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_specify.html">2.
+ Runtime Configuration
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_devtools.html">3.
+ Command Line Configuration
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_conf_devtools.html#ref_guide_conf_devtools_format">3.1.
+ Code Formatting
+ </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_conf_plugins.html">4.
+ Plugin Configuration
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html">5.
+ OpenJPA Properties
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.AutoClear">5.1.
+ openjpa.AutoClear
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.AutoDetach">5.2.
+ openjpa.AutoDetach
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.BrokerFactory">5.3.
+ openjpa.BrokerFactory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.BrokerImpl">5.4.
+ openjpa.BrokerImpl
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Callbacks">5.5. openjpa.Callbacks</a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ClassResolver">5.6.
+ openjpa.ClassResolver
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Compatibility">5.7.
+ openjpa.Compatibility
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionDriverName">5.8.
+ openjpa.ConnectionDriverName
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Connection2DriverName">5.9.
+ openjpa.Connection2DriverName
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactory">5.10.
+ openjpa.ConnectionFactory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactory2">5.11.
+ openjpa.ConnectionFactory2
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactoryName">5.12.
+ openjpa.ConnectionFactoryName
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactory2Name">5.13.
+ openjpa.ConnectionFactory2Name
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactoryMode">5.14.
+ openjpa.ConnectionFactoryMode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactoryProperties">5.15.
+ openjpa.ConnectionFactoryProperties
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionFactory2Properties">5.16.
+ openjpa.ConnectionFactory2Properties
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionPassword">5.17.
+ openjpa.ConnectionPassword
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Connection2Password">5.18.
+ openjpa.Connection2Password
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionProperties">5.19.
+ openjpa.ConnectionProperties
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Connection2Properties">5.20.
+ openjpa.Connection2Properties
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionURL">5.21.
+ openjpa.ConnectionURL
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Connection2URL">5.22.
+ openjpa.Connection2URL
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionUserName">5.23.
+ openjpa.ConnectionUserName
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Connection2UserName">5.24.
+ openjpa.Connection2UserName
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ConnectionRetainMode">5.25.
+ openjpa.ConnectionRetainMode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.DataCache">5.26.
+ openjpa.DataCache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.DataCacheManager">5.27.
+ openjpa.DataCacheManager
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.DataCacheMode">5.28.
+ openjpa.DataCacheMode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.DataCacheTimeout">5.29.
+ openjpa.DataCacheTimeout
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.DetachState">5.30.
+ openjpa.DetachState
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.DynamicDataStructs">5.31.
+ openjpa.DynamicDataStructs
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.DynamicEnhancementAgent">5.32. openjpa.DynamicEnhancementAgent</a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.FetchBatchSize">5.33.
+ openjpa.FetchBatchSize
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.EncryptionProvider">5.34.
+ openjpa.EncryptionProvider
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.FetchGroups">5.35.
+ openjpa.FetchGroups
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.FlushBeforeQueries">5.36.
+ openjpa.FlushBeforeQueries
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.IgnoreChanges">5.37.
+ openjpa.IgnoreChanges
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Id">5.38. openjpa.Id</a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.InitializeEagerly">5.39.
+ openjpa.InitializeEagerly
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Instrumentation">5.40.
+ openjpa.Instrumentation
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.InverseManager">5.41.
+ openjpa.InverseManager
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.LockManager">5.42.
+ openjpa.LockManager
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.LockTimeout">5.43.
+ openjpa.LockTimeout
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Log">5.44.
+ openjpa.Log
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ManagedRuntime">5.45.
+ openjpa.ManagedRuntime
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Mapping">5.46.
+ openjpa.Mapping
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.MaxFetchDepth">5.47.
+ openjpa.MaxFetchDepth
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.MetaDataFactory">5.48.
+ openjpa.MetaDataFactory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.MetaDataRepository">5.49.
+ openjpa.MetaDataRepository
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Multithreaded">5.50.
+ openjpa.Multithreaded
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Optimistic">5.51.
+ openjpa.Optimistic
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.OptimizeIdCopy">5.52.
+ openjpa.OptimizeIdCopy
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.OrphanedKeyAction">5.53.
+ openjpa.OrphanedKeyAction
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.NontransactionalRead">5.54.
+ openjpa.NontransactionalRead
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.NontransactionalWrite">5.55.
+ openjpa.NontransactionalWrite
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ProxyManager">5.56.
+ openjpa.ProxyManager
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.PostLoadOnMerge">5.57.
+ openjpa.PostLoadOnMerge
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.QueryCache">5.58.
+ openjpa.QueryCache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.QueryCompilationCache">5.59.
+ openjpa.QueryCompilationCache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.ReadLockLevel">5.60.
+ openjpa.ReadLockLevel
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.RemoteCommitProvider">5.61.
+ openjpa.RemoteCommitProvider
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.RestoreState">5.62.
+ openjpa.RestoreState
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.RetainState">5.63.
+ openjpa.RetainState
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.RetryClassRegistration">5.64.
+ openjpa.RetryClassRegistration
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.RuntimeUnenhancedClasses">5.65. openjpa.RuntimeUnenhancedClasses</a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.SavepointManager">5.66.
+ openjpa.SavepointManager
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Sequence">5.67.
+ openjpa.Sequence
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.Specification">5.68.
+ openjpa.Specification
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.TransactionMode">5.69.
+ openjpa.TransactionMode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_openjpa.html#openjpa.WriteLockLevel">5.70.
+ openjpa.WriteLockLevel
+ </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_conf_jdbc.html">6.
+ OpenJPA JDBC Properties
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.ConnectionDecorators">6.1.
+ openjpa.jdbc.ConnectionDecorators
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.DBDictionary">6.2.
+ openjpa.jdbc.DBDictionary
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.DriverDataSource">6.3.
+ openjpa.jdbc.DriverDataSource
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.EagerFetchMode">6.4.
+ openjpa.jdbc.EagerFetchMode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.FetchDirection">6.5.
+ openjpa.jdbc.FetchDirection
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.JDBCListeners">6.6.
+ openjpa.jdbc.JDBCListeners
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.LRSSize">6.7.
+ openjpa.jdbc.LRSSize
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.MappingDefaults">6.8.
+ openjpa.jdbc.MappingDefaults
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.MappingFactory">6.9.
+ openjpa.jdbc.MappingFactory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.QuerySQLCache">6.10.
+ openjpa.jdbc.QuerySQLCache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.ResultSetType">6.11.
+ openjpa.jdbc.ResultSetType
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.Schema">6.12.
+ openjpa.jdbc.Schema
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.SchemaFactory">6.13.
+ openjpa.jdbc.SchemaFactory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.Schemas">6.14.
+ openjpa.jdbc.Schemas
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.SQLFactory">6.15.
+ openjpa.jdbc.SQLFactory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.SubclassFetchMode">6.16.
+ openjpa.jdbc.SubclassFetchMode
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.SynchronizeMappings">6.17.
+ openjpa.jdbc.SynchronizeMappings
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.TransactionIsolation">6.18.
+ openjpa.jdbc.TransactionIsolation
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#openjpa.jdbc.UpdateManager">6.19.
+ openjpa.jdbc.UpdateManager
+ </a></span></dt><dt><span class="section"><a href="ref_guide_conf_jdbc.html#ref_guide_spec_compatibility">6.20. Compatibility with Specification</a></span></dt></dl></dd></dl></div>
+
+ <a class="indexterm" name="d5e6704"></a>
+ <div class="section" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_conf_intro">1.
+ Introduction
+ </h2></div></div></div>
+
+ <p>
+This chapter describes the OpenJPA configuration framework. It concludes with
+descriptions of all the configuration properties recognized by OpenJPA. You may
+want to browse these properties now, but it is not necessary. Most of them will
+be referenced later in the documentation as we explain the various features they
+apply to.
+ </p>
+ </div>
+
+
+
+
+
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_intro.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_conf_specify.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1.
+ Introduction
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2.
+ Runtime Configuration
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_conf.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_conf_devtools.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_conf_devtools.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_conf_devtools.html Wed May 14 22:22:23 2014
@@ -0,0 +1,127 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>3. Command Line Configuration</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_conf.html" title="Chapter 2. Configuration"><link rel="prev" href="ref_guide_conf_specify.html" title="2. Runtime Configuration"><link rel="next" href="ref_guide_conf_plugins.html" title="4. Plugin Configuration"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.
+ Command Line Configuration
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_conf_specify.html">Prev</a> </td><th width="60%" align="center">Chapter 2.
+ Configuration
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_conf_plugins.html">Next</a></td></tr></table><hr></div><div class="section" title="3. Command Line Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_conf_devtools">3.
+ Command Line Configuration
+ </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_conf_devtools.html#ref_guide_conf_devtools_format">3.1.
+ Code Formatting
+ </a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e6767"></a>
+ <p>
+OpenJPA development tools share the same set of configuration defaults and
+overrides as the runtime system. They also allow you to specify property values
+on the command line:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">-properties/-p <configuration file or resource></code>: Use
+the <code class="literal">-properties</code> flag, or its shorter <code class="literal">-p</code>
+form, to specify a configuration file to use. Note that OpenJPA always searches
+the default file locations described above, so this flag is only needed when you
+do not have a default resource in place, or when you wish to override the
+defaults. The given value can be the path to a file, or the resource name of a
+file somewhere in the <code class="literal">CLASSPATH</code>. OpenJPA will search the
+given location as well as the location prefixed by <code class="filename"> META-INF/
+</code>. Thus, to point an OpenJPA tool at <code class="filename">
+META-INF/my-persistence.xml</code>, you can use:
+ </p>
+<pre class="programlisting">
+<tool> -p my-persistence.xml
+</pre>
+ <p>
+If you want to run a tool against just one particular persistence unit in
+a configuration file, you can do so by specifying an anchor along with the
+resource. If you do not specify an anchor, the tools will run against all
+the persistence units defined within the specified resource, or the default
+resource if none is specified. If the persistence unit is defined within
+the default resource location, then you can just specify the raw anchor itself:
+ </p>
+<pre class="programlisting">
+<tool> -p my-persistence.xml#sales-persistence-unit
+<tool> -p #invoice-persistence-unit
+</pre>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-<property name> <property value></code>: Any
+configuration property that you can specify in a configuration file can be
+overridden with a command line flag. The flag name is always the last token of
+the corresponding property name, with the first letter in either upper or lower
+case. For example, to override the <code class="literal">openjpa.ConnectionUserName</code>
+property, you could pass the <code class="literal">-connectionUserName <value>
+</code> flag to any tool. Values set this way override both the values in the
+configuration file and values set via System properties.
+ </p>
+ </li></ul></div>
+ <div class="section" title="3.1. Code Formatting"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_conf_devtools_format">3.1.
+ Code Formatting
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e6790"></a>
+ <p>
+Some OpenJPA development tools generate Java code. These tools share a common
+set of command-line flags for formatting their output to match your coding
+style. All code formatting flags can begin with either the <code class="literal">codeFormat
+</code> or <code class="literal">cf</code> prefix.
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">-codeFormat./-cf.tabSpaces <spaces></code>: The number of
+spaces that make up a tab, or 0 to use tab characters. Defaults to using tab
+characters.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-codeFormat./-cf.spaceBeforeParen <true/t | false/f></code>:
+Whether or not to place a space before opening parentheses on method calls, if
+statements, loops, etc. Defaults to <code class="literal">false</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-codeFormat./-cf.spaceInParen <true/t | false/f></code>:
+Whether or not to place a space within parentheses; i.e. <code class="literal">method( arg)
+</code>. Defaults to <code class="literal">false</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-codeFormat./-cf.braceOnSameLine <true/t | false/f></code>:
+Whether or not to place opening braces on the same line as the declaration that
+begins the code block, or on the next line. Defaults to <code class="literal">true</code>
+.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-codeFormat./-cf.braceAtSameTabLevel <true/t | false/f></code>
+: When the <code class="literal">braceOnSameLine</code> option is disabled, you can choose
+whether to place the brace at the same tab level of the contained code. Defaults
+to <code class="literal">false</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-codeFormat./-cf.scoreBeforeFieldName <true/t | false/f>
+</code>: Whether to prefix an underscore to names of private member
+variables. Defaults to <code class="literal">false</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-codeFormat./-cf.linesBetweenSections <lines></code>: The
+number of lines to skip between sections of code. Defaults to 1.
+ </p>
+ </li></ul></div>
+ <div class="example"><a name="ref_guide_conf_devtools_format_ex"></a><p class="title"><b>Example 2.1.
+ Code Formatting with the Application Id Tool
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+java org.apache.openjpa.enhance.ApplicationIdTool -cf.spaceBeforeParen true -cf.tabSpaces 4
+</pre>
+ </div></div><br class="example-break">
+ </div>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_conf_specify.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_conf.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_conf_plugins.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.
+ Runtime Configuration
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 4.
+ Plugin Configuration
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_conf_devtools.html
------------------------------------------------------------------------------
svn:mime-type = text/plain