You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/10/04 01:00:18 UTC
svn commit: r452672 [2/3] - in /incubator/openjpa/trunk:
openjpa-persistence/src/main/java/org/apache/openjpa/persistence/
openjpa-project/src/doc/manual/
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml?view=diff&rev=452672&r1=452671&r2=452672
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml Tue Oct 3 16:00:18 2006
@@ -37,13 +37,26 @@
</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="name"/>
-
<colspec colname="desc" colwidth="4*"/>
-
<tbody valign="top">
<row>
<entry colname="name">
<emphasis role="bold">
+ Plugin in a Connection Pool
+ </emphasis>
+ <para>
+<emphasis>performance, scalability</emphasis>
+ </para>
+ </entry>
+ <entry colname="desc">
+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.
+ </entry>
+ </row>
+ <row>
+ <entry colname="name">
+ <emphasis role="bold">
Optimize database indexes
</emphasis>
<para>
@@ -51,15 +64,11 @@
</para>
</entry>
<entry colname="desc">
-
- 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.
<para>
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
@@ -79,26 +88,6 @@
<row>
<entry colname="name">
<emphasis role="bold">
- Use the best JDBC driver
- </emphasis>
- <para>
-<emphasis>performance, scalability, reliability</emphasis>
- </para>
- </entry>
- <entry colname="desc">
-
- 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.
-
- </entry>
- </row>
- <row>
- <entry colname="name">
- <emphasis role="bold">
JVM optimizations
</emphasis>
<para>
@@ -106,16 +95,10 @@
</para>
</entry>
<entry colname="desc">
-
- 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
-
- <ulink url="http://java.sun.com/docs/hotspot/PerformanceFAQ.html">
- </ulink>
- .
-
+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 <ulink url="http://java.sun.com/docs/hotspot/PerformanceFAQ.html"/>.
</entry>
</row>
<row>
@@ -128,74 +111,32 @@
</para>
</entry>
<entry colname="desc">
-
- Using OpenJPA's
- <link linkend="ref_guide_cache">
- data and
- query caching
- </link>
- 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
-
- <link linkend="ref_guide_cache_concurrent">
- concurrent cache
-
- </link>
- option to see if it fits your needs.
-
+Using OpenJPA's <link linkend="ref_guide_cache">data and query caching</link>
+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.
</entry>
</row>
<row>
<entry colname="name">
<emphasis role="bold">
- Set
- <literal>
- LargeTransaction
-
- </literal>
- to true, or set
- <literal>
- PopulateDataCache
-
- </literal>
- to false
+ Set <literal>LargeTransaction</literal> to true,
+ or set <literal> PopulateDataCache</literal> to
+ false
</emphasis>
<para>
<emphasis>performance vs. scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- When using OpenJPA's
- <link linkend="ref_guide_cache">
- data
- caching
- </link>
- 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
- <literal>
-
- LargeTransaction
- </literal>
- to true and perform periodic
- flushes during your transaction to reduce its memory
- requirements. See the Javadoc:
-
- <ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
-
- OpenJPAEntityManager.setLargeTransaction
- </ulink>
-
-
-
- Note that transactions in large mode have to
- more aggressively flush items from the data cache.
-
+When using OpenJPA's <link linkend="ref_guide_cache">data caching</link>
+features in a transaction that will delete, modify, or create a very large
+number of objects you can set <literal>LargeTransaction</literal> to true and
+perform periodic flushes during your transaction to reduce its memory
+requirements. See the Javadoc:
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
+OpenJPAEntityManager.setLargeTransaction</ulink>. Note that transactions in
+large mode have to more aggressively flush items from the data cache.
<para>
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 @@
<row>
<entry colname="name">
<emphasis role="bold">
- Disable logging, performance
- tracking
+ Disable logging, performance tracking
</emphasis>
<para>
<emphasis>performance</emphasis>
</para>
</entry>
<entry colname="desc">
-
- 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.
</entry>
</row>
<row>
<entry colname="name">
<emphasis role="bold">
- Set
- <literal>
- IgnoreChanges
- </literal>
-
- to true, or set
- <literal>
- FlushBeforeQueries
- </literal>
- to
- true
+ Set <literal>IgnoreChanges</literal> to true, or
+ set <literal>FlushBeforeQueries</literal> to true
</emphasis>
<para>
<emphasis>performance vs. scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- When both the
- <link linkend="openjpa.IgnoreChanges">
- <literal>
- openjpa.IgnoreChanges
- </literal>
- </link>
- and
-
- <link linkend="openjpa.FlushBeforeQueries">
- <literal>
-
- openjpa.FlushBeforeQueries
- </literal>
- </link>
- 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
-
- <literal>
- FlushBeforeQueries
- </literal>
-
- to automatically flush before queries involving dirty
- objects will ensure that this never
- happens. Setting
- <literal>
- IgnoreChanges
- </literal>
- to
- false will result in a small performance hit even if
-
- <literal>
- FlushBeforeQueries
- </literal>
- 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.
-
- <para>
-Note that the default setting of <literal>FlushBeforeQueries</literal> is
-<literal>with-connection</literal>, which means that data will be flushed only
-if a dedicated connection is already in use by the <classname>EntityManager
-</classname>. So, the default value may not be appropriate for you.
- </para>
+When both the <link linkend="openjpa.IgnoreChanges"><literal>
+openjpa.IgnoreChanges</literal></link> and
+<link linkend="openjpa.FlushBeforeQueries"><literal>openjpa.FlushBeforeQueries
+</literal></link> 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 <literal>FlushBeforeQueries
+</literal> to automatically flush before queries involving dirty objects will
+ensure that this never happens. Setting <literal>IgnoreChanges</literal> to
+false will result in a small performance hit even if <literal>FlushBeforeQueries
+</literal> is true, as incremental flushing is not as efficient overall as
+delaying all flushing to a single operation during commit.
<para>
Setting <literal>IgnoreChanges</literal> to <literal>true</literal> will help
performance, since dirty objects can be ignored for queries, meaning that
@@ -312,41 +201,26 @@
<row>
<entry colname="name">
<emphasis role="bold">
- Configure
- <literal>
-
- openjpa.ConnectionRetainMode
- </literal>
- appropriately
+ Configure <literal>openjpa.ConnectionRetainMode
+ </literal> appropriately
</emphasis>
<para>
<emphasis>performance vs. scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- The
- <link linkend="openjpa.ConnectionRetainMode">
- <literal>
-
- ConnectionRetainMode
- </literal>
- </link>
- 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 <link linkend="openjpa.ConnectionRetainMode"><literal>ConnectionRetainMode
+</literal></link> 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.
<para>
The default setting of <literal>on-demand</literal> 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 <classname>DataSource</classname> is not efficient at managing its
+minimal amount of time. However, if you are not using connection pooling, or
+if your <classname>DataSource</classname> is not efficient at managing its
pool, then this default value could cause undesirable pool contention.
</para>
</entry>
@@ -354,40 +228,17 @@
<row>
<entry colname="name">
<emphasis role="bold">
- Ensure that batch updates are
- available
- </emphasis>
- <para>
-<emphasis>performance, scalability</emphasis>
- </para>
- </entry>
- <entry colname="desc">
-
- 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.
-
- </entry>
- </row>
- <row>
- <entry colname="name">
- <emphasis role="bold">
- Use
- flat inheritance
+ Use flat inheritance
</emphasis>
<para>
<emphasis>performance, scalability vs. disk space</emphasis>
</para>
</entry>
<entry colname="desc">
-
- 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.
<para>
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 @@
</para>
</entry>
<entry colname="desc">
-
- 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.
</entry>
</row>
<row>
@@ -426,13 +273,10 @@
</para>
</entry>
<entry colname="desc">
-
- 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.
<para>
Optimistic transactions provide the same transactional guarantees as datastore
transactions, except that you must handle a potential optimistic verification
@@ -451,21 +295,17 @@
<entry colname="name">
<emphasis role="bold">
Use query aggregates and projections
-
</emphasis>
<para>
<emphasis>performance, scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- 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.
</entry>
</row>
<row>
@@ -496,30 +336,6 @@
<row>
<entry colname="name">
<emphasis role="bold">
- Optimize connection pool
- settings
- </emphasis>
- <para>
-<emphasis>performance, scalability</emphasis>
- </para>
- </entry>
- <entry colname="desc">
- <para>
-OpenJPA's built-in connection pool's default settings may not be optimal for all
-applications. For applications that instantiate and close many <classname>
-EntityManager</classname>s (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.
- </para>
- <para>
-You may want to tune the prepared statement pool size with the connection pool
-size.
- </para>
- </entry>
- </row>
- <row>
- <entry colname="name">
- <emphasis role="bold">
Use detached state managers
</emphasis>
<para>
@@ -545,205 +361,91 @@
<row>
<entry colname="name">
<emphasis role="bold">
- Utilize the
- <classname>
-
- EntityManager
- </classname>
- cache
+ Utilize the <classname>EntityManager</classname>
+ cache
</emphasis>
<para>
<emphasis>performance, scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- When possible and appropriate, re-using
- <classname>
-
- EntityManager
- </classname>
- s and setting the
-
- <link linkend="openjpa.RetainState">
- <literal>
-
- RetainState
- </literal>
- </link>
- configuration option to
-
- <literal>
- true
- </literal>
- may result in significant
- performance gains, since the
- <classname>
-
- EntityManager
- </classname>
- 's built-in
- object cache will be used.
-
+When possible and appropriate, re-using <classname>EntityManager</classname>s
+and setting the <link linkend="openjpa.RetainState"><literal>RetainState
+</literal></link> configuration option to <literal>true</literal> may result in
+significant performance gains, since the <classname>EntityManager</classname>'s
+built-in object cache will be used.
</entry>
</row>
<row>
<entry colname="name">
<emphasis role="bold">
- Enable multithreaded operation only
- when necessary
+ Enable multithreaded operation only when necessary
</emphasis>
<para>
<emphasis>performance</emphasis>
</para>
</entry>
<entry colname="desc">
-
- OpenJPA respects the
- <link linkend="openjpa.Multithreaded">
- <literal>
- openjpa.Multithreaded
- </literal>
- </link>
- option in
- that it does not impose synchronization overhead for
- applications that set this value to
-
- <literal>
- false
- </literal>
- . If your application is
- guaranteed to only use single-threaded access to OpenJPA
- resources and persistent objects, setting this option to
-
- <literal>
- false
- </literal>
- will result
- in the elimination of synchronization overhead, and may
- result in a modest performance increase.
-
+OpenJPA respects the <link linkend="openjpa.Multithreaded"><literal>
+openjpa.Multithreaded</literal></link> option in that it does not impose as
+much synchronization overhead for applications that do not set this value to
+<literal>true</literal>. If your application is guaranteed to only use
+single-threaded access to OpenJPA resources and persistent objects, leaving
+this option as <literal>false</literal> will reduce synchronization overhead,
+and may result in a modest performance increase.
</entry>
</row>
<row>
<entry colname="name">
<emphasis role="bold">
- Enable large data set
- handling
+ Enable large data set handling
</emphasis>
<para>
<emphasis>performance, scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- 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
-
- <link linkend="ref_guide_dbsetup_lrs">
- large result set
- handling
- </link>
- 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 <link linkend="ref_guide_dbsetup_lrs">large result
+set handling</link> where appropriate can dramatically speed up your
+application, since OpenJPA will bring the data sets into memory from the
+database only as necessary.
</entry>
</row>
<row>
<entry colname="name">
<emphasis role="bold">
Disable large data set handling
-
- </emphasis>
- <para>
-<emphasis>performance, scalability</emphasis>
- </para>
- </entry>
- <entry colname="desc">
-
- 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.
-
- </entry>
- </row>
- <row>
- <entry colname="name">
- <emphasis role="bold">
- Use short discriminator values, or
- turn off the discriminator
-
</emphasis>
<para>
<emphasis>performance, scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- 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.
-
- <para>
-Alternately, if certain persistent classes in your application do not make use
-of inheritance, then you can disable the discriminator for these classes
-altogether.
- </para>
+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.
</entry>
</row>
<row>
<entry colname="name">
<emphasis role="bold">
- Use the
- <classname>
-
- DynamicSchemaFactory
- </classname>
+ Use the <classname>DynamicSchemaFactory</classname>
</emphasis>
<para>
<emphasis>performance, validation</emphasis>
</para>
</entry>
<entry colname="desc">
-
- If you are using a
- <link linkend="openjpa.jdbc.SchemaFactory">
- <literal>
- openjpa.jdbc.SchemaFactory
- </literal>
- </link>
- setting
- of something other than the default of
- <literal>
-
- dynamic
- </literal>
- , 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
-
- <classname>
- DynamicSchemaFactory
- </classname>
-
- can reduce the warm-up time for your application.
-
+If you are using a <link linkend="openjpa.jdbc.SchemaFactory"><literal>
+openjpa.jdbc.SchemaFactory</literal></link> setting of something other than
+the default of <literal>dynamic</literal>, 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
+<classname>DynamicSchemaFactory</classname> can reduce the warm-up time for
+your application.
</entry>
</row>
<row>
@@ -756,14 +458,9 @@
</para>
</entry>
<entry colname="desc">
- <link linkend="ref_guide_enterprise_xa">
- XA transactions
-
- </link>
- can be orders of magnitude slower than standard
- transactions. Unless distributed transaction functionality
- is required by your application, use standard transactions.
-
+<link linkend="ref_guide_enterprise_xa">XA transactions</link> can be orders of
+magnitude slower than standard transactions. Unless distributed transaction
+functionality is required by your application, use standard transactions.
<para>
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 @@
<row>
<entry colname="name">
<emphasis role="bold">
- Use
- <classname>
- Set
- </classname>
- s
- instead of
- <classname>
- List/Collection
- </classname>
- s
-
+ Use <classname>Set</classname>s instead of
+ <classname>List/Collection</classname>s
</emphasis>
<para>
<emphasis>performance, scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- 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
- <classname>
- Set, SortedSet,
- HashSet,
- </classname>
- or
- <classname>
- TreeSet
- </classname>
- .
-
- </entry>
- </row>
- <row>
- <entry colname="name">
- <emphasis role="bold">
- Use query parameters instead of
- encoding search data in filter strings
- </emphasis>
- <para>
-<emphasis>performance</emphasis>
- </para>
- </entry>
- <entry colname="desc">
-
- 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.
-
+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 <classname>Set, SortedSet, HashSet,</classname> or
+<classname>TreeSet</classname>.
</entry>
</row>
<row>
<entry colname="name">
<emphasis role="bold">
- Tune your fetch groups
- appropriately
+ Tune your fetch groups appropriately
</emphasis>
<para>
<emphasis>performance, scalability</emphasis>
</para>
</entry>
<entry colname="desc">
-
- The
- <link linkend="ref_guide_fetch">
- fetch groups
- </link>
-
- 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 <link linkend="ref_guide_fetch">fetch groups</link> 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.
<para>
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 @@
</para>
</entry>
<entry colname="desc">
-
- Using
- <link linkend="ref_guide_perfpack_eager">
- eager
- fetching
- </link>
- 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 <link linkend="ref_guide_perfpack_eager">eager fetching</link> 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.
</entry>
</row>
</tbody>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml?view=diff&rev=452672&r1=452671&r2=452672
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml Tue Oct 3 16:00:18 2006
@@ -22,9 +22,9 @@
the datastore and execute their actions in the same JVM as the code using them.
It is <emphasis>online</emphasis> in that all changes to managed objects must be
made in the context of an active <classname> EntityManager</classname>. These
-two properties, combined with the fact that <classname> EntityManager
-</classname>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 <classname>
+EntityManager</classname>s cannot be serialized for storage or network transfer,
+make the standard JPA runtime difficult to incorporate into some enterprise and
client/server program designs.
</para>
<para>
@@ -78,9 +78,9 @@
explicitly detach objects at any time.
</para>
<programlisting>
-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):
</programlisting>
<para>
Each detach method returns detached copies of the given instances. The copy
@@ -220,11 +220,9 @@
</listitem>
<listitem>
<para>
-<literal>fgs</literal>: Detach all fields and relations in the default fetch
-group, and any other fetch groups that you have added to the current
+<literal>fgs</literal>: Detach all fields and relations in the current
<link linkend="ref_guide_runtime">fetch configuration</link>. For more
-information on custom fetch groups, see <xref linkend="ref_guide_fetch"/>
-.
+information on custom fetch groups, see <xref linkend="ref_guide_fetch"/>.
</para>
</listitem>
<listitem>
@@ -330,8 +328,8 @@
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);
</programlisting>
<section id="ref_guide_detach_field">
<title>
@@ -365,8 +363,8 @@
@Entity
public class Magazine
- implements Serializable
-{
+ implements Serializable {
+
private String name;
@DetachedState private Object state;
...
@@ -474,7 +472,6 @@
</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 @@
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>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml?view=diff&rev=452672&r1=452671&r2=452672
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml Tue Oct 3 16:00:18 2006
@@ -85,7 +85,7 @@
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 @@
<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 @@
</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 @@
</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 @@
<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 @@
...
-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 @@
</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 @@
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 @@
</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 @@
<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 @@
...
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 @@
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 @@
<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 @@
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 @@
<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 @@
</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 @@
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 @@
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 @@
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 @@
...
-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 @@
</itemizedlist>
</section>
</section>
+ <!--
<section id="ref_guide_enterprise_queryext">
<title>
Query Language Extensions
@@ -1020,7 +1011,6 @@
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 @@
</itemizedlist>
</section>
</section>
+ -->
<section id="ref_guide_enterprise_methodql">
<title>
MethodQL
@@ -1311,36 +1302,23 @@
// 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 @@
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 @@
<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 @@
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 @@
<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 @@
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 @@
<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 @@
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 @@
</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 @@
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 @@
<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 @@
<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 @@
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