<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>4.&nbsp; Mapping Defaults</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA User's Guide"><link rel="up" href="ref_guide_mapping.html" title="Chapter&nbsp;7.&nbsp; Mapping"><link rel="prev" href="ref_guide_mapping_middle.html" title="3.&nbsp; Meet-in-the-Middle Mapping"><link rel="next" href="ref_guide_mapping_factory.html" title="5.&nbsp; Mapping Factory"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.&nbsp;
            Mapping Defaults
        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_mapping_middle.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;7.&nbsp;
        Mapping
    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_mapping_factory.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_mapping_defaults"></a>4.&nbsp;
            Mapping Defaults
        </h2></div></div></div><a class="indexterm" name="d0e24599"></a><a class="indexterm" name="d0e24602"></a><p>
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
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaults.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.meta.MappingDefaults</code></a>
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.
        </p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
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 <a href="ref_guide_schema_info.html#ref_guide_schema_info_factory" title="11.2.&nbsp; Schema Factory">Section&nbsp;11.2, &#8220;
                Schema Factory
            &#8221;</a>),
or use explicit foreign key mappings as described in
<a href="ref_guide_mapping_jpa.html#ref_guide_mapping_jpa_fk" title="7.9.2.&nbsp; Foreign Keys">Section&nbsp;7.9.2, &#8220;
                    Foreign Keys
                &#8221;</a>.
            </p></div><p>
The <a href="ref_guide_conf_jdbc.html#openjpa.jdbc.MappingDefaults" title="6.8.&nbsp; openjpa.jdbc.MappingDefaults"><code class="literal">
openjpa.jdbc.MappingDefaults</code></a> configuration property controls
the <code class="classname">MappingDefaults</code> interface implementation in use. This
is a plugin property (see <a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a>), so
you can substitute your own implementation or configure the existing ones.
OpenJPA includes the following standard implementations:
        </p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">jpa</code>: Provides defaults in compliance with the JPA standard.
This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/PersistenceMappingDefaults.html" target="_top">
<code class="classname">org.apache.openjpa.persistence.jdbc.PersistenceMappingDefaults
</code></a> class. This class extends the <code class="classname">
MappingDefaultsImpl</code> class described below, so it has all the same
properties (though with different default values), as well as:
                </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">PrependFieldNameToJoinTableInverseJoinColumns</code>: 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.
                        </p></li></ul></div></li><li><p>
<code class="literal">default</code>: This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/MappingDefaultsImpl.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.meta.MappingDefaultsImpl</code></a>
class. This default implementation is highly configurable. It has the following
properties:
                </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">DefaultMissingInfo</code>: 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
<code class="literal">buildSchema</code> and <code class="literal">validate</code>.
                        </p></li><li><p>
<code class="literal">BaseClassStrategy</code>: The default mapping strategy for base
classes. You can specify a built-in strategy alias or the full class name of a
<a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_class" title="10.1.&nbsp; Custom Class Mapping">custom class strategy</a>.
You can also use OpenJPA's plugin format (see
<a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a>) to pass arguments to the
strategy instance. See the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html" target="_top">
<code class="literal">org.apache.openjpa.jdbc.meta.strats</code></a> package for
available strategies.
                        </p></li><li><p>
<code class="literal">SubclassStrategy</code>: The default mapping strategy for
subclasses. You can specify a builtin strategy alias or the full class name of a
<a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_class" title="10.1.&nbsp; Custom Class Mapping"> custom class strategy</a>.
You can also use OpenJPA's plugin format (see
<a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a>) to pass arguments to the
strategy instance. Common strategies are <code class="literal">vertical</code> and
<code class="literal">flat</code>, the default. See the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html" target="_top">
<code class="literal">org.apache.openjpa.jdbc.meta.strats</code></a> package for all
available strategies.
                        </p></li><li><p>
<code class="literal">VersionStrategy</code>: The default version strategy for classes
without a version field. You can specify a builtin strategy alias or the full
class name of a <a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_versdiscrim" title="10.2.&nbsp; Custom Discriminator and Version Strategies"> custom
version strategy</a>. You can also use OpenJPA's plugin format (see
<a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a>) to pass arguments to the
strategy instance. Common strategies are <code class="literal">none</code>, <code class="literal">
state-comparison</code>, <code class="literal"> timestamp</code>, and <code class="literal">
version-number</code>, the default. See the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html" target="_top">
<code class="literal">org.apache.openjpa.jdbc.meta.strats</code></a> package for all
available strategies.
                        </p></li><li><p>
<code class="literal">DiscriminatorStrategy</code>: The default discriminator strategy
when no discriminator value is given. You can specify a builtin strategy alias
or the full class name of a
<a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_versdiscrim" title="10.2.&nbsp; Custom Discriminator and Version Strategies"> custom discriminator
strategy</a>. You can also use OpenJPA's plugin format (see
<a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a>) to pass arguments to the
strategy instance. Common strategies are <code class="literal">final</code> for a base
class without subclasses, <code class="literal">none</code> to use joins to subclass
tables rather than a discriminator column, and <code class="literal"> class-name</code>,
the default. See the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/strats/package-summary.html" target="_top">
<code class="literal">org.apache.openjpa.jdbc.meta.strats</code></a> package for all
available strategies.
                        </p></li><li><p>
<code class="literal">FieldStrategies</code>: This property associates field types with
custom strategies. The format of this property is similar to that of plugin
strings (see <a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a> ), 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
<a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_field" title="10.3.&nbsp; Custom Field Mapping">Section&nbsp;10.3, &#8220;
                Custom Field Mapping
            &#8221;</a> for information on custum
field strategies.
                        </p></li><li><p>
<code class="literal">ForeignKeyDeleteAction</code>: The default delete action of foreign
keys representing relations to other objects. Recognized values include
<code class="literal">restrict</code>, <code class="literal">cascade</code>, <code class="literal">null</code>
, <code class="literal">default</code>. These values correspond exactly to the standard
database foreign key actions of the same names.
                        </p><p>
The value <code class="literal">none</code> tells OpenJPA not to create database foreign
keys on relation columns. This is the default.
                        </p></li><li><p>
<code class="literal">JoinForeignKeyDeleteAction</code>: 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 <code class="literal">
ForeignKeyDeleteAction</code> property above.
                        </p></li><li><p>
<code class="literal">DeferConstraints</code>: Whether to use deferred database
constraints if possible. Defaults to false.
                        </p></li><li><p>
<code class="literal">IndexLogicalForeignKeys</code>: 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 <code class="literal">ForeignKey</code> properties above not to use a physical
database foreign key. Defaults to true.
                        </p></li><li><p>
<code class="literal">DataStoreIdColumnName</code>: The default name of datastore
identity columns.
                        </p></li><li><p>
<code class="literal">DiscriminatorColumnName</code>: The default name of discriminator
columns.
                        </p></li><li><p>
<code class="literal">IndexDiscriminator</code>: Whether to index the discriminator
column. Defaults to true.
                        </p></li><li><p>
<code class="literal">VersionColumnName</code>: The default name of version columns.
                        </p></li><li><p>
<code class="literal">IndexVersion</code>: Whether to index the version column. Defaults
to false.
                        </p></li><li><p>
<code class="literal">AddNullIndicator</code>: 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.
                        </p></li><li><p>
<code class="literal">NullIndicatorColumnName</code>: The default name of synthetic null
indicator columns for embedded objects.
                        </p></li><li><p>
<code class="literal">OrderLists</code>: Whether to create a database ordering column for
maintaining the order of persistent lists and arrays.
                        </p></li><li><p>
<code class="literal">OrderColumnName</code>: The default name of collection and array
ordering columns.
                        </p></li><li><p>
<code class="literal">StoreEnumOrdinal</code>: 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.
                        </p></li><li><p>
<code class="literal">StoreUnmappedObjectIdString</code>: 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.
                        </p></li></ul></div></li></ul></div><p>
The example below turns on foreign key generation during schema creation and
associates the <code class="classname">org.mag.data.InfoStruct</code> field type with
the custom <code class="classname">org.mag.mapping.InfoStructHandler</code> value
handler.
        </p><div class="example"><a name="ref_guide_mapping_defaults_conf"></a><p class="title"><b>Example&nbsp;7.12.&nbsp;
                Configuring Mapping Defaults
            </b></p><div class="example-contents"><pre class="programlisting">
&lt;property name="openjpa.jdbc.MappingDefaults"
    value="ForeignKeyDeleteAction=restrict,
    FieldStrategies='org.mag.data.InfoStruct=org.mag.mapping.InfoStructHandler'"/&gt;
</pre></div></div><br class="example-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_mapping_middle.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_mapping.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_mapping_factory.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.&nbsp;
            Meet-in-the-Middle Mapping
        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.&nbsp;
            Mapping Factory
        </td></tr></table></div></body></html>