openjpa-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Patrick Linskey" <plins...@gmail.com>
Subject Re: svn commit: r560330 [2/2] - /openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
Date Fri, 27 Jul 2007 19:32:12 GMT
No worries. Also, FYI, I didn't correct it per se -- I just happened
to be making changes to the same file at the same time.

-Patrick

On 7/27/07, catalina wei <catalina.wei@gmail.com> wrote:
> Hi, Patrick,
> Sorry about this mess and thanks for correcting it.
> The attached openjpa-project.patch looked GOOD.
> Probably the  "irgnore white space diffs" got turned on when comparing the
> working copy with the latest revision in svn, but forgot to turn it off at
> commit time.
> We will be careful next time.
>
> Catalina
>
>
> On 7/27/07, Patrick Linskey <plinskey@gmail.com> wrote:
> >
> > Hi,
> >
> > These types of commits are really difficult to parse -- I find it hard
> > to believe that we really needed to change every line of the file.
> > Does anyone know of any way to put in place some sort of line-ending
> > restrictions, or otherwise avoid these sorts of commits?
> >
> > -Patrick
> >
> > On 7/27/07, wisneskid@apache.org <wisneskid@apache.org> wrote:
> > >
> > > 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 ...]
> > >
> > >
> >
> >
> > --
> > Patrick Linskey
> > 202 669 5907
> >
>


-- 
Patrick Linskey
202 669 5907

Mime
View raw message