From afe9acd57616e633d7c4a2278a3885621ba7e3e6 Mon Sep 17 00:00:00 2001 From: "A. Abram White" Date: Tue, 3 Oct 2006 23:00:18 +0000 Subject: [PATCH] Doc corrections. git-svn-id: https://svn.apache.org/repos/asf/incubator/openjpa/trunk@452672 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/openjpa/persistence/QueryImpl.java | 4 +- .../src/doc/manual/jpa_resources.xml | 9 +- .../src/doc/manual/ref_guide_caching.xml | 669 ++++-------------- .../src/doc/manual/ref_guide_deploy.xml | 166 ++--- .../src/doc/manual/ref_guide_integration.xml | 57 +- .../src/doc/manual/ref_guide_optimization.xml | 643 ++++------------- .../src/doc/manual/ref_guide_remote.xml | 29 +- .../src/doc/manual/ref_guide_runtime.xml | 261 +++---- .../src/doc/manual/supported_databases.xml | 472 ++++++------ 9 files changed, 707 insertions(+), 1603 deletions(-) diff --git a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java index 17e25c2bb..12d8e0cb9 100644 --- a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java +++ b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/QueryImpl.java @@ -333,9 +333,9 @@ public class QueryImpl } 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)) { diff --git a/openjpa-project/src/doc/manual/jpa_resources.xml b/openjpa-project/src/doc/manual/jpa_resources.xml index 1928bf873..fc780bf6b 100644 --- a/openjpa-project/src/doc/manual/jpa_resources.xml +++ b/openjpa-project/src/doc/manual/jpa_resources.xml @@ -16,18 +16,13 @@ EJB 3 JSR page -Locally mirrored + javax.persistence Javadoc -OpenJPA API Javadoc - - - - -Full OpenJPA Javadoc +OpenJPA Javadoc diff --git a/openjpa-project/src/doc/manual/ref_guide_caching.xml b/openjpa-project/src/doc/manual/ref_guide_caching.xml index 1d631ebf8..e809c8958 100644 --- a/openjpa-project/src/doc/manual/ref_guide_caching.xml +++ b/openjpa-project/src/doc/manual/ref_guide_caching.xml @@ -44,21 +44,54 @@ id, and iteration over an Extent. OpenJPA's cache plugin accelerates three of these mechanisms. It does not provide any caching of large result set relations or Extent iterators. If you find yourself in need of higher-performance Extent iteration, -see . Data -access methods - -Access method -Uses cache - Standard relation traversal -Yes - Large result set relation traversal -No -QueryYes - Lookups by object id -Yes - Iteration over an Extent -No
+see . + + + Data access methods + + + + + + Access method + Uses cache + + + + + + Standard relation traversal + + + Yes + + + + + Large result set relation traversal + + No + + + Query + Yes + + + + Lookups by object id + + Yes + + + + Iteration over an Extent + + No + + + +
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 @@ are loaded from the datastore. 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 , or -through one of OpenJPA's integrations with third-party distributed caches (see - ). +through custom integrations with a third-party distributed cache. The single JVM mode of operation maintains and shares a data cache across all @@ -105,8 +137,6 @@ set the openjpa.RemoteCommitProvider property appropriately, or integrate OpenJPA with a third-party caching solution. Remote commit providers are described in . - enumerates supported -third-party caching solutions. @@ -117,16 +147,17 @@ third-party caching solutions. size -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 CacheSize 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. 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 SoftReferenceSize property. Soft references +keeps with the SoftReferenceSize property. Soft references are unlimited by default. Set to 0 to disable soft references completely. @@ -161,8 +192,7 @@ Timeout Employee objects after 10 seconds. @Entity @DataCache(timeout=10000) -public class Employee -{ +public class Employee { ... } @@ -223,56 +253,6 @@ past 3 PM on Sunday. true(EvictionSchedule='15,45 15 * * 1') - - - - caching - - - named caches - - -It is also possible for different persistence-capable classes to use different -caches. This is achieved by specifying a cache name in a -metadata extension. - - - - Named Data Cache Specification - - -import org.apache.openjpa.persistence.*; - -@Entity -@DataCache(name="small-cache", timeout=10000) -public class Employee -{ - ... -} - - - -See the -org.apache.openjpa.persistence.DataCache Javadoc -for more information on the DataCache annotation. - - -The metadata above will cause instances of the Employee -class to be stored in a cache named small-cache. This -small-cache cache can be explicitly configured in the -openjpa.DataCache 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 openjpa.DataCache -property. - - - - Named Data Cache Configuration - - -<property name="openjpa.DataCache" value="true, true(Name=small-cache, CacheSize=100)"/> - -
@@ -296,24 +276,11 @@ This facade has methods to pin and unpin records, evict data from the cache, and 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 @@ import org.apache.openjpa.persistence.*; ... -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 @@ the datastore cache; otherwise the OpenJPA runtime, oblivious to the changes, 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 @@ import org.apache.openjpa.persistence.*; ... -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 @@ to the standard set of JPA runtime interfaces. 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 @@ import org.apache.openjpa.persistence.*; ... -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 @@ import org.apache.openjpa.persistence.*; ... -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 @@ There are certain situations in which the query cache is bypassed: <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 @@ outside of OpenJPA's control. You can also evict individual queries, or clear 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 @@ import org.apache.openjpa.persistence.*; ... -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 @@ Tangosol cache implementation, it is not necessary to do this in every JVM 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 @@ import org.apache.openjpa.persistence.*; ... -OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf); -QueryResultCache qcache = kemf.getQueryResultCache (); -EntityManager em = emf.createEntityManager (); +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); +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 @@ when cache flushing occurs. However, pinned results will be removed from the 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 @@ import org.apache.openjpa.persistence.*; ... // 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 - - -The concurrent 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: - - - - -The cache is big enough to hold all of your commonly-used data. - - - - -Your application is heavily concurrent. - - - - -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. - - -To use the concurrent data cache instead of the standard data cache, set your -openjpa.DataCache property to concurrent -instead of true. Or, you can mix concurrent and standard -caches in a set of named caches. - - -The concurrent cache has the following configuration parameters: - - - - -CacheSize: 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. - - - - -Name: The unique name of the cache. - - - - -EvictionSchedule: A cron-style eviction schedule that this -cache should follow. - - - - -LRUThresholdRatio: 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. - - - - - - Concurrent Data Cache Configuration - - -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. - - -<property name="openjpa.DataCache" value="true, concurrent(Name=secondary)"/> - - -
-
- - Third-Party Integrations - - -OpenJPA includes built-in integrations with Tangosol Coherence and GemStone -GemFire caching products. - -
- - Tangosol Integration - - - - caching - - - tangosol integration - - - -The OpenJPA data cache can integrate with Tangosol's Coherence caching system. -To use Tangosol integration, set the -openjpa.DataCache configuration property to -tangosol, with the appropriate plugin properties for your Tangosol -setup. For example: - - - - Tangosol Cache Configuration - - -<property name="openjpa.DataCache" value="tangosol(TangosolCacheName=openjpa)"/> - - - -The Tangosol cache understands the following properties: - - - - -TangosolCacheName: The name of the Tangosol Coherence cache -to use. Defaults to openjpa. - - - - -TangosolCacheType: The type of Tangosol Coherence cache to -use (optional). Valid values are named, distributed -, or replicated. Defaults to named -, which means that the cache is looked up via the -com.tangosol.net.CacheFactory.getCache(String) method. This method -looks up the cached by name as defined in the Coherence configuration. - - - -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. - - - - - -ClearOnClose: Whether the Tangosol named cache should be -completely cleared when the EntityManagerFactory -is closed. Defaults to false. - - - - -The OpenJPA query cache can also integrate with Tangosol's Coherence caching -system. To use Tangosol query cache integration, set the -openjpa.QueryCache -configuration property to tangosol, with the appropriate -plugin properties for your Tangosol setup. For example: - - - - Tangosol Query Cache Configuration - - -<property name="openjpa.QueryCache" value="tangosol(TangosolCacheName=openjpa-query)"/> - - - -The Tangosol query cache understands the same properties as the data cache, with -a default Tangosol cache name of openjpa-query. - -
-
- - GemStone GemFire Integration - - -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 -gemfire.properties to have the property -enable-shared-memory=true. You will also need to add both OpenJPA and -GemFire to your classpath and then start a GemFire server. - - -prompt> gemfire start - - -By default, the GemFire data cache will use a GemFire region of -root/openjpa-data-cache and the GemFire query cache will use a region -of root/openjpa-query-cache. This can be changed be setting -the optional property GemFireCacheName. - - - - GemFire Cache Configuration - - -persistence.xml: - - -<property name="openjpa.DataCache" - value="gemfire(GemFireCacheName=/root/my-openjpa-data-cache)"/> -<property name="openjpa.QueryCache" - value="gemfire(GemFireCacheName=/root/my-openjpa-query-cache)"/> - - -GemFire cache.xml: - - -... - <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> - ... - - - -If you set GemFire for both openjpa.DataCache and -openjpa.QueryCache you aren't required to specify a -openjpa.RemoteCommitProvider unless you are registering your own - RemoteCommitListener s. - - -Some notes regarding using GemFire with OpenJPA: - - - - -Custom field types mapped with externalizers or custom mappings must be -serializable. - - - - -The -openjpa.DynamicDataStructs option is not supported. - - - -
-
Cache Extension @@ -965,8 +664,8 @@ mechanism, extend <classname>org.apache.openjpa.datacache.AbstractDataCache </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 @@ directly. <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 @@ specification. 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 @@ import org.apache.openjpa.persistence.*; ... -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 - - - - caching - - - query compilation cache - - - -The query compilation cache is a Map 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 - -openjpa.QueryCompilationCache configuration property. This -property accepts a plugin string (see -) describing the Map used to associate query -strings and their parsed form. This property accepts the following aliases: - - - - Pre-defined aliases - - - - - - - - - - - - Alias - - - Value - - - Notes - - - - - - - - true - - - - - openjpa.util.CacheMap - - - - - The default option. Uses a - - - - CacheMap - - - to store - compilation data. - - CacheMap - - 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. - - - - - - - all - - - - - java.util.HashMap - - - - - 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. - - - - - - - false - - - - - none - - - - - Disables the compilation cache. - - - - - -
-
diff --git a/openjpa-project/src/doc/manual/ref_guide_deploy.xml b/openjpa-project/src/doc/manual/ref_guide_deploy.xml index 499caad8d..4ad6cf593 100644 --- a/openjpa-project/src/doc/manual/ref_guide_deploy.xml +++ b/openjpa-project/src/doc/manual/ref_guide_deploy.xml @@ -94,141 +94,103 @@ entity managers into your session beans using the PersistenceContext OpenJPA EntityManagers have the ability to automatically -synchronize their transactions with an external transaction manager. -### -If you -deploy via EntityManager - injection as described above, this synchronization is -typically automatic. Whether +synchronize their transactions with an external transaction manager. Whether or not EntityManagers from a given EntityManagerFactory exhibit this behavior by default depends on -the - kodo.TransactionMode configuration property. - The property can take the following values: - - - Kodo PersistenceManagers have the ability - to automatically synchronize their transactions with an external - transaction manager. Whether or not - PersistenceManagers from a given - PersistenceManagerFactory exhibit this behavior - by default depends on the - kodo.TransactionMode configuration property. - The property can take the following values: - - - Kodo EntityManagers and - PersistenceManagers have the ability - to automatically synchronize their transactions with an external - transaction manager. Whether or not - EntityManagers and - PersistenceManagers from a given factory exhibit this - behavior by default depends on the - kodo.TransactionMode configuration property. - The property can take the following values: - +the transaction type you set for the factory's persistence unit in +your persistence.xml file. OpenJPA uses the given +transaction type internally to set the +openjpa.TransactionMode + configuration property. This property accepts the following +modes: + - local: Perform transaction operations - locally. +local: Perform transaction operations locally. - managed: Integrate with the application - server's managed global transactions. +managed: Integrate with the application server's managed +global transactions. - - You can override the global transaction mode setting when you obtain an - EntityManager using the - - KodoEntityManagerFactory's - createEntityManager(PersistenceContextType ctype, boolean managed, int connRetainMode) - method. - - - You can override the global transaction mode setting when you obtain a - PersistenceManager using the - - KodoPersistenceManagerFactory's - getPersistenceManager(boolean managed, int connRetainMode) - method. + +You can override the global transaction mode setting when you obtain an +EntityManager using the + +EntityManagerFactory's +createEntityManager(Map props) method. Simply set the +openjpa.TransactionMode key of the given Map + to the desired value. + + +You can also override the openjpa.ConnectionUserName, +openjpa.ConnectionPassword, and +openjpa.ConnectionRetainMode settings using the given +Map. + + - ManagedRuntime - In order to use global transactions, Kodo must be able to access - the application server's javax.transaction.TransactionManager - . 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 - kodo.ManagedRuntime configuration property. This - property describes a - - kodo.ee.ManagedRuntime implementation to use - for transaction manager discovery. You can specify your own - implementation, or use one of the built-ins: +ManagedRuntime +In order to use global transactions, OpenJPA must be able to access the +application server's +javax.transaction.TransactionManager. 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 +openjpa.ManagedRuntime configuration property. This +property describes an + +org.apache.openjpa.ee.ManagedRuntime implementation to use +for transaction manager discovery. You can specify your own implementation, +or use one of the built-ins: - auto: This is the default. It is an alias - for the - - kodo.ee.AutomaticManagedRuntime - class. This managed runtime is able to automatically integrate - with several common application servers. +auto: This is the default. It is an alias for the + +org.apache.openjpa.ee.AutomaticManagedRuntime +class. This managed runtime is able to automatically integrate with several +common application servers. - invocation: An alias for the - - kodo.ee.InvocationManagedRuntime - class. You can configure this runtime to invoke any static - method in order to obtain the appserver's transaction manager. +invocation: An alias for the + +org.apache.openjpa.ee.InvocationManagedRuntime +class. You can configure this runtime to invoke any static +method in order to obtain the appserver's transaction manager. - jndi: An alias for the - - kodo.ee.JNDIManagedRuntime - class. You can configure this runtime to look up the - transaction manager at any JNDI location. +jndi: An alias for the + +org.apache.openjpa.ee.JNDIManagedRuntime +class. You can configure this runtime to look up the transaction manager at +any JNDI location. - 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. - &feature-enterprise; Configuring Transaction Manager Integration - JPA XML format: - - -]]> - - JDO properties format: - -kodo.TransactionMode: managed -kodo.ManagedRuntime: jndi(TransactionManagerName=java:/TransactionManager) + + +]]> - - 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. - -
XA Transactions @@ -315,6 +277,12 @@ Given these components, setting up OpenJPA to participate in distributed 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 diff --git a/openjpa-project/src/doc/manual/ref_guide_integration.xml b/openjpa-project/src/doc/manual/ref_guide_integration.xml index 08984599c..18cd6a048 100644 --- a/openjpa-project/src/doc/manual/ref_guide_integration.xml +++ b/openjpa-project/src/doc/manual/ref_guide_integration.xml @@ -112,29 +112,27 @@ loaded relative to the current CLASSPATH. </para> <example id="ref_guide_integration_props"> <title> - Using the Properties Attribute of the <config> - Tag + Using the Properties Attribute of the <config> Tag <mappingtool> <fileset dir="${basedir}"> <include name="**/model/*.java"/> </fileset> - <config properties="openjpa-dev.properties"/> + <config properties="openjpa-dev.xml"/> </mappingtool> - Using the PropertiesFile Attribute of the <config> - Tag + Using the PropertiesFile Attribute of the <config> Tag <mappingtool> <fileset dir="${basedir}"> <include name="**/model/*.java"/> </fileset> - <config propertiesFile="../conf/openjpa-dev.properties"/> + <config propertiesFile="../conf/openjpa-dev.xml"/> </mappingtool> @@ -209,15 +207,17 @@ formatting attributes. 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 -openjpac. +versions of the command-line arguments to the + +org.apache.openjpa.enhance.PCEnhancer. The enhancer task accepts a nested fileset tag to specify the files that should be processed. You can specify .java or .class files. If you do not specify any files, the task -will run on the classes listed in your - openjpa.MetaDataFactory property. +will run on the classes listed in your persistence.xml or + +openjpa.MetaDataFactory property. Following is an example of using the enhancer task in a build.xml @@ -266,17 +266,17 @@ Following is an example of using the enhancer task in a build.xml 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 -appidtool -. +correspond exactly to the long versions of the command-line arguments to the + +org.openjpa.enhance.ApplicationIdTool. The application identity tool task accepts a nested fileset tag to specify the files that should be processed. You can specify .java or .class files. If you do not specify any -files, the task will run on the classes listed in your - openjpa.MetaDataFactory - property. +files, the task will run on the classes listed in your persistence.xml + file or +openjpa.MetaDataFactory property. Following is an example of using the application identity tool task in a @@ -330,14 +330,15 @@ object-relational mapping data is always synchronized with your persistent class 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 -mappingtool. +org.apache.openjpa.jdbc.meta.MappingTool. The mapping tool task accepts a nested fileset tag to specify the files that should be processed. You can specify .java or .class files. If you do not specify any files, the task -will run on the classes listed in your - openjpa.MetaDataFactory property. +will run on the classes listed in your persistence.xml file +or +openjpa.MetaDataFactory property. Following is an example of a build.xml target that invokes @@ -389,8 +390,8 @@ The reverse mapping tool task allows you to directly invoke the reverse mapping 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 - -reversemappingtool. + +org.apache.openjpa.jdbc.meta.ReverseMappingTool. Following is an example of a build.xml target that invokes @@ -440,8 +441,8 @@ the reverse mapping tool: 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 - schematool -. + +org.apache.openjpa.jdbc.schema.SchemaTool. Following is an example of a build.xml target that invokes @@ -469,14 +470,4 @@ the schema tool:
-
- - Maven - - - - Maven - - -
diff --git a/openjpa-project/src/doc/manual/ref_guide_optimization.xml b/openjpa-project/src/doc/manual/ref_guide_optimization.xml index 94024aea5..92accc502 100644 --- a/openjpa-project/src/doc/manual/ref_guide_optimization.xml +++ b/openjpa-project/src/doc/manual/ref_guide_optimization.xml @@ -37,10 +37,23 @@ more work onto the server will have a negative impact on scalability. - - + + + + Plugin in a Connection Pool + + +performance, scalability + + + +OpenJPA's built-in datasource does not perform connection pooling or +prepared statement caching. Plugging in a third-party pooling datasource may +drastically improve performance. + + @@ -51,15 +64,11 @@ more work onto the server will have a negative impact on scalability. - - The default set of indexes created by OpenJPA's mapping - tool may not always be the most appropriate for your - application. Manually setting indexes in your mapping - metadata or manually manipulating database indexes to - include frequently-queried fields (as well as dropping - indexes on rarely-queried fields) can yield significant - performance benefits. - +The default set of indexes created by OpenJPA's mapping tool may not always be +the most appropriate for your application. Manually setting indexes in your +mapping metadata or manually manipulating database indexes to include +frequently-queried fields (as well as dropping indexes on rarely-queried +fields) can yield significant performance benefits. A database must do extra work on insert, update, and delete to maintain an index. This extra work will benefit selects with WHERE clauses, which will @@ -76,26 +85,6 @@ or deletes. - - - - Use the best JDBC driver - - -performance, scalability, reliability - - - - - The JDBC driver provided by the database vendor is not - always the fastest and most efficient. Some JDBC drivers - do not support features like batched statements, the lack - of which can significantly slow down OpenJPA's data access - and increase load on the database, reducing system - performance and scalability. - - - @@ -106,16 +95,10 @@ or deletes. - - Manipulating various parameters of the Java Virtual Machine - (such as hotspot compilation modes and the maximum memory) - can result in performance improvements. For more details - about optimizing the JVM execution environment, please see - - - - . - +Manipulating various parameters of the Java Virtual Machine (such as hotspot +compilation modes and the maximum memory) can result in performance +improvements. For more details about optimizing the JVM execution environment, +please see . @@ -128,74 +111,32 @@ or deletes. - - Using OpenJPA's - - data and - query caching - - features can often result - in a dramatic improvement in performance. Additionally, - these caches can significantly reduce the amount of load on - the database, increasing the scalability characteristics of - your application. Also, be sure to read about the - - - concurrent cache - - - option to see if it fits your needs. - +Using OpenJPA's data and query caching +features can often result in a dramatic improvement in performance. +Additionally, these caches can significantly reduce the amount of load on +the database, increasing the scalability characteristics of your application. - Set - - LargeTransaction - - - to true, or set - - PopulateDataCache - - - to false + Set LargeTransaction to true, + or set PopulateDataCache to + false performance vs. scalability - - When using OpenJPA's - - data - caching - - features (available in OpenJPA JDO - Performance Pack and Enterprise Edition) - in a transaction that will delete, modify, or create - a very large number of objects you can set - - - LargeTransaction - - to true and perform periodic - flushes during your transaction to reduce its memory - requirements. See the Javadoc: - - - - OpenJPAEntityManager.setLargeTransaction - - - - - Note that transactions in large mode have to - more aggressively flush items from the data cache. - +When using OpenJPA's data caching +features in a transaction that will delete, modify, or create a very large +number of objects you can set LargeTransaction to true and +perform periodic flushes during your transaction to reduce its memory +requirements. See the Javadoc: + +OpenJPAEntityManager.setLargeTransaction. Note that transactions in +large mode have to more aggressively flush items from the data cache. If your transaction will visit objects that you know are very unlikely to be accessed by other transactions, for example an exhaustive report run only once a @@ -210,94 +151,42 @@ OpenJPAEntityManager.setPopulateDataCache - Disable logging, performance - tracking + Disable logging, performance tracking performance - - Developer options such as verbose logging and the - JDBC performance tracker can result in serious performance - hits for your application. Before evaluating OpenJPA's - performance, these options should all be disabled. - +Developer options such as verbose logging and the JDBC performance tracker can +result in serious performance hits for your application. Before evaluating +OpenJPA's performance, these options should all be disabled. - Set - - IgnoreChanges - - - to true, or set - - FlushBeforeQueries - - to - true + Set IgnoreChanges to true, or + set FlushBeforeQueries to true performance vs. scalability - - When both the - - - openjpa.IgnoreChanges - - - and - - - - - openjpa.FlushBeforeQueries - - - properties are set - to false, OpenJPA needs to consider in-memory dirty instances - during queries. This can sometimes result in OpenJPA needing - to evaluate the entire extent objects in order to - return the correct query results, which can have drastic - performance consequences. If it is appropriate for your - application, configuring - - - FlushBeforeQueries - - - to automatically flush before queries involving dirty - objects will ensure that this never - happens. Setting - - IgnoreChanges - - to - false will result in a small performance hit even if - - - FlushBeforeQueries - - is true, as - incremental flushing is not as efficient overall as - delaying all flushing to a single operation during commit. - This is because incrementally flushing decreases OpenJPA's - ability to maximize statement batching, and increases - resource utilization. - - -Note that the default setting of FlushBeforeQueries is -with-connection, which means that data will be flushed only -if a dedicated connection is already in use by the EntityManager -. So, the default value may not be appropriate for you. - +When both the +openjpa.IgnoreChanges and +openjpa.FlushBeforeQueries + properties are set to false, OpenJPA needs to consider +in-memory dirty instances during queries. This can sometimes result in OpenJPA +needing to evaluate the entire extent objects in order to return the correct +query results, which can have drastic performance consequences. If it is +appropriate for your application, configuring FlushBeforeQueries + to automatically flush before queries involving dirty objects will +ensure that this never happens. Setting IgnoreChanges to +false will result in a small performance hit even if FlushBeforeQueries + is true, as incremental flushing is not as efficient overall as +delaying all flushing to a single operation during commit. Setting IgnoreChanges to true will help performance, since dirty objects can be ignored for queries, meaning that @@ -312,41 +201,26 @@ before queries, since more operations will be performed on the database server. - Configure - - - openjpa.ConnectionRetainMode - - appropriately + Configure openjpa.ConnectionRetainMode + appropriately performance vs. scalability - - The - - - - ConnectionRetainMode - - - configuration option - controls when OpenJPA will obtain a connection, and how long - it will hold that connection. The optimal settings for this - option will vary considerably depending on the particular - behavior of your application. You may even benefit from - using different retain modes for different parts of your - application. - +The ConnectionRetainMode + configuration option controls when OpenJPA will obtain a +connection, and how long it will hold that connection. The optimal settings for +this option will vary considerably depending on the particular behavior of +your application. You may even benefit from using different retain modes for +different parts of your application. The default setting of on-demand minimizes the amount of time that OpenJPA holds onto a datastore connection. This is generally the best option from a scalability standpoind, as database resources are held for a -minimal amount of time. However, if your connection pool is overly small -relative to the number of concurrent sessions that need access to the database, -or if your DataSource is not efficient at managing its +minimal amount of time. However, if you are not using connection pooling, or +if your DataSource is not efficient at managing its pool, then this default value could cause undesirable pool contention. @@ -354,40 +228,17 @@ pool, then this default value could cause undesirable pool contention. - Ensure that batch updates are - available - - -performance, scalability - - - - - When performing bulk inserts, updates, or deletes, OpenJPA - will use batched statements. If this feature is not - available in your JDBC driver, then OpenJPA will need to - issue multiple SQL statements instead of a single batch - statement. - - - - - - - Use - flat inheritance + Use flat inheritance performance, scalability vs. disk space - - Mapping inheritance hierarchies to a single database table - is faster for most operations than other strategies - employing multiple tables. If it is appropriate for your - application, you should use this strategy whenever possible. - +Mapping inheritance hierarchies to a single database table is faster for most +operations than other strategies employing multiple tables. If it is +appropriate for your application, you should use this strategy whenever +possible. However, this strategy will require more disk space on the database side. Disk space is relatively inexpensive, but if your object model is particularly large, @@ -405,15 +256,11 @@ it can become a factor. - - For applications that perform large bulk inserts, the - retrieval of sequence numbers can be a bottleneck. - Increasing sequence increments and using table-based rather - than native database sequences can reduce or eliminate - this bottleneck. In some cases, - implementing your own sequence factory can further optimize - sequence number retrieval. - +For applications that perform large bulk inserts, the retrieval of sequence +numbers can be a bottleneck. Increasing sequence increments and using +table-based rather than native database sequences can reduce or eliminate +this bottleneck. In some cases, implementing your own sequence factory can +further optimize sequence number retrieval. @@ -426,13 +273,10 @@ it can become a factor. - - Using datastore transactions translates into pessimistic - database row locking, which can be a performance hit - (depending on the database). If appropriate for your - application, optimistic transactions are typically faster - than datastore transactions. - +Using datastore transactions translates into pessimistic database row locking, +which can be a performance hit (depending on the database). If appropriate for +your application, optimistic transactions are typically faster than datastore +transactions. Optimistic transactions provide the same transactional guarantees as datastore transactions, except that you must handle a potential optimistic verification @@ -451,21 +295,17 @@ the user redo any work. Use query aggregates and projections - performance, scalability - - Using aggregates to compute reporting data on the database - server can drastically speed up queries. Similarly, using - projections when you are interested in specific - object fields or relations rather than the entire object - state can reduce the amount of data OpenJPA must transfer - from the database to your application. - +Using aggregates to compute reporting data on the database server can +drastically speed up queries. Similarly, using projections when you are +interested in specific object fields or relations rather than the entire object +state can reduce the amount of data OpenJPA must transfer from the database to +your application. @@ -493,30 +333,6 @@ close them, but it is always faster if it is done at the application level. - - - - Optimize connection pool - settings - - -performance, scalability - - - - -OpenJPA's built-in connection pool's default settings may not be optimal for all -applications. For applications that instantiate and close many -EntityManagers (such as a web application), increasing the size of -the connection pool will reduce the overhead of waiting on free connections or -opening new connections. - - -You may want to tune the prepared statement pool size with the connection pool -size. - - - @@ -545,205 +361,91 @@ client tier. - Utilize the - - - EntityManager - - cache + Utilize the EntityManager + cache performance, scalability - - When possible and appropriate, re-using - - - EntityManager - - s and setting the - - - - - RetainState - - - configuration option to - - - true - - may result in significant - performance gains, since the - - - EntityManager - - 's built-in - object cache will be used. - +When possible and appropriate, re-using EntityManagers +and setting the RetainState + configuration option to true may result in +significant performance gains, since the EntityManager's +built-in object cache will be used. - Enable multithreaded operation only - when necessary + Enable multithreaded operation only when necessary performance - - OpenJPA respects the - - - openjpa.Multithreaded - - - option in - that it does not impose synchronization overhead for - applications that set this value to - - - false - - . If your application is - guaranteed to only use single-threaded access to OpenJPA - resources and persistent objects, setting this option to - - - false - - will result - in the elimination of synchronization overhead, and may - result in a modest performance increase. - +OpenJPA respects the +openjpa.Multithreaded option in that it does not impose as +much synchronization overhead for applications that do not set this value to +true. If your application is guaranteed to only use +single-threaded access to OpenJPA resources and persistent objects, leaving +this option as false will reduce synchronization overhead, +and may result in a modest performance increase. - Enable large data set - handling + Enable large data set handling performance, scalability - - If you execute queries that return large numbers of objects - or have relations (collections or maps) that are large, and - if you often only access parts of these data sets, enabling - - - large result set - handling - - where appropriate can - dramatically speed up your application, since OpenJPA will - bring the data sets into memory from the database only as - necessary. - +If you execute queries that return large numbers of objects or have relations +(collections or maps) that are large, and if you often only access parts of +these data sets, enabling large result +set handling where appropriate can dramatically speed up your +application, since OpenJPA will bring the data sets into memory from the +database only as necessary. Disable large data set handling - performance, scalability - - If you have enabled scrollable result sets and on-demand - loading but do you not require it, consider disabling it - again. Some JDBC drivers and databases (SQLServer for - example) are much slower when used with scrolling result - sets. - +If you have enabled scrollable result sets and on-demand loading but do you not +require it, consider disabling it again. Some JDBC drivers and databases +(SQLServer for example) are much slower when used with scrolling result sets. - Use short discriminator values, or - turn off the discriminator - - - -performance, scalability - - - - - The default discriminator strategy of storing the class - name in the discriminator column is quite robust, in that - it can handle any class and needs no configuration, but - the downside of this robustness is that it puts a - relatively lengthy string into each row of the database. - With a little application-specific configuration, you can - easily reduce this to a single character or integer. This - can result in significant performance gains when dealing - with many small objects, - since the subclass indicator data can become a significant - proportion of the data transferred between the JVM and - the database. - - -Alternately, if certain persistent classes in your application do not make use -of inheritance, then you can disable the discriminator for these classes -altogether. - - - - - - - Use the - - - DynamicSchemaFactory - + Use the DynamicSchemaFactory performance, validation - - If you are using a - - - openjpa.jdbc.SchemaFactory - - - setting - of something other than the default of - - - dynamic - - , consider switching back. While other - factories can ensure that object-relational mapping - information is valid when a persistent class is first used, - this can be a slow process. Though the validation is only - performed once for each class, switching back to the - - - DynamicSchemaFactory - - - can reduce the warm-up time for your application. - +If you are using a +openjpa.jdbc.SchemaFactory setting of something other than +the default of dynamic, consider switching back. While other +factories can ensure that object-relational mapping information is valid when +a persistent class is first used, this can be a slow process. Though the +validation is only performed once for each class, switching back to the +DynamicSchemaFactory can reduce the warm-up time for +your application. @@ -756,14 +458,9 @@ altogether. - - XA transactions - - - can be orders of magnitude slower than standard - transactions. Unless distributed transaction functionality - is required by your application, use standard transactions. - +XA transactions can be orders of +magnitude slower than standard transactions. Unless distributed transaction +functionality is required by your application, use standard transactions. Recall that XA transactions are distinct from managed transactions - managed transaction services such as that provided by EJB declarative transactions can @@ -777,88 +474,37 @@ example). - Use - - Set - - s - instead of - - List/Collection - - s - + Use Sets instead of + List/Collections performance, scalability - - There is a small amount of extra overhead for OpenJPA to - maintain collections where each element is not guaranteed - to be unique. If your application does not require - duplicates for a collection, you should always declare your - fields to be of type - - Set, SortedSet, - HashSet, - - or - - TreeSet - - . - +There is a small amount of extra overhead for OpenJPA to maintain collections +where each element is not guaranteed to be unique. If your application does +not require duplicates for a collection, you should always declare your +fields to be of type Set, SortedSet, HashSet, or +TreeSet. - Use query parameters instead of - encoding search data in filter strings - - -performance - - - - - If your queries depend on parameter data only known at - runtime, you should use query parameters rather than - dynamically building different query strings. OpenJPA - performs aggressive caching of query compilation - data, and the effectiveness of this cache is diminished if - multiple query filters are used where a single one could - have sufficed. - - - - - - - Tune your fetch groups - appropriately + Tune your fetch groups appropriately performance, scalability - - The - - fetch groups - - - used when loading an object control how much data is - eagerly loaded, and by extension, which fields must be - lazily loaded at a future time. The ideal fetch group - configuration loads all the data that is needed in one - fetch, and no extra fields - this minimizes both the - amount of data transferred from the database, and the - number of trips to the database. - +The fetch groups used when loading an +object control how much data is eagerly loaded, and by extension, which fields +must be lazily loaded at a future time. The ideal fetch group configuration +loads all the data that is needed in one fetch, and no extra fields - this +minimizes both the amount of data transferred from the database, and the +number of trips to the database. If extra fields are specified in the fetch groups (in particular, large fields such as binary data, or relations to other persistence-capable objects), then @@ -879,16 +525,9 @@ trips to the database to load additional fields as necessary. - - Using - - eager - fetching - - when loading subclass data or traversing - relations for each instance in a large collection of - results can speed up data loading by orders of magnitude. - +Using eager fetching when +loading subclass data or traversing relations for each instance in a large +collection of results can speed up data loading by orders of magnitude. diff --git a/openjpa-project/src/doc/manual/ref_guide_remote.xml b/openjpa-project/src/doc/manual/ref_guide_remote.xml index 001a47dde..143d8347e 100644 --- a/openjpa-project/src/doc/manual/ref_guide_remote.xml +++ b/openjpa-project/src/doc/manual/ref_guide_remote.xml @@ -22,9 +22,9 @@ such as EntityManagers and queries connect directly to the datastore and execute their actions in the same JVM as the code using them. It is online in that all changes to managed objects must be made in the context of an active EntityManager. These -two properties, combined with the fact that EntityManager -s cannot be serialized for storage or network transfer, make the -standard JPA runtime difficult to incorporate into some enterprise and +two properties, combined with the fact that +EntityManagers cannot be serialized for storage or network transfer, +make the standard JPA runtime difficult to incorporate into some enterprise and client/server program designs. @@ -78,9 +78,9 @@ The extended explicitly detach objects at any time. -public Object detach (Object pc): -public Object[] detachAll (Object... pcs): -public Collection detachAll (Collection pcs): +public Object detach(Object pc): +public Object[] detachAll(Object... pcs): +public Collection detachAll(Collection pcs): Each detach method returns detached copies of the given instances. The copy @@ -220,11 +220,9 @@ default. -fgs: Detach all fields and relations in the default fetch -group, and any other fetch groups that you have added to the current +fgs: Detach all fields and relations in the current fetch configuration. For more -information on custom fetch groups, see -. +information on custom fetch groups, see . @@ -330,8 +328,8 @@ for controlling detached state: public static final int DETACH_LOADED; public static final int DETACH_FGS; public static final int DETACH_ALL; -public int getDetachState (); -public void setDetachState (int mode); +public int getDetachState(); +public void setDetachState(int mode);
@@ -365,8 +363,8 @@ import org.apache.openjpa.persistence.*; @Entity public class Magazine - implements Serializable -{ + implements Serializable { + private String name; @DetachedState private Object state; ... @@ -474,7 +472,6 @@ OpenJPA includes built in remote commit providers for JMS and TCP communication. </tertiary> </indexterm> <para> -OpenJPA includes built in remote commit providers for JMS and TCP communication. The JMS remote commit provider can be configured by setting the <link linkend="openjpa.RemoteCommitProvider"><literal> openjpa.RemoteCommitProvider</literal></link> property to contain the @@ -551,7 +548,7 @@ The TCP remote commit provider has several options that are defined as host specifications containing a host name or IP address and an optional port separated by a colon. For example, the host specification <literal> saturn.bea.com:1234</literal> represents an <classname>InetAddress</classname> -retrieved by invoking <methodname>InetAddress.getByName ("saturn.bea.com") +retrieved by invoking <methodname>InetAddress.getByName("saturn.bea.com") </methodname> and a port of 1234. </para> <para> diff --git a/openjpa-project/src/doc/manual/ref_guide_runtime.xml b/openjpa-project/src/doc/manual/ref_guide_runtime.xml index bb47340c0..364427a3e 100644 --- a/openjpa-project/src/doc/manual/ref_guide_runtime.xml +++ b/openjpa-project/src/doc/manual/ref_guide_runtime.xml @@ -85,7 +85,7 @@ The <link linkend="ref_guide_runtime_openjpapersistence"><classname> org.apache.openjpa.persistence.OpenJPAPersistence</classname></link> helper allows you to convert between <classname>EntityManagerFactories</classname> and <classname>BrokerFactories</classname>, <classname>EntityManager</classname>s -and <classname>Broker</classname> s. +and <classname>Broker</classname>s. </para> <section id="ref_guide_runtime_pmextension"> <title> @@ -153,14 +153,14 @@ preventing a straight cast. <classname>OpenJPAPersistence</classname>'s <methodname>cast</methodname> methods work around these proxies. </para> <programlisting> -public static OpenJPAEntityManagerFactory cast (EntityManagerFactory emf); -public static OpenJPAEntityManager cast (EntityManager em); -public static OpenJPAQuery cast (Query q); +public static OpenJPAEntityManagerFactory cast(EntityManagerFactory emf); +public static OpenJPAEntityManager cast(EntityManager em); +public static OpenJPAQuery cast(Query q); </programlisting> <para> We provide additional information on the <classname>OpenJPAPersistence -</classname> helper <link linkend="ref_guide_runtime_openjpapersistence"> below -</link>. +</classname> helper <link linkend="ref_guide_runtime_openjpapersistence"> +below</link>. </para> <section id="ref_guide_runtime_emfactory"> <title> @@ -187,9 +187,8 @@ The <classname>org.apache.openjpa.persistence.OpenJPAEntityManagerFactory </classname> interface extends the basic <classname> javax.persistence.EntityManagerFactory</classname> with OpenJPA-specific features. The <classname>OpenJPAEntityManagerFactory</classname> offers APIs to -obtain managed and unmanaged <classname>EntityManager</classname>s from the -same factory, to access the OpenJPA data and query caches, and to perform other -OpenJPA-specific operations. See the +access the OpenJPA data and query caches and to perform other OpenJPA-specific +operations. See the <ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.html"> interface Javadoc</ulink> for details. </para> @@ -221,7 +220,7 @@ All OpenJPA <classname>EntityManager</classname>s implement the </ulink> interface. This interface extends the standard <classname> javax.persistence.EntityManager</classname>. Just as the standard <classname> EntityManager</classname> is the primary window into JPA services, the -<classname> OpenJPAEntityManager</classname> is the primary window from JPA into +<classname>OpenJPAEntityManager</classname> is the primary window from JPA into OpenJPA-specific functionality. We strongly encourage you to investigate the API extensions this interface contains. </para> @@ -249,8 +248,8 @@ extensions this interface contains. <para> OpenJPA extends JPA's standard query functionality with the <classname> org.apache.openjpa.persistence.OpenJPAQuery</classname> interface. See its -<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAQuery.html">Javadoc</ulink> for -details on the convenience methods it provides. +<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAQuery.html">Javadoc +</ulink> for details on the convenience methods it provides. </para> </section> <section id="ref_guide_runtime_jpaextent"> @@ -290,8 +289,8 @@ import org.apache.openjpa.persistence.*; ... -OpenJPAEntityManager kem = OpenJPAPersistence.cast (em); -Extent<Magazine> mags = kem.getExtent (Magazine.class, false); +OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); +Extent<Magazine> mags = kem.getExtent(Magazine.class, false); for (Magazine m : mags) processMagazine (m); </programlisting> @@ -352,7 +351,7 @@ OpenJPA. </seealso> </indexterm> <para> -Many of the aforementioned OpenJPA interfaces give you access to a <classname> +Many of the aforementioned OpenJPA interfaces give you access to an <classname> org.apache.openjpa.persistence.FetchPlan</classname> instance. The <classname> FetchPlan</classname> allows you to exercise some control over how objects are fetched from the datastore, including <link linkend="ref_guide_dbsetup_lrs"> @@ -366,14 +365,14 @@ OpenJPA goes one step further, extending <classname>FetchPlan</classname> with to add additional JDBC-specific tuning methods. Unless you have customized OpenJPA to use a non-relational back-end (see <xref linkend="ref_guide_enterprise_abstractstore"/> ), all <classname> -FetchPlan</classname>s in OpenJPA implement <classname>JDBCFetchPlan</classname> -, so feel free to cast to this interface. +FetchPlan</classname>s in OpenJPA implement <classname> +JDBCFetchPlan</classname>, so feel free to cast to this interface. </para> <para> Fetch plans pass on from parent components to child components. The <classname> EntityManagerFactory</classname> settings (via your configuration properties) for things like the fetch size, result set type, and custom fetch groups are -passed on to the fetch plan of the <classname> EntityManager</classname>s it +passed on to the fetch plan of the <classname>EntityManager</classname>s it produces. The settings of each <classname>EntityManager</classname>, in turn, are passed on to each <classname>Query</classname> and <classname>Extent </classname> it returns. Note that the opposite, however, is not true. Modifying @@ -384,7 +383,7 @@ configuration does not affect the <classname> EntityManagerFactory</classname>. </para> <para> <xref linkend="ref_guide_fetch"/> includes examples using <classname> -FetchPlan</classname> s. +FetchPlan</classname>s. </para> </section> <section id="ref_guide_runtime_openjpapersistence"> @@ -515,12 +514,12 @@ locked. You can also use the fetch plan of an individual <classname>Query <classname>Query</classname>. </para> <programlisting> -public LockModeType getReadLockMode (); -public FetchPlan setReadLockMode (LockModeType mode); -public LockModeType getWriteLockMode (); -public FetchPlan setWriteLockMode (LockModeType mode); -long getLockTimeout (); -FetchPlan setLockTimeout (long timeout); +public LockModeType getReadLockMode(); +public FetchPlan setReadLockMode(LockModeType mode); +public LockModeType getWriteLockMode(); +public FetchPlan setWriteLockMode(LockModeType mode); +long getLockTimeout(); +FetchPlan setLockTimeout(long timeout); </programlisting> <para> Controlling locking through these runtime APIs works even during optimistic @@ -538,24 +537,24 @@ import org.apache.openjpa.persistence.*; ... EntityManager em = ...; -em.getTransaction ().begin (); +em.getTransaction().begin(); // load stock we know we're going to update at write lock mode -Query q = em.createQuery ("select s from Stock s where symbol = :s"); -q.setParameter ("s", symbol); -OpenJPAQuery kq = OpenJPAPersistence.cast (q); -FetchPlan fetch = kq.getFetchPlan (); -fetch.setReadLockMode (LockModeType.WRITE); -fetch.setLockTimeout (3000); // 3 seconds -Stock stock = (Stock) q.getSingleResult (); +Query q = em.createQuery("select s from Stock s where symbol = :s"); +q.setParameter("s", symbol); +OpenJPAQuery oq = OpenJPAPersistence.cast(q); +FetchPlan fetch = oq.getFetchPlan (); +fetch.setReadLockMode(LockModeType.WRITE); +fetch.setLockTimeout(3000); // 3 seconds +Stock stock = (Stock) q.getSingleResult(); // load an object we don't need locked at none lock mode -fetch = (OpenJPAPersistence.cast (em)).getFetchPlan (); -fetch.setReadLockMode (null); -Market market = em.find (Market.class, marketId); +fetch = OpenJPAPersistence.cast(em).getFetchPlan(); +fetch.setReadLockMode(null); +Market market = em.find(Market.class, marketId); -stock.setPrice (market.calculatePrice (stock)); -em.getTransaction ().commit (); +stock.setPrice(market.calculatePrice(stock)); +em.getTransaction().commit(); </programlisting> </example> </section> @@ -576,7 +575,7 @@ In addition to allowing you to control implicit locking levels, OpenJPA provides explicit APIs to lock objects and to retrieve their current lock level. </para> <programlisting> -public LockModeType OpenJPAEntityManager.getLockMode (Object pc); +public LockModeType OpenJPAEntityManager.getLockMode(Object pc); </programlisting> <para> Returns the level at which the given object is currently locked. @@ -584,19 +583,19 @@ Returns the level at which the given object is currently locked. <para> In addition to the standard <ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html"> -<methodname>EntityManager.lock (Object, LockModeType)</methodname></ulink> +<methodname>EntityManager.lock(Object, LockModeType)</methodname></ulink> method, the <ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"> <classname>OpenJPAEntityManager</classname></ulink> exposes the following methods to lock objects explicitly: </para> <programlisting> -public void lock (Object pc); -public void lock (Object pc, LockModeType mode, long timeout); -public void lockAll (Object... pcs); -public void lockAll (Object... pcs, LockModeType mode, long timeout); -public void lockAll (Collection pcs); -public void lockAll (Collection pcs, LockModeType mode, long timeout); +public void lock(Object pc); +public void lock(Object pc, LockModeType mode, long timeout); +public void lockAll(Object... pcs); +public void lockAll(Object... pcs, LockModeType mode, long timeout); +public void lockAll(Collection pcs); +public void lockAll(Collection pcs, LockModeType mode, long timeout); </programlisting> <para> Methods that do not take a lock level or timeout parameter default to the @@ -610,21 +609,21 @@ current fetch plan. The example below demonstrates these methods in action. import org.apache.openjpa.persistence.*; // retrieve the lock level of an object -OpenJPAEntityManager kem = OpenJPAPersistence.cast (em); +OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); Stock stock = ...; -LockModeType level = kem.getLockMode (stock); +LockModeType level = oem.getLockMode(stock); if (level == OpenJPAModeType.WRITE) ... ... -kem.setOptimistic (true); -kem.getTransaction ().begin (); +oem.setOptimistic(true); +oem.getTransaction().begin (); // override default of not locking during an opt trans to lock stock object -kem.lock (stock, LockModeType.WRITE, 1000); -stock.setPrice (market.calculatePrice (stock)); +oem.lock(stock, LockModeType.WRITE, 1000); +stock.setPrice(market.calculatePrice(stock)); -kem.getTransaction ().commit (); +oem.getTransaction().commit(); </programlisting> </example> </section> @@ -658,9 +657,10 @@ own lock manager, or use one of the bundled options: <para> <literal>pessimistic</literal>: This is an alias for the <ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/PessimisticLockManager.html"> -<classname>org.apache.openjpa.jdbc.kernel.PessimisticLockManager</classname> -</ulink>, which uses SELECT FOR UPDATE statements (or the database's -equivalent) to lock the database rows corresponding to locked objects. This lock +<classname>o +rg.apache.openjpa.jdbc.kernel.PessimisticLockManager</classname></ulink>, which +uses SELECT FOR UPDATE statements (or the database's equivalent) to lock the +database rows corresponding to locked objects. This lock manager does not distinguish between read locks and write locks; all locks are write locks. </para> @@ -685,16 +685,6 @@ does not perform any locking at all. </listitem> <listitem> <para> -<literal>sjvm</literal>: An alias for the -<ulink url="../apidocs/org/apache/openjpa/kernel/SingleJVMExclusiveLockManager.html"> -<classname>org.apache.openjpa.kernel.SingleJVMExclusiveLockManager</classname> -</ulink>. This lock manager uses in-memory mutexes to obtain exclusive locks on -object ids. It does not perform any database-level locking. Also, it does not -distinguish between read and write locks; all locks are write locks. - </para> - </listitem> - <listitem> - <para> <literal>version</literal>: An alias for the <ulink url="../apidocs/org/apache/openjpa/kernel/VersionLockManager.html"> <classname>org.apache.openjpa.kernel.VersionLockManager</classname></ulink>. @@ -839,16 +829,16 @@ locks the object. The only way to positively guarantee that the object is locked and has the most recent state to refresh the object after locking it. </para> <para> -When using the default lock manager, the case above can only occur when OpenJPA -cannot issue the state-loading SELECT as a locking statement due to database -limitations. For example, some databases cannot lock SELECTs that use joins. The -default lock manager will log an INFO message to the <literal>openjpa.Runtime -</literal> logging channel whenever it cannot lock the initial SELECT due to -database limitations. By paying attention to these log messages, you can see -where you might consider using an object refresh to guarantee that you have the -most recent state, or where you might rethink the way you load the state in -question to circumvent the database limitations that prevent OpenJPA from -issuing a locking SELECT in the first place. +When using the pessimistic lock manager, the case above can only occur when +OpenJPA cannot issue the state-loading SELECT as a locking statement due to +database limitations. For example, some databases cannot lock SELECTs that use +joins. The pessimistic lock manager will log an INFO message to the <literal> +openjpa.Runtime</literal> logging channel whenever it cannot lock the initial +SELECT due to database limitations. By paying attention to these log messages, +you can see where you might consider using an object refresh to guarantee that +you have the most recent state, or where you might rethink the way you load the +state in question to circumvent the database limitations that prevent OpenJPA +from issuing a locking SELECT in the first place. </para> </listitem> </itemizedlist> @@ -888,9 +878,9 @@ transaction, and that a rollback of the transaction will rollback all of the changes in the transaction regardless of any savepoints set. </para> <programlisting> -void setSavepoint (String name); -void releaseSavepoint (String name); -void rollbackToSavepoint (String name); +void setSavepoint(String name); +void releaseSavepoint(String name); +void rollbackToSavepoint(String name); </programlisting> <para> To set a savepoint, simply call <methodname>setSavepoint</methodname>, passing @@ -910,9 +900,9 @@ still set new savepoints. Savepoints will also be cleared after the current transaction is committed or rolled back. </para> <para> -If a savepoint is no longer needed, you can release any resources such as in -memory state and datastore resources by calling <methodname>releaseSavepoint -</methodname>. This method should not be called for savepoints that have been +If a savepoint is no longer needed, you can release any resources it is +consuming resources by calling <methodname>releaseSavepoint</methodname>. This +method should not be called for savepoints that have been released automatically through other means, such as commit of a transaction or rollback to a prior savepoint. While savepoints made after this savepoint will also be released, there are no other effects on the current transaction. @@ -930,26 +920,26 @@ import org.apache.openjpa.persistence.*; ... -OpenJPAEntityManager kem = OpenJPAPersistence.cast (em); -kem.getTransaction ().begin (); +OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); +oem.getTransaction().begin(); -Magazine mag = kem.find (Magazine.class, id); -mag.setPageCount (300); -kem.setSavepoint ("pages"); +Magazine mag = oem.find(Magazine.class, id); +mag.setPageCount(300); +oem.setSavepoint("pages"); -mag.setPrice (mag.getPageCount () * pricePerPage); +mag.setPrice(mag.getPageCount() * pricePerPage); // we decide to release pages since price depends on pages. -kem.releaseSavepoint ("pages"); -kem.setSavepoint ("price"); +oem.releaseSavepoint("pages"); +oem.setSavepoint("price"); -mag.setPrice (testPrice); +mag.setPrice(testPrice); ... // we determine the test price is not good -kem.rollbackToSavepoint ("price"); +oem.rollbackToSavepoint("price"); -// the price is now restored to mag.getPageCount () * pricePerPage -kem.getTransaction ().commit (); +// the price is now restored to mag.getPageCount() * pricePerPage +oem.getTransaction().commit(); </programlisting> </example> </section> @@ -1000,6 +990,7 @@ implements savepoints by issuing a flush to the database. </itemizedlist> </section> </section> + <!-- <section id="ref_guide_enterprise_queryext"> <title> Query Language Extensions @@ -1020,7 +1011,6 @@ JPQL is a powerful, easy-to-use query language, but you may occasionally find it limiting in some way. To circumvent the limitations of JPQL, OpenJPA provides extensions to the JPQL language, and allows you to extend it as well. </para> - <!-- ### --> <warning> <para> The JPQL parser in this release does not yet allow extensions. They will be made @@ -1275,6 +1265,7 @@ Javadoc</ulink> for details. </itemizedlist> </section> </section> + --> <section id="ref_guide_enterprise_methodql"> <title> MethodQL @@ -1311,36 +1302,23 @@ import org.apache.openjpa.persistence.*; // the class is in the candidate class' package or in the query imports, you // can omit the package; if the method is in the candidate class, you can omit // the class name and just specify the method name -OpenJPAEntityManager kem = OpenJPAPersistence.cast (emf); -OpenJPAQuery q = kem.createQuery ("openjpa.MethodQL", "com.xyz.Finder.getByName"); +OpenJPAEntityManager oem = OpenJPAPersistence.cast(emf); +OpenJPAQuery q = oem.createQuery("openjpa.MethodQL", "com.xyz.Finder.getByName"); // set the type of objects that the method returns -q.setResultClass (Person.class); +q.setResultClass(Person.class); // parameters are passed the same way as in standard queries -q.setParameter ("firstName", "Fred").setParameter ("lastName", "Lucas"); +q.setParameter("firstName", "Fred").setParameter("lastName", "Lucas"); // this executes your method to get the results -List results = q.getResultList (); +List results = q.getResultList(); </programlisting> <para> For datastore queries, the method must have the following signature: </para> <programlisting> -public static -<ulink url="../apidocs/org/apache/openjpa/lib/rop/ResultObjectProvider.html">ResultObjectProvider -</ulink> - xxx( -<ulink url="../apidocs/org/apache/openjpa/kernel/StoreContext.html">StoreContext -</ulink> - ctx, - -<ulink url="../apidocs/org/apache/openjpa/meta/ClassMetaData.html">ClassMetaData -</ulink> - meta, boolean subclasses, Map params, -<ulink url="../apidocs/org/apache/openjpa/kernel/FetchConfiguration.html">FetchConfiguration -</ulink> - fetch) +public static <ulink url="../apidocs/org/apache/openjpa/lib/rop/ResultObjectProvider.html">ResultObjectProvider</ulink> xxx(<ulink url="../apidocs/org/apache/openjpa/kernel/StoreContext.html">StoreContext</ulink> ctx, <ulink url="../apidocs/org/apache/openjpa/meta/ClassMetaData.html">ClassMetaData</ulink> meta, boolean subclasses, Map params, <ulink url="../apidocs/org/apache/openjpa/kernel/FetchConfiguration.html">FetchConfiguration </ulink> fetch) </programlisting> <para> The returned result object provider should produce objects of the candidate @@ -1354,24 +1332,16 @@ In-memory execution is slightly different, taking in one object at a time and returning a boolean on whether the object matches the query: </para> <programlisting> -public static boolean xxx( -<ulink url="../apidocs/org/apache/openjpa/kernel/StoreContext.html">StoreContext -</ulink> - ctx, -<ulink url="../apidocs/org/apache/openjpa/meta/ClassMetaData.html">ClassMetaData -</ulink> - meta, - boolean subclasses, Object obj, Map params, -<ulink url="../apidocs/org/apache/openjpa/kernel/FetchConfiguration.html">FetchConfiguration -</ulink> - fetch) +public static boolean xxx(<ulink url="../apidocs/org/apache/openjpa/kernel/StoreContext.html">StoreContext</ulink> ctx, <ulink url="../apidocs/org/apache/openjpa/meta/ClassMetaData.html">ClassMetaData</ulink> meta, boolean subclasses, Object obj, Map params, <ulink url="../apidocs/org/apache/openjpa/kernel/FetchConfiguration.html">FetchConfiguration</ulink> fetch) </programlisting> <para> In both method versions, the given <literal>params</literal> map contains the names and values of all the parameters for the query. </para> </section> + <!-- </section> + --> <section id="ref_guide_sequence"> <title> Generators @@ -1398,7 +1368,7 @@ including the current persistence environment, the JDBC <classname>DataSource <ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/AbstractJDBCSeq.html"> <classname>org.apache.openjpa.jdbc.kernel.AbstractJDBCSeq</classname></ulink> helps you create custom JDBC-based sequences. OpenJPA also supplies the -following built-in <classname>Seq</classname> s: +following built-in <classname>Seq</classname>s: </para> <itemizedlist> <listitem> @@ -1418,11 +1388,10 @@ alias for the class. The <classname>TableJDBCSeq</classname> uses a special single-row table to store a global sequence number. If the table does not already exist, it is created the first time you run the -<link linkend="ref_guide_mapping_mappingtool"> mapping tool</link>'s on a class -that requires it. You can also use the class' <methodname>main</methodname> -method or the <literal>sequencetable</literal> shell/bat script to manipulate -the table; see the <methodname>TableJDBCSeq.main</methodname> method Javadoc for -usage details. +<link linkend="ref_guide_mapping_mappingtool">mapping tool</link> on a class +that requires it. You can also use the class's <methodname>main</methodname> +method to manipulate the table; see the +<methodname>TableJDBCSeq.main</methodname> method Javadoc for usage details. </para> <para> This <classname>Seq</classname> has the following properties: @@ -1480,8 +1449,8 @@ OPENJPA_SEQUENCES_TABLE</literal>. It also adds the following properties: <listitem> <para> <literal>IgnoreUnmapped</literal>: Whether to ignore unmapped base classes, and -instead use one row per least-derived mapped class. Defaults to <literal>false -</literal>. +instead use one row per least-derived mapped class. Defaults to <literal> +false</literal>. </para> </listitem> <listitem> @@ -1496,8 +1465,7 @@ primary key value of each row, rather than the full class name. Defaults to As with the <classname>TableJDBCSeq</classname>, the <classname> ClassTableJDBCSeq</classname> creates its table automatically during mapping tool runs. However, you can manually manipulate the table through the class' -<methodname>main</methodname> method, or through the <literal> -classsequencetable</literal> shell/bat script. See the Javadoc for the +<methodname>main</methodname> method. See the Javadoc for the <methodname> ClassTableJDBCSeq.main</methodname> method for usage details. </para> </listitem> @@ -1523,8 +1491,7 @@ rather than a fixed pattern of one row per class. Its table defaults to <itemizedlist> <listitem> <para> -<literal>PrimaryKeyValue</literal>: The primary key value used by this -instance. +<literal>PrimaryKeyValue</literal>: The primary key value used by this instance. </para> </listitem> </itemizedlist> @@ -1532,9 +1499,8 @@ instance. As with the <classname>TableJDBCSeq</classname>, the <classname> ValueTableJDBCSeq</classname> creates its table automatically during mapping tool runs. However, you can manually manipulate the table through the class' -<methodname>main</methodname> method, or through the <literal> -valuesequencetable</literal> shell/bat script. See the Javadoc for the -<methodname> ValueTableJDBCSeq.main</methodname> method for usage details. +<methodname>main</methodname> method. See the Javadoc for the +<methodname>ValueTableJDBCSeq.main</methodname> method for usage details. </para> </listitem> <listitem> @@ -1573,8 +1539,7 @@ properties: </listitem> <listitem> <para> -<literal>Increment</literal>: The amount the sequence increments. Defaults to -1. +<literal>Increment</literal>: The amount the sequence increments. Defaults to 1. </para> </listitem> <listitem> @@ -1610,7 +1575,7 @@ You can use JPA <literal>SequenceGenerator</literal>s to describe any built-in implementation. Set the <literal>sequenceName</literal> attribute to a plugin string describing your choice. See <xref linkend="jpa_overview_mapping_sequence"/> in the JPA Overview for -details on defining <literal>SequenceGenerator</literal> s. +details on defining <literal>SequenceGenerator</literal>s. </para> <para> See <xref linkend="ref_guide_conf_plugins"/> for plugin string formatting. @@ -1622,8 +1587,8 @@ See <xref linkend="ref_guide_conf_plugins"/> for plugin string formatting. <programlisting> @Entity @Table(name="AUTO") -public class Author -{ +public class Author { + @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="AuthorSeq") @SequenceGenerator(name="AuthorSeq" sequence="table(Table=AUTO_SEQ, Increment=100)") @@ -1685,7 +1650,7 @@ OpenJPA allows you to access named generators at runtime through the <methodname>OpenJPAEntityManager.getNamedGenerator</methodname> method: </para> <programlisting> -public Generator getNamedGenerator (String name); +public Generator getNamedGenerator(String name); </programlisting> <para> The returned @@ -1728,8 +1693,8 @@ and more. Where appropriate, event notifications include the set of persistence-capable objects participating in the transaction. </para> <programlisting> -public void addTransactionListener (Object listener); -public void removeTransactionListener (Object listener); +public void addTransactionListener(Object listener); +public void removeTransactionListener(Object listener); </programlisting> <para> These <classname>OpenJPAEntityManager</classname> methods allow you to add and diff --git a/openjpa-project/src/doc/manual/supported_databases.xml b/openjpa-project/src/doc/manual/supported_databases.xml index 1d88529c5..7129d3c92 100644 --- a/openjpa-project/src/doc/manual/supported_databases.xml +++ b/openjpa-project/src/doc/manual/supported_databases.xml @@ -68,9 +68,7 @@ by OpenJPA. 6.0 </entry> <entry colname="drivname"> - - Borland JDataStore - + Borland JDataStore </entry> <entry colname="drivversion"> 6.0 @@ -84,9 +82,7 @@ by OpenJPA. 8.1 </entry> <entry colname="drivname"> - - IBM DB2 JDBC Universal Driver - + IBM DB2 JDBC Universal Driver </entry> <entry colname="drivversion"> 1.0.581 @@ -100,9 +96,7 @@ by OpenJPA. 8.62 </entry> <entry colname="drivname"> - - Empress Category 2 JDBC Driver - + Empress Category 2 JDBC Driver </entry> <entry colname="drivversion"> 8.62 @@ -172,9 +166,7 @@ by OpenJPA. 9.0 (a.k.a. "2000") </entry> <entry colname="drivname"> - - DataDirect SequeLink - + DataDirect SequeLink </entry> <entry colname="drivversion"> 5.4.0038 @@ -185,9 +177,7 @@ by OpenJPA. Microsoft SQL Server </entry> <entry colname="dbversion"> - - 9.00.1399 (SQL Server 2005) - + 9.00.1399 (SQL Server 2005) </entry> <entry colname="drivname"> SQLServer @@ -204,9 +194,7 @@ by OpenJPA. 7.0 </entry> <entry colname="drivname"> - - DataDirect SequeLink - + DataDirect SequeLink </entry> <entry colname="drivversion"> 5.4.0038 @@ -270,9 +258,7 @@ by OpenJPA. </row> <row> <entry colname="dbname"> - - Sybase Adaptive Server Enterprise - + Sybase Adaptive Server Enterprise </entry> <entry colname="dbversion"> 12.5 @@ -318,19 +304,20 @@ openjpa.ConnectionURL: jdbc:interbase://SERVER_NAME:SERVER_PORT/DB_PATH <title> Known issues with Interbase - - Interbase does not support record locking, so + + + +Interbase does not support record locking, so datastore transactions cannot use the pessimistic lock manager. - - - - + + + + Interbase does not support the LOWER, SUBSTRING , or INSTR SQL functions> - - - - + + +
@@ -364,24 +351,24 @@ openjpa.ConnectionURL: jdbc:db2://SERVER_NAME:SERVER_PORT/DB_NAME Known issues with DB2 - -Floats and doubles may lose precision when -stored. - - - - + + + +Floats and doubles may lose precision when stored. + + + + Empty char values are stored as NULL. - - - - + + + + Fields of type BLOB and CLOB are limited to 1M. This number can be increased by extending DB2Dictionary. - - - - + + +
@@ -401,19 +388,20 @@ openjpa.ConnectionURL: jdbc:empress://SERVER=yourserver;PORT=6322;DATABASE=yourd Known issues with Empress - - Empress enforces pessimistic semantics (lock on + + + +Empress enforces pessimistic semantics (lock on read) when not using AllowConcurrentRead property (which bypasses row locking) for EmpressDictionary. - - - - + + + + Only the category 2 non-local driver is supported. - - - - + + +
@@ -433,20 +421,15 @@ openjpa.ConnectionURL: jdbc:hsqldb:DB_NAME Known issues with Hypersonic - - Hypersonic does not properly support foreign key -constraints. - - - - + + + Hypersonic does not support pessimistic locking, so non-optimistic transactions will fail unless the SimulateLocking property is set for the openjpa.jdbc.DBDictionary - - - - + + +
@@ -466,24 +449,19 @@ openjpa.ConnectionURL: jdbc:firebirdsql://SERVER_NAME:SERVER_PORT/DB_PATH Known issues with Firebird - - The Firebird JDBC driver does not have proper -support for batch updates, so batch updates are disabled. - - - - + + + Firebird does not support auto-increment columns. - - - - + + + + Firebird does not support the LOWER, SUBSTRING , or INSTR SQL functions. - - - - + + +
@@ -504,12 +482,13 @@ openjpa.ConnectionURL: \ Known issues with Informix - - none - - - - + + + +None + + +
@@ -529,13 +508,14 @@ openjpa.ConnectionURL: jdbc:Cache://SERVER_NAME:SERVER_PORT/DB_NAME Known issues with InterSystems Cache - - Support for Cache is done via SQL access over -JDBC, not through their object database APIs. - - - - + + + +Support for Cache is done via SQL access over JDBC, not through their object +database APIs. + + +
@@ -555,13 +535,13 @@ openjpa.ConnectionURL: jdbc:sequelink://SERVER_NAME:SERVER_PORT Known issues with Microsoft Access - -Using the Sun JDBC-ODBC bridge to connect is not -supported. - - - - + + + +Using the Sun JDBC-ODBC bridge to connect is not supported. + + +
@@ -582,42 +562,43 @@ openjpa.ConnectionURL: \ Known issues with SQL Server - - SQL Server date fields are accurate only to the -nearest 3 milliseconds, possibly resulting in precision loss in stored dates. - - - - + + + +SQL Server date fields are accurate only to the nearest 3 milliseconds, +possibly resulting in precision loss in stored dates. + + + + The ConnectionURL must always contain the " selectMethod=cursor " string. - - - - + + + + Adding sendStringParametersAsUnicode=false to the ConnectionURL may significantly increase performance. - - - - + + + + The Microsoft SQL Server driver only emulates batch updates. The DataDirect JDBC driver has true support for batch updates, and may result in a significant performance gain. - - - - + + + + Floats and doubles may lose precision when stored. - - - - + + + + TEXT columns cannot be used in queries. - - - - + + +
@@ -637,13 +618,13 @@ openjpa.ConnectionURL: jdbc:sequelink://SERVER_NAME:SERVER_PORT Known issues with Microsoft FoxPro - -Using the Sun JDBC-ODBC bridge to connect is not -supported. - - - - + + + +Using the Sun JDBC-ODBC bridge to connect is not supported. + + +
@@ -663,52 +644,52 @@ openjpa.ConnectionURL: jdbc:mysql://SERVER_NAME/DB_NAME Known issues with MySQL - - The default table types that MySQL uses do not -support transactions, which will prevent OpenJPA from being able to roll back -transactions. Use the InnoDB table type for any tables that -OpenJPA will access. - - - - + + + +The default table types that MySQL uses do not support transactions, which will +prevent OpenJPA from being able to roll back transactions. Use the +InnoDB table type for any tables that OpenJPA will access. + + + + MySQL does not support sub-selects in versions prior to 4.1, and are disabled by default. Some operations (such as the isEmpty() method in a query) will fail due to this. If you are using MySQL 4.1 or later, you can lift this restriction by setting the SupportsSubselect=true parameter of the openjpa.jdbc.DBDictionary property. - - - - + + + + Rollback due to database error or optimistic lock violation is not supported unless the table type is one of the MySQL transactional types. Explicit calls to rollback() before a transaction has been committed, however, are always supported. - - - - + + + + Floats and doubles may lose precision when stored in some datastores. - - - - + + + + When storing a field of type java.math.BigDecimal, some datastores will add extraneous trailing 0 characters, causing an equality mismatch between the field that is stored and the field that is retrieved. - - - - + + + + Some version of the MySQL JDBC driver have a bug that prevents OpenJPA from being able to interrogate the database for foreign keys. Version 3.0.14 (or higher) of the MySQL driver is required in order to get around this bug. - - - - + + +
@@ -740,16 +721,9 @@ the most intensive queries. Using Oracle Hints -Query query = pm.createQuery (...); -query.addExtension (org.apache.openjpa.jdbc.sql.OracleDictionary.SELECT_HINT, - "/*+ first_rows(100) */"); -List results = (List) query.execute (); - - -Query query = em.createQuery (...); -query.setHint (org.apache.openjpa.jdbc.sql.OracleDictionary.SELECT_HINT, - "/*+ first_rows(100) */"); -List results = query.getResultList (); +Query query = em.createQuery(...); +query.setHint("openjpa.hint.OracleSelectHint", "/*+ first_rows(100) */"); +List results = query.getResultList();
@@ -757,49 +731,49 @@ List results = query.getResultList (); Known issues with Oracle - - The Oracle JDBC driver has significant -differences between different versions. It is important to use the officially -supported version of the driver (10.2.0.1.0), which is backward compatible with -previous versions of the Oracle server. It can be downloaded from + + + +The Oracle JDBC driver has significant differences between different versions. +It is important to use the officially supported version of the driver +(10.2.0.1.0), which is backward compatible with previous versions of the Oracle +server. It can be downloaded from -http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc101040.html -. - - - - +http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc101040.html. + + + + For VARCHAR fields, null and a blank string are equivalent. This means that an object that stores a null string field will have it get read back as a blank string. - - - - + + + + Oracle corp's JDBC driver for Oracle has only limited support for batch updates. The result for OpenJPA is that in some cases, the exact object that failed an optimistic lock check cannot be determined, and OpenJPA will throw an OptimisticVerificationException with more failed objects than actually failed. - - - - + + + + Oracle cannot store numbers with more than 38 digits in numeric columns. - - - - + + + + Floats and doubles may lose precision when stored. - - - - + + + + CLOB columns cannot be used in queries. - - - - + + +
@@ -820,14 +794,15 @@ openjpa.ConnectionURL: \ Known issues with Pointbase - - Fields of type BLOB and CLOB are limited to 1M. -This number can be increased by extending PointbaseDictionary -. - - - - + + + +Fields of type BLOB and CLOB are limited to 1M. Set the BlobTypeName + and/or ClobTypeName properties of the +openjpa.jdbc.DBDictionary setting to override. + + +
@@ -847,23 +822,23 @@ openjpa.ConnectionURL: jdbc:postgresql://SERVER_NAME:5432/DB_NAME Known issues with PostgreSQL - - Floats and doubles may lose precision when -stored. - - - - + + + +Floats and doubles may lose precision when stored. + + + + PostgreSQL cannot store very low and very high dates. - - - - + + + + Empty string/char values are stored as NULL. - - - - + + +
@@ -884,35 +859,36 @@ openjpa.ConnectionURL: \ Known issues with Sybase - - The " DYNAMIC_PREPARE " -parameter of the Sybase JDBC driver cannot be used with OpenJPA. - - - - + + + +The "DYNAMIC_PREPARE" parameter of the Sybase JDBC driver +cannot be used with OpenJPA. + + + + Datastore locking cannot be used when manipulating many-to-many relations using the default OpenJPA schema created by the schematool, unless an auto-increment primary key field is manually added to the table. - - - - + + + + Persisting a zero-length string results in a string with a single space characted being returned from Sybase, Inc.'s JDBC driver. - - - - + + + + The BE_AS_JDBC_COMPLIANT_AS_POSSIBLE is required in order to use datastore (pessimistic) locking. Failure to set this property may lead to obscure errors like " FOR UPDATE can not be used in a SELECT which is not part of the declaration of a cursor or which is not inside a stored procedure. ". - - - - + + +