openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From wisnes...@apache.org
Subject svn commit: r560330 [2/2] - /openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
Date Fri, 27 Jul 2007 17:38:25 GMT

Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml?view=diff&rev=560330&r1=560329&r2=560330
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml Fri Jul 27 10:38:24 2007
@@ -1,3032 +1,3328 @@
-<?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.   
--->
-<chapter id="ref_guide_mapping">
-    <title>
-        Mapping
-    </title>
-    <indexterm zone="ref_guide_mapping">
-        <primary>
-            mapping metadata
-        </primary>
-    </indexterm>
-    <para>
-The JPA Overview's <xref linkend="jpa_overview_mapping"/> explains
-object-relational mapping under JPA. This chapter reviews the mapping utilities
-OpenJPA provides and examines OpenJPA features that go beyond the JPA
-specification.
-    </para>
-    <section id="ref_guide_mapping_mappingtool">
-        <title>
-            Forward Mapping
-        </title>
-        <indexterm zone="ref_guide_mapping_mappingtool">
-            <primary>
-                forward mapping
-            </primary>
-        </indexterm>
-        <indexterm zone="ref_guide_mapping_mappingtool">
-            <primary>
-                mapping tool
-            </primary>
-            <seealso>
-                forward mapping
-            </seealso>
-        </indexterm>
-        <indexterm>
-            <primary>
-                mapping metadata
-            </primary>
-            <secondary>
-                forward mapping
-            </secondary>
-            <see>
-                forward mapping
-            </see>
-        </indexterm>
-        <para>
-<emphasis>Forward mapping</emphasis> is the process of creating mappings and
-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
-its Java class,
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/MappingTool"><classname>
-org.apache.openjpa.jdbc.meta.MappingTool</classname></ulink>.
-        </para>
-        <note>
-            <para>
-<xref linkend="ref_guide_integration_mappingtool"/> describes the mapping
-tool Ant task.
-            </para>
-        </note>
-        <example id="ref_guide_mapping_mappingtool_typical">
-            <title>
-                Using the Mapping Tool
-            </title>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool Magazine.java
-</programlisting>
-        </example>
-        <para>
-In addition to the universal flags of the
-<link linkend="ref_guide_conf_devtools">configuration framework</link>, the
-mapping tool accepts the following command line arguments:
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>
-<literal>-schemaAction/-sa &lt;add | refresh | drop | build | retain | reflect | createDB | dropDB | import | export | none&gt;
-</literal>: The action to take on the schema. These options correspond to the
-same-named actions on the schema tool described in
-<xref linkend="ref_guide_schema_schematool"/>. Actions can be composed in a
-comma-separated list. Unless you are running the mapping tool on all of
-your persistent types at once or dropping a mapping, we strongly
-recommend you use the default <literal>add</literal> action or the
-<literal>build</literal> action. Otherwise you may end up inadvertently
-dropping schema components that are used by classes you are not
-currently running the tool over.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-schemaFile/-sf &lt;stdout | output file&gt;</literal>: Use this
-option to write the planned schema to an XML document rather than modify the
-database. The document can then be manipulated and committed to the database
-with the <link linkend="ref_guide_schema_schematool"> schema tool</link>.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-sqlFile/-sql &lt;stdout | output file&gt;</literal>: Use this option
-to write the planned schema modifications to a SQL script rather than modify the
-database. Combine this with a <literal>schemaAction</literal> of <literal>build
-</literal> to generate a script that recreates the schema for the current
-mappings, even if the schema already exists.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-dropTables/-dt &lt;true/t | false/f&gt;</literal>: Corresponds to the
-same-named option on the schema tool.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-dropSequences/-dsq &lt;true/t | false/f&gt;</literal>: Corresponds to
-the same-named option on the schema tool.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-openjpaTables/-ot &lt;true/t | false/f&gt;</literal>: Corresponds to
-the same-named option on the schema tool.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-ignoreErrors/-i &lt;true/t | false/f&gt;</literal>: Corresponds to
-the same-named option on the schema tool.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-schemas/-s &lt;schema and table names&gt;</literal>: Corresponds to
-the same-named option on the schema tool. This option is ignored if <literal>
-readSchema</literal> is not set to <literal>true</literal>.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-readSchema/-rs &lt;true/t | false/f&gt;</literal>: Set this option to
-<literal>true</literal> to read the entire existing schema when the tool runs.
-Reading the existing schema ensures that OpenJPA does not generate any mappings
-that use table, index, primary key, or foreign key names that conflict with
-existing names. Depending on the JDBC driver, though, it can be a slow process
-for large schemas.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-primaryKeys/-pk &lt;true/t | false/f&gt;</literal>: Whether to read
-and manipulate primary key information of existing tables. Defaults to false.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-foreignKeys/-fk &lt;true/t | false/f&gt;</literal>: Whether to read
-and manipulate foreign key information of existing tables. Defaults to false.
-This means that to add any new foreign keys to a class that has already been
-mapped, you must explicitly set this flag to true.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-indexes/-ix &lt;true/t | false/f&gt;</literal>: Whether to read and
-manipulate index information of existing tables. Defaults to false. This means
-that to add any new indexes to a class that has already been mapped once, you
-must explicitly set this flag to true.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-sequences/-sq &lt;true/t | false/f&gt;</literal>: Whether to
-manipulate sequences. Defaults to true.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>-meta/-m &lt;true/t | false/f&gt;</literal>: Whether the given action
-applies to metadata rather than or in addition to mappings.
-                </para>
-            </listitem>
-        </itemizedlist>
-        <para>
-The mapping tool also uses an <literal>-action/-a</literal> argument to specify
-the action to take on each class. The available actions are:
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>
-<literal>buildSchema</literal>: This is the default action. It
-makes the database schema match your existing mappings. If your provided
-mappings conflict with your class definitions, OpenJPA will fail with an 
-informative exception.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-<literal>validate</literal>: Ensure that the mappings for the given classes are
-valid and that they match the schema. No mappings or tables will be changed. An
-exception is thrown if any mappings are invalid.
-                </para>
-            </listitem>
-        </itemizedlist>
-        <para>
-Each additional argument to the tool should be one of:
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>
-The full name of a persistent class.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-The .java file for a persistent class.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-The <filename>.class</filename> file of a persistent class.
-                </para>
-            </listitem>
-        </itemizedlist>
-        <para>
-If you do not supply any arguments to the mapping tool, it will run on the
-classes in your persistent classes list (see
-<xref linkend="ref_guide_pc_pcclasses"/>).
-        </para>
-        <para>
-The mappings generated by the mapping tool are stored by the system <emphasis>
-mapping factory</emphasis>. <xref linkend="ref_guide_mapping_factory"/>
-discusses your mapping factory options.
-        </para>
-        <section id="ref_guide_mapping_mappingtool_examples">
-            <title>
-                Using the Mapping Tool
-            </title>
-            <indexterm zone="ref_guide_mapping_mappingtool_examples">
-                <primary>
-                    mapping tool
-                </primary>
-                <secondary>
-                    use cases
-                </secondary>
-            </indexterm>
-            <para>
-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 on your persistent classes.  The default <literal>buildSchema
-</literal> mapping tool action manipulates the database schema to
-match your mappings. It fails if any of your mappings don't match your object
-model.
-            </para>
-            <example id="ref_guide_mapping_mappingtool_buildschema">
-                <title>
-                    Creating the Relational Schema from Mappings
-                </title>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool Magazine.java
-</programlisting>
-            </example>
-            <para>
-To drop the schema for a persistent class, set the mapping tool's <literal>
-schemaAction</literal> to <literal>drop</literal>.
-            </para>
-            <example id="ref_guide_mapping_mappingtool_cleanup_tables">
-                <title>
-                    Refreshing entire schema and cleaning out tables
-                </title>
-	            <indexterm zone="ref_guide_mapping_mappingtool_cleanup_tables">
-    	            <primary>
-        	            testing
-            	    </primary>
-                	<secondary>
-                    	Rebuild mappings and clean tables
-	                </secondary>
-    	        </indexterm>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool -sa add,deleteTableContents
-</programlisting>
-            </example>
-            <example id="ref_guide_mapping_mappingtool_dropschema">
-                <title>
-                    Dropping Mappings and Association Schema
-                </title>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool -sa drop Magazine.java
-</programlisting>
-            </example>
-        </section>
-        <section id="ref_guide_ddl_examples">
-            <title>
-                Generating DDL SQL
-            </title>
-            <indexterm zone="ref_guide_ddl_examples">
-                <primary>
-                    mapping tool
-                </primary>
-                <secondary>
-                    DDL generation
-                </secondary>
-            </indexterm>
-            <indexterm zone="ref_guide_ddl_examples">
-                <primary>
-                    DDL
-                </primary>
-                <secondary>
-                    with mapping tool
-                </secondary>
-            </indexterm>
-            <para>
-The examples below show how to use the mapping tool to generate DDL SQL scripts,
-rather than modifying the database directly.
-            </para>
-            <example id="ref_guid_mapping_ddl_full_ddl">
-                <title>
-                    Create DDL for Current Mappings
-                </title>
-                <para>
-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 -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 Mappings
-                </title>
-                <para>
-This example uses your existing mappings to determine the needed schema. It then
-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 -sql update.sql Magazine.java
-</programlisting>
-            </example>
-        </section>
-        <section id="ref_guide_mapping_synch">
-            <title>
-                Runtime Forward Mapping
-            </title>
-            <indexterm zone="ref_guide_mapping_synch">
-                <primary>
-                    forward mapping
-                </primary>
-                <secondary>
-                    automatic runtime mapping
-                </secondary>
-            </indexterm>
-            <indexterm zone="ref_guide_mapping_synch">
-                <primary>
-                    mapping metadata
-                </primary>
-                <secondary>
-                    automatic runtime mapping
-                </secondary>
-            </indexterm>
-            <para>
-You can configure OpenJPA to automatically run the mapping tool at runtime
-through the <link linkend="openjpa.jdbc.SynchronizeMappings"><literal>
-openjpa.jdbc.SynchronizeMappings</literal></link> configuration property. Using
-this property saves you the trouble of running the mapping tool manually, and is
-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"/>.
-            </para>
-            <para>
-OpenJPA will run the mapping tool on these classes when your application obtains
-its first <classname>EntityManager</classname>.
-            </para>
-            <para>
-The <literal>openjpa.jdbc.SynchronizeMappings</literal> property is a plugin
-string (see <xref linkend="ref_guide_conf_plugins"/>) where the class
-name is the mapping tool action to invoke, and the properties are the
-<classname>MappingTool</classname> class' JavaBean properties. These properties
-correspond go the long versions of the tool's command line flags.
-            </para>
-            <example id="ref_guide_mapping_synchex">
-                <title>
-                    Configuring Runtime Forward Mapping
-                </title>
-<programlisting>
-&lt;property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/&gt;
-</programlisting>
-                <para>
-The setting above corresponds to running the following command:
-                </para>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool -a buildSchema -fk true
-</programlisting>
-            </example>
-        </section>
-    </section>
-    <section id="ref_guide_pc_reverse">
-        <title>
-            Reverse Mapping
-        </title>
-        <indexterm zone="ref_guide_pc_reverse">
-            <primary>
-                reverse mapping
-            </primary>
-        </indexterm>
-        <indexterm zone="ref_guide_pc_reverse">
-            <primary>
-                reverse mapping tool
-            </primary>
-            <seealso>
-                reverse mapping
-            </seealso>
-        </indexterm>
-        <indexterm>
-            <primary>
-                mapping metadata
-            </primary>
-            <secondary>
-                reverse mapping
-            </secondary>
-            <see>
-                reverse mapping
-            </see>
-        </indexterm>
-        <para>
-OpenJPA includes a <emphasis>reverse mapping</emphasis> tool for generating
-persistent class definitions, complete with metadata, from an existing database
-schema. You do not have to use the reverse mapping tool to access an existing
-schema; you are free to write your classes and mappings yourself, as described
-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>
-        <para>
-To use the reverse mapping tool, follow the steps below:
-        </para>
-        <orderedlist>
-            <listitem>
-                <para>
-Use the <link linkend="ref_guide_schema_schematool"> schema tool</link> to
-export your current schema to an XML schema file. You can skip this step and the
-next step if you want to run the reverse mapping tool directly against the
-database.
-                </para>
-                <example id="ref_guide_pc_reverse_schemagen">
-                    <title>
-                        Reflection with the Schema Tool
-                    </title>
-<programlisting>
-java org.apache.openjpa.jdbc.schema.SchemaTool -a reflect -f schema.xml
-</programlisting>
-                </example>
-            </listitem>
-            <listitem>
-                <para>
-Examine the generated schema file. JDBC drivers often provide incomplete or
-faulty metadata, in which case the file will not exactly match the actual
-schema. Alter the XML file to match the true schema. The XML format for the
-schema file is described in <xref linkend="ref_guide_schema_xml"/>.
-                </para>
-                <para>
-After fixing any errors in the schema file, modify the XML to include foreign
-keys between all relations. The schema tool will have automatically detected
-existing foreign key constraints; many schemas, however, do not employ database
-foreign keys for every relation. By manually adding any missing foreign keys,
-you will give the reverse mapping tool the information it needs to generate the
-proper relations between the persistent classes it creates.
-                </para>
-            </listitem>
-            <listitem>
-                <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 its Java class,
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/ReverseMappingTool">
-<classname>org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></ulink>.
-                </para>
-                <example id="ref_guide_pc_reverse_reversemappingtool">
-                    <title>
-                        Using the Reverse Mapping Tool
-                    </title>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -d ~/src -cp customizer.properties schema.xml
-</programlisting>
-                </example>
-                <para>
-In addition to OpenJPA's <link linkend="ref_guide_conf_devtools">standard
-configuration flags</link>, including
-<link linkend="ref_guide_conf_devtools_format">code formatting options</link>,
-the reverse mapping tool recognizes the following command line arguments:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-<literal>-schemas/-s &lt;schema and table names&gt;</literal>: A
-comma-separated list of schema and table names to reverse map, if no XML schema
-file is supplied. Each element of the list must follow the naming conventions
-for the <literal>openjpa.jdbc.Schemas</literal> property described in
-<xref linkend="ref_guide_schema_info_list"/>. In fact, if this flag is
-omitted, it defaults to the value of the <literal>Schemas</literal> property. If
-the <literal>Schemas</literal> property is not defined, all schemas will be
-reverse-mapped.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-package/-pkg &lt;package name&gt;</literal>: The package name of the
-generated classes. If no package name is given, the generated code will not
-contain package declarations.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-directory/-d &lt;output directory&gt;</literal>: All generated code
-and metadata will be written to the directory at this path. If the path does not
-match the package of a class, the package structure will be created beneath this
-directory. Defaults to the current directory.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-metadata/-md &lt;class | package | none&gt;</literal>: Specify the
-level the metadata should be generated at. Defaults to generating a single
-package-level metadata file. Set to <literal>none</literal> to disable orm.xml
-generation.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-annotations/-ann &lt;true/t | false/f&gt;</literal>: Set to true to
-generate JPA annotations in generated java classes. 
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-accessType/-access &lt;field | property&gt;</literal>: Change access
-type for generated annotations. Defaults to field access.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-useSchemaName/-sn &lt;true/t | false/f&gt;</literal>: Set this flag
-to <literal>true</literal> to include the schema as well as table name in the
-name of each generated class. This can be useful when dealing with multiple
-schemas with same-named tables.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-useForeignKeyName/-fkn &lt;true/t | false/f&gt;</literal>: Set this
-flag to <literal>true</literal> if you would like field names for relations to
-be based on the database foreign key name. By default, relation field names are
-derived from the name of the related class.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-nullableAsObject/-no &lt;true/t | false/f&gt;</literal>: By default,
-all non-foreign key columns are mapped to primitives. Set this flag to <literal>
-true</literal> to generate primitive wrapper fields instead for columns that
-allow null values.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-blobAsObject/-bo &lt;true/t | false/f&gt;</literal>: By default, all
-binary columns are mapped to <classname>byte[]</classname> fields. Set this flag
-to <literal>true</literal> to map them to <classname>Object</classname> fields
-instead. Note that when mapped this way, the column is presumed to contain a
-serialized Java object.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-primaryKeyOnJoin/-pkj &lt;true/t | false/f&gt;</literal>: The
-standard reverse mapping tool behavior is to map all tables with primary keys to
-persistent classes. If your schema has primary keys on many-many join tables as
-well, set this flag to <literal>true</literal> to avoid creating classes for
-those tables.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-inverseRelations/-ir &lt;true/t | false/f&gt;</literal>: Set to
-<literal>false</literal> to prevent the creation of inverse 1-many/1-1 relations
-for every many-1/1-1 relation detected.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-useGenericCollections/-gc &lt;true/t | false/f&gt;</literal>: Set to
-true to use generic collections on OneToMany and ManyToMany relations (requires
-JDK 1.5 or higher).
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-useDatastoreIdentity/-ds &lt;true/t | false/f&gt;</literal>: Set to
-<literal>true</literal> to use datastore identity for tables that have single
-numeric primary key columns. The tool typically uses application identity for
-all generated classes.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-useBuiltinIdentityClass/-bic &lt;true/t | false/f&gt;</literal>: Set
-to <literal>false</literal> to prevent the tool from using built-in application
-identity classes when possible. This will force the tool to to create custom
-application identity classes even when there is only one primary key column.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-innerIdentityClasses/-inn &lt;true/t | false/f&gt;</literal>: Set to
-<literal>true</literal> to have any generated application identity classes be
-created as static inner classes within the persistent classes. Defaults to
-<literal>false</literal>.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-identityClassSuffix/-is &lt;suffix&gt;</literal>: Suffix to append to
-class names to form application identity class names, or for inner identity
-classes, the inner class name. Defaults to <literal>Id</literal>.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-typeMap/-typ &lt;type mapping&gt;</literal>: A string that specifies
-the default Java classes to generate for each SQL type that is seen in the
-schema. The format is <literal> SQLTYPE1=JavaClass1,SQLTYPE2=JavaClass2
-</literal>. The SQL type name first looks for a customization based on <literal>
-SQLTYPE(SIZE,PRECISION)</literal>, then <literal>SQLTYPE(SIZE)</literal>, then
-<literal>SQLTYPE(SIZE,PRECISION)</literal>. So if a column whose type name is
-<literal>CHAR</literal> is found, it will first look for the <literal>
-CHAR(50,0)</literal> type name specification, then it will look for <literal>
-CHAR(50)</literal>, and finally it will just look for <literal>CHAR</literal>.
-For example, to generate a char array for every <literal>CHAR</literal> column
-whose size is exactly 50, and to generate a <literal>short</literal> for every
-type name of <literal>INTEGER</literal>, you might specify: <literal>
-CHAR(50)=char[],INTEGER=short</literal>. Note that since various databases
-report different type names differently, one database's type name specification
-might not work for another database. Enable <literal>TRACE</literal> level
-logging on the <literal>MetaData</literal> channel to track which type names
-OpenJPA is examining.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-customizerClass/-cc &lt;class name&gt;</literal>: The full class name
-of a
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html">
-<classname>org.apache.openjpa.jdbc.meta.ReverseCustomizer</classname></ulink>
-customization plugin. If you do not specify a reverse customizer of your own,
-the system defaults to a
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html">
-<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</link>.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-customizerProperties/-cp &lt;properties file or resource&gt;</literal>
-: The path or resource name of a properties file to pass to the reverse
-customizer on initialization.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>-customizer./-c.&lt;property name&gt; &lt;property value&gt;</literal>
-: The given property name will be matched with the corresponding Java bean
-property in the specified reverse customizer, and set to the given value.
-                        </para>
-                    </listitem>
-                </itemizedlist>
-                <para>
-Running the tool will generate <filename>.java</filename> files for each
-generated class (and its application identity class, if applicable), along with
-JPA annotations (if enabled by setting <literal>-annotations true</literal>),
-or an <filename>orm.xml</filename> file (if not disabled with <literal>
--metadata none</literal>) containing the corresponding persistence metadata.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-Examine the generated class, metadata, and mapping information, and modify it as
-necessary. Remember that the reverse mapping tool only provides a starting
-point, and you are free to make whatever modifications you like to the code it
-generates.
-                </para>
-                <para>
-After you are satisfied with the generated classes and their mappings, you
-should first compile the classes with <literal>javac</literal>, <literal>
-jikes</literal>, or your favorite Java compiler. Make sure the classes are 
-located in the directory corresponding to the <literal>-package</literal> flag 
-you gave the reverse mapping tool.  Next, if you have generated an <filename>
-orm.xml</filename>, move that 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>
-        </orderedlist>
-        <para>
-Your persistent classes are now ready to access your existing schema.
-        </para>
-        <section id="ref_guide_pc_reverse_custom">
-            <title>
-                Customizing Reverse Mapping
-            </title>
-            <para>
-The <classname>org.apache.openjpa.jdbc.meta.ReverseCustomizer</classname> plugin
-interface allows you to customze the reverse mapping process. See the class
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html">
-Javadoc</ulink> for details on the hooks that this interface provides. Specify
-the concrete plugin implementation to use with the <literal>
--customizerClass/-cc</literal> command-line flag, described in the preceding
-section.
-            </para>
-            <para>
-By default, the reverse mapping tool uses a
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html">
-<classname>org.apache.openjpa.jdbc.meta.PropertiesReverseCustomizer</classname>
-</ulink>. This customizer allows you to perform relatively simple
-customizations through the properties file named with the <literal>
--customizerProperties</literal> tool flag. The customizer recognizes the
-following properties:
-            </para>
-            <itemizedlist>
-                <listitem>
-                    <para>
-<literal>&lt;table name&gt;.table-type &lt;type&gt;</literal>: Override the
-default type of the table with name <literal>&lt;table name&gt;</literal>.
-Legal values are:
-                    </para>
-                    <itemizedlist>
-                        <listitem>
-                            <para>
-<literal>base</literal>: Primary table for a base class.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-<literal>secondary</literal>: Secondary table for a class. The table must have
-a foreign key joining to a class table.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-<literal>secondary-outer</literal>: Outer-joined secondary table for a class.
-The table must have a foreign key joining to a class table.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-<literal>association</literal>: Association table. The table must have two
-foreign keys to class tables.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-<literal>collection</literal>: Collection table. The table must have one
-foreign key to a class table and one data column.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-<literal>subclass</literal>: A joined subclass table. The table must have a
-foreign key to the superclass' table.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-<literal>none</literal>: The table should not be reverse-mapped.
-                            </para>
-                        </listitem>
-                    </itemizedlist>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>&lt;class name&gt;.rename &lt;new class name&gt;</literal>: Override
-the given tool-generated name <literal>&lt;class name&gt;</literal> with a new
-value. Use full class names, including package. You are free to rename a class
-to a new package. Specify a value of <literal>none</literal> to reject the class
-and leave the corresponding table unmapped.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>&lt;table name&gt;.class-name &lt;new class name&gt;</literal>: Assign
-the given fully-qualified class name to the type created from the table with
-name <literal>&lt;table name&gt;</literal>. Use a value of <literal>none
-</literal> to prevent reverse mapping this table. This property can be used in
-place of the <literal>rename</literal> property.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>&lt;class name&gt;.identity &lt;datastore | builtin | identity class
-name&gt;</literal>: Set this property to <literal>datastore</literal> to use
-datastore identity for the class <literal>&lt;class name&gt;</literal>,
-<literal>builtin</literal> to use a built-in identity class, or the desired
-application identity class name. Give full class names, including package. You
-are free to change the package of the identity class this way. If the persistent
-class has been renamed, use the new class name for this property key. Remember
-that datastore identity requires a table with a single numeric primary key
-column, and built-in identity requires a single primary key column of any type.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>&lt;class name&gt;.&lt;field name&gt;.rename &lt;new field name&gt;
-</literal>: Override the tool-generated <literal>&lt;field name&gt;</literal> in
-class <literal>&lt;class name&gt;</literal> with the given name. Use the field
-owner's full class name in the property key. If the field owner's class was
-renamed, use the new class name. The property value should be the new field
-name, without the preceding class name. Use a value of <literal>none</literal>
-to reject the generated mapping and remove the field from the class.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>&lt;table name&gt;.&lt;column name&gt;.field-name &lt;new field
-name&gt;</literal>: Set the generated field name for the <literal>&lt;table
-name&gt;</literal> table's <literal>&lt;column name&gt;</literal> column. If
-this is a multi-column mapping, any of the columns can be used. Use a value of
-<literal>none</literal> to prevent the column and its associated columns from
-being reverse-mapped.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>&lt;class name&gt;.&lt;field name&gt;.type &lt;field type&gt;</literal>
-: The type to give the named field. Use full class names. If the field or the
-field's owner class has been renamed, use the new name.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>&lt;class name&gt;.&lt;field name&gt;.value</literal>: The initial
-value for the named field. The given string will be placed as-is in the
-generated Java code, so be sure it is valid Java. If the field or the field's
-owner class has been renamed, use the new name.
-                    </para>
-                </listitem>
-            </itemizedlist>
-            <para>
-All property keys are optional; if not specified, the customizer keeps the
-default value generated by the reverse mapping tool.
-            </para>
-            <example id="ref_guide_pc_reverse_custom_ex">
-                <title>
-                    Customizing Reverse Mapping with Properties
-                </title>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -cp custom.properties schema.xml
-</programlisting>
-                <para>
-Example <filename>custom.properties</filename>:
-                </para>
-<programlisting>
-com.xyz.TblMagazine.rename:             com.xyz.Magazine
-com.xyz.TblArticle.rename:              com.xyz.Article
-com.xyz.TblPubCompany.rename:           com.xyz.pub.Company
-com.xyz.TblSysInfo.rename:              none
-
-com.xyz.Magazine.allArticles.rename:    articles
-com.xyz.Magazine.articles.type:         java.util.Collection
-com.xyz.Magazine.articles.value:        new TreeSet()
-com.xyz.Magazine.identity:              datastore
-
-com.xyz.pub.Company.identity:           com.xyz.pub.CompanyId
-</programlisting>
-            </example>
-        </section>
-    </section>
-    <section id="ref_guide_mapping_middle">
-        <title>
-            Meet-in-the-Middle Mapping
-        </title>
-        <indexterm zone="ref_guide_pc_reverse">
-            <primary>
-                meet-in-the-middle mapping
-            </primary>
-        </indexterm>
-        <indexterm zone="ref_guide_pc_reverse">
-            <primary>
-                reverse mapping tool
-            </primary>
-            <seealso>
-                reverse mapping
-            </seealso>
-        </indexterm>
-        <indexterm>
-            <primary>
-                mapping metadata
-            </primary>
-            <secondary>
-                meet-in-the-middle mapping
-            </secondary>
-            <see>
-                meet-in-the-middle mapping
-            </see>
-        </indexterm>
-        <para>
-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. This 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">
-            <title>
-                Validating Mappings
-            </title>
-<programlisting>
-java org.apache.openjpa.jdbc.meta.MappingTool -a validate Magazine.java
-</programlisting>
-        </example>
-        <para>
-The <literal>buildSchema</literal> action we discussed in
-<xref linkend="ref_guide_mapping_mappingtool"/> is also somewhat useful
-during meet-in-the-middle mapping. Unlike the <literal>validate</literal>
-action, which throws an exception if your mapping data does not match the
-existing schema, the <literal>buildSchema</literal> action assumes your mapping
-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>
-    </section>
-    <section id="ref_guide_mapping_defaults">
-        <title>
-            Mapping Defaults
-        </title>
-        <indexterm zone="ref_guide_mapping_defaults">
-            <primary>
-                MappingDefaults
-            </primary>
-        </indexterm>
-        <indexterm>
-            <primary>
-                mapping metadata
-            </primary>
-            <secondary>
-                defaults
-            </secondary>
-            <see>
-                MappingDefaults
-            </see>
-        </indexterm>
-        <para>
-The previous sections showed how to use the mapping tool to generate default
-mappings. But how does the mapping tool know what mappings to generate? The
-answer lies in the
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaults.html">
-<classname>org.apache.openjpa.jdbc.meta.MappingDefaults</classname></ulink>
-interface. OpenJPA uses an instance of this interface to decide how to name
-tables and columns, where to put foreign keys, and generally how to create a
-schema that matches your object model.
-        </para>
-        <important>
-            <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, 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>
-        <para>
-The <link linkend="openjpa.jdbc.MappingDefaults"><literal>
-openjpa.jdbc.MappingDefaults</literal></link> configuration property controls
-the <classname>MappingDefaults</classname> interface implementation in use. This
-is a plugin property (see <xref linkend="ref_guide_conf_plugins"/>), so
-you can substitute your own implementation or configure the existing ones.
-OpenJPA includes the following standard implementations:
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>
-<literal>jpa</literal>: Provides defaults in compliance with the JPA standard.
-This is an alias for the
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/PersistenceMappingDefaults.html">
-<classname>org.apache.openjpa.persistence.jdbc.PersistenceMappingDefaults
-</classname></ulink> class. This class extends the <classname>
-MappingDefaultsImpl</classname> class described below, so it has all the same
-properties (though with different default values), as well as:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-<literal>PrependFieldNameToJoinTableInverseJoinColumns</literal>: Whether to
-prepend the owning field name to the names of inverse join columns in join 
-tables.  Defaults to true per the JPA specification.  Set to false for
-compatibility with older OpenJPA versions which did not prepend the field name.
-                        </para>
-                    </listitem>
-                </itemizedlist>
-            </listitem>
-            <listitem>
-                <para>
-<literal>default</literal>: This is an alias for the
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaultsImpl.html">
-<classname>org.apache.openjpa.jdbc.meta.MappingDefaultsImpl</classname></ulink>
-class. This default implementation is highly configurable. It has the following
-properties:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-<literal>DefaultMissingInfo</literal>: Whether to default missing column and
-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>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>BaseClassStrategy</literal>: The default mapping strategy for base
-classes. You can specify a built-in strategy alias or the full class name of a
-<link linkend="ref_guide_mapping_custom_class">custom class strategy</link>.
-You can also use OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
-strategy instance. See the
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html">
-<literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package for
-available strategies.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>SubclassStrategy</literal>: The default mapping strategy for
-subclasses. You can specify a builtin strategy alias or the full class name of a
-<link linkend="ref_guide_mapping_custom_class"> custom class strategy</link>.
-You can also use OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
-strategy instance. Common strategies are <literal>vertical</literal> and
-<literal>flat</literal>, the default. See the
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html">
-<literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package for all
-available strategies.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>VersionStrategy</literal>: The default version strategy for classes
-without a version field. You can specify a builtin strategy alias or the full
-class name of a <link linkend="ref_guide_mapping_custom_versdiscrim"> custom
-version strategy</link>. You can also use OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
-strategy instance. Common strategies are <literal>none</literal>, <literal>
-state-comparison</literal>, <literal> timestamp</literal>, and <literal>
-version-number</literal>, the default. See the
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html">
-<literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package for all
-available strategies.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>DiscriminatorStrategy</literal>: The default discriminator strategy
-when no discriminator value is given. You can specify a builtin strategy alias
-or the full class name of a
-<link linkend="ref_guide_mapping_custom_versdiscrim"> custom discriminator
-strategy</link>. You can also use OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
-strategy instance. Common strategies are <literal>final</literal> for a base
-class without subclasses, <literal>none</literal> to use joins to subclass
-tables rather than a discriminator column, and <literal> class-name</literal>,
-the default. See the
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html">
-<literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package for all
-available strategies.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>FieldStrategies</literal>: This property associates field types with
-custom strategies. The format of this property is similar to that of plugin
-strings (see <xref linkend="ref_guide_conf_plugins"/> ), without the class
-name. It is a comma-separated list of key/value pairs, where each key is a
-possible field type, and each value is itself a plugin string describing the
-strategy for that type. We present an example below. See
-<xref linkend="ref_guide_mapping_custom_field"/> for information on custum
-field strategies.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>ForeignKeyDeleteAction</literal>: The default delete action of foreign
-keys representing relations to other objects. Recognized values include
-<literal>restrict</literal>, <literal>cascade</literal>, <literal>null</literal>
-, <literal>default</literal>. These values correspond exactly to the standard
-database foreign key actions of the same names.
-                        </para>
-                        <para>
-The value <literal>none</literal> tells OpenJPA not to create database foreign
-keys on relation columns. This is the default.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>JoinForeignKeyDeleteAction</literal>: The defualt delete action of
-foreign keys that join join secondary, collection, map, or subclass tables to
-the primary table. Accepts the same values as the <literal>
-ForeignKeyDeleteAction</literal> property above.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>DeferConstraints</literal>: Whether to use deferred database
-constraints if possible. Defaults to false.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>IndexLogicalForeignKeys</literal>: Boolean property controlling
-whether to create indexes on logical foreign keys. Logical foreign keys are
-columns that represent a link between tables, but have been configured through
-the <literal>ForeignKey</literal> properties above not to use a physical
-database foreign key. Defaults to true.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>DataStoreIdColumnName</literal>: The default name of datastore
-identity columns.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>DiscriminatorColumnName</literal>: The default name of discriminator
-columns.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>IndexDiscriminator</literal>: Whether to index the discriminator
-column. Defaults to true.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>VersionColumnName</literal>: The default name of version columns.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>IndexVersion</literal>: Whether to index the version column. Defaults
-to false.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>AddNullIndicator</literal>: Whether to create a synthetic null
-indicator column for embedded mappings. The null indicator column allows OpenJPA
-to distinguish between a null embedded object and one with default values for
-all persistent fields.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>NullIndicatorColumnName</literal>: The default name of synthetic null
-indicator columns for embedded objects.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>OrderLists</literal>: Whether to create a database ordering column for
-maintaining the order of persistent lists and arrays.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>OrderColumnName</literal>: The default name of collection and array
-ordering columns.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>StoreEnumOrdinal</literal>: Set to true to store enum fields as
-numeric ordinal values in the database. The default is to store the enum value
-name as a string, which is more robust if the Java enum declaration might be
-rearranged.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>StoreUnmappedObjectIdString</literal>: Set to true to store the
-stringified identity of related objects when the declared related type is
-unmapped. By default, OpenJPA stores the related object's primary key value(s).
-However, this breaks down if different subclasses of the related type use
-incompatible primary key structures. In that case, stringifying the identity
-value is the better choice.
-                        </para>
-                    </listitem>
-                </itemizedlist>
-            </listitem>
-        </itemizedlist>
-        <para>
-The example below turns on foreign key generation during schema creation and
-associates the <classname>org.mag.data.InfoStruct</classname> field type with
-the custom <classname>org.mag.mapping.InfoStructHandler</classname> value
-handler.
-        </para>
-        <example id="ref_guide_mapping_defaults_conf">
-            <title>
-                Configuring Mapping Defaults
-            </title>
-<programlisting>
-&lt;property name="openjpa.jdbc.MappingDefaults"
-    value="ForeignKeyDeleteAction=restrict,
-    FieldStrategies='org.mag.data.InfoStruct=org.mag.mapping.InfoStructHandler'"/&gt;
-</programlisting>
-        </example>
-    </section>
-    <section id="ref_guide_mapping_factory">
-        <title>
-            Mapping Factory
-        </title>
-        <indexterm zone="ref_guide_mapping_factory">
-            <primary>
-                MappingFactory
-            </primary>
-        </indexterm>
-        <indexterm>
-            <primary>
-                mapping metadata
-            </primary>
-            <secondary>
-                loading and storing
-            </secondary>
-            <see>
-                MappingFactory
-            </see>
-        </indexterm>
-        <para>
-An important decision in the object-relational mapping process is how and where
-to store the data necessary to map your persistent classes to the database
-schema.
-        </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
-built-in mapping factories below, and you can create your own factory if you
-have custom needs. You control which mapping factory OpenJPA uses with the
-<link linkend="openjpa.jdbc.MappingFactory"><literal>
-openjpa.jdbc.MappingFactory</literal></link> configuration property.
-        </para>
-        <para>
-The bundled mapping factories are:
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>
-<literal>-</literal>: Leaving the <literal> openjpa.jdbc.MappingFactory
-</literal> property unset allows your metadata factory to take over mappings as
-well.  If you are using the default <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>
-        <example id="ref_guide_mapping_factory_jpa">
-            <title>
-                Standard JPA Configuration
-            </title>
-            <para>
-In the standard JPA configuration, the mapping factory is left unset.
-            </para>
-<programlisting>
-&lt;property name="openjpa.MetaDataFactory" value="jpa"/&gt;
-</programlisting>
-        </example>
-    </section>
-    <section id="ref_guide_mapping_notes_nonstdjoins">
-        <title>
-            Non-Standard Joins
-        </title>
-        <indexterm zone="ref_guide_mapping_notes_nonstdjoins">
-            <primary>
-                joins
-            </primary>
-            <secondary>
-                non-standard
-            </secondary>
-        </indexterm>
-        <para>
-The JPA Overview's <xref linkend="jpa_overview_mapping"/> explains join
-mapping. All of the examples in that document, however, use "standard" joins, in
-that there is one foreign key column for each primary key column in the target
-table. OpenJPA supports additional join patterns, including partial primary key
-joins, non-primary key joins, and joins using constant values.
-        </para>
-        <para>
-        <indexterm>
-            <primary>
-                joins
-            </primary>
-            <secondary>
-                partial primary key
-            </secondary>
-        </indexterm>
-In a partial primary key join, the source table only has foreign key columns for
-a subset of the primary key columns in the target table. So long as this subset
-of columns correctly identifies the proper row(s) in the referenced table,
-OpenJPA will function properly. There is no special syntax for expressing a
-partial primary key join - just do not include column definitions for missing
-foreign key columns.
-        </para>
-        <para>
-        <indexterm>
-            <primary>
-                joins
-            </primary>
-            <secondary>
-                non-primary key
-            </secondary>
-        </indexterm>
-In a non-primary key join, at least one of the target columns is not a primary
-key. Once again, OpenJPA supports this join type with the same syntax as a
-primary key join. There is one restriction, however: each non-primary key column
-you are joining to must be controlled by a field mapping that implements the
-<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/Joinable.html"><classname>
-org.apache.openjpa.jdbc.meta.Joinable</classname></ulink> interface. All built
-in basic mappings implement this interface, including basic fields of embedded
-objects. OpenJPA will also respect any custom mappings that implement this
-interface. See <xref linkend="ref_guide_mapping_custom"/> for an
-examination of custom mappings.
-        </para>
-        <para>
-        <indexterm>
-            <primary>
-                joins
-            </primary>
-            <secondary>
-                constant
-            </secondary>
-        </indexterm>
-Not all joins consist of only links between columns. In some cases you might
-have a schema in which one of the join criteria is that a column in the source
-or target table must have some constant value. OpenJPA calls joins involving
-constant values <emphasis>constant joins</emphasis>.
-        </para>
-        <para>
-To form a constant join in JPA mapping, first set the <literal>JoinColumn
-</literal>'s <literal>name</literal> attribute to the name of the column. If the
-column with the constant value is the target of the join, give its fully
-qualified name in the form <literal>&lt;table name&gt;.&lt;column name&gt;
-</literal>. Next, set the <literal>referencedColumnName</literal> attribute to
-the constant value. If the constant value is a string, place it in single quotes
-to differentiate it from a column name.
-        </para>
-        <mediaobject>
-            <imageobject>
-                <!-- PNG image data, 427 x 211 (see README) -->
-                <imagedata fileref="img/joins-constant.png" width="285px"/>
-
-            </imageobject>
-        </mediaobject>
-        <para>
-Consider the tables above. First, we want to join row <literal>T1.R1</literal>
-to row <literal>T2.R1</literal>. If we just join column <literal>T1.FK</literal>
-to <literal>T2.PK1</literal>, we will wind up matching both <literal>T2.R1
-</literal> and <literal> T2.R2</literal>. So in addition to joining <literal>
-T1.FK</literal> to <literal>T2.PK1</literal>, we also have to specify that
-<literal>T2.PK2</literal> has the value <literal>a</literal>. Here is how we'd
-accomplish this in mapping metadata.
-        </para>
-<programlisting>
-@Entity
-@Table(name="T1")
-public class ...  {
-
-    @ManyToOne
-    @JoinColumns({
-        @JoinColumn(name="FK" referencedColumnName="PK1"),
-        @JoinColumn(name="T2.PK2" referencedColumnName="'a'")
-    });
-    private ...;
-}
-</programlisting>
-        <para>
-Notice that we had to fully qualify the name of column <literal>PK2</literal>
-because it is in the target table. Also notice that we put single quotes around
-the constant value so that it won't be confused with a column name. You do not
-need single quotes for numeric constants. For example, the syntax to join
-<literal>T1.R2</literal> to <literal>T2.R4</literal> is:
-        </para>
-<programlisting>
-@Entity
-@Table(name="T1")
-public class ...  {
-
-    @ManyToOne
-    @JoinColumns({
-        @JoinColumn(name="FK" referencedColumnName="PK2"),
-        @JoinColumn(name="T2.PK1" referencedColumnName="2")
-    });
-    private ...;
-}
-</programlisting>
-        <para>
-Finally, from the inverse direction, these joins would look like this:
-        </para>
-<programlisting>
-@Entity
-@Table(name="T2")
-public class ...  {
-
-    @ManyToOne
-    @JoinColumns({
-        @JoinColumn(name="T1.FK" referencedColumnName="PK1"),
-        @JoinColumn(name="PK2" referencedColumnName="'a'")
-    });
-    private ...;
-
-    @ManyToOne
-    @JoinColumns({
-        @JoinColumn(name="T1.FK" referencedColumnName="PK2"),
-        @JoinColumn(name="PK1" referencedColumnName="2")
-    });
-    private ...;
-}
-</programlisting>
-    </section>
-    <section id="ref_guide_mapping_jpa">
-        <title>
-            Additional JPA Mappings
-        </title>
-        <indexterm zone="ref_guide_mapping_jpa">
-            <primary>
-                mapping metadata
-            </primary>
-            <secondary>
-                JPA additions
-            </secondary>
-        </indexterm>
-        <para>
-OpenJPA supports many persistence strategies beyond those of the JPA
-specification. <xref linkend="ref_guide_meta_jpa"/> covered the logical
-metadata for OpenJPA's additional persistence strategies. We now demonstrate how
-to map entities using these strategies to the database.
-        </para>
-        <section id="ref_guide_mapping_jpa_datastoreid">
-            <title>
-                Datastore Identity Mapping
-            </title>
-            <indexterm zone="ref_guide_mapping_jpa_datastoreid">
-                <primary>
-                    datastore identity
-                </primary>
-                <secondary>
-                    mapping
-                </secondary>
-            </indexterm>
-            <indexterm zone="ref_guide_mapping_jpa_datastoreid">
-                <primary>
-                    mapping metadata
-                </primary>
-                <secondary>
-                    datastore identity
-                </secondary>
-                <seealso>
-                    identity
-                </seealso>
-            </indexterm>
-            <indexterm zone="ref_guide_mapping_jpa_datastoreid">
-                <primary>
-                    DataStoreIdColumn
-                </primary>
-                <seealso>
-                    mapping metadata
-                </seealso>
-            </indexterm>
-            <indexterm>
-                <primary>
-                    primary key
-                </primary>
-            </indexterm>
-            <para>
-<xref linkend="ref_guide_pc_oid"/> describes how to use datastore identity
-in JPA. OpenJPA requires a single numeric primary key column to hold datastore
-identity values. The
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/DataStoreIdColumn.html">
-<classname>org.apache.openjpa.persistence.jdbc.DataStoreIdColumn</classname>
-</ulink> annotation customizes the datastore identity column. This annotation
-has the following properties:
-            </para>
-            <itemizedlist>
-                <listitem>
-                    <para>
-<literal>String name</literal>: Defaults to <literal>ID</literal>.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>int precision</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>String columnDefinition</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>boolean insertable</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>boolean updatable</literal>
-                    </para>
-                </listitem>
-            </itemizedlist>
-            <para>
-All properties correspond exactly to the same-named properties on the standard
-<classname>Column</classname> annotation, described in
-<xref linkend="jpa_overview_mapping_column"/>.
-            </para>
-            <example id="ref_guide_mapping_jpa_datastoreidex">
-                <title>
-                    Datastore Identity Mapping
-                </title>
-<programlisting>
-import org.apache.openjpa.persistence.*;
-import org.apache.openjpa.persistence.jdbc.*;
-
-@Entity
-@Table(name="LOGS")
-@DataStoreIdColumn(name="ENTRY")
-public class LogEntry {
-
-    @Lob
-    private String content;
-
-    ...
-}
-</programlisting>
-            </example>
-        </section>
-        <section id="ref_guide_mapping_jpa_version">
-            <title>
-                Surrogate Version Mapping
-            </title>
-            <indexterm zone="ref_guide_mapping_jpa_datastoreid">
-                <primary>
-                    version
-                </primary>
-                <secondary>
-                    mapping
-                </secondary>
-            </indexterm>
-            <indexterm zone="ref_guide_mapping_jpa_version">
-                <primary>
-                    mapping metadata
-                </primary>
-                <secondary>
-                    version
-                </secondary>
-                <seealso>
-                    version
-                </seealso>
-            </indexterm>
-            <indexterm zone="ref_guide_mapping_jpa_version">
-                <primary>
-                    VersionColumn
-                </primary>
-                <seealso>
-                    mapping metadata
-                </seealso>
-            </indexterm>
-            <para>
-OpenJPA supports version fields as defined by the JPA specification, but allows
-you to use a surrogate version column in place of a version field if you like.
-You map the surrogate version column with the
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/VersionColumn.html">
-<classname>org.apache.openjpa.persistence.jdbc.VersionColumn</classname></ulink>
-annotation. You can also use the
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/VersionColumns.html">
-<classname>org.apache.openjpa.persistence.jdbc.VersionColumns</classname>
-</ulink> annotation to declare an array of <classname>VersionColumn</classname>
-values. Each <classname>VersionColumn</classname> has the following properties:
-            </para>
-            <itemizedlist>
-                <listitem>
-                    <para>
-<literal>String name</literal>: Defaults to <literal>VERSN</literal>.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>int length</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>int precision</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>int scale</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>String columnDefinition</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>boolean nullable</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>boolean insertable</literal>
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>boolean updatable</literal>
-                    </para>
-                </listitem>
-            </itemizedlist>
-            <para>
-All properties correspond exactly to the same-named properties on the standard
-<classname>Column</classname> annotation, described in
-<xref linkend="jpa_overview_mapping_column"/>.
-            </para>
-            <para>
-By default, OpenJPA assumes that surrogate versioning uses a version number
-strategy. You can choose a different strategy with the <classname>
-VersionStrategy</classname> annotation described in
-<xref linkend="version-strategy"/>.
-            </para>
-        </section>
-        <section id="ref_guide_mapping_jpa_columns">
-            <title>
-                Multi-Column Mappings
-            </title>
-            <indexterm zone="ref_guide_mapping_jpa_columns">
-                <primary>
-                    mapping metadata
-                </primary>
-                <secondary>
-                    column
-                </secondary>
-            </indexterm>
-            <indexterm zone="ref_guide_mapping_jpa_columns">
-                <primary>
-                    mapping metadata
-                </primary>
-                <secondary>
-                    multi-column mappings
-                </secondary>
-            </indexterm>
-            <indexterm zone="ref_guide_mapping_jpa_columns">
-                <primary>
-                    Columns
-                </primary>
-                <seealso>
-                    mapping metadata
-                </seealso>
-            </indexterm>
-            <para>
-OpenJPA makes it easy to create multi-column
-<link linkend="ref_guide_mapping_custom_field">custom mappings</link>. The JPA
-specification includes a <classname>Column</classname> annotation, but is
-missing a way to declare multiple columns for a single field. OpenJPA remedies
-this with the
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/Columns.html">
-<classname>org.apache.openjpa.persistence.jdbc.Columns</classname></ulink>
-annotation, which contains an array of <classname>Column</classname> values.
-            </para>
-            <para>
-Remember to annotate custom field types with <classname>Persistent</classname>,
-as described in <xref linkend="ref_guide_meta_jpa_persistent"/>.
-            </para>
-        </section>
-        <section id="ref_guide_mapping_jpa_fieldjoin">
-            <title>
-                Join Column Attribute Targets
-            </title>
-            <para>
-<xref linkend="jpa_overview_mapping_rel"/> in the JPA Overview introduced
-you to the <classname>JoinColumn</classname> annotation. A <classname>
-JoinColumn</classname>'s <literal> referencedColumnName</literal> property
-declares which column in the table of the related type this join column links
-to. Suppose, however, that the related type is unmapped, or that it is part of a
-table-per-class inheritance hierarchy. Each subclass that might be assigned to
-the field could reside in a different table, and could use entirely different
-names for its primary key columns. It becomes impossible to supply a single
-<literal>referencedColumnName</literal> that works for all subclasses.
-            </para>
-            <para>
-OpenJPA rectifies this by allowing you to declare which <emphasis>attribute
-</emphasis> in the related type each join column links to, rather than which
-column. If the attribute is mapped differently in various subclass tables,
-OpenJPA automatically forms the proper join for the subclass record at hand. The
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/XJoinColumn.html">
-<classname>org.apache.openjpa.persistence.jdbc.XJoinColumn</classname></ulink>
-annotation has all the same properties as the standard <classname>JoinColumn
-</classname> annotation, but adds an additional <literal>
-referencedAttributeName</literal> property for this purpose. Simply use a
-<classname>XJoinColumn</classname> in place of a <classname>JoinColumn
-</classname> whenever you need to access this added functionality.
-            </para>
-            <para>
-For compound keys, use the
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/XJoinColumns.html">
-<classname>org.apache.openjpa.persistence.jdbc.XJoinColumns</classname></ulink>
-annotation. The value of this annotation is an array of individual <classname>
-XJoinColumn</classname>s.
-            </para>
-        </section>
-        <section id="ref_guide_mapping_jpa_embed">
-            <title>
-                Embedded Mapping
-            </title>
-            <para>
-JPA uses the <classname>AttributeOverride</classname> annotation to override the
-default mappings of an embeddable class. The JPA Overview details this process
-in <xref linkend="jpa_overview_mapping_embed"/>. <classname>
-AttributeOverride</classname>s suffice for simple mappings, but do not allow
-you to override complex mappings. Also, JPA has no way to differentitate between
-a null embedded object and one with default values for all of its fields.
-            </para>
-            <para>
-OpenJPA overcomes these shortcomings with the
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/EmbeddedMapping.html">
-<classname>org.apache.openjpa.persistence.jdbc.EmbeddedMapping</classname>
-</ulink> annotation. This annotation has the following properties:
-            </para>
-            <itemizedlist>
-                <listitem>
-                    <para>
-<literal>String nullIndicatorColumnName</literal>: If the named column's value
-is <literal>NULL</literal>, then the embedded object is assumed to be null. If
-the named column has a non- <literal>NULL</literal> value, then the embedded
-object will get loaded and populated with data from the other embedded fields.
-This property is entirely optional. By default, OpenJPA always assumes the
-embedded object is non-null, just as in standard JPA mapping.
-                    </para>
-                    <para>
-If the column you name does not belong to any fields of the embedded object,
-OpenJPA will create a synthetic null-indicator column with this name. In fact,
-you can specify a value of <literal>true</literal> to simply indicate that you
-want a synthetic null-indicator column, without having to come up with a name
-for it. A value of <literal>false</literal> signals that you explicitly do not
-want a null-indicator column created for this mapping (in case you have
-configured your <link linkend="ref_guide_mapping_defaults">mapping defaults
-</link> to create one by default).
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>String nullIndicatorFieldName</literal>: Rather than name a null
-indicator column, you can name a field of the embedded type. OpenJPA will use
-the column of this field as the null-indicator column.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>MappingOverride[] overrides</literal>: This array allows you to
-override any mapping of the embedded object.
-                    </para>
-                </listitem>
-            </itemizedlist>
-            <para>
-The <classname>EmbeddedMapping</classname>'s <literal>overrides</literal> array
-serves the same purpose as standard JPA's <classname>AttributeOverride
-</classname>s and <classname>AssociationOverride</classname> s. In fact, you can
-also use the <classname>MappingOverride</classname> annotation on an entity
-class to override a complex mapping of its mapped superclass, just as you can
-with <classname> AttributeOverride</classname> and <classname>
-AssociationOverride</classname> s. The <classname>MappingOverrides</classname>
-annotation, whose value is an array of <classname>MappingOverride</classname> s,
-allows you to overide multiple mapped superclass mappings.
-            </para>
-            <para>
-Each
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/MappingOverride.html">
-<classname>org.apache.openjpa.persistence.jdbc.MappingOverride</classname>
-</ulink> annotation has the following properties:
-            </para>
-            <itemizedlist>
-                <listitem>
-                    <para>
-<literal>String name</literal>: The name of the field that is being overridden.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>Column[] columns</literal>: Columns for the new field mapping.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>XJoinColumn[] joinColumns</literal>: Join columns for the new field
-mapping, if it is a relation field.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>ContainerTable containerTable</literal>: Table for the new collection
-or map field mapping. We cover collection mappings in
-<xref linkend="ref_guide_mapping_jpa_coll"/>, and map mappings in
-<xref linkend="ref_guide_mapping_jpa_map"/>.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-<literal>ElementJoinColumn[] elementJoinColumns</literal>: Element join columns
-for the new collection or map field mapping. You will see how to use element
-join columns in <xref linkend="ref_guide_mapping_jpa_coll_joincols"/>.
-                    </para>
-                </listitem>
-            </itemizedlist>
-            <para>
-The following example defines an embeddable <classname> PathCoordinate
-</classname> class with a custom mapping of a <classname>java.awt.Point
-</classname> field to two columns. It then defines an entity which embeds a
-<classname> PointCoordinate</classname> and overrides the default mapping for
-the point field. The entity also declares that if the <classname>PathCoordinate
-</classname>'s <literal>siteName</literal> field column is null, it means that
-no <classname>PathCoordinate</classname> is stored in the embedded record; the
-owning field will load as null.
-            </para>
-            <example id="ref_guide_mapping_jpa_embedex">
-                <title>
-                    Overriding Complex Mappings
-                </title>
-<programlisting>
-import org.apache.openjpa.persistence.jdbc.*;
-
-@Embeddable
-public class PathCoordinate {
-
-    private String siteName;
-
-    @Persistent
-    @Strategy("com.xyz.openjpa.PointValueHandler")
-    private Point point;
-
-    ...
-}
-
-@Entity
-public class Path {
-
-    @Embedded
-    @EmbeddedMapping(nullIndicatorFieldName="siteName", overrides={
-        @MappingOverride(name="siteName", columns=@Column(name="START_SITE")),
-        @MappingOverride(name="point", columns={
-            @Column(name="START_X"),
-            @Column(name="START_Y")
-        })
-    })
-    private PathCoordinate start;
-
-    ...
-}
-</programlisting>
-            </example>
-        </section>
-        <section id="ref_guide_mapping_jpa_coll">
-            <title>
-                Collections
-            </title>
-            <indexterm zone="ref_guide_mapping_jpa_coll">
-                <primary>
-                    mapping metadata
-                </primary>
-                <secondary>
-                    collections
-                </secondary>
-            </indexterm>
-            <para>
-In <xref linkend="ref_guide_meta_jpa_persistent_coll"/>, we explored the
-<classname>PersistentCollection</classname> annotation for persistent collection
-fields that aren't a standard <literal>OneToMany</literal> or <literal>
-ManyToMany</literal> relation. To map these non-standard collections, combine
-OpenJPA's <classname>ContainerTable</classname> annotation with
-<classname>ElementJoinColumn</classname>s.
-We explore the annotations below.
-            </para>
-            <section id="ref_guide_mapping_jpa_coll_table">
-                <title>
-                    Container Table
-                </title>
-                <indexterm zone="ref_guide_mapping_jpa_coll_table">
-                    <primary>
-                        ContainerTable
-                    </primary>
-                    <seealso>
-                        mapping metadata
-                    </seealso>
-                </indexterm>
-                <para>
-The
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/ContainerTable.html">
-<classname>org.apache.openjpa.persistence.jdbc.ContainerTable</classname>
-</ulink> annotation describes a database table that holds collection (or map)
-elements. This annotation has the following properties:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-<literal>String name</literal>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>String catalog</literal>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>String schema</literal>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>XJoinColumn[] joinColumns</literal>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>ForeignKey joinForeignKey</literal>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>Index joinIndex</literal>
-                        </para>
-                    </listitem>
-                </itemizedlist>
-                <para>
-The <literal>name</literal>, <literal>catalog</literal>, <literal>schema
-</literal>, and <literal>joinColumns</literal> properties describe the container
-table and how it joins to the owning entity's table. These properties correspond
-to the same-named properties on the standard <classname> JoinTable</classname>
-annotation, described in <xref linkend="jpa_overview_mapping_assoccoll"/>
-. If left unspecified, the name of the table defaults to the first five
-characters of the entity table name, plus an underscore, plus the field name.
-The <literal>joinForeignKey</literal> and <literal> joinIndex</literal>
-properties override default foreign key and index generation for the join
-columns. We explore foreign keys and indexes later in this chapter.
-                </para>
-                <para>
-You may notice that the container table does not define how to store the
-collection elements. That is left to separate annotations, which are the subject
-of the next sections.
-                </para>
-            </section>
-            <section id="ref_guide_mapping_jpa_coll_joincols">
-                <title>
-                    Element Join Columns
-                </title>
-                <indexterm zone="ref_guide_mapping_jpa_coll_joincols">
-                    <primary>
-                        ElementJoinColumn
-                    </primary>
-                    <seealso>
-                        mapping metadata
-                    </seealso>
-                </indexterm>
-                <para>
-Element join columns are equivalent to standard JPA join columns, except that
-they represent a join to a collection or map element entity rather than a direct
-relation. You represent an element join column with OpenJPA's
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/ElementJoinColumn.html">
-<classname>org.apache.openjpa.persistence.jdbc.ElementJoinColumn</classname>
-</ulink> annotation. To declare a compound join, enclose an array of <classname>
-ElementJoinColumn</classname>s in the
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/ElementJoinColumns.html">
-<classname>org.apache.openjpa.persistence.jdbc.ElementJoinColumns</classname>
-</ulink> annotation.
-                </para>
-                <para>
-An <classname>ElementJoinColumn</classname> always resides in a container table,
-so it does not have the <literal> table</literal> property of a standard
-<classname> JoinColumn</classname>. Like <classname> XJoinColumn</classname>s
-above, <classname> ElementJoinColumn</classname>s can reference a linked
-attribute rather than a static linked column. Otherwise, the <classname>
-ElementJoinColumn</classname> and standard <classname>JoinColumn</classname>
-annotations are equivalent. See <xref linkend="jpa_overview_mapping_rel"/>
-in the JPA Overview for a review of the <classname>JoinColumn</classname>
-annotation.
-                </para>
-            </section>
-            <section id="ref_guide_mapping_jpa_coll_order">
-                <title>
-                    Order Column
-                </title>
-                <indexterm zone="ref_guide_mapping_jpa_coll_order">
-                    <primary>
-                        OrderColumn
-                    </primary>
-                    <seealso>
-                        mapping metadata
-                    </seealso>
-                </indexterm>
-                <para>
-Relational databases do not guarantee that records are returned in insertion
-order. If you want to make sure that your collection elements are loaded in the
-same order they were in when last stored, you must declare an order column.
-OpenJPA's
-<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/OrderColumn">
-<classname>org.apache.openjpa.persistence.jdbc.OrderColumn</classname></ulink>
-annotation has the following properties:
-                </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>
-<literal>String name</literal>: Defaults to <literal>ORDR</literal>.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-<literal>boolean enabled</literal>
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>

[... 4307 lines stripped ...]


Mime
View raw message