OPENJPA-849 Committing documentation updates contributed by Dianne Richards

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

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

@@ -1025,6 +1025,20 @@ language. For relational databases, this the Structured Query Language (SQL).
 native query support.
         </para>
     </section>
+    <section id="jpa_overview_em_properties">
+		<title>
+			Retrieving Properties Information
+		</title>
+		<indexterm zone="jpa_overview_em_properties">
+            <primary>
+                EntityManager
+            </primary>
+            <secondary>
+                properties information
+            </secondary>
+        </indexterm>
+        &properties_info.xml;
+    </section>
     <section id="jpa_overview_em_closing">
         <title>
             Closing

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

@@ -372,6 +372,20 @@ em.close();
             </example>
         </section>
     </section>
+    <section id="jpa_overview_emf_properties">
+		<title>
+			Retrieving Properties Information
+		</title>
+		<indexterm zone="jpa_overview_emf_properties">
+            <primary>
+                EntityManagerFactory
+            </primary>
+            <secondary>
+                properties information
+            </secondary>
+        </indexterm>
+        &properties_info.xml;
+    </section>
     <section id="jpa_overview_emfactory_close">
         <title>
             Closing the EntityManagerFactory

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

@@ -31,8 +31,8 @@
     <!ENTITY jpa_overview_emfactory.xml SYSTEM "jpa_overview_emfactory.xml">
     <!ENTITY jpa_overview_em.xml SYSTEM "jpa_overview_em.xml">
     <!ENTITY jpa_overview_trans.xml SYSTEM "jpa_overview_trans.xml">
-    <!ENTITY jpa_overview_query.xml SYSTEM "jpa_overview_query.xml">
+    <!ENTITY jpa_overview_query.xml SYSTEM "jpa_overview_query.xml">
-    <!ENTITY jpa_overview_criteria.xml SYSTEM "jpa_overview_criteria.xml">
+    <!ENTITY jpa_overview_criteria.xml SYSTEM "jpa_overview_criteria.xml">
     <!ENTITY jpa_overview_sqlquery.xml SYSTEM "jpa_overview_sqlquery.xml">
     <!ENTITY jpa_overview_mapping.xml SYSTEM "jpa_overview_mapping.xml">
     <!ENTITY jpa_overview_conclusion.xml SYSTEM "jpa_overview_conclusion.xml">
@@ -47,13 +47,15 @@
     <!ENTITY ref_guide_deploy.xml SYSTEM "ref_guide_deploy.xml">
     <!ENTITY ref_guide_runtime.xml SYSTEM "ref_guide_runtime.xml">
     <!ENTITY ref_guide_caching.xml SYSTEM "ref_guide_caching.xml">
-    <!ENTITY ref_guide_remote.xml SYSTEM "ref_guide_remote.xml">
+    <!ENTITY ref_guide_remote.xml SYSTEM "ref_guide_remote.xml">
     <!ENTITY ref_guide_slice.xml SYSTEM "ref_guide_slice.xml">
     <!ENTITY ref_guide_integration.xml SYSTEM "ref_guide_integration.xml">
     <!ENTITY ref_guide_optimization.xml SYSTEM "ref_guide_optimization.xml">
     <!ENTITY samples_guide.xml SYSTEM "samples_guide.xml">
     <!ENTITY jpa_resources.xml SYSTEM "jpa_resources.xml">
     <!ENTITY supported_databases.xml SYSTEM "supported_databases.xml">
+    <!ENTITY migration_considerations.xml SYSTEM "migration_considerations.xml">
+    <!ENTITY properties_info.xml SYSTEM "properties_info.xml">
 ]>
 <book id="manual">
     <bookinfo>
@@ -76,8 +78,8 @@
         &jpa_overview_emfactory.xml;
         &jpa_overview_em.xml;
         &jpa_overview_trans.xml;
-        &jpa_overview_query.xml;
+        &jpa_overview_query.xml;
-        &jpa_overview_criteria.xml;
+        &jpa_overview_criteria.xml;
         &jpa_overview_sqlquery.xml;
         &jpa_overview_mapping.xml;
         &jpa_overview_conclusion.xml;
@@ -103,7 +105,7 @@
         &ref_guide_deploy.xml;
         &ref_guide_runtime.xml;
         &ref_guide_caching.xml;
-        &ref_guide_remote.xml;
+        &ref_guide_remote.xml;
         &ref_guide_slice.xml;
         &ref_guide_integration.xml;
         &ref_guide_optimization.xml;
@@ -118,4 +120,5 @@
 
     &jpa_resources.xml;
     &supported_databases.xml;
+    &migration_considerations.xml;
 </book>

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

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+ http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.   
+-->
+<appendix id="migration_considerations">
+    <title>
+        Migration Considerations
+    </title>
+    <section id="jpa_2.0">
+    	<title>
+    		JPA 2.0
+    	</title>
+    	<section id="jpa_2.0_incompatibilities">
+    		<title>
+    			Incompatibilities
+    		</title>
+    		<para>
+    		The following list indicates changes that are incompatible between
+    		OpenJPA 1.x.x releases and the 2.0 release. Some of these may
+    		require application changes.
+    			<orderedlist>
+    				<listitem>
+    					<para>
+    					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
+    					JPA specification.
+    					</para>
+    				</listitem>
+    			</orderedlist>
+    		</para>
+    	</section>
+    </section>
+</appendix>

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

@@ -75,6 +75,33 @@ opportunities OpenJPA provides. Later, you can use the guide when you need
 details on a specific aspect of OpenJPA.
                 </para>
             </listitem>
+            <listitem>
+            	<para>
+            	Appendices
+            	<itemizedlist>
+            		<listitem>
+            			<para>
+            			The appendix <link linkend="jpa_resources">JPA Resources
+            			</link> provides links to other resources.
+            			</para>
+            		</listitem>
+            		<listitem>
+            			<para>
+            			The appendix <link linkend="supported_databases">
+            			Supported Databases</link> provides information on
+            			databases supported by OpenJPA.
+            			</para>
+            		</listitem>
+            		<listitem>
+            			<para>
+            			The appendix <link linkend="migration_considerations">
+            			Migration Considerations</link> provides information
+            			related to migration to a different release.
+            			</para>
+            		</listitem>
+            	</itemizedlist>
+            	</para>
+            </listitem>
         </itemizedlist>
     </section>
 </chapter>

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

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+ http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.   
+-->
+<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
+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>
+are two different keys for the same property.
+</para>
+<para>
+There are two methods that can be used to retrieve information related to
+properties:
+	<itemizedlist>
+		<listitem>
+			<para>
+			getProperties() - This method 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 
+			with the default value.
+			</para>
+		</listitem>
+		<listitem>
+			<para>
+			getSupportedProperties() - This method returns a set of
+			property keys. See the javadoc in the latest JPA
+			specification for the definition of the set. If a property
+			has more than one key, all possible keys will be returned.
+			</para>
+		</listitem>
+	</itemizedlist>
+</para>