Author: awhite
Date: Tue Oct 3 16:00:18 2006
New Revision: 452672
URL: http://svn.apache.org/viewvc?view=rev&rev=452672
Log:
Doc corrections.
Modified:
incubator/openjpa/trunk/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
incubator/openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml
Modified:
incubator/openjpa/trunk/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java
URL:
http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java?view=diff&rev=452672&r1=452671&r2=452672
==============================================================================
---
incubator/openjpa/trunk/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java
(original)
+++
incubator/openjpa/trunk/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java
Tue Oct 3 16:00:18 2006
@@ -333,9 +333,9 @@
}
public OpenJPAQuery setHint(String key, Object value) {
- if (key == null || !key.startsWith("org.apache.openjpa."))
+ if (key == null || !key.startsWith("openjpa."))
return this;
- String k = key.substring("org.apache.openjpa.".length());
+ String k = key.substring("openjpa.".length());
try {
if ("Subclasses".equals(k)) {
Modified:
incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml
URL:
http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml?view=diff&rev=452672&r1=452671&r2=452672
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml
(original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_resources.xml
Tue Oct 3 16:00:18 2006
@@ -16,18 +16,13 @@
</listitem>
<listitem>
<para>
-<ulink url="http://java.sun.com/javaee/5/docs/api/index.html";>Locally mirrored
+<ulink url="http://java.sun.com/javaee/5/docs/api/index.html";>
javax.persistence Javadoc</ulink>
</para>
</listitem>
<listitem>
<para>
-<ulink url="../apidocs/index.html">OpenJPA API Javadoc</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
-<ulink url="../apidocs/index.html">Full OpenJPA Javadoc</ulink>
+<ulink url="../apidocs/index.html">OpenJPA Javadoc</ulink>
</para>
</listitem>
<listitem>
Modified:
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
URL:
http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml?view=diff&rev=452672&r1=452671&r2=452672
==============================================================================
---
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
(original)
+++
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
Tue Oct 3 16:00:18 2006
@@ -44,21 +44,54 @@
accelerates three of these mechanisms. It does not provide any caching of large
result set relations or <classname>Extent</classname> iterators. If you find
yourself in need of higher-performance <classname>Extent</classname> iteration,
-see <xref linkend="ref_guide_cache_limits_extent"/>. <table><title>Data
-access methods</title><tgroup cols="2" align="left" colsep="1" rowsep="1">
-<colspec colname="access-method"/><colspec colname="cacheable"/>
-<thead><row><entry colname="access-method">Access method</entry>
-<entry colname="cacheable">Uses cache</entry></row></thead><tbody><row>
-<entry colname="access-method"> Standard relation traversal</entry>
-<entry colname="cacheable">Yes</entry></row><row>
-<entry colname="access-method"> Large result set relation traversal</entry>
-<entry colname="cacheable">No</entry></row><row><entry colname="access-method">
-Query</entry><entry colname="cacheable">Yes</entry></row><row>
-<entry colname="access-method"> Lookups by object id</entry>
-<entry colname="cacheable">Yes</entry></row><row>
-<entry colname="access-method"> Iteration over an <classname>Extent</classname>
-</entry><entry colname="cacheable">No</entry></row></tbody></tgroup></table>
+see <xref linkend="ref_guide_cache_limits_extent"/>.
</para>
+ <table>
+ <title>
+ Data access methods
+ </title>
+ <tgroup cols="2" align="left" colsep="1" rowsep="1">
+ <colspec colname="access-method"/><colspec
colname="cacheable"/>
+ <thead>
+ <row>
+ <entry colname="access-method">Access method</entry>
+ <entry colname="cacheable">Uses cache</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry colname="access-method">
+ Standard relation traversal
+ </entry>
+ <entry colname="cacheable">
+ Yes
+ </entry>
+ </row>
+ <row>
+ <entry colname="access-method">
+ Large result set relation traversal
+ </entry>
+ <entry colname="cacheable">No</entry>
+ </row>
+ <row>
+ <entry colname="access-method">Query</entry>
+ <entry colname="cacheable">Yes</entry>
+ </row>
+ <row>
+ <entry colname="access-method">
+ Lookups by object id
+ </entry>
+ <entry colname="cacheable">Yes</entry>
+ </row>
+ <row>
+ <entry colname="access-method">
+ Iteration over an <classname>Extent</classname>
+ </entry>
+ <entry colname="cacheable">No</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
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
@@ -68,8 +101,7 @@
OpenJPA's data cache can in both single-JVM and multi-JVM environments.
Multi-JVM caching is achieved through the use of the distributed event
notification framework described in <xref linkend="ref_guide_event"/>, or
-through one of OpenJPA's integrations with third-party distributed caches (see
-<xref linkend="ref_guide_datacacheintegrations"/> ).
+through custom integrations with a third-party distributed cache.
</para>
<para>
The single JVM mode of operation maintains and shares a data cache across all
@@ -105,8 +137,6 @@
openjpa.RemoteCommitProvider</literal></link> property appropriately, or
integrate OpenJPA with a third-party caching solution. Remote commit providers
are described in <xref linkend="ref_guide_event"/>.
-<xref linkend="ref_guide_datacacheintegrations"/> enumerates supported
-third-party caching solutions.
</para>
<para>
<indexterm>
@@ -117,16 +147,17 @@
size
</secondary>
</indexterm>
-OpenJPA's default implementation maintains a least-recently-used map of object
-ids to cache data. By default, 1000 elements are kept in cache. This can be
+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 <literal>CacheSize</literal> 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 the maximum.
+not counted when determining if the cache size exceeds its maximum size.
</para>
<para>
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 <literal> SoftReferenceSize</literal> property. Soft references
+keeps with the <literal>SoftReferenceSize</literal> property. Soft references
are unlimited by default. Set to 0 to disable soft references completely.
</para>
<example id="ref_guide_cache_conf_size">
@@ -161,8 +192,7 @@
<programlisting>
@Entity
@DataCache(timeout=10000)
-public class Employee
-{
+public class Employee {
...
}
</programlisting>
@@ -223,56 +253,6 @@
<programlisting>
true(EvictionSchedule='15,45 15 * * 1')
</programlisting>
- <para>
- <indexterm>
- <primary>
- caching
- </primary>
- <secondary>
- named caches
- </secondary>
- </indexterm>
-It is also possible for different persistence-capable classes to use different
-caches. This is achieved by specifying a cache name in a
-<link linkend="ref_guide_meta_ext">metadata extension</link>.
- </para>
- <example id="ex_non_default_cache">
- <title>
- Named Data Cache Specification
- </title>
-<programlisting>
-import org.apache.openjpa.persistence.*;
-
[EMAIL PROTECTED]
[EMAIL PROTECTED](name="small-cache", timeout=10000)
-public class Employee
-{
- ...
-}
-</programlisting>
- </example>
- <para>
-See the <ulink url="../apidocs/org/apache/openjpa/persistence/DataCache.html">
-<classname>org.apache.openjpa.persistence.DataCache</classname></ulink> Javadoc
-for more information on the <classname>DataCache</classname> annotation.
- </para>
- <para>
-The metadata above will cause instances of the <classname>Employee</classname>
-class to be stored in a cache named <literal> small-cache</literal>. This
-<literal>small-cache</literal> cache can be explicitly configured in the
-<literal>openjpa.DataCache</literal> plugin string, or can be implicitly
-defined, in which case it will take on the same default configuration
properties
-as the default cache identified in the <literal>openjpa.DataCache</literal>
-property.
- </para>
- <example id="ref_guide_cache_named">
- <title>
- Named Data Cache Configuration
- </title>
-<programlisting>
-<property name="openjpa.DataCache" value="true, true(Name=small-cache,
CacheSize=100)"/>
-</programlisting>
- </example>
</section>
<section id="ref_guide_cache_use">
<title>
@@ -296,24 +276,11 @@
more.
</para>
<programlisting>
-public StoreCache getStoreCache ();
-public StoreCache getStoreCache (String name);
+public StoreCache getStoreCache();
</programlisting>
<para>
You obtain the <classname>StoreCache</classname> through the <methodname>
-OpenJPAEntityManagerFactory.getStoreCache</methodname> methods. When you have
-multiple data caches configured as in the <literal>small-cache</literal>
example
-above, the <classname> StoreCache</classname> can act as a unified facade over
-all your caches. For every oid parameter to the <classname>StoreCache
-</classname> methods, it determines the correct data cache for that oid's
-corresponding persistent class, and dynamically delegates to that cache.
- </para>
- <para>
-If you know that you want to access a certain data cache and no others, the
-<ulink
url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.html">
-<methodname>OpenJPAEntityManagerFactory.getStoreCache(String name)</methodname>
-</ulink> method returns a <classname>StoreCache</classname> interface to a
-particular named data cache.
+OpenJPAEntityManagerFactory.getStoreCache</methodname> method.
</para>
<example id="ref_guide_cache_access_jpa">
<title>
@@ -324,18 +291,16 @@
...
-OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
-StoreCache cache = kemf.getStoreCache ();
-...
-StoreCache smallCache = kemf.getStoreCache ("small-cache");
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+StoreCache cache = oemf.getStoreCache();
...
</programlisting>
</example>
<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);
+public void evict(Class cls, Object oid);
+public void evictAll();
+public void evictAll(Class cls, Object... oids);
+public void evictAll(Class cls, Collection oids);
</programlisting>
<para>
The <methodname>evict</methodname> methods tell the cache to release data. Each
@@ -348,12 +313,12 @@
will maintain its stale copy.
</para>
<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);
+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);
</programlisting>
<para>
Most caches are of limited size. Pinning an identity to the cache ensures that
@@ -374,10 +339,10 @@
...
-OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
-StoreCache cache = kemf.getStoreCache ();
-cache.pin (Magazine.class, popularMag.getId ());
-cache.evict (Magazine.class, changedMag.getId ());
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+StoreCache cache = oemf.getStoreCache();
+cache.pin(Magazine.class, popularMag.getId());
+cache.evict(Magazine.class, changedMag.getId());
</programlisting>
</example>
<para>
@@ -391,8 +356,8 @@
The examples above include calls to <methodname>evict</methodname> 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
<classname>OpenJPAEntityManager</classname>
-'s eviction APIs.
+from the data cache when you use the <classname>
+OpenJPAEntityManager</classname>'s eviction APIs.
</para>
<example id="ref_guide_cache_pmevict">
<title>
@@ -406,8 +371,8 @@
...
-OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
-kem.evict (changedMag); // will evict from data cache also
+OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
+oem.evict(changedMag); // will evict from data cache also
</programlisting>
</example>
</section>
@@ -460,8 +425,8 @@
...
-OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
-QueryResultCache qcache = kemf.getQueryResultCache ();
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+QueryResultCache qcache = oemf.getQueryResultCache();
</programlisting>
</example>
<para>
@@ -498,7 +463,7 @@
<listitem>
<para>
Caching is not used for in-memory queries (queries in which the candidates are
a
-collection instead of a class or <classname>Extent</classname> ).
+collection instead of a class or <classname>Extent</classname>).
</para>
</listitem>
<listitem>
@@ -556,9 +521,9 @@
the entire cache.
</para>
<programlisting>
-public void evict (Query q);
-public void evictAll (Class cls);
-public void evictAll ();
+public void evict(Query q);
+public void evictAll(Class cls);
+public void evictAll();
</programlisting>
<para>
For JPA queries with parameters, set the desired parameter values into the
@@ -574,17 +539,17 @@
...
-OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
-QueryResultCache qcache = kemf.getQueryResultCache ();
+OpenJPAEntityManagerFactory oemf = OpenJPAPersistence.cast(emf);
+QueryResultCache qcache = oemf.getQueryResultCache();
// evict all queries that can be affected by changes to Magazines
-qcache.evictAll (Magazine.class);
+qcache.evictAll(Magazine.class);
// evict an individual query with parameters
-EntityManager em = emf.createEntityManager ();
-Query q = em.createQuery (...).
- setParameter (0, paramVal0).
- setParameter (1, paramVal1);
+EntityManager em = emf.createEntityManager();
+Query q = em.createQuery(...).
+ setParameter(0, paramVal0).
+ setParameter(1, paramVal1);
qcache.evict (q);
</programlisting>
</example>
@@ -597,13 +562,13 @@
the coherent cache.
</para>
<para>
-Queries can also be pinned and unpinned through the <classname>QueryResultCache
-</classname>. The semantics of these operations are the same as pinning and
-unpinning data from the data cache.
+Queries can also be pinned and unpinned through the <classname>
+QueryResultCache</classname>. The semantics of these operations are the same
+as pinning and unpinning data from the data cache.
</para>
<programlisting>
-public void pin (Query q);
-public void unpin (Query q);
+public void pin(Query q);
+public void unpin(Query q);
</programlisting>
<para>
For JPA queries with parameters, set the desired parameter values into the
@@ -622,18 +587,18 @@
...
-OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
-QueryResultCache qcache = kemf.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);
+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);
</programlisting>
</example>
<para>
@@ -642,8 +607,8 @@
cache if an event occurs that invalidates the results.
</para>
<para>
-You can disable caching on a per- <classname>EntityManager</classname> or per-
-<classname>Query</classname> basis:
+You can disable caching on a per-<classname>EntityManager</classname> or
+per-<classname>Query</classname> basis:
</para>
<example id="ref_guide_cache_query_disable">
<title>
@@ -655,281 +620,15 @@
...
// temporarily disable query caching for all queries created from em
-OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
-kem.getFetchPlan ().setQueryResultCache (false);
+OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
+oem.getFetchPlan ().setQueryResultCache(false);
// re-enable caching for a particular query
-OpenJPAQuery kq = kem.createQuery (...);
-kq.getFetchPlan ().setQueryResultCache (true);
-</programlisting>
-<programlisting>
-import org.apache.openjpa.jdo.*;
-
-...
-
-// temporarily disable query caching for all queries created from pm
-PersistenceManager pm = ...;
-OpenJPAFetchPlan fetch = (OpenJPAFetchPlan) pm.getFetchPlan ();
-fetch.setQueryResultCache (false);
-
-// re-enable caching for a particular query
-Query q = pm.newQuery (...);
-OpenJPAFetchPlan fetch = OpenJPAJDOHelper.cast (pm.getFetchPlan ());
-fetch.setQueryResultCache (true);
+OpenJPAQuery oq = oem.createQuery(...);
+oq.getFetchPlan().setQueryResultCache(true);
</programlisting>
</example>
</section>
- <section id="ref_guide_cache_concurrent">
- <title>
- The Concurrent Data Cache
- </title>
- <para>
-The <emphasis>concurrent</emphasis> is a new data cache plugin for OpenJPA. It
-has not been as thoroughly tested as OpenJPA's standard data cache. The
-concurrent cache can, however, offer considerably greater performance and
-scalability characteristics compared to the standard cache when the following
-conditions are met:
- </para>
- <orderedlist>
- <listitem>
- <para>
-The cache is big enough to hold all of your commonly-used data.
- </para>
- </listitem>
- <listitem>
- <para>
-Your application is heavily concurrent.
- </para>
- </listitem>
- </orderedlist>
- <para>
-Additionally, this cache does not fully index its contents by class, but rather
-just keeps track of which clasess are in the cache. It services requests to
drop
-given classes by checking to see if any instances of that class might be in the
-cache, and then clearing the entire cache. This inefficiency can easily be
-worked around with careful cache partitioning.
- </para>
- <para>
-To use the concurrent data cache instead of the standard data cache, set your
-<literal>openjpa.DataCache</literal> property to <literal>concurrent</literal>
-instead of <literal>true</literal>. Or, you can mix concurrent and standard
-caches in a set of named caches.
- </para>
- <para>
-The concurrent cache has the following configuration parameters:
- </para>
- <orderedlist>
- <listitem>
- <para>
-<literal>CacheSize</literal>: The maximum number of objects that this cache
-will hold. The default is 1000 objects. This setting differs from the setting
-for the default data cache in that instances that are pinned into cache do
count
-towards this limit.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>Name</literal>: The unique name of the cache.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>EvictionSchedule</literal>: A cron-style eviction schedule that this
-cache should follow.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>LRUThresholdRatio</literal>: The ratio above which this implementation
-should start applying its least-recently-used algorithm to prepare for eviction
-should the need arise. Default is 80%. Values should be integers between 1 and
-100.
- </para>
- </listitem>
- </orderedlist>
- <example id="ref_guide_cache_concurrent_conf">
- <title>
- Concurrent Data Cache Configuration
- </title>
- <para>
-The following configuration uses the standard OpenJPA cache as the primary
cache
-and a named concurrent cache as a secondary cache. Various classes can be
-configured to use this secondary cache in their metadata.
- </para>
-<programlisting>
-<property name="openjpa.DataCache" value="true,
concurrent(Name=secondary)"/>
-</programlisting>
- </example>
- </section>
- <section id="ref_guide_datacacheintegrations">
- <title>
- Third-Party Integrations
- </title>
- <para>
-OpenJPA includes built-in integrations with Tangosol Coherence and GemStone
-GemFire caching products.
- </para>
- <section id="ref_guide_cache_tangosol">
- <title>
- Tangosol Integration
- </title>
- <indexterm zone="ref_guide_cache_tangosol">
- <primary>
- caching
- </primary>
- <secondary>
- tangosol integration
- </secondary>
- </indexterm>
- <para>
-The OpenJPA data cache can integrate with Tangosol's Coherence caching system.
-To use Tangosol integration, set the <link linkend="openjpa.DataCache">
-<literal>openjpa.DataCache</literal></link> configuration property to <literal>
-tangosol</literal>, with the appropriate plugin properties for your Tangosol
-setup. For example:
- </para>
- <example id="ref_guide_cache_tangosol_conf">
- <title>
- Tangosol Cache Configuration
- </title>
-<programlisting>
-<property name="openjpa.DataCache"
value="tangosol(TangosolCacheName=openjpa)"/>
-</programlisting>
- </example>
- <para>
-The Tangosol cache understands the following properties:
- </para>
- <itemizedlist>
- <listitem>
- <para>
-<literal>TangosolCacheName</literal>: The name of the Tangosol Coherence cache
-to use. Defaults to <literal>openjpa</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>TangosolCacheType</literal>: The type of Tangosol Coherence cache to
-use (optional). Valid values are <literal>named</literal>, <literal>distributed
-</literal>, or <literal>replicated</literal>. Defaults to <literal> named
-</literal>, which means that the cache is looked up via the <literal>
-com.tangosol.net.CacheFactory.getCache(String)</literal> method. This method
-looks up the cached by name as defined in the Coherence configuration.
- </para>
- <note>
- <para>
-As of this writing, it is not possible to use a Tangosol Coherence 1.2.2
-distributed cache type with Apple's OS X 1.3.1 JVM. Use their replicated cache
-instead.
- </para>
- </note>
- </listitem>
- <listitem>
- <para>
-<literal>ClearOnClose</literal>: Whether the Tangosol named cache should be
-completely cleared when the <classname>EntityManagerFactory</classname>
-is closed. Defaults to <literal>false</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
-The OpenJPA query cache can also integrate with Tangosol's Coherence caching
-system. To use Tangosol query cache integration, set the
-<link linkend="openjpa.QueryCache"><literal>openjpa.QueryCache</literal></link>
-configuration property to <literal>tangosol</literal>, with the appropriate
-plugin properties for your Tangosol setup. For example:
- </para>
- <example id="ref_guide_cache_tangosol_query_conf">
- <title>
- Tangosol Query Cache Configuration
- </title>
-<programlisting>
-<property name="openjpa.QueryCache"
value="tangosol(TangosolCacheName=openjpa-query)"/>
-</programlisting>
- </example>
- <para>
-The Tangosol query cache understands the same properties as the data cache,
with
-a default Tangosol cache name of <literal>openjpa-query</literal>.
- </para>
- </section>
- <section id="ref_guide_cache_gemfire">
- <title>
- GemStone GemFire Integration
- </title>
- <para>
-The OpenJPA data cache can integrate with GemStone's GemFire v3.5.1 caching
-system. later. To use GemFire in OpenJPA you will need to change your <literal>
-gemfire.properties</literal> to have the property <literal>
-enable-shared-memory=true</literal>. You will also need to add both OpenJPA and
-GemFire to your classpath and then start a GemFire server.
- </para>
-<programlisting>
-prompt> gemfire start
-</programlisting>
- <para>
-By default, the GemFire data cache will use a GemFire region of <literal>
-root/openjpa-data-cache</literal> and the GemFire query cache will use a region
-of <literal>root/openjpa-query-cache</literal>. This can be changed be setting
-the optional property <literal>GemFireCacheName</literal>.
- </para>
- <example id="ref_guide_datacacheintegrations_gemfire_conf">
- <title>
- GemFire Cache Configuration
- </title>
- <para>
-<filename>persistence.xml</filename>:
- </para>
-<programlisting>
-<property name="openjpa.DataCache"
- value="gemfire(GemFireCacheName=/root/my-openjpa-data-cache)"/>
-<property name="openjpa.QueryCache"
- value="gemfire(GemFireCacheName=/root/my-openjpa-query-cache)"/>
-</programlisting>
- <para>
-GemFire <filename>cache.xml</filename>:
- </para>
-<programlisting>
-...
- <shared-root-region name="root">
- <region-attributes>
- ...
- </region-attributes>
- <region name="My-openjpa-data-cache">
- <region-attributes>
- </region-attributes>
- </region>
- <region name="My-openjpa-query-cache">
- <region-attributes>
- </region-attributes>
- </region>
- </shared-root-region>
- ...
-</programlisting>
- </example>
- <para>
-If you set GemFire for both <literal>openjpa.DataCache</literal> and <literal>
-openjpa.QueryCache</literal> you aren't required to specify a <literal>
-openjpa.RemoteCommitProvider</literal> unless you are registering your own
-<classname> RemoteCommitListener</classname> s.
- </para>
- <para>
-Some notes regarding using GemFire with OpenJPA:
- </para>
- <itemizedlist>
- <listitem>
- <para>
-Custom field types mapped with externalizers or custom mappings must be
-serializable.
- </para>
- </listitem>
- <listitem>
- <para>
-The <link linkend="openjpa.DynamicDataStructs"><literal>
-openjpa.DynamicDataStructs</literal></link> option is not supported.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
<section id="ref_guide_cache_extension">
<title>
Cache Extension
@@ -965,8 +664,8 @@
</classname> directly. If you want to implement a distributed cache that uses
an
unsupported method for communications, create an implementation of <classname>
org.apache.openjpa.event.RemoteCommitProvider</classname>. This process is
-described in greater detail in <xref linkend="ref_guide_event_customization"/>
-.
+described in greater detail in
+<xref linkend="ref_guide_event_customization"/>.
</para>
<para>
The query cache is just as easy to extend. Add functionality by extending the
@@ -985,7 +684,7 @@
<listitem>
<para>
The default cache implementations <emphasis>do not</emphasis> automatically
-refresh objects in other <classname> EntityManager</classname>s when the cache
+refresh objects in other <classname>EntityManager</classname>s when the cache
is updated or invalidated. This behavior would not be compliant with the JPA
specification.
</para>
@@ -995,7 +694,7 @@
Invoking <methodname>OpenJPAEntityManager.evict</methodname><emphasis>does not
</emphasis> result in the corresponding data being dropped from the data cache,
unless you have set the proper configuration options as explained above (see
-<xref linkend="ref_guide_cache_pmevict"/> ). Other methods related to the
+<xref linkend="ref_guide_cache_pmevict"/>). Other methods related to the
<classname>EntityManager</classname> cache also do not effect the data cache.
</para>
<para>
@@ -1073,146 +772,20 @@
...
-OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
-Extent extent = kem.getExtent (Magazine.class, false);
+OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
+Extent extent = oem.getExtent(Magazine.class, false);
// This iterator does not benefit from caching...
-Iterator uncachedIterator = extent.iterator ();
+Iterator uncachedIterator = extent.iterator();
// ... but this one does.
-OpenJPAQuery extentQuery = kem.createQuery (...);
-extentQuery.setSubclasses (false);
-Iterator cachedIterator = extentQuery.getResultList ().iterator ();
+OpenJPAQuery extentQuery = oem.createQuery(...);
+extentQuery.setSubclasses(false);
+Iterator cachedIterator = extentQuery.getResultList().iterator();
</programlisting>
</example>
</listitem>
</itemizedlist>
</section>
- </section>
- <section id="ref_guide_cache_querycomp">
- <title>
- Query Compilation Cache
- </title>
- <indexterm zone="ref_guide_cache_querycomp">
- <primary>
- caching
- </primary>
- <secondary>
- query compilation cache
- </secondary>
- </indexterm>
- <para>
-The query compilation cache is a <classname>Map</classname> used to cache
parsed
-query strings. As a result, most queries are only parsed once in OpenJPA, and
-cached thereafter. You can control the compilation cache through the
-<link linkend="openjpa.QueryCompilationCache"><literal>
-openjpa.QueryCompilationCache</literal></link> configuration property. This
-property accepts a plugin string (see <xref linkend="ref_guide_conf_plugins"/>
-) describing the <classname>Map</classname> used to associate query
-strings and their parsed form. This property accepts the following aliases:
- </para>
- <table>
- <title>
- Pre-defined aliases
- </title>
- <tgroup cols="2" align="left" colsep="1" rowsep="1">
- <colspec colname="alias"/>
-
- <colspec colname="value"/>
-
- <colspec colname="notes"/>
-
- <thead>
- <row>
- <entry colname="alias">
- Alias
- </entry>
- <entry colname="value">
- Value
- </entry>
- <entry colname="notes">
- Notes
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry colname="alias">
- <literal>
- true
- </literal>
- </entry>
- <entry colname="value">
- <literal>
- openjpa.util.CacheMap
- </literal>
- </entry>
- <entry colname="notes">
-
- The default option. Uses a
-
- <ulink
url="../apidocs/org/apache/openjpa/util/CacheMap.html">
- <literal>
- CacheMap
- </literal>
- </ulink>
- to store
- compilation data.
- <literal>
- CacheMap
- </literal>
- uses
- a least-recently-used strategy for a fixed number
- of cache entries, and an optional soft reference
- map for entries that are moved out of the LRU
- space. So, for applications that have a
- monotonically increasing number of distinct queries,
- this option can be used to ensure that a fixed
- amount of memory is used by the cache.
-
- </entry>
- </row>
- <row>
- <entry colname="alias">
- <literal>
- all
- </literal>
- </entry>
- <entry colname="value">
- <literal>
- java.util.HashMap
- </literal>
- </entry>
- <entry colname="notes">
-
- This is the fastest option, but compilation data is
- never dropped from the cache, so if you use a large
- number of dynamic queries, this option may result in
- ever-increasing memory usage. Note that if your
- queries only differ in the values of the parameters,
- this should not be an issue.
-
- </entry>
- </row>
- <row>
- <entry colname="alias">
- <literal>
- false
- </literal>
- </entry>
- <entry colname="value">
- <emphasis>
- none
- </emphasis>
- </entry>
- <entry colname="notes">
-
- Disables the compilation cache.
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
</section>
</chapter>
Modified:
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
URL:
http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml?view=diff&rev=452672&r1=452671&r2=452672
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
(original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
Tue Oct 3 16:00:18 2006
@@ -94,141 +94,103 @@
</indexterm>
<para>
OpenJPA <classname>EntityManager</classname>s have the ability to automatically
-synchronize their transactions with an external transaction manager.
-###
-If you
-deploy via <link linkend="ref_guide_deploy_inject"><classname>EntityManager
-</classname> injection</link> as described above, this synchronization is
-typically automatic. Whether
+synchronize their transactions with an external transaction manager. Whether
or not <classname>EntityManager</classname>s from a given <classname>
EntityManagerFactory</classname> exhibit this behavior by default depends on
-the <link linkend="kodo.TransactionMode">
- <literal>kodo.TransactionMode</literal></link> configuration
property.
- The property can take the following values:
- </para>
- <para condition="jdo_notcombo">
- Kodo <classname>PersistenceManager</classname>s have the
ability
- to automatically synchronize their transactions with an
external
- transaction manager. Whether or not <classname>
- PersistenceManager</classname>s from a given
- <classname>PersistenceManagerFactory</classname> exhibit this
behavior
- by default depends on the <link linkend="kodo.TransactionMode">
- <literal>kodo.TransactionMode</literal></link> configuration
property.
- The property can take the following values:
- </para>
- <para condition="combo">
- Kodo <classname>EntityManager</classname>s and <classname>
- PersistenceManager</classname>s have the ability
- to automatically synchronize their transactions with an
external
- transaction manager. Whether or not <classname>
- EntityManager</classname>s and <classname>
- PersistenceManager</classname>s from a given factory exhibit
this
- behavior by default depends on the <link
linkend="kodo.TransactionMode">
- <literal>kodo.TransactionMode</literal></link> configuration
property.
- The property can take the following values:
- </para>
+the transaction type you set for the factory's persistence unit in
+your <filename>persistence.xml</filename> file. OpenJPA uses the given
+transaction type internally to set the
+<link linkend="openjpa.TransactionMode"><literal>openjpa.TransactionMode
+</literal></link> configuration property. This property accepts the following
+modes:
+ </para>
<itemizedlist>
<listitem>
<para>
- <literal>local</literal>: Perform transaction
operations
- locally.
+<literal>local</literal>: Perform transaction operations locally.
</para>
</listitem>
<listitem>
<para>
- <literal>managed</literal>: Integrate with the
application
- server's managed global transactions.
+<literal>managed</literal>: Integrate with the application server's managed
+global transactions.
</para>
</listitem>
</itemizedlist>
- <para condition="ejb">
- You can override the global transaction mode setting when you
obtain an
- <classname>EntityManager</classname> using the
- <ulink
url="&api-dir;/kodo/persistence/KodoEntityManagerFactory.html">
- <classname>KodoEntityManagerFactory</classname></ulink>'s
- <methodname>createEntityManager(PersistenceContextType ctype,
boolean managed, int connRetainMode)
- </methodname> method.
- </para>
- <para condition="jdo">
- You can override the global transaction mode setting when you
obtain a
- <classname>PersistenceManager</classname> using the
- <ulink
url="&api-dir;/kodo/jdo/KodoPersistenceManagerFactory.html">
- <classname>KodoPersistenceManagerFactory</classname></ulink>'s
- <methodname>getPersistenceManager(boolean managed, int
connRetainMode)
- </methodname> method.
+ <para>
+You can override the global transaction mode setting when you obtain an
+<classname>EntityManager</classname> using the
+<ulink
url="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManagerFactory.html";>
+<classname>EntityManagerFactory</classname></ulink>'s
+<methodname>createEntityManager(Map props)</methodname> method. Simply set the
+<literal>openjpa.TransactionMode</literal> key of the given <classname>Map
+</classname> to the desired value.
</para>
+ <note>
+ <para>
+You can also override the <literal>openjpa.ConnectionUserName</literal>,
+<literal>openjpa.ConnectionPassword</literal>, and <literal>
+openjpa.ConnectionRetainMode</literal> settings using the given <classname>
+Map</classname>.
+ </para>
+ </note>
<para>
- <indexterm><primary>ManagedRuntime</primary></indexterm>
- In order to use global transactions, Kodo must be able to access
- the application server's
<classname>javax.transaction.TransactionManager
- </classname>. Kodo can automatically discover the transaction
- manager for most major application servers. Occasionally,
however,
- you might have to point Kodo to the transaction manager for an
- unrecognized or non-standard application server setup. This is
- accomplished through the <link
linkend="kodo.ManagedRuntime"><literal>
- kodo.ManagedRuntime</literal></link> configuration property.
This
- property describes a
- <ulink
url="&javadoc-dir;/kodo/ee/ManagedRuntime.html"><classname>
- kodo.ee.ManagedRuntime</classname></ulink> implementation to use
- for transaction manager discovery. You can specify your own
- implementation, or use one of the built-ins:
+<indexterm><primary>ManagedRuntime</primary></indexterm>
+In order to use global transactions, OpenJPA must be able to access the
+application server's <classname>
+javax.transaction.TransactionManager</classname>. OpenJPA can automatically
+discover the transaction manager for most major application servers.
+Occasionally, however, you might have to point OpenJPA to the transaction
+manager for an unrecognized or non-standard application server setup. This is
+accomplished through the <link linkend="openjpa.ManagedRuntime"><literal>
+openjpa.ManagedRuntime</literal></link> configuration property. This
+property describes an
+<ulink url="../apidocs/org/apache/openjpa/ee/ManagedRuntime.html"><classname>
+org.apache.openjpa.ee.ManagedRuntime</classname></ulink> implementation to use
+for transaction manager discovery. You can specify your own implementation,
+or use one of the built-ins:
</para>
<itemizedlist>
<listitem>
<para>
- <literal>auto</literal>: This is the default.
It is an alias
- for the
- <ulink
url="&javadoc-dir;/kodo/ee/AutomaticManagedRuntime.html">
-
<classname>kodo.ee.AutomaticManagedRuntime</classname></ulink>
- class. This managed runtime is able to
automatically integrate
- with several common application servers.
+<literal>auto</literal>: This is the default. It is an alias for the
+<ulink url="../apidocs/org/apache/openjpa/ee/AutomaticManagedRuntime.html">
+<classname>org.apache.openjpa.ee.AutomaticManagedRuntime</classname></ulink>
+class. This managed runtime is able to automatically integrate with several
+common application servers.
</para>
</listitem>
<listitem>
<para>
- <literal>invocation</literal>: An alias for the
- <ulink
url="&javadoc-dir;/kodo/ee/InvocationManagedRuntime.html">
-
<classname>kodo.ee.InvocationManagedRuntime</classname></ulink>
- class. You can configure this runtime to
invoke any static
- method in order to obtain the appserver's
transaction manager.
+<literal>invocation</literal>: An alias for the
+<ulink url="../apidocs/org/apache/openjpa/ee/InvocationManagedRuntime.html">
+<classname>org.apache.openjpa.ee.InvocationManagedRuntime</classname></ulink>
+class. You can configure this runtime to invoke any static
+method in order to obtain the appserver's transaction manager.
</para>
</listitem>
<listitem>
<para>
- <literal>jndi</literal>: An alias for the
- <ulink
url="&javadoc-dir;/kodo/ee/JNDIManagedRuntime.html">
-
<classname>kodo.ee.JNDIManagedRuntime</classname></ulink>
- class. You can configure this runtime to look
up the
- transaction manager at any JNDI location.
+<literal>jndi</literal>: An alias for the
+<ulink url="../apidocs/org/apache/openjpa/ee/JNDIManagedRuntime.html">
+<classname>org.apache.openjpa.ee.JNDIManagedRuntime</classname></ulink>
+class. You can configure this runtime to look up the transaction manager at
+any JNDI location.
</para>
</listitem>
</itemizedlist>
<para>
- See the Javadoc for of each class for details on the bean
properties
- you can pass to these plugins in your configuration string.
+See the Javadoc for of each class for details on the bean properties
+you can pass to these plugins in your configuration string.
</para>
- &feature-enterprise;
<example id="ref_guide_enterprise_transex">
<title>Configuring Transaction Manager
Integration</title>
- <para condition="combo">JPA XML format:</para>
-<programlisting condition="ejb">
-<![CDATA[<property name="kodo.TransactionMode" value="managed"/>
-<property name="kodo.ManagedRuntime"
value="jndi(TransactionManagerName=java:/TransactionManager)"/>]]>
-</programlisting>
- <para condition="combo">JDO properties format:</para>
-<programlisting condition="jdo">
-kodo.TransactionMode: managed
-kodo.ManagedRuntime: jndi(TransactionManagerName=java:/TransactionManager)
+<programlisting>
+<![CDATA[<property name="openjpa.TransactionMode" value="managed"/>
+<property name="openjpa.ManagedRuntime"
value="jndi(TransactionManagerName=java:/TransactionManager)"/>]]>
</programlisting>
</example>
- <para>
- Note that even when Kodo is using managed transaction, you can
control
- transactions through the specification local transaction APIs
if you
- wish. Kodo will propagate your transaction calls to the global
- transaction.
- </para>
</section>
-
<section id="ref_guide_enterprise_xa">
<title>
XA Transactions
@@ -315,6 +277,12 @@
transactions is a simple two-step process:
</para>
<orderedlist>
+ <listitem>
+ <para>
+Integrate OpenJPA with your application server's transaction manager, as
+detailed in <xref linkend="ref_guide_enterprise_trans"/> above.
+ </para>
+ </listitem>
<listitem>
<para>
Point OpenJPA at an enlisted <classname>XADataSource</classname>, and configure
Modified:
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
URL:
http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml?view=diff&rev=452672&r1=452671&r2=452672
==============================================================================
---
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
(original)
+++
incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
Tue Oct 3 16:00:18 2006
@@ -112,29 +112,27 @@
</para>
<example id="ref_guide_integration_props">
<title>
- Using the Properties Attribute of the <config>
- Tag
+ Using the Properties Attribute of the <config> Tag
</title>
<programlisting>
<mappingtool>
<fileset dir="${basedir}">
<include name="**/model/*.java"/>
</fileset>
- <config properties="openjpa-dev.properties"/>
+ <config properties="openjpa-dev.xml"/>
</mappingtool>
</programlisting>
</example>
<example id="ref_guide_integration_propsfile">
<title>
- Using the PropertiesFile Attribute of the <config>
- Tag
+ Using the PropertiesFile Attribute of the <config>
Tag
</title>
<programlisting>
<mappingtool>
<fileset dir="${basedir}">
<include name="**/model/*.java"/>
</fileset>
- <config propertiesFile="../conf/openjpa-dev.properties"/>
+ <config propertiesFile="../conf/openjpa-dev.xml"/>
</mappingtool>
</programlisting>
</example>
@@ -209,15 +207,17 @@
<para>
The enhancer task allows you to invoke the OpenJPA enhancer directly from
within
the Ant build process. The task's parameters correspond exactly to the long
-versions of the command-line arguments to <link linkend="ref_guide_pc_enhance">
-<literal>openjpac</literal></link>.
+versions of the command-line arguments to the
+<link linkend="ref_guide_pc_enhance"><classname>
+org.apache.openjpa.enhance.PCEnhancer</classname></link>.
</para>
<para>
The enhancer task accepts a nested <literal>fileset</literal> tag to specify
the
files that should be processed. You can specify <filename>.java</filename> or
<filename>.class</filename> files. If you do not specify any files, the task
-will run on the classes listed in your <link linkend="openjpa.MetaDataFactory">
-<literal> openjpa.MetaDataFactory</literal></link> property.
+will run on the classes listed in your <filename>persistence.xml</filename> or
+<link linkend="openjpa.MetaDataFactory"><literal>
+openjpa.MetaDataFactory</literal></link> property.
</para>
<para>
Following is an example of using the enhancer task in a <filename>build.xml
@@ -266,17 +266,17 @@
<para>
The application identity tool task allows you to invoke the application
identity
tool directly from within the Ant build process. The task's parameters
-correspond exactly to the long versions of the command-line arguments to
-<link
linkend="ref_guide_pc_appid_appidtool"><literal>appidtool</literal></link>
-.
+correspond exactly to the long versions of the command-line arguments to the
+<link linkend="ref_guide_pc_appid_appidtool"><classname>
+org.openjpa.enhance.ApplicationIdTool</classname></link>.
</para>
<para>
The application identity tool task accepts a nested <literal>fileset</literal>
tag to specify the files that should be processed. You can specify <filename>
.java</filename> or <filename>.class</filename> files. If you do not specify
any
-files, the task will run on the classes listed in your
-<link linkend="openjpa.MetaDataFactory"><literal> openjpa.MetaDataFactory
-</literal></link> property.
+files, the task will run on the classes listed in your
<filename>persistence.xml
+</filename> file or <link linkend="openjpa.MetaDataFactory"><literal>
+openjpa.MetaDataFactory</literal></link> property.
</para>
<para>
Following is an example of using the application identity tool task in a
@@ -330,14 +330,15 @@
definitions, without needing to remember to invoke the mapping tool manually.
The task's parameters correspond exactly to the long versions of the
command-line arguments to the <link linkend="ref_guide_mapping_mappingtool">
-<literal>mappingtool</literal></link>.
+<classname>org.apache.openjpa.jdbc.meta.MappingTool</classname></link>.
</para>
<para>
The mapping tool task accepts a nested <literal>fileset</literal> tag to
specify
the files that should be processed. You can specify <filename>.java</filename>
or <filename>.class</filename> files. If you do not specify any files, the task
-will run on the classes listed in your <link linkend="openjpa.MetaDataFactory">
-<literal> openjpa.MetaDataFactory</literal></link> property.
+will run on the classes listed in your <filename>persistence.xml</filename>
file
+or <link linkend="openjpa.MetaDataFactory"><literal>
+openjpa.MetaDataFactory</literal></link> property.
</para>
<para>
Following is an example of a <filename>build.xml</filename> target that invokes
@@ -389,8 +390,8 @@
tool from within Ant. While many users will only run the reverse mapping
process
once, others will make it part of their build process. The task's parameters
correspond exactly to the long versions of the command-line arguments to the
-<link linkend="ref_guide_pc_reverse_reversemappingtool"><literal>
-reversemappingtool</literal></link>.
+<link linkend="ref_guide_pc_reverse_reversemappingtool"><classname>
+org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></link>.
</para>
<para>
Following is an example of a <filename>build.xml</filename> target that invokes
@@ -440,8 +441,8 @@
The schema tool task allows you to directly invoke the schema tool from within
the Ant build process. The task's parameters correspond exactly to the long
versions of the command-line arguments to the
-<link linkend="ref_guide_schema_schematool"><literal> schematool</literal>
-</link>.
+<link linkend="ref_guide_schema_schematool"><classname>
+org.apache.openjpa.jdbc.schema.SchemaTool</classname></link>.
</para>
<para>
Following is an example of a <filename>build.xml</filename> target that invokes
@@ -468,15 +469,5 @@
</programlisting>
</example>
</section>
- </section>
- <section id="ref_guide_integration_maven">
- <title>
- Maven
- </title>
- <indexterm zone="ref_guide_integration_maven">
- <primary>
- Maven
- </primary>
- </indexterm>
</section>
</chapter>
