OPENJPA-1932: Documentation update: remove Java 5 references, improve formatting and wording, point out that getSupportedProperties is an OpenJPA extension (no longer in the JPA 2.0 spec), remove link to criteria API draft (criteria API is in the final 2.0 spec).

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

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

@@ -38,7 +38,7 @@
         </see>
     </indexterm>
     <para>
-    JPA 2.0 Specification introduces a new API to define queries dynamically
+    JPA 2.0 specification introduces a new API to define queries dynamically
     via construction of an object-based 
     <classname>javax.persistence.CriteriaQuery</classname> instance, rather
     than string-based approach used in JPQL (Java Persistence Query Language).
@@ -116,7 +116,7 @@ Root&lt;Order&gt; order = customer.join(customer.get(Customer_.orders));
     <section>
     <title>Executing a CriteriaQuery</title>
     <para>
-    A CriteriaQuery is executed in a similar fashion of a string-based JPQL
+    A CriteriaQuery is executed in a similar fashion to a string-based JPQL
     query via the EntityManager and Query interfaces.
     <programlisting>
 EntityManager em = ...
@@ -130,12 +130,6 @@ List result = query.getResultList();
     </para>
     
     <para>
-    The JPA 2.0 Specification on Criteria API can be found at 
-    <ulink url="http://jcp.org/aboutJava/communityprocess/pr/jsr317/index.html">
-    public draft</ulink>.
-    </para>
-    <para>
-    
     <ulink url="http://www.ibm.com/developerworks/java/library/j-typesafejpa/">A developerworks article</ulink>
     explains details and further usage of Criteria API and its OpenJPA extensions.  
     </para>
@@ -145,18 +139,18 @@ List result = query.getResultList();
     <title>Extension to Criteria API</title>
     <para>
     Criteria API has provided an alternative means to string-based JPQL to 
-    execute a query. However, JPA 2.0 Specification has not explicitly specified 
+    execute a query. However, JPA 2.0 specification has not explicitly specified 
     any equivalence between a dynamically constructed CriteriaQuery and
     a JPQL string. OpenJPA provides a mechanism to convert a CriteriaQuery to
     an equivalent JPQL query string via the extended OpenJPACriteriaQuery API.
     <programlisting>
-    	public interface OpenJPACriteriaQuery extends CriteriaQuery {
+public interface OpenJPACriteriaQuery extends CriteriaQuery {
-		/**
+    /**
-	 	 * Gets equivalent JPQL String for the given CriteriaQuery.
+     * Gets equivalent JPQL String for the given CriteriaQuery.
- 		*/
+     */
-		public String toCQL();
+    public String toCQL();
-	}
+}
-	</programlisting>
+    </programlisting>
     
     </para>
     </section>
@@ -197,7 +191,7 @@ The Annotation Processor recognizes the following options specified in the comma
                -Aopenjpa.naming=class name : fully-qualified name of a class implementing 
                <code>org.apache.openjpa.meta.MetaDataFactory</code> that determines
 the name of a meta-class given the name of the original persistent Java entity class. Defaults to
-<code>org.apache.openjpa.persistence.PersistenceMetaDataFactory</code> which appends a underscore character
+<code>org.apache.openjpa.persistence.PersistenceMetaDataFactory</code> which appends an underscore character
 (<code>_</code>) to the original Java class name. 
              </para>
         </listitem>
@@ -205,7 +199,7 @@ the name of a meta-class given the name of the original persistent Java entity c
 			<para>
                -Aopenjpa.header=&lt;url&gt; : A url whose content will appear as comment header to the generated file(s). 
                Recognizes special value <code>ASL</code> for Apache Source License header as comment. 
-               By default, adds a OpenJPA proprietary text as comment block.
+               By default, adds an OpenJPA proprietary text as comment block.
              </para>
         </listitem>
     </itemizedlist>

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

@@ -446,7 +446,7 @@ public PersistenceUnitUtil getPersistenceUnitUtil();
 </programlisting>
         <para>
 The <classname>EntityManagerFactory</classname> method 
-<methodname>getPersistenceUnitUtil</methodname> to provide access to a 
+<methodname>getPersistenceUnitUtil</methodname> provides access to a 
 <classname>PersistenceUnitUtil</classname> utility. <classname>PersistenceUnitUtil</classname>
 can be used to obtain the identity of a managed object and determine the load
 state of the entity or one of its attributes.  If the object is not
@@ -461,7 +461,7 @@ if (puUtil.getIdentifier(deptEntity) == null) {
     throw new Exception("Identity is not valid.");
 }
 if (!puUtil.isLoaded(deptEntity, "employees")) {
-    throw new Exception("Employees not loaded.")
+    throw new Exception("Employees not loaded.");
 }
 </programlisting>
         </para>

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

@@ -65,7 +65,7 @@ simply reflecting on the persistent class.
             annotations
         </primary>
     </indexterm>
-Persistence metadata is specified using either the Java 5 annotations defined in
+Persistence metadata is specified using either the Java annotations defined in
 the <literal>javax.persistence</literal> package, XML mapping files, or a
 mixture of both. In the latter case, XML declarations override conflicting
 annotations. If you choose to use XML metadata, the XML files must be available

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

@@ -882,7 +882,7 @@ To specify an isolation level, specify a hint name of "openjpa.FetchPlan.Is
                     Other Fetchplan Hints
                 </title>
                 <para>
-Any property of  an OpenJPA FetchPlan can be changed using a hint by using a name of the form &quot;openjpa.FetchPlan.&quot;&lt;property name&gt;.Valid property names include :
+Any property of  an OpenJPA FetchPlan can be changed using a hint by using a name of the form &quot;openjpa.FetchPlan.&quot;&lt;property name&gt;. Valid property names include:
 <classname>MaxFetchDepth</classname>, <classname>FetchBatchSize</classname>, <classname>LockTimeOut</classname>, <classname>EagerFetchMode</classname>, <classname>SubclassFetchMode</classname> and <classname>Isolation</classname>.
                 </para>
             </section>

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

@@ -50,8 +50,8 @@
                     The OpenJPAEntityManagerFactory interface getProperties()
                     method was changed to return a Map instead of a
                     Properties object. This change was made in order to
-                    support the getProperties() method defined in the 2.0
+                    support the getProperties() method defined in the
-                    JPA specification.
+                    JPA 2.0 specification.
                 </para>
             </section>
             <section id="migration_detach_behavior">

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

@@ -77,7 +77,7 @@ The openjpa-all aggregate JAR includes software developed by the:
     Apache Geronimo project (JMS 1.1, JTA 1.1 and JPA 2.0 spec APIs)
                 </para></listitem>
                 <listitem><para>
-    JCP JSR-317 JPA 2.0 Schemas
+    JCP JSR-317 JPA 2.0 schemas
                 </para></listitem>
                 <listitem><para>
     SERP project

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

@@ -19,7 +19,7 @@
 -->
 <para>
 There are two sets of properties that may be specified: those that
-are specific to openjpa and those that have been defined by the JPA
+are specific to OpenJPA and those that have been defined by the JPA
 specification. In some cases, two properties may be equivalent, but
 have different keys. For example, <emphasis>openjpa.LockTimeout
 </emphasis> and <emphasis>javax.persistence.lock.timeout</emphasis>
@@ -28,24 +28,35 @@ are two different keys for the same property.
 <para>
 There are two methods that can be used to retrieve information related to
 properties:
+<programlisting>
+public Map&lt;String,Object&gt; getProperties();
+public Set&lt;String&gt; getSupportedProperties();
+</programlisting>
 	<itemizedlist>
 		<listitem>
 			<para>
-			getProperties() - This method provides a list of current 
+			<methodname>getProperties</methodname> - Provides a list of current 
 			properties. If a property has more than one key, the key
 			that will be returned is the one that was used when the
 			property was set. If the property was not explicitly
-			set, the key defined by JPA specification will be returned 
+			set, the key defined by the JPA specification will be returned 
 			with the default value.
 			</para>
 		</listitem>
 		<listitem>
 			<para>
-			getSupportedProperties() - This method returns a set of
+			<methodname>getSupportedProperties</methodname> - Returns a set of
-			property keys. See the javadoc in the latest JPA
+			supported property keys. This includes keys defined by the JPA
-			specification for the definition of the set. If a property
+			specification as well as keys specific to OpenJPA.
+			If a property
 			has more than one key, all possible keys will be returned.
 			</para>
 		</listitem>
 	</itemizedlist>
 </para>
+<note>
+	<para>
+		The <methodname>getSupportedProperties</methodname> method is an OpenJPA
+		extension to the JPA specification.
+	</para>
+</note>

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

@@ -303,7 +303,7 @@ java org.apache.openjpa.enhance.ApplicationIdTool -cf.spaceBeforeParen true -cf.
         <para>
 Because OpenJPA is a highly customizable environment, many configuration
 properties relate to the creation and configuration of system plugins. Plugin
-properties have a syntax very similar to that of Java 5 annotations. They allow
+properties have a syntax very similar to that of Java annotations. They allow
 you to specify both what class to use for the plugin and how to configure the
 public fields or bean properties of the instantiated plugin instance. The
 easiest way to describe the plugin syntax is by example:
@@ -396,8 +396,8 @@ default JDBC store.
         </para>
         
         <para>
-Few of the properties recognized by OpenJPA have been standardized in JPA 2.0 
+A few of the properties recognized by OpenJPA have been standardized in JPA 2.0 
-Specification using equivalent names. These properties can be specified either
+specification using equivalent names. These properties can be specified either
 by the JPA standard key or equivalent OpenJPA key. Specifying the same key once
 as JPA standard key and again as equivalent OpenJPA key in the same configuration, 
 however, is not allowed. The following table lists these standard JPA properties 
@@ -4234,7 +4234,7 @@ implementation is
         <para>
 The default behavior of certain OpenJPA API methods can evolve to align with the behaviors
 defined in JPA specification. To maintain backward compatibility, OpenJPA allows configuration
-options such that while the default behavior changes to align with current JPA Specification, the
+options such that while the default behavior changes to align with current JPA specification, the
 previous behaviors can always be emulated. 
 		</para>
 		<para>
@@ -4253,13 +4253,13 @@ JPA 2.0 <literal>detach()</literal> semantics does not require a dirty instance
 before detach.        
 		</para>
 		<para>
-A user application running with OpenJPA that is compliant to a specific version of JPA of specification,
+A user application running with OpenJPA that is compliant to a specific version of JPA specification
-the older behavior can be emulated by configuring OpenJPA Compatibility options.
+can emulate the older behavior by configuring OpenJPA compatibility options.
 For example, <literal>openjpa.Compatibility=FlushBeforeDetach=false,CopyOnDetach=true</literal>
-will emulate the older behavior of detach even when running with OpenJPA that are
+will emulate the older behavior of detach even when running with OpenJPA that is
-compliant to JPA 2.0 Specification.  The configuration can also be set to a different version of the specification.
+compliant to JPA 2.0 specification.  The configuration can also be set to a different version of the specification.
 For example, <literal>openjpa.Specification="JPA 1.0"</literal> configuration setting will emulate
-default OpenJPA behavior as it were for JPA Specification version 1.0. Setting via
+default OpenJPA behavior as it were for JPA specification version 1.0. Setting
 <literal>openjpa.Specification</literal> is a shorthand for more fine-grained control available via
 <literal>openjpa.Compatibility</literal>.    
   

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

@@ -3909,7 +3909,7 @@ the operation will fail.
         		Delimited Identifiers Support
         	</title>
         	<para>
-OpenJPA provides support for delimited identifiers as defined in the 2.0 JPA specification. 
+OpenJPA provides support for delimited identifiers as defined in the JPA 2.0 specification.
 Identifiers can either be automatically delimited or individually manually
 delimited. To have OpenJPA automatically delimit identifiers, add the
 <literal>&lt;delimited-identifiers/&gt;</literal> tag

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

@@ -278,7 +278,7 @@ For example, when loading an application that uses OpenJPA, a message like the
 following will be sent to the <literal>openjpa.Runtime</literal> channel:
         </para>
 <programlisting>
-2107  INFO   [main] openjpa.Runtime - Starting OpenJPA 0.9.7
+2107  INFO   [main] openjpa.Runtime - Starting OpenJPA 2.2.0
 </programlisting>
         <para>
 The default logging system accepts the following parameters:

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

@@ -2286,7 +2286,7 @@ default fetch group or in any other active fetch groups to the set of
 fields that will be eagerly loaded from the database.
             </para>
             <para>
-JPA <classname>FetchPlan</classname> methods:
+OpenJPA <classname>FetchPlan</classname> methods:
             </para>
 <programlisting>
 public FetchPlan addField(String field);
@@ -2318,7 +2318,6 @@ publisher</literal>.
             </para>
             
             <para>
-            <title>Extended Path Lookup</title>
 To include the fields defined in a super class by the subclass or to distinguish
 between fields that are defined in <emphasis>both</emphasis> super- and subclass,
 set <literal>setExtendedPathLookup(boolean)</literal> on <literal>FetchPlan