MetaDataFactory.newInstance method no longer needed. Continue work on docs

(note: docs may temporarily be in invalid state).



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

openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/meta/MappingRepository.java

@@ -266,14 +266,6 @@ public class MappingRepository
         return getQueryKey(cls, name);
     }
 
-    public MetaDataRepository newInstance() {
-        MappingRepository repos = new MappingRepository();
-        repos.setConfiguration(getConfiguration());
-        repos.startConfiguration();
-        repos.endConfiguration();
-        return repos;
-    }
-
     public ClassMapping getMapping(Class cls, ClassLoader envLoader,
         boolean mustExist) {
         return (ClassMapping) super.getMetaData(cls, envLoader, mustExist);

openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DataSourceFactory.java

@@ -146,11 +146,9 @@ public class DataSourceFactory {
                 ecd.addListener(listeners[i]);
             decorators.add(ecd);
 
-            // ask the DriverDataSource to provide any additional
+            // ask the DriverDataSource to provide any additional decorators
-            // decorators
             if (ds instanceof DriverDataSource) {
-                List decs = ((DriverDataSource) ds).
+                List decs = ((DriverDataSource)ds).createConnectionDecorators();
-                    createConnectionDecorators();
                 if (decs != null)
                     decorators.addAll(decs);
             }

openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DriverDataSource.java

@@ -30,34 +30,79 @@ import org.apache.openjpa.jdbc.sql.DBDictionary;
 public interface DriverDataSource
     extends DataSource {
 
+    /**
+     * JDBC URL.
+     */
     public void setConnectionURL(String connectionURL);
 
+    /**
+     * JDBC URL.
+     */
     public String getConnectionURL();
 
+    /**
+     * Driver class name.
+     */
     public void setConnectionDriverName(String connectionDriverName);
 
+    /**
+     * Driver class name.
+     */
     public String getConnectionDriverName();
 
+    /**
+     * JDBC user name.
+     */
     public void setConnectionUserName(String connectionUserName);
 
+    /**
+     * JDBC user name.
+     */
     public String getConnectionUserName();
 
+    /**
+     * JDBC password.
+     */
     public void setConnectionPassword(String connectionPassword);
 
+    /**
+     * JDBC password.
+     */
     public void setClassLoader(ClassLoader classLoader);
 
+    /**
+     * Classloader for loading driver class, etc.
+     */
     public ClassLoader getClassLoader();
 
+    /**
+     * Configuration of datasource properties.
+     */
     public void setConnectionFactoryProperties(Properties props);
 
+    /**
+     * Configuration of datasource properties.
+     */
     public Properties getConnectionFactoryProperties();
 
+    /**
+     * Configuration of connection.
+     */
     public void setConnectionProperties(Properties props);
 
+    /**
+     * Configuration of connection.
+     */
     public Properties getConnectionProperties();
 
+    /**
+     * Provide any built-in decorators; may be null.
+     */
     public List createConnectionDecorators();
 
+    /**
+     * Initialize self and dictionary once available.
+     */
     public void initDBDictionary(DBDictionary dict);
 }
 

openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/SimpleDriverDataSource.java

@@ -23,17 +23,14 @@ import java.sql.SQLException;
 import java.util.List;
 import java.util.Properties;
 
-import org.apache.openjpa.jdbc.conf.JDBCConfiguration;
 import org.apache.openjpa.jdbc.sql.DBDictionary;
-import org.apache.openjpa.lib.conf.Configurable;
-import org.apache.openjpa.lib.conf.Configuration;
 import org.apache.openjpa.util.StoreException;
 
 /**
  * Non-pooling driver data source.
  */
 public class SimpleDriverDataSource
-    implements DriverDataSource, Configurable {
+    implements DriverDataSource {
 
     private String _connectionDriverName;
     private String _connectionURL;
@@ -41,7 +38,6 @@ public class SimpleDriverDataSource
     private String _connectionPassword;
     private Properties _connectionProperties;
     private Properties _connectionFactoryProperties;
-    private JDBCConfiguration _conf;
     private Driver _driver;
     private ClassLoader _classLoader;
 
@@ -68,7 +64,7 @@ public class SimpleDriverDataSource
 
     public Connection getConnection(Properties props)
         throws SQLException {
-        return _driver.connect(_conf.getConnectionURL(), props);
+        return getDriver().connect(_connectionURL, props);
     }
 
     public int getLoginTimeout() {
@@ -85,33 +81,6 @@ public class SimpleDriverDataSource
     public void setLogWriter(PrintWriter out) {
     }
 
-    public void setConfiguration(Configuration conf) {
-        _conf = (JDBCConfiguration) conf;
-    }
-
-    public void startConfiguration() {
-    }
-
-    public void endConfiguration() {
-        try {
-            _driver = DriverManager.getDriver(_connectionURL);
-            if (_driver == null) {
-                try {
-                    Class.forName(_connectionDriverName, true, _classLoader);
-                } catch (Exception e) {
-                }
-                _driver = DriverManager.getDriver(_connectionURL);
-            }
-            if (_driver == null)
-                _driver = (Driver) Class.forName(_connectionDriverName,
-                    true, _classLoader).newInstance();
-        } catch (Exception e) {
-            if (e instanceof RuntimeException)
-                throw(RuntimeException) e;
-            throw new StoreException(e);
-        }
-    }
-
     public void initDBDictionary(DBDictionary dict) {
     }
 
@@ -170,5 +139,38 @@ public class SimpleDriverDataSource
     public String getConnectionDriverName() {
         return _connectionDriverName;
     }
+
+    private Driver getDriver() {
+        if (_driver != null)
+            return _driver;
+
+        try { 
+            _driver = DriverManager.getDriver(_connectionURL);
+            if (_driver != null)
+                return _driver;
+        } catch (Exception e) {
+        }
+
+        try {
+            Class.forName(_connectionDriverName, true, _classLoader);
+        } catch (Exception e) {
+        }
+        try {
+            _driver = DriverManager.getDriver(_connectionURL);
+            if (_driver != null)
+                return _driver;
+        } catch (Exception e) {
+        }
+
+        try {
+            _driver = (Driver) Class.forName(_connectionDriverName,
+                true, _classLoader).newInstance();
+            return _driver;
+        } catch (Exception e) {
+            if (e instanceof RuntimeException)
+                throw(RuntimeException) e;
+            throw new StoreException(e);
+        }
+    }
 }
 

openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java

@@ -156,18 +156,6 @@ public class MetaDataRepository
         return _log;
     }
 
-    /**
-     * Create a new instance of the same type as this instance, using this
-     * instance's configuration.
-     */
-    public MetaDataRepository newInstance() {
-        MetaDataRepository repos = new MetaDataRepository();
-        repos.setConfiguration(_conf);
-        repos.startConfiguration();
-        repos.endConfiguration();
-        return repos;
-    }
-
     /**
      * The I/O used to load metadata.
      */

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

@@ -13,7 +13,7 @@ turn.
             Factory Deployment
         </title>
         <para>
-OpenJPA offers several <classname>EntityManagerFactory</classname>
+OpenJPA offers two <classname>EntityManagerFactory</classname>
 deployment options.
         </para>
         <section id="ref_guide_deploy_factory_standalone">
@@ -44,19 +44,191 @@ Javadoc</ulink> details these extensions.
             </para>
             <para>
 After obtaining the factory, you can cache it for all <classname>
-EntityManager</classname> creation duties.
+EntityManager</classname> creation duties.  OpenJPA factories support being 
+bound to JNDI as well.
             </para>
         </section>
         <section id="ref_guide_deploy_inject">
             <title>
                 EntityManager Injection
             </title>
-            <!-- ### -->
             <para>
-TBD
+Java EE 5 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>
         </section>
     </section>
+	<section id="ref_guide_enterprise_trans">
+		<title>
+            Integrating with the Transaction Manager
+        </title>
+		<indexterm zone="ref_guide_enterprise_trans">
+			<primary>
+                transactions
+            </primary>
+			<secondary>
+                managed
+            </secondary>
+		</indexterm>
+		<indexterm zone="ref_guide_enterprise_trans">
+			<primary>
+                TransactionManager
+            </primary>
+			<secondary>
+                integration
+            </secondary>
+		</indexterm>
+		<indexterm>
+			<primary>
+                managed transactions
+            </primary>
+			<see>
+                transactions
+            </see>
+		</indexterm>
+		<indexterm>
+            <primary>
+                TransactionMode
+            </primary>
+        </indexterm>
+		<para>
+OpenJPA <classname>EntityManager</classname>s have the ability to automatically
+synchronize their transactions with an external transaction manager.  
+###
+If you 
+deploy via <link linkend="ref_guide_deploy_inject"><classname>EntityManager
+</classname> injection</link> as described above, this synchronization is
+typically automatic.   Whether 
+or not <classname>EntityManager</classname>s from a given <classname>
+EntityManagerFactory</classname> exhibit this behavior by default depends on 
+the <link linkend="kodo.TransactionMode">
+		<literal>kodo.TransactionMode</literal></link> configuration property.
+		The property can take the following values:
+		</para>
+		<para condition="jdo_notcombo">
+		Kodo <classname>PersistenceManager</classname>s have the ability 
+		to automatically synchronize their transactions with an external 
+		transaction manager.  Whether or not <classname>
+		PersistenceManager</classname>s from a given 
+		<classname>PersistenceManagerFactory</classname> exhibit this behavior 
+		by default depends on the <link linkend="kodo.TransactionMode">
+		<literal>kodo.TransactionMode</literal></link> configuration property.
+		The property can take the following values:
+		</para>
+		<para condition="combo">
+		Kodo <classname>EntityManager</classname>s and <classname>
+		PersistenceManager</classname>s have the ability 
+		to automatically synchronize their transactions with an external 
+		transaction manager.  Whether or not <classname>
+		EntityManager</classname>s and <classname>
+		PersistenceManager</classname>s from a given factory exhibit this 
+		behavior by default depends on the <link linkend="kodo.TransactionMode">
+		<literal>kodo.TransactionMode</literal></link> configuration property.
+		The property can take the following values:
+		</para>
+		<itemizedlist> 
+			<listitem>
+				<para>
+				<literal>local</literal>: Perform transaction operations
+				locally.
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+				<literal>managed</literal>: Integrate with the application
+				server's managed global transactions.  
+				</para>
+			</listitem>
+		</itemizedlist> 
+		<para condition="ejb">
+		You can override the global transaction mode setting when you obtain an
+		<classname>EntityManager</classname> using the 
+		<ulink url="&api-dir;/kodo/persistence/KodoEntityManagerFactory.html">
+		<classname>KodoEntityManagerFactory</classname></ulink>'s
+		<methodname>createEntityManager(PersistenceContextType ctype, boolean managed, int connRetainMode)
+		</methodname> method.
+		</para>
+		<para condition="jdo">
+		You can override the global transaction mode setting when you obtain a 
+		<classname>PersistenceManager</classname> using the 
+		<ulink url="&api-dir;/kodo/jdo/KodoPersistenceManagerFactory.html">
+		<classname>KodoPersistenceManagerFactory</classname></ulink>'s
+		<methodname>getPersistenceManager(boolean managed, int connRetainMode)
+		</methodname> method.
+		</para>
+		<para>
+		<indexterm><primary>ManagedRuntime</primary></indexterm>
+		In order to use global transactions, Kodo must be able to access
+		the application server's <classname>javax.transaction.TransactionManager
+		</classname>.  Kodo can automatically discover the transaction
+		manager for most major application servers.  Occasionally, however, 
+		you might have to point Kodo to the transaction manager for an 
+		unrecognized or non-standard application server setup.  This is 
+		accomplished through the <link linkend="kodo.ManagedRuntime"><literal>
+		kodo.ManagedRuntime</literal></link> configuration property.  This
+		property describes a 
+		<ulink url="&javadoc-dir;/kodo/ee/ManagedRuntime.html"><classname>
+		kodo.ee.ManagedRuntime</classname></ulink> implementation to use
+		for transaction manager discovery.  You can specify your own 
+		implementation, or use one of the built-ins:
+		</para>
+		<itemizedlist>
+			<listitem>
+				<para>
+				<literal>auto</literal>: This is the default.  It is an alias 
+				for the
+				<ulink url="&javadoc-dir;/kodo/ee/AutomaticManagedRuntime.html">
+				<classname>kodo.ee.AutomaticManagedRuntime</classname></ulink>
+				class.  This managed runtime is able to automatically integrate
+				with several common application servers.
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+				<literal>invocation</literal>: An alias for the
+				<ulink url="&javadoc-dir;/kodo/ee/InvocationManagedRuntime.html">
+				<classname>kodo.ee.InvocationManagedRuntime</classname></ulink>
+				class.  You can configure this runtime to invoke any static
+				method in order to obtain the appserver's transaction manager.
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+				<literal>jndi</literal>: An alias for the
+				<ulink url="&javadoc-dir;/kodo/ee/JNDIManagedRuntime.html">
+				<classname>kodo.ee.JNDIManagedRuntime</classname></ulink>
+				class.  You can configure this runtime to look up the
+				transaction manager at any JNDI location.
+				</para>
+			</listitem>
+		</itemizedlist>
+		<para>
+		See the Javadoc for of each class for details on the bean properties 
+		you can pass to these plugins in your configuration string.  
+		</para>
+		&feature-enterprise;
+		<example id="ref_guide_enterprise_transex">
+			<title>Configuring Transaction Manager Integration</title>
+			<para condition="combo">JPA XML format:</para>
+<programlisting condition="ejb">
+<![CDATA[<property name="kodo.TransactionMode" value="managed"/>
+<property name="kodo.ManagedRuntime" value="jndi(TransactionManagerName=java:/TransactionManager)"/>]]>
+</programlisting>
+			<para condition="combo">JDO properties format:</para>
+<programlisting condition="jdo">
+kodo.TransactionMode: managed
+kodo.ManagedRuntime: jndi(TransactionManagerName=java:/TransactionManager)
+</programlisting>
+		</example>
+		<para>
+		Note that even when Kodo is using managed transaction, you can control
+		transactions through the specification local transaction APIs if you
+		wish.  Kodo will propagate your transaction calls to the global
+		transaction.
+		</para>
+	</section>
+
     <section id="ref_guide_enterprise_xa">
         <title>
             XA Transactions
@@ -128,7 +300,7 @@ managed environment. The following components are required:
                 <listitem>
                     <para>
 A managed environment that provides an XA compliant transaction manager.
-Examples of this are application servers such as JBoss and WebLogic.
+Examples of this are application servers such as WebLogic or JBoss.
                     </para>
                 </listitem>
                 <listitem>

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

@@ -46,8 +46,7 @@ specification.
 their corresponding database schema from your object model. OpenJPA supports
 forward mapping through the <emphasis>mapping tool</emphasis>. The next section
 presents several common mapping tool use cases. You can invoke the tool through
-the <literal>mappingtool</literal> shell/batch script included in the OpenJPA
+its Java class,
-distribution, or through its Java class,
 <ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingTool"><classname>
 org.apache.openjpa.jdbc.meta.MappingTool</classname></ulink>.
         </para>
@@ -115,7 +114,7 @@ the same-named option on the schema tool.
             </listitem>
             <listitem>
                 <para>
-<literal>-openjpaTables/-kt &lt;true/t | false/f&gt;</literal>: Corresponds to
+<literal>-openjpaTables/-ot &lt;true/t | false/f&gt;</literal>: Corresponds to
 the same-named option on the schema tool.
                 </para>
             </listitem>
@@ -184,11 +183,10 @@ the action to take on each class. The available actions are:
         <itemizedlist>
             <listitem>
                 <para>
-<literal>buildSchema</literal>: This is the default action when using JPA
+<literal>buildSchema</literal>: This is the default action. It
-mapping defaults (see <xref linkend="ref_guide_mapping_defaults"/> ). It
 makes the database schema match your existing mappings. If your provided
-mappings conflict with a class definition, OpenJPA will fail with an informative
+mappings conflict with your class definitions, OpenJPA will fail with an 
-exception.
+informative exception.
                 </para>
             </listitem>
             <listitem>
@@ -246,12 +244,8 @@ The JPA specification defines a comprehensive set of defaults for missing
 mapping information. Thus, forward mapping in JPA is virtually automatic. After
 using the mapping annotations covered in <xref linkend="jpa_overview_mapping"/>
 of the JPA Overview to override any unsatisfactory defaults, run the
-mapping tool's <literal>buildSchema</literal> action on your persistent classes.
+mapping tool on your persistent classes.  The default <literal>buildSchema
-This is the default action when you use JPA mapping defaults (see
+</literal> mapping tool action manipulates the database schema to
-<xref linkend="ref_guide_mapping_defaults"/> ).
-            </para>
-            <para>
-The <literal>buildSchema</literal> action manipulates the database schema to
 match your mappings. It fails if any of your mappings don't match your object
 model.
             </para>
@@ -309,13 +303,12 @@ This example uses your existing mappings to determine the needed schema, then
 writes the SQL to create that schema to <filename>create.sql</filename>.
                 </para>
 <programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool -a buildSchema -sa build -sql create.sql Magazine.java
+java org.apache.openjpa.jdbc.meta.MappingTool -sa build -sql create.sql Magazine.java
 </programlisting>
             </example>
             <example id="ref_guid_mapping_ddl_part_ddl">
                 <title>
-                    Create DDL to Update Database for Current
+                    Create DDL to Update Database for Current Mappings
-        Mappings
                 </title>
                 <para>
 This example uses your existing mappings to determine the needed schema. It then
@@ -323,7 +316,7 @@ writes the SQL to add any missing tables and columns to the current schema to
 <filename>update.sql</filename>.
                 </para>
 <programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool -a buildSchema -sql update.sql Magazine.java
+java org.apache.openjpa.jdbc.meta.MappingTool -sql update.sql Magazine.java
 </programlisting>
             </example>
         </section>
@@ -356,8 +349,7 @@ meant for use during rapid test/debug cycles.
             </para>
             <para>
 In order to enable automatic runtime mapping, you must first list all your
-persistent classes as described in <xref linkend="ref_guide_pc_pcclasses"/>
+persistent classes as described in <xref linkend="ref_guide_pc_pcclasses"/>.
-.
             </para>
             <para>
 OpenJPA will run the mapping tool on these classes when your application obtains
@@ -423,13 +415,6 @@ in <xref linkend="ref_guide_mapping_middle"/>. The reverse mapping tool,
 however, can give you an excellent starting point from which to grow your
 persistent classes.
         </para>
-        <!-- ### -->
-        <note>
-            <para>
-The reverse mapping tool in this release does not yet output JPA annotations. It
-is limited to JDO metadata output.
-            </para>
-        </note>
         <para>
 To use the reverse mapping tool, follow the steps below:
         </para>
@@ -470,8 +455,7 @@ proper relations between the persistent classes it creates.
                 <para>
 Run the reverse mapping tool on the finished schema file. If you do not supply
 the schema file to reverse map, the tool will run directly against the schema in
-the database. The tool can be run via the included <literal>reversemappingtool
+the database. The tool can be run via its Java class,
-</literal> script, or through its Java class,
 <ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ReverseMappingTool">
 <classname>org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></ulink>.
                 </para>
@@ -630,8 +614,8 @@ the system defaults to a
 <classname>PropertiesReverseCustomizer</classname></ulink>. This customizer
 allows you to specify simple customization options in the properties file given
 with the <literal>-customizerProperties</literal> flag below. We present the
-available property keys <link linkend="ref_guide_pc_reverse_custom"> below
+available property keys <link linkend="ref_guide_pc_reverse_custom"> 
-</link>.
+below</link>.
                         </para>
                     </listitem>
                     <listitem>
@@ -652,7 +636,8 @@ property in the specified reverse customizer, and set to the given value.
                 <para>
 Running the tool will generate <filename>.java</filename> files for each
 generated class (and its application identity class, if applicable), along with
-all necessary persistence metadata and mappings.
+an <filename>orm.xml</filename> file containing the corresponding persistence 
+metadata.
                 </para>
             </listitem>
             <listitem>
@@ -664,10 +649,12 @@ generates.
                 </para>
                 <para>
 After you are satisfied with the generated classes and their mappings, you
-should first compile them with <literal>javac</literal>, <literal>jikes
+should first compile the classes with <literal>javac</literal>, <literal>
-</literal>, or your favorite Java compiler. Make sure the classes and their
+jikes</literal>, or your favorite Java compiler. Make sure the classes are 
-metadata are located in the directory corresponding to the <literal>-package
+located in the directory corresponding to the <literal>-package</literal> flag 
-</literal> flag you gave the reverse mapping tool. Finally, enhance the classes
+you gave the reverse mapping tool.  Next, move the generated <filename>
+orm.xml</filename> file to a <filename>META-INF</filename> directory within a
+directory in your classpath.  Finally, enhance the classes
 if necessary (see <xref linkend="ref_guide_pc_enhance"/> ).
                 </para>
             </listitem>
@@ -843,11 +830,6 @@ com.xyz.Magazine.identity:              datastore
 com.xyz.pub.Company.identity:           com.xyz.pub.CompanyId
 </programlisting>
             </example>
-            <para>
-Your OpenJPA download includes the <classname> PropertiesReverseCustomizer
-</classname> source code. You can use this code as an example when writing your
-own customization class.
-            </para>
         </section>
     </section>
     <section id="ref_guide_mapping_middle">
@@ -883,10 +865,8 @@ In the <emphasis>meet-in-the-middle</emphasis>
 mapping approach, you control both the relational model and the object model. It
 is up to you to define the mappings between these models.  The mapping
 tool's <literal>validate</literal> action is useful to meet-in-the-middle
-mappers. We examined the mapping tool in
+mappers. This action verifies that the mapping information for a class matches 
-<xref linkend="ref_guide_mapping_mappingtool"/>. The <literal>validate
+the class definition and the existing schema. It throws an informative exception
-</literal> action verifies that the mapping information for a class matches the
-class definition and the existing schema. It throws an informative exception
 when your mappings are incorrect.
         </para>
         <example id="ref_guide_mapping_mappingtool_validate">
@@ -907,18 +887,6 @@ data is correct, and modifies the schema to match your mappings. This lets you
 modify your mapping data manually, but saves you the hassle of using your
 database's tools to bring the schema up-to-date.
         </para>
-        <para>
-<literal>buildSchema</literal> is the default action when you use JPA mapping
-defaults ( <xref linkend="ref_guide_mapping_defaults"/> ).
-        </para>
-        <example id="ref_guide_mapping_middle_buildschema_mid">
-            <title>
-                Creating the Relational Schema from Mappings
-            </title>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool Magazine.java
-</programlisting>
-        </example>
     </section>
     <section id="ref_guide_mapping_defaults">
         <title>
@@ -954,7 +922,9 @@ schema that matches your object model.
             <para>
 OpenJPA relies on foreign key constraint information at runtime to order SQL
 appropriately. Be sure to set your mapping defaults to reflect your existing
-database constraints, or use explicit foreign key mappings as described in
+database constraints, set the schema factory to reflect on the database for 
+constraint information (see <xref linkend="ref_guide_schema_info_factory"/>), 
+or use explicit foreign key mappings as described in
 <xref linkend="ref_guide_mapping_jpa_fk"/>.
             </para>
         </important>
@@ -990,14 +960,10 @@ properties:
                     <listitem>
                         <para>
 <literal>DefaultMissingInfo</literal>: Whether to default missing column and
-table names rather than throw an exception. Defaults to false, meaning full
+table names rather than throw an exception. If set to false, full explicit
 mappings are required at runtime and when using mapping tool actions like
 <literal>buildSchema</literal> and <literal>validate</literal>.
                         </para>
-                        <para>
-The <literal>jpa</literal> plugin above sets this property to true to meet the
-JPA specification.
-                        </para>
                     </listitem>
                     <listitem>
                         <para>
@@ -1152,11 +1118,7 @@ indicator columns for embedded objects.
                     <listitem>
                         <para>
 <literal>OrderLists</literal>: Whether to create a database ordering column for
-maintaining the order of persistent lists and arrays. Defaults to true.
+maintaining the order of persistent lists and arrays.
-                        </para>
-                        <para>
-The <literal>jpa</literal> plugin above sets this property to false in
-accordance with the JPA specification.
                         </para>
                     </listitem>
                     <listitem>
@@ -1229,12 +1191,6 @@ to store the data necessary to map your persistent classes to the database
 schema.
         </para>
         <para>
-In JPA, mapping metadata is defined in annotations. Future versions of the JPA
-drafts will also define a mapping XML format.
-<xref linkend="jpa_overview_mapping"/> in the JPA Overview describes JPA
-mapping options.
-        </para>
-        <para>
 <xref linkend="ref_guide_meta_factory"/> introduced OpenJPA's <classname>
 MetaDataFactory</classname> interface. OpenJPA uses this same interface to
 abstract the storage and retrieval of mapping information. OpenJPA includes the
@@ -1251,12 +1207,9 @@ The bundled mapping factories are:
                 <para>
 <literal>-</literal>: Leaving the <literal> openjpa.jdbc.MappingFactory
 </literal> property unset allows your metadata factory to take over mappings as
-well.
+well.  If you are using the default <literal>jpa</literal> metadata factory, 
-                </para>
+OpenJPA will read mapping information from your annotations and 
-                <para>
+<filename>orm.xml</filename> when you leave the mapping factory unspecified.
-If you are using the <literal>jpa</literal> metadata factory, OpenJPA will read
-mapping information from your annotations and <filename>orm.xml</filename> when
-you leave the mapping factory unspecified.
                 </para>
             </listitem>
         </itemizedlist>
@@ -1369,8 +1322,8 @@ accomplish this in mapping metadata.
 <programlisting>
 @Entity
 @Table(name="T1")
-public class ...
+public class ...  {
-{
+
     @ManyToOne
     @JoinColumns({
         @JoinColumn(name="FK" referencedColumnName="PK1"),
@@ -1389,8 +1342,8 @@ need single quotes for numeric constants. For example, the syntax to join
 <programlisting>
 @Entity
 @Table(name="T1")
-public class ...
+public class ...  {
-{
+
     @ManyToOne
     @JoinColumns({
         @JoinColumn(name="FK" referencedColumnName="PK2"),
@@ -1405,8 +1358,8 @@ Finally, from the inverse direction, these joins would look like this:
 <programlisting>
 @Entity
 @Table(name="T2")
-public class ...
+public class ...  {
-{
+
     @ManyToOne
     @JoinColumns({
         @JoinColumn(name="T1.FK" referencedColumnName="PK1"),
@@ -1529,8 +1482,8 @@ import org.apache.openjpa.persistence.jdbc.*;
 @Entity
 @Table(name="LOGS")
 @DataStoreIdColumn(name="ENTRY")
-public class LogEntry
+public class LogEntry {
-{
+
     @Lob
     private String content;
 
@@ -1675,8 +1628,8 @@ this with the
 annotation, which contains an array of <classname>Column</classname> values.
             </para>
             <para>
-Remember to annotate custom field types with <classname> Persistent</classname>
+Remember to annotate custom field types with <classname>Persistent</classname>,
-, as described in <xref linkend="ref_guide_meta_jpa_persistent"/>.
+as described in <xref linkend="ref_guide_meta_jpa_persistent"/>.
             </para>
         </section>
         <section id="ref_guide_mapping_jpa_fieldjoin">
@@ -1836,8 +1789,8 @@ owning field will load as null.
 import org.apache.openjpa.persistence.jdbc.*;
 
 @Embeddable
-public class PathCoordinate
+public class PathCoordinate {
-{
+
     private String siteName;
 
     @Persistent
@@ -1848,8 +1801,8 @@ public class PathCoordinate
 }
 
 @Entity
-public class Path
+public class Path {
-{
+
     @Embedded
     @EmbeddedMapping(nullIndicatorFieldName="siteName", overrides={
         @MappingOverride(name="siteName", columns=@Column(name="START_SITE")),
@@ -1991,28 +1944,6 @@ in the JPA Overview for a review of the <classname>JoinColumn</classname>
 annotation.
                 </para>
             </section>
-            <section id="ref_guide_mapping_jpa_coll_embed">
-                <title>
-                    Element Embedded Mapping
-                </title>
-                <indexterm zone="ref_guide_mapping_jpa_coll_embed">
-                    <primary>
-                        ElementEmbeddedMapping
-                    </primary>
-                    <seealso>
-                        mapping metadata
-                    </seealso>
-                </indexterm>
-                <para>
-The
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementEmbeddedMapping.html">
-<classname>org.apache.openjpa.persistence.jdbc.ElementEmbeddedMapping
-</classname></ulink> annotation allows you to map your collection or map's
-embedded element type to your container table. This annotation has exactly the
-same properties as the <classname>EmbeddedMapping</classname> annotation
-described <link linkend="ref_guide_mapping_jpa_embed">above</link>.
-                </para>
-            </section>
             <section id="ref_guide_mapping_jpa_coll_order">
                 <title>
                     Order Column
@@ -2134,15 +2065,14 @@ import org.apache.openjpa.persistence.jdbc.*;
 
 @Entity
 @Table(name="LINE_ITEM", schema="CNTRCT")
-public class LineItem
+public class LineItem {
-{
     ...
 }
 
 @Entity
 @Table(name="SUB", schema="CNTRCT")
-public class Subscription
+public class Subscription {
-{
+
     @Id private long id;
 
     @OneToMany
@@ -2168,11 +2098,8 @@ public class Subscription
             </indexterm>
             <para>
 We detailed the <literal>ContainerTable</literal> annotation in
-<xref linkend="ref_guide_mapping_jpa_coll_table"/>. We also discussed
+<xref linkend="ref_guide_mapping_jpa_coll_table"/>. Custom map mappings may 
-join columns embedded mappings in
+also use this annotation to represent a map table.
-<xref linkend="ref_guide_mapping_jpa_coll_joincols"/> and
-<xref linkend="ref_guide_mapping_jpa_coll_embed"/>. Key columns, join
-columns, and embedded mappings are new, however; we tackle them below.
             </para>
         </section>
         <section id="ref_guide_mapping_jpa_constraints">
@@ -2188,8 +2115,8 @@ batch size.
             </para>
             <para>
 OpenJPA assumes certain columns have indexes or constraints based on your
-mapping defaults, as detailed in <xref linkend="ref_guide_mapping_defaults"/>
+mapping defaults, as detailed in <xref linkend="ref_guide_mapping_defaults"/>. 
-. You can override the configured defaults on individual joins, field
+You can override the configured defaults on individual joins, field
 values, collection elements, map keys, or map values using the annotations
 presented in the following sections.
             </para>
@@ -2216,14 +2143,10 @@ The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Index.html">
 annotation represents an index on the columns of a field. It is also used within
 the <link linkend="ref_guide_mapping_jpa_coll_table"><classname>ContainerTable
 </classname></link> annotation to index join columns.
-                </para>
+To index the columns of a collection element, use the
-                <para>
-To index the columns of a collection or map element or map key, use the
 <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementIndex.html">
 <classname> org.apache.openjpa.persistence.jdbc.ElementIndex</classname></ulink>
-and <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyIndex.html">
+annotation. These annotations have the following properties:
-<classname>org.apache.openjpa.persistence.jdbc.KeyIndex</classname></ulink>
-annotations, respectively. These annotations have the following properties:
                 </para>
                 <itemizedlist>
                     <listitem>
@@ -2270,18 +2193,11 @@ The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ForeignKey.html">
 annotation represents a foreign key on the columns of a field. It is also used
 within the <link linkend="ref_guide_mapping_jpa_coll_table"><classname>
 ContainerTable</classname></link> annotation to set a database foreign key on
-join columns.
+join columns.  To set a constraint to the columns of a collection element, use 
-                </para>
+the
-                <para>
-To set a constraint to the columns of a collection or map element or map value,
-use the
 <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementForeignKey.html">
 <classname> org.apache.openjpa.persistence.jdbc.ElementForeignKey</classname>
-</ulink> and
+</ulink> annotation. These annotations have the following properties:
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyForeignKey.html">
-<classname> org.apache.openjpa.persistence.jdbc.KeyForeignKey</classname>
-</ulink> annotations, respectively. These annotations have the following
-properties:
                 </para>
                 <itemizedlist>
                     <listitem>
@@ -2327,7 +2243,9 @@ Keep in mind that OpenJPA uses foreign key information at runtime to avoid
 constraint violations; it is important, therefore, that your
 <link linkend="ref_guide_mapping_defaults">mapping defaults</link> and foreign
 key annotations combine to accurately reflect your existing database
-constraints.
+constraints, or that  you configure OpenJPA to reflect on your database schema
+to discover existing foreign keys (see
+<xref linkend="ref_guide_schema_info_factory"/>).
                 </para>
             </section>
             <section id="ref_guide_mapping_jpa_unique">
@@ -2379,22 +2297,6 @@ supported by the database.
                     </listitem>
                 </itemizedlist>
             </section>
-            <section id="ref_guide_mapping_jpa_constraintex">
-                <title>
-                    Examples
-                </title>
-                <para>
-Here again is our map example from <xref linkend="ref_guide_mapping_jpa_map"/>
-, now with explicit indexes and constraints added.
-                </para>
-                <mediaobject>
-                    <imageobject>
-                        <!-- PNG image data, 410 x 266 (see README) -->
-                        <imagedata fileref="img/string-rel-map.png" width="273px"/>
-
-                    </imageobject>
-                </mediaobject>
-            </section>
         </section>
     </section>
     <section id="ref_guide_mapping_limits">
@@ -2663,7 +2565,7 @@ efficiency of your relations.
                 <note>
                     <para>
 OpenJPA also includes the <literal>type</literal> metadata extension for
-narrowing the declared type of a field See <xref linkend="type"/>.
+narrowing the declared type of a field. See <xref linkend="type"/>.
                     </para>
                 </note>
                 <para>
@@ -2681,13 +2583,6 @@ OpenJPA defines the following extensions for nonpolymorphic values:
                         <para>
 <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementNonpolymorphic.html">
 <classname>org.apache.openjpa.persistence.jdbc.ElementNonpolymorphic</classname>
-</ulink>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyNonpolymorphic.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyNonpolymorphic</classname>
 </ulink>
                         </para>
                     </listitem>
@@ -2741,9 +2636,8 @@ In these cases, set the proper class critera extension to <literal>true
 </literal> to force OpenJPA to append class criteria to its select SQL.
                 </para>
                 <para>
-OpenJPA defines the following class criteria annotations for field relations,
+OpenJPA defines the following class criteria annotations for field relations and
-array, collection, and map element relations, and map key relations,
+array or collection element relations, respectively:
-respectively:
                 </para>
                 <itemizedlist>
                     <listitem>
@@ -2756,13 +2650,6 @@ respectively:
                         <para>
 <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementClassCriteria.html">
 <classname>org.apache.openjpa.persistence.jdbc.ElementClassCriteria</classname>
-</ulink>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyClassCriteria.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyClassCriteria</classname>
 </ulink>
                         </para>
                     </listitem>
@@ -2787,54 +2674,14 @@ respectively:
                     </seealso>
                 </indexterm>
                 <para>
-OpenJPA's family of strategy extensions allow you to specify a custom mapping
+OpenJPA's 
+<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
+<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
+extension allows you to specify a custom mapping
 strategy or value handler for a field. See
 <xref linkend="ref_guide_mapping_custom"/> for information on custom
 mappings.
                 </para>
-                <para>
-OpenJPA includes the following JPA strategy annotations:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
-<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>:
-Field strategy or value handler plugin string.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyStrategy.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyStrategy</classname></ulink>:
-Map key value handler plugin string.
-                        </para>
-                    </listitem>
-                </itemizedlist>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-<literal>jdbc-strategy</literal>: Field strategy or value handler plugin
-string.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>jdbc-element-strategy</literal>: Collection or array element value
-handler plugin string.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>jdbc-key-strategy</literal>: Map key value handler plugin string.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>jdbc-value-strategy</literal>: Map value handler plugin string.
-                        </para>
-                    </listitem>
-                </itemizedlist>
             </section>
         </section>
     </section>
@@ -2882,8 +2729,7 @@ The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
 annotation allows you to declare a custom class mapping strategy in JPA mapping
 metadata. Set the value of the annotation to the full class name of your custom
 strategy. You can configure your strategy class' bean properties using
-OpenJPA's plugin syntax, detailed in <xref linkend="ref_guide_conf_plugins"/>
+OpenJPA's plugin syntax, detailed in <xref linkend="ref_guide_conf_plugins"/>.
-.
             </para>
         </section>
         <section id="ref_guide_mapping_custom_versdiscrim">
@@ -2957,19 +2803,10 @@ Value handlers make it trivial to map any type that you can break down into one
 or more simple values. All value handlers implement the <classname>
 org.apache.openjpa.jdbc.meta.ValueHandler</classname> interface; see its
 <ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ValueHandler.html"> Javadoc
-</ulink> for details. Rather than give synthetic examples of value handlers,
+</ulink> for details.  Also, examine the built-in handlers in the <filename>
-OpenJPA provides the source to most of the built-in handlers in the <filename>
+src/openjpa/jdbc/meta/strats</filename> directory of your OpenJPA source 
-src/openjpa/jdbc/meta/strats</filename> directory of your OpenJPA distribution.
+distribution.  Use these functional implementations as examples when you 
-Use these functional implementations as examples when you create your own value
+create your own value handlers.
-handlers.
-                </para>
-                <para>
-Note that value handlers are not only simple to write, but are highly reusable.
-For example, imagine that you create a handler for <classname>java.awt.Point
-</classname> values. You can not only use this handler to map fields of type
-<classname>Point</classname>, but also to map <classname> Collection</classname>
-s or <classname>Map</classname>s of <classname>Point</classname>s with no
-additional work.
                 </para>
             </section>
             <section id="ref_guide_mapping_custom_fieldstrat">
@@ -3020,8 +2857,8 @@ MappingDefaults</classname> implementations allows you to globally associate
 field types with their corresponding custom value handler or strategy. OpenJPA
 will automatically use your custom strategies when it encounters a field of the
 associated type. OpenJPA will use your custom value handlers whenever it
-encounters a field, collection element, map key, or map value of the associated
+encounters a field of the associated type. 
-type. <xref linkend="ref_guide_mapping_defaults"/> described mapping
+<xref linkend="ref_guide_mapping_defaults"/> described mapping
 defaults in detail.
                 </para>
                 <para>
@@ -3092,16 +2929,13 @@ openjpa.Runtime</literal>.
             </listitem>
             <listitem>
                 <para>
-<literal>exception</literal>: Throw an exception when OpenJPA discovers an
+<literal>exception</literal>: Throw an <classname>
+EntityNotFoundException</classname> when OpenJPA discovers an
 orphaned key. This is an alias for the
 <ulink url="../apidocs/org/apache/openjpa/event/ExceptionOrphanedKeyAction.html">
 <classname>org.apache.openjpa.event.ExceptionOrphanedKeyAction</classname>
 </ulink> class.
                 </para>
-                <para>
-In JPA, the exception type will be <classname>
-javax.persistence.EntityNotFoundException</classname>.
-                </para>
             </listitem>
             <listitem>
                 <para>

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

@@ -230,6 +230,133 @@ annotation exists. For example, <xref linkend="ref_guide_mapping_jpa_columns"/>
 to denote a persistent <classname>java.awt.Point</classname> field.
             </para>
         </section>
+		<section id="ref_guide_meta_jpa_persistent_coll">
+			<title>Persistent Collection Fields</title>
+			<indexterm zone="ref_guide_meta_jpa_persistent_coll">
+				<primary>persistent fields</primary>
+				<secondary>collection metadata</secondary>
+			</indexterm>
+			<para>
+JPA standardizes support for collections of entities with the <literal>
+OneToMany</literal> and <literal>ManyToMany</literal> persistence strategies.  
+OpenJPA supports these strategies, and may be extended for other strategies as 
+well.  For extended strategies, use the 
+<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentCollection.html">
+<classname>kodo.persistence.PersistentCollection</classname></ulink> metadata 
+annotation to represents any persistent collection field.  It has the following
+properties:
+			</para>
+			<itemizedlist>
+				<listitem>
+					<para>
+<literal>Class elementType</literal>: The class of the collection elements.  
+This information is usually taken from the parameterized collection element 
+type.  You must supply it explicitly, however, if your field isn't a 
+parameterized type.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>FetchType fetch</literal>: Whether to load the collection eagerly or 
+lazily.  Corresponds exactly to the same-named property of standard JPA 
+annotations such as <link linkend="ejb3_overview_meta_basic"><classname>
+Basic</classname></link>. Defaults to <literal>FetchType.LAZY</literal>.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>String mappedBy</literal>: Names the field in the related entity that 
+maps this bidirectional relation.  Corresponds to the same-named property of 
+standard JPA annotations such as <link linkend="ejb3_overview_meta_manytomany">
+<classname>ManyToMany</classname></link>.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>CascadeType[] elementCascade</literal>: Array of enum values defining 
+cascade behavior for the collection elements.  Corresponds exactly to the 
+<literal>cascade</literal> property of standard JPA annotations such as 
+<link linkend="ejb3_overview_meta_manytomany"><classname>
+ManyToMany</classname></link>. Defaults to empty array.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>boolean elementEmbedded</literal>: Set this property to <literal>true
+</literal> if the elements are stored as embedded objects.
+					</para>
+				</listitem>
+			</itemizedlist>
+		</section>
+		<section id="ref_guide_meta_jpa_persistent_map">
+			<title>Persistent Map Fields</title>
+			<indexterm zone="ref_guide_meta_jpa_persistent_map">
+				<primary>persistent fields</primary>
+				<secondary>map metadata</secondary>
+			</indexterm>
+			<para>
+JPA has limited support for maps.  If you extend JPA's standard map support to 
+encompass new mappings, use the 
+<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentMap.html">
+<classname>kodo.persistence.PersistentMap</classname></ulink> metadata 
+annotation to represent your custom persistent map fields.  It has the 
+following properties:
+			</para>
+			<itemizedlist>
+				<listitem>
+					<para>
+<literal>Class keyType</literal>: The class of the map keys.  This information 
+is usually taken from the parameterized map key type.  You must supply it 
+explicitly, however, if your field isn't a parameterized type.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>Class elementType</literal>: The class of the map values.  This 
+information is usually taken from the parameterized map value type.  You must 
+supply it explicitly, however, if your field isn't a parameterized type.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>FetchType fetch</literal>: Whether to load the collection eagerly or 
+lazily.  Corresponds exactly to the same-named property of standard JPA 
+annotations such as <link linkend="ejb3_overview_meta_basic"><classname>
+Basic</classname></link>. Defaults to <literal>FetchType.LAZY</literal>.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>CascadeType[] keyCascade</literal>: Array of enum values defining 
+cascade behavior for the map keys.  Corresponds exactly to the <literal>cascade
+</literal> property of standard JPA annotations such as 
+<link linkend="ejb3_overview_meta_manytoone"><classname>
+ManyToOne</classname></link>. Defaults to empty array.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>CascadeType[] elementCascade</literal>: Array of enum values defining 
+cascade behavior for the map values.  Corresponds exactly to the 
+<literal>cascade</literal> property of standard JPA annotations such as 
+<link linkend="ejb3_overview_meta_manytoone"><classname>
+ManyToOne</classname></link>. Defaults to empty array.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>boolean keyEmbedded</literal>: Set this property to <literal>true
+</literal> if the map keys are stored as embedded objects.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+<literal>boolean elementEmbedded</literal>: Set this property to <literal>
+true</literal> if the map values are stored as embedded objects.
+					</para>
+				</listitem>
+			</itemizedlist>
+		</section>
     </section>
     <section id="ref_guide_meta_ext">
         <title>