Author: mikedd
Date: Fri Jan 23 13:53:41 2009
New Revision: 737202
URL: http://svn.apache.org/viewvc?rev=737202&view=rev
Log:
OPENJPA-809 documentation updates
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml?rev=737202&r1=737201&r2=737202&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml Fri Jan
23 13:53:41 2009
@@ -287,17 +287,58 @@
</para>
<para>
Rather than use the low-level <literal>org.apache.openjpa.datacache</literal>
-package APIs, JPA users should typically access the data cache through
OpenJPA's
+package APIs, JPA users should typically access the data cache through the JPA
+standard <classname>javax.persistence.Cache</classname> interface, or OpenJPA's
high-level
<ulink url="../javadoc/org/apache/openjpa/persistence/StoreCache.html">
-<classname>org.apache.openjpa.persistence.StoreCache</classname></ulink>
facade.
-This facade has methods to pin and unpin records, evict data from the cache,
and
-provides basic statistics of number of read or write requests and hit ratio of
-the cache.
+<classname>org.apache.openjpa.persistence.StoreCache</classname></ulink>
facade.
</para>
-<programlisting>
-public StoreCache getStoreCache();
-</programlisting>
+ <para>
+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.
+ </para>
+<section id="ref_guide_cache_use_JPA">
+<title>Using the JPA standard Cache interface</title>
+ You may obtain the <classname>javax.persistence.Cache</classname> through
+ the EntityManagerFactory.getCache() method.
+ <example id="ref_guide_cache_access_jpa_standard">
+ <title>
+ Accessing the Cache
+ </title>
+ <programlisting>
+import javax.persistence.Cache;
+import javax.persistence.EntityManagerFactory;
+import javax.persistence.Persistence;
+. . .
+EntityManagerFactory em =
+ Persistence.createEntityManagerFactory("myPersistenceUnit");
+Cache cache = em.getCache();
+. . .
+ </programlisting>
+ </example>
+
+ <example id="ref_guide_cache_use_jpa_standard">
+ <title>Using the javax.persistence.Cache interface</title>
+ <programlisting>
+// Check whether the cache contains a entity with a provided ID
+Cache cache = em.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();
+ </programlisting>
+ </example>
+</section>
+<section id="ref_guide_cache_use_openJPA">
+<title>Using the OpenJPA StoreCache extensions</title>
<para>
You obtain the <classname>StoreCache</classname> through the <methodname>
OpenJPAEntityManagerFactory.getStoreCache</methodname> method.
@@ -313,6 +354,7 @@
StoreCache cache = oemf.getStoreCache();
...
</programlisting>
+Alternatively you can just cast the same object returned from
</example>
<programlisting>
public void evict(Class cls, Object oid);
@@ -370,6 +412,7 @@
<xref linkend="ref_guide_runtime"/> discusses OpenJPA's other extensions
to the standard set of JPA runtime interfaces.
</para>
+</section>
<para>
The examples above include calls to <methodname>evict</methodname> to manually
remove data from the data cache. Rather than evicting objects from the data
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml?rev=737202&r1=737201&r2=737202&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml Fri Jan
23 13:53:41 2009
@@ -361,11 +361,12 @@
</primary>
</indexterm>
<para>
-In addition to the <classname>EntityManager</classname> object cache mandated
by
-the JPA specification, OpenJPA includes a flexible datastore-level cache. You
-can access this cache from your JPA code using the
+In addition to the <classname>EntityManager</classname> object cache the JPA
+specification provides access to a second level cache via the
+javax.persistence.Cache interface. OpenJPA provides further extensions via
+the org.apache.openjpa.persistence.StoreCache interface documented at
<ulink url="../javadoc/org/apache/openjpa/persistence/StoreCache.html">
-<classname>org.apache.openjpa.persistence.StoreCache</classname></ulink>
facade.
+<classname>org.apache.openjpa.persistence.StoreCache</classname></ulink>.
<xref linkend="ref_guide_cache"/> has detailed information on OpenJPA's
data caching system, including the <classname>StoreCache</classname> facade.
</para>
