You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
svn commit: r434517 [17/23] - in /incubator/openjpa/trunk:
openjpa-kernel/src/main/java/org/apache/openjpa/meta/
openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/
openjpa-project/src/doc/manual/
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml Thu Aug 24 13:41:12 2006
@@ -1,799 +1,835 @@
-
- <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>
+<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"></xref> 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>
+ <primary>
+ forward mapping
+ </primary>
</indexterm>
<indexterm zone="ref_guide_mapping_mappingtool">
- <primary>mapping tool</primary>
- <seealso>forward mapping</seealso>
+ <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 the <literal>mappingtool
- </literal> shell/batch script included in the OpenJPA distribution,
- or through its Java class,
- <ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingTool"><classname>
- org.apache.openjpa.jdbc.meta.MappingTool</classname></ulink>.
- </para>
+ <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
+the <literal>mappingtool</literal> shell/batch script included in the OpenJPA
+distribution, or through its Java class,
+<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingTool"><classname>
+org.apache.openjpa.jdbc.meta.MappingTool</classname></ulink>.
+ </para>
<note>
- <para><xref linkend="ref_guide_integration_mappingtool"/>
- describes the mapping tool Ant task.
- </para>
+ <para>
+<xref linkend="ref_guide_integration_mappingtool"></xref> describes the mapping
+tool Ant task.
+ </para>
</note>
<example id="ref_guide_mapping_mappingtool_typical">
- <title>Using the Mapping Tool</title>
- <programlisting format="linespecific">
+ <title>
+ Using the Mapping Tool
+ </title>
+<programlisting>
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 <add | refresh | drop | build
- | retain | none></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"/>.
- 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 <stdout | output file></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 <stdout | output file></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 <true/t | false/f></literal>:
- Corresponds to the same-named option on the schema tool.
- </para>
- </listitem>
- <listitem>
- <para><literal>-dropSequences/-dsq <true/t | false/f></literal>:
- Corresponds to the same-named option on the schema tool.
- </para>
- </listitem>
- <listitem>
- <para><literal>-openjpaTables/-kt <true/t | false/f></literal>:
- Corresponds to the same-named option on the schema tool.
- </para>
- </listitem>
- <listitem>
- <para><literal>-ignoreErrors/-i <true/t | false/f></literal>:
- Corresponds to the same-named option on the schema tool.
- </para>
- </listitem>
- <listitem>
- <para><literal>-schemas/-s <schema and table names></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 <true/t | false/f></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 <true/t | false/f></literal>:
- Whether to read and manipulate primary key information of
- existing tables. Defaults to false.
- </para>
- </listitem>
- <listitem>
- <para><literal>-foreignKeys/-fk <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></literal>:
- Whether to manipulate sequences. Defaults to true.
- </para>
- </listitem>
- <listitem>
- <para><literal>-meta/-m <true/t | false/f></literal>: Whether
- the given action applies to metadata rather than or in addition
- to mappings.
+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>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>-schemaAction/-sa <add | refresh | drop | build | retain | none>
+</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"></xref>. 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 <stdout | output file></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 <stdout | output file></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 <true/t | false/f></literal>: Corresponds to the
+same-named option on the schema tool.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>-dropSequences/-dsq <true/t | false/f></literal>: Corresponds to
+the same-named option on the schema tool.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>-openjpaTables/-kt <true/t | false/f></literal>: Corresponds to
+the same-named option on the schema tool.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>-ignoreErrors/-i <true/t | false/f></literal>: Corresponds to
+the same-named option on the schema tool.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>-schemas/-s <schema and table names></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 <true/t | false/f></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 <true/t | false/f></literal>: Whether to read
+and manipulate primary key information of existing tables. Defaults to false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>-foreignKeys/-fk <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></literal>: Whether to
+manipulate sequences. Defaults to true.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>-meta/-m <true/t | false/f></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 when
- using JPA mapping defaults (see
- <xref linkend="ref_guide_mapping_defaults"/>). It makes the
- database schema match your existing mappings. If your provided
- mappings conflict with a class definition, OpenJPA will fail with
- an informative 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.
+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>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>buildSchema</literal>: This is the default action when using JPA
+mapping defaults (see <xref linkend="ref_guide_mapping_defaults"></xref> ). It
+makes the database schema match your existing mappings. If your provided
+mappings conflict with a class definition, 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.
+Each additional argument to the tool should be one of:
</para>
- </listitem>
+ <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>
+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"></xref> ).
+ </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>
+The mappings generated by the mapping tool are stored by the system <emphasis>
+mapping factory</emphasis>. <xref linkend="ref_guide_mapping_factory"></xref>
+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's <literal>buildSchema</literal>
- action on your persistent classes. This is the default action when
- you use JPA mapping defaults
- (see <xref linkend="ref_guide_mapping_defaults"/>).
- </para>
- <para>
- The <literal>buildSchema</literal> action manipulates the database
- schema to match your mappings. It fails if any of your mappings
- don't match your object model.
- </para>
- <example id="ref_guide_mapping_mappingtool_buildschema">
- <title>Creating the Relational Schema from Mappings</title>
- <programlisting format="linespecific">
+ <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">
+</xref> of the JPA Overview to override any unsatisfactory defaults, run the
+mapping tool's <literal>buildSchema</literal> action on your persistent classes.
+This is the default action when you use JPA mapping defaults (see
+<xref linkend="ref_guide_mapping_defaults"></xref> ).
+ </para>
+ <para>
+The <literal>buildSchema</literal> action manipulates the database schema to
+match your mappings. It fails if any of your mappings don't match your object
+model.
+ </para>
+ <example id="ref_guide_mapping_mappingtool_buildschema">
+ <title>
+ Creating the Relational Schema from Mappings
+ </title>
+<programlisting>
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_dropschema">
- <title>Dropping Mappings and Association Schema</title>
- <programlisting format="linespecific">
+ </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_dropschema">
+ <title>
+ Dropping Mappings and Association Schema
+ </title>
+<programlisting>
mappingtool -sa drop Magazine.java
</programlisting>
- </example>
+ </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 format="linespecific">
+ <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>
mappingtool -a buildSchema -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 format="linespecific">
+ </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>
mappingtool -a buildSchema -sql update.sql Magazine.java
</programlisting>
- </example>
+ </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 format="linespecific">
+ <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">
+</xref>.
+ </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"></xref>) 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>
<property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>
</programlisting>
- <para>
- The setting above corresponds to running the following command:
- </para>
- <programlisting format="linespecific">
+ <para>
+The setting above corresponds to running the following command:
+ </para>
+<programlisting>
mappingtool -a buildSchema -fk true
</programlisting>
- </example>
+ </example>
</section>
- </section>
- <section id="ref_guide_pc_reverse">
- <title>Reverse Mapping</title>
+ </section>
+ <section id="ref_guide_pc_reverse">
+ <title>
+ Reverse Mapping
+ </title>
<indexterm zone="ref_guide_pc_reverse">
- <primary>reverse mapping</primary>
+ <primary>
+ reverse mapping
+ </primary>
</indexterm>
<indexterm zone="ref_guide_pc_reverse">
- <primary>reverse mapping tool</primary>
- <seealso>reverse mapping</seealso>
+ <primary>
+ reverse mapping tool
+ </primary>
+ <seealso>
+ reverse mapping
+ </seealso>
</indexterm>
<indexterm>
- <primary>mapping metadata</primary>
- <secondary>reverse mapping</secondary>
- <see>reverse mapping</see>
+ <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>
-<!-- ### EJBDOC -->
+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"></xref>. The reverse mapping tool,
+however, can give you an excellent starting point from which to grow your
+persistent classes.
+ </para>
+ <!-- ### -->
<note>
- <para>
- The reverse mapping tool in this release does not yet output JPA
- annotations. It is limited to JDO metadata output.
- </para>
+ <para>
+The reverse mapping tool in this release does not yet output JPA annotations. It
+is limited to JDO metadata output.
+ </para>
</note>
<para>
- To use the reverse mapping tool, follow the steps below:
- </para>
+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 format="linespecific">
+ <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>
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 the included
- <literal>reversemappingtool</literal> script, or through
- its Java class,
- <ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ReverseMappingTool"><classname>org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></ulink>.
- </para>
- <example id="ref_guide_pc_reverse_reversemappingtool">
- <title>Using the Reverse Mapping Tool</title>
- <programlisting format="linespecific">
+ </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"></xref>.
+ </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 the included <literal>reversemappingtool
+</literal> script, or through its Java class,
+<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ReverseMappingTool">
+<classname>org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></ulink>.
+ </para>
+ <example id="ref_guide_pc_reverse_reversemappingtool">
+ <title>
+ Using the Reverse Mapping Tool
+ </title>
+<programlisting>
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:
+ </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 <schema and table names></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"></xref>. 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 <package name></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 <output directory></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>-useSchemaName/-sn <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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>-useDatastoreIdentity/-ds <true/t | false/f></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 <true/t | false/f></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 <true/t | false/f></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 <suffix></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 <type mapping></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 <class name></literal>: The full class name
+of a
+<ulink url="../apidocs/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="../apidocs/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 <properties file or resource></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.<property name> <property value></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
+all necessary persistence metadata and mappings.
+ </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 them with <literal>javac</literal>, <literal>jikes
+</literal>, or your favorite Java compiler. Make sure the classes and their
+metadata are located in the directory corresponding to the <literal>-package
+</literal> flag you gave the reverse mapping tool. Finally, enhance the classes
+if necessary (see <xref linkend="ref_guide_pc_enhance"></xref> ).
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+Your persistent classes are now ready to access your existing schema.
</para>
- <itemizedlist>
- <listitem>
- <para><literal>-schemas/-s <schema and table names>
- </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 <package name></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 <output directory>
- </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>-useSchemaName/-sn <true/t | false/f>
- </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
- <true/t | false/f></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 <true/t | false/f>
- </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 <true/t | false/f>
- </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 <true/t | false/f>
- </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 <true/t
- | false/f></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>-useDatastoreIdentity/-ds
- <true/t | false/f></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 <true/t
- | false/f></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 <true/t
- | false/f></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
- <suffix></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>
-<!-- ### EJBDOC : need some EJB equiv -->
-<!-- ### EJBDOC : need some EJB equiv -->
-<!-- ### EJBDOC : need some EJB equiv form XML / anno -->
- <listitem>
- <para><literal>-typeMap/-typ <type mapping></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
- <class name></literal>: The full class name of a
- <ulink url="../apidocs/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="../apidocs/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 <properties
- file or resource></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.<property name>
- <property value></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.
+ <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="../apidocs/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="../apidocs/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>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal><table name>.table-type <type></literal>: Override the
+default type of the table with name <literal><table name></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><class name>.rename <new class name></literal>: Override
+the given tool-generated name <literal><class name></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><table name>.class-name <new class name></literal>: Assign
+the given fully-qualified class name to the type created from the table with
+name <literal><table name></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><class name>.identity <datastore | builtin | identity class
+name></literal>: Set this property to <literal>datastore</literal> to use
+datastore identity for the class <literal><class name></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><class name>.<field name>.rename <new field name>
+</literal>: Override the tool-generated <literal><field name></literal> in
+class <literal><class name></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><table name>.<column name>.field-name <new field
+name></literal>: Set the generated field name for the <literal><table
+name></literal> table's <literal><column name></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><class name>.<field name>.type <field type></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><class name>.<field name>.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>
- Running the tool will generate <filename>.java</filename> files
- for each generated class (and its application identity class,
- if applicable), along with all necessary persistence metadata
- and mappings.
- </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 them with
- <literal>javac</literal>, <literal>jikes</literal>, or your
- favorite Java compiler. Make sure the classes and their
- metadata are located in the directory corresponding to
- the <literal>-package</literal> flag you gave the reverse
- mapping tool. 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="../apidocs/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="../apidocs/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><table name>.table-type <type>
- </literal>: Override the default type of the table with
- name <literal><table name></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><class name>.rename <new class name>
- </literal>: Override the given tool-generated name
- <literal><class name></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><table name>.class-name
- <new class name></literal>: Assign the given
- fully-qualified class name to the type created from the
- table with name <literal><table name></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><class name>.identity <datastore |
- builtin | identity class name></literal>: Set this
- property to <literal>datastore</literal> to use datastore
- identity for the class <literal><class
- name></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><class name>.<field name>.rename
- <new field name></literal>: Override the
- tool-generated <literal><field name></literal> in
- class <literal><class name></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><table name>.<column name>.field-name
- <new field name></literal>: Set the generated field
- name for the <literal><table name></literal> table's
- <literal><column name></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><class name>.<field name>.type
- <field type></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><class name>.<field name>.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 format="linespecific">
+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>
reversemappingtool -pkg com.xyz -cp custom.properties schema.xml
</programlisting>
- <para>
- Example <filename>custom.properties</filename>:
- </para>
- <programlisting format="linespecific">
+ <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
@@ -806,483 +842,534 @@
com.xyz.pub.Company.identity: com.xyz.pub.CompanyId
</programlisting>
- </example>
- <para>
- Your OpenJPA download includes the <classname>
- PropertiesReverseCustomizer</classname> source code. You can use
- this code as an example when writing your own customization class.
- </para>
+ </example>
+ <para>
+Your OpenJPA download includes the <classname> PropertiesReverseCustomizer
+</classname> source code. You can use this code as an example when writing your
+own customization class.
+ </para>
</section>
- </section>
- <section id="ref_guide_mapping_middle">
- <title>Meet-in-the-Middle Mapping</title>
+ </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>
+ <primary>
+ meet-in-the-middle mapping
+ </primary>
</indexterm>
<indexterm zone="ref_guide_pc_reverse">
- <primary>reverse mapping tool</primary>
- <seealso>reverse mapping</seealso>
+ <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. OpenJPA has two
- tools to aid meet-in-the-middle mapping. First, the OpenJPA Workbench
- includes a visual interface to wiring your classes and schema together.
-<!-- ### JDO2MIG
- See <xref linkend="gui_intro"/> to get started with the Workbench.
--->
- Second, the mapping tool's <literal>validate</literal> action is useful
- to meet-in-the-middle mappers. We examined the mapping tool in
- <xref linkend="ref_guide_mapping_mappingtool"/>. The <literal>validate
- </literal> action verifies that the mapping information for a class
- matches the class definition and the existing schema. It throws an
- informative exception when your mappings are incorrect.
- </para>
+ <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. We examined the mapping tool in
+<xref linkend="ref_guide_mapping_mappingtool"></xref>. The <literal>validate
+</literal> action verifies that the mapping information for a class matches the
+class definition and the existing schema. It throws an informative exception
+when your mappings are incorrect.
+ </para>
<example id="ref_guide_mapping_mappingtool_validate">
- <title>Validating Mappings</title>
- <programlisting format="linespecific">
+ <title>
+ Validating Mappings
+ </title>
+<programlisting>
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>
- <para><literal>buildSchema</literal> is the default action when you use
- JPA mapping defaults (<xref linkend="ref_guide_mapping_defaults"/>).
- </para>
+The <literal>buildSchema</literal> action we discussed in
+<xref linkend="ref_guide_mapping_mappingtool"></xref> 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>
+ <para>
+<literal>buildSchema</literal> is the default action when you use JPA mapping
+defaults ( <xref linkend="ref_guide_mapping_defaults"></xref> ).
+ </para>
<example id="ref_guide_mapping_middle_buildschema_mid">
- <title>Creating the Relational Schema from Mappings</title>
- <programlisting format="linespecific">
+ <title>
+ Creating the Relational Schema from Mappings
+ </title>
+<programlisting>
mappingtool Magazine.java
</programlisting>
</example>
- </section>
- <section id="ref_guide_mapping_defaults">
- <title>Mapping Defaults</title>
+ </section>
+ <section id="ref_guide_mapping_defaults">
+ <title>
+ Mapping Defaults
+ </title>
<indexterm zone="ref_guide_mapping_defaults">
- <primary>MappingDefaults</primary>
+ <primary>
+ MappingDefaults
+ </primary>
</indexterm>
<indexterm>
- <primary>mapping metadata</primary>
- <secondary>defaults</secondary>
- <see>MappingDefaults</see>
+ <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="../apidocs/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>
+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="../apidocs/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, or use explicit
- foreign key mappings as described in
- <phrase><xref linkend="ref_guide_mapping_jpa_fk"/></phrase>
-
- .
- </para>
+ <para>
+OpenJPA relies on foreign key constraint information at runtime to order SQL
+appropriately. Be sure to set your mapping defaults to reflect your existing
+database constraints, or use explicit foreign key mappings as described in
+<phrase><xref linkend="ref_guide_mapping_jpa_fk"></xref></phrase>.
+ </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="../apidocs/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).
- </para>
- </listitem>
- <listitem>
- <para><phrase><literal>default</literal>:
- </phrase>
- This is an alias for the
- <ulink url="../apidocs/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:
+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"></xref> ), so
+you can substitute your own implementation or configure the existing ones.
+OpenJPA includes the following standard implementations:
</para>
- <itemizedlist>
- <listitem>
- <para><literal>DefaultMissingInfo</literal>: Whether to
- default missing column and table names rather than
- throw an exception. Defaults to false, meaning full
- mappings are required at runtime and when using
- mapping tool actions like <literal>buildSchema</literal>
- and <literal>validate</literal>.
- </para>
- <para>
- The <literal>jpa</literal> plugin above sets this
- property to true to meet the JPA specification.
- </para>
- </listitem>
- <listitem>
- <para><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="../apidocs/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="../apidocs/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="../apidocs/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="../apidocs/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>,
[... 4162 lines stripped ...]