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.

git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@1086719 13f79535-47bb-0310-9956-ffa450edef68

openjpa-project/src/doc/manual/jpa_overview_intro.xml

@@ -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
+datastore. This document provides an overview of JPA 2.0. Unless
-higher, as it makes heavy use of new Java language features such as annotations
-and generics. This document provides an overview of JPA. Unless
 otherwise noted, the information presented applies to all JPA implementations.
     </para>
     <note>
@@ -55,7 +53,7 @@ see the <link linkend="ref_guide_intro">Reference Guide</link>.
         <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>

openjpa-project/src/doc/manual/ref_guide_caching.xml

@@ -136,10 +136,7 @@ a distributed environment, as caches in different JVMs or created from different
             <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
+property to <literal>true</literal>:
-<link linkend="openjpa.RemoteCommitProvider"><literal>
-openjpa.RemoteCommitProvider</literal></link> property to <literal>sjvm
-</literal>:
             </para>
             <example id="ref_guide_cache_conf_sjvm">
                 <title>
@@ -147,7 +144,6 @@ openjpa.RemoteCommitProvider</literal></link> property to <literal>sjvm
                 </title>
 <programlisting>
 &lt;property name="openjpa.DataCache" value="true"/&gt;
-&lt;property name="openjpa.RemoteCommitProvider" value="sjvm"/&gt;
 </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>
 &lt;property name="openjpa.DataCache" value="true(Lru=true)"/&gt;
@@ -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. 
+            list of fully qualified class names in the <literal>ExcludedTypes</literal> argument. 
-            The entities provided via ExcludedTypes will not be cached 
+            The entities provided via <literal>ExcludedTypes</literal> will not be cached 
-            regardless of the @DataCache annotation. 
+            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. 
+                    Exclude entities <classname>foo.bar.Person</classname> and
-                    <programlisting>
+                    <classname>foo.bar.Employee</classname> from the cache. 
+<programlisting>
 &lt;property name="openjpa.DataCache" value="true(ExcludedTypes=foo.bar.Person;foo.bar.Employee)"/&gt;
-                    </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
+            Entities may be explicitly included in the cache by providing a
-            list of fully qualified class names in the Types argument.
+            list of fully qualified class names in the <literal>Types</literal> argument.
-            The entities provided via ExcludedTypes will not cached regardless
+            Any entities which are not included
-            of the @DataCache annotation. 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. 
+                    Include only entity <classname>foo.bar.FullTimeEmployee</classname> in the cache.
-                    <programlisting>
+<programlisting>
 &lt;property name="openjpa.DataCache" value="true(Types=foo.bar.FullTimeEmployee)"/&gt;
-                    </programlisting>
+</programlisting>
                 </para>
             </example>
             <para>
@@ -337,7 +333,7 @@ format of this property is a <literal>+</literal> followed by the number of minu
 between each time that the cache should be evicted.
             </para>
             <para>            
-For example, the following openjpa.DataCache setting schedules the default cache 
+For example, the following <literal>openjpa.DataCache</literal> setting schedules the default cache
 to evict values from the cache every 120 minutes.
             </para>
             <para>            
@@ -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
+Setting <literal>EvictOnBulkUpdate</literal> to <literal>false</literal> will tell OpenJPA to not evict from the DataCache when executing
-and UPDATE or DELETE statement. The default for the value is true.                
+an UPDATE or DELETE statement. The default for the value is <literal>true</literal>.
                 </para>
                 <para> 
 <programlisting>&lt;property name="openjpa.DataCache" value="true(EvictOnBulkUpdate=false)"/&gt;</programlisting>

openjpa-project/src/doc/manual/ref_guide_dbsetup.xml

@@ -91,13 +91,13 @@ distribution if you are using the normal <literal>openjpa.jar</literal>.
             </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.openjpa.jdbc.schema.DBCPDriverDataSource</c
                 </secondary>
             </indexterm>
             <para>
-If you choose to use OpenJPA's <classname>DataSource
+If you choose to use OpenJPA's <classname>DataSource</classname>,
-</classname>, then you must specify the following properties:
+then you must specify the following properties:
             </para>
             <itemizedlist>
             <listitem>
@@ -560,9 +560,9 @@ about the database in use (e.g. version, JDBC driver 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 
+                    If a JTA DataSource is not available when the EntityManager is created, an 
-                    <link linkend=""><literal>ArgumentException</literal></link> will be thrown.
+                    <literal>IllegalArgumentException</literal> will be thrown.
-                    The EntityManager will not fall back on the JTA DataSource defined in the 
+                    The EntityManager will not fall back to the JTA DataSource defined in the 
                     configuration. 
                     </para> 
                     <para>

openjpa-project/src/doc/manual/ref_guide_deploy.xml

@@ -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>

openjpa-project/src/doc/manual/ref_guide_instrumentation.xml

@@ -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')"/>

openjpa-project/src/doc/manual/ref_guide_optimization.xml

@@ -601,7 +601,7 @@ collection of results can speed up data loading by orders of magnitude.
                         </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

openjpa-project/src/doc/manual/ref_guide_pc.xml

@@ -274,14 +274,14 @@ class load error, simply re-compile and re-enhance the offending classes.
                 </tertiary>
             </indexterm>
             <para>
-The Java EE 5 specification includes hooks to automatically enhance JPA entities
+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
+when they are deployed into a container. Thus, if you are using a Java EE-compliant application server,
-5-compliant application server, OpenJPA will enhance your entities automatically
+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 execution environment.
             <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 persistent data.
                 <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">
+enabled via the <xref linkend="openjpa.RuntimeUnenhancedClasses">
-openjpa.RuntimeUnenhancedClasses configuration </xref>option.
+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>
 <![CDATA[<properties> 
     . . .

openjpa-project/src/doc/manual/ref_guide_runtime.xml

@@ -122,7 +122,7 @@ and <classname>Broker</classname>s.
                 </tertiary>
             </indexterm>
             <para>
-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
 environment, the default OpenJPAEntityManager implementation automatically
 closes itself during instance finalization. This guards against accidental
 resource leaks that may occur if a developer fails to explicitly close