Author: mtylenda
Date: Tue Mar 29 20:19:30 2011
New Revision: 1086719
URL: http://svn.apache.org/viewvc?rev=1086719&view=rev
Log:
OPENJPA-1932: Documentation update: remove Java 5 references (OpenJPA requires
Java 6), remove sjvm setting from examples (no longer needed), improve
formatting (we should remember to use literal/classname tags), fix typos.
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml?rev=1086719&r1=1086718&r2=1086719&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_intro.xml Tue Mar
29 20:19:30 2011
@@ -35,11 +35,9 @@
JPA
</primary>
</indexterm>
-The Java Persistence API (JPA) is a specification
+The Java Persistence 2.0 API (JPA 2.0) is a specification
for the persistence of Java objects to any relational
-datastore. JPA requires J2SE 1.5 (also referred to as "Java 5") or
-higher, as it makes heavy use of new Java language features such as annotations
-and generics. This document provides an overview of JPA. Unless
+datastore. This document provides an overview of JPA 2.0. Unless
otherwise noted, the information presented applies to all JPA implementations.
</para>
<note>
@@ -55,7 +53,7 @@ see the <link linkend="ref_guide_intro">
<para>
This document is intended for developers who want to learn about JPA
in order to use it in their applications. It assumes that you have a strong
-knowledge of object-oriented concepts and Java, including Java 5 annotations
and
+knowledge of object-oriented concepts and Java, including annotations and
generics. It also assumes some experience with relational databases and the
Structured Query Language (SQL).
</para>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml?rev=1086719&r1=1086718&r2=1086719&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml Tue Mar
29 20:19:30 2011
@@ -136,10 +136,7 @@ a distributed environment, as caches in
<para>
To enable the basic single-factory cache set the
<link linkend="openjpa.DataCache"><literal>openjpa.DataCache</literal></link>
-property to <literal>true</literal>, and set the
-<link linkend="openjpa.RemoteCommitProvider"><literal>
-openjpa.RemoteCommitProvider</literal></link> property to <literal>sjvm
-</literal>:
+property to <literal>true</literal>:
</para>
<example id="ref_guide_cache_conf_sjvm">
<title>
@@ -147,7 +144,6 @@ openjpa.RemoteCommitProvider</literal></
</title>
<programlisting>
<property name="openjpa.DataCache" value="true"/>
-<property name="openjpa.RemoteCommitProvider" value="sjvm"/>
</programlisting>
</example>
<para>
@@ -186,7 +182,7 @@ scalable as the default map.
</para>
<example id="ref_guide_cache_conf_lru">
<title>
- Data Cache Size
+ Lru Cache
</title>
<programlisting>
<property name="openjpa.DataCache" value="true(Lru=true)"/>
@@ -237,19 +233,20 @@ public class Employee {
<secondary>exclusions</secondary>
</indexterm>
Entities may be explicitly excluded from the cache by providing a
- list of fully qualified class names in the ExcludedTypes argument.
- The entities provided via ExcludedTypes will not be cached
- regardless of the @DataCache annotation.
+ list of fully qualified class names in the
<literal>ExcludedTypes</literal> argument.
+ The entities provided via <literal>ExcludedTypes</literal> will
not be cached
+ regardless of the <classname>DataCache</classname> annotation.
</para>
<example id="ex_exclude_types_from_cache">
<title>
Excluding entities
</title>
<para>
- Exclude entities foo.bar.Person and foo.bar.Employee from
the cache.
- <programlisting>
+ Exclude entities <classname>foo.bar.Person</classname> and
+ <classname>foo.bar.Employee</classname> from the cache.
+<programlisting>
<property name="openjpa.DataCache"
value="true(ExcludedTypes=foo.bar.Person;foo.bar.Employee)"/>
- </programlisting>
+</programlisting>
</para>
</example>
@@ -258,10 +255,9 @@ public class Employee {
<primary>caching</primary>
<secondary>inclusions</secondary>
</indexterm>
- Entities may be explicitly included from the cache by providing a
- list of fully qualified class names in the Types argument.
- The entities provided via ExcludedTypes will not cached regardless
- of the @DataCache annotation. Any entities which are not included
+ Entities may be explicitly included in the cache by providing a
+ list of fully qualified class names in the
<literal>Types</literal> argument.
+ Any entities which are not included
in this list will not be cached.
</para>
<example id="ex_include_types_in_cache">
@@ -269,10 +265,10 @@ public class Employee {
Including entities
</title>
<para>
- Include only entity foo.bar.FullTimeEmployee from the
cache.
- <programlisting>
+ Include only entity
<classname>foo.bar.FullTimeEmployee</classname> in the cache.
+<programlisting>
<property name="openjpa.DataCache"
value="true(Types=foo.bar.FullTimeEmployee)"/>
- </programlisting>
+</programlisting>
</para>
</example>
<para>
@@ -337,8 +333,8 @@ format of this property is a <literal>+<
between each time that the cache should be evicted.
</para>
<para>
-For example, the following openjpa.DataCache setting schedules the default
cache
-to evict values from the cache every 120 minutes.
+For example, the following <literal>openjpa.DataCache</literal> setting
schedules the default cache
+to evict values from the cache every 120 minutes.
</para>
<para>
<programlisting>
@@ -350,8 +346,8 @@ true(EvictionSchedule='+120')
Bulk updates and cache eviction
</title>
<para>
-For the example, setting EvictOnBulkUpdate to false will tell OpenJPA to not
evict from the DataCache when executing
-and UPDATE or DELETE statement. The default for the value is true.
+Setting <literal>EvictOnBulkUpdate</literal> to <literal>false</literal> will
tell OpenJPA to not evict from the DataCache when executing
+an UPDATE or DELETE statement. The default for the value is
<literal>true</literal>.
</para>
<para>
<programlisting><property name="openjpa.DataCache"
value="true(EvictOnBulkUpdate=false)"/></programlisting>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml?rev=1086719&r1=1086718&r2=1086719&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml Tue Mar
29 20:19:30 2011
@@ -91,13 +91,13 @@ distribution if you are using the normal
</para>
<para>
To disable the automatic usage of Apache Commons DBCP when it is discovered
-on the classpath, then set -
+on the classpath, set
<literal>openjpa.jdbc.DriverDataSource=simple</literal>, which will revert
OpenJPA to the prior behavior of using
<classname>org.apache.openjpa.jdbc.schema.SimpleDriverDataSource</classname>
</para>
<para>
To force usage of Apache Commons DBCP, which will cause a fatal exception to
-be thrown if it cannot be loaded from the classpath, then set -
+be thrown if it cannot be loaded from the classpath, set
<literal>openjpa.jdbc.DriverDataSource=dbcp</literal>, which will cause
OpenJPA to use
<classname>org.apache.openjpa.jdbc.schema.DBCPDriverDataSource</classname>
</para>
@@ -115,8 +115,8 @@ OpenJPA to use <classname>org.apache.ope
</secondary>
</indexterm>
<para>
-If you choose to use OpenJPA's <classname>DataSource
-</classname>, then you must specify the following properties:
+If you choose to use OpenJPA's <classname>DataSource</classname>,
+then you must specify the following properties:
</para>
<itemizedlist>
<listitem>
@@ -560,9 +560,9 @@ about the database in use (e.g. version,
<section id="ref_guide_dbsetup_setDSError">
<title>Error handling</title>
<para>
- If a JTA DataSource is not available when the
EntityManager is created an
- <link
linkend=""><literal>ArgumentException</literal></link> will be thrown.
- The EntityManager will not fall back on the JTA DataSource
defined in the
+ If a JTA DataSource is not available when the
EntityManager is created, an
+ <literal>IllegalArgumentException</literal> will be thrown.
+ The EntityManager will not fall back to the JTA DataSource
defined in the
configuration.
</para>
<para>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml?rev=1086719&r1=1086718&r2=1086719&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_deploy.xml Tue Mar
29 20:19:30 2011
@@ -72,7 +72,7 @@ bound to JNDI as well.
EntityManager Injection
</title>
<para>
-Java EE 5 application servers allow you to <emphasis>inject</emphasis>
+Java EE application servers allow you to <emphasis>inject</emphasis>
entity managers into your session beans using the <literal>PersistenceContext
</literal> annotation. See your application server documentation for details.
</para>
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml?rev=1086719&r1=1086718&r2=1086719&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
Tue Mar 29 20:19:30 2011
@@ -62,7 +62,6 @@
<property name="openjpa.DataCache"
value="true(EnableStatistics=true)"/>
<property name="openjpa.QueryCache"
value="true(EnableStatistics=true)"/>
<property name="openjpa.jdbc.QuerySQLCache"
value="true(EnableStatistics=true)"/>
- <property name="openjpa.RemoteCommitProvider" value="sjvm"/>
<!-- Enable jmx provider and instruments for Data, Query, and
QuerySQL caches -->
<property name="openjpa.Instrumentation"
value="jmx(Instrument='DataCache,QueryCache,QuerySQLCache')"/>
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml?rev=1086719&r1=1086718&r2=1086719&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml Tue
Mar 29 20:19:30 2011
@@ -601,7 +601,7 @@ collection of results can speed up data
</para>
</entry>
<entry colname="desc">
-Outside of a Java EE 5 application server or other JPA persistence container,
+Outside of a Java EE application server or other JPA persistence container,
OpenJPA's EntityManagers use finalizers to ensure that resources
get cleaned up. If you are properly managing your resources, this finalization
is not necessary, and will introduce unneeded synchronization, leading to
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml?rev=1086719&r1=1086718&r2=1086719&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml Tue Mar 29
20:19:30 2011
@@ -274,14 +274,14 @@ class load error, simply re-compile and
</tertiary>
</indexterm>
<para>
-The Java EE 5 specification includes hooks to automatically enhance JPA
entities
-when they are deployed into a container. Thus, if you are using a Java EE
-5-compliant application server, OpenJPA will enhance your entities
automatically
+The Java EE specification includes hooks to automatically enhance JPA entities
+when they are deployed into a container. Thus, if you are using a Java
EE-compliant application server,
+OpenJPA will enhance your entities automatically
at runtime. Note that if you prefer build-time enhancement, OpenJPA's runtime
enhancer will correctly recognize and skip pre-enhanced classes.
</para>
<para>
-If your application server does not support the Java EE 5 enhancement hooks,
+If your application server does not support the Java EE enhancement hooks,
consider using the build-time enhancement described above, or the more general
runtime enhancement described in the next section.
</para>
@@ -454,7 +454,7 @@ state tracking, depending on the executi
<itemizedlist>
<listitem><para>
<emphasis>Deploy-time enhancement</emphasis>: if you are running your
-application inside a Java EE 5 container, or another environment that supports
+application inside a Java EE container, or another environment that supports
the JPA container contract, then OpenJPA will automatically perform class
transformation at deploy time.
</para></listitem>
@@ -497,14 +497,14 @@ notifications when you read or write per
<para>
<note>
Runtime Unenhanced Classes has some known limitations which are discussed below
-and documented in JIRA issues on the OpenJPA website. As a result this option
is
+and documented in JIRA issue tracker on the OpenJPA website. As a result this
option is
disabled by default. Support for this method of automatic enhancement may be
-enabled via the<xref linkend="openjpa.RuntimeUnenhancedClasses">
-openjpa.RuntimeUnenhancedClasses configuration </xref>option.
+enabled via the <xref linkend="openjpa.RuntimeUnenhancedClasses">
+openjpa.RuntimeUnenhancedClasses configuration </xref> option.
</note>
</para>
<para>
-To enable Runtime Unenhanced Classes for a specific persistence unit add the
following property to persistence.xml :
+To enable Runtime Unenhanced Classes for a specific persistence unit, add the
following property to persistence.xml:
<programlisting>
<