<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>10.&nbsp; Custom Mappings</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_ext.html" title="9.&nbsp; Mapping Extensions"><link rel="next" href="ref_guide_orphan.html" title="11.&nbsp; Orphaned Keys"></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">10.&nbsp;
            Custom Mappings
        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_mapping_ext.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_orphan.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_custom"></a>10.&nbsp;
            Custom Mappings
        </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_class">10.1. 
                Custom Class Mapping
            </a></span></dt><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_versdiscrim">10.2. 
                Custom Discriminator and Version Strategies
            </a></span></dt><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_field">10.3. 
                Custom Field Mapping
            </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_vhandler">10.3.1. 
                    Value Handlers
                </a></span></dt><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_fieldstrat">10.3.2. 
                    Field Strategies
                </a></span></dt><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_field_conf">10.3.3. 
                    Configuration
                </a></span></dt></dl></dd></dl></div><a class="indexterm" name="d0e26455"></a><a class="indexterm" name="d0e26458"></a><p>
In OpenJPA, you are not limited to the set of standard mappings defined by the
specification. OpenJPA allows you to define custom class, discriminator,
version, and field mapping strategies with all the power of OpenJPA's built-in
strategies.
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_custom_class"></a>10.1.&nbsp;
                Custom Class Mapping
            </h3></div></div></div><p>
To create a custom class mapping, write an implementation of the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/ClassStrategy.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.meta.ClassStrategy</code></a>
interface. You will probably want to extend one of the existing abstract or
concrete strategies in the <code class="literal">org.apache.openjpa.jdbc.meta.strats
</code> package.
            </p><p>
The <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Strategy.html" target="_top">
<code class="classname">org.apache.openjpa.persistence.jdbc.Strategy</code></a>
annotation allows you to declare a custom class mapping strategy in JPA mapping
metadata. Set the value of the annotation to the full class name of your custom
strategy. You can configure your strategy class' bean properties using
OpenJPA's plugin syntax, detailed in <a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a>.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_custom_versdiscrim"></a>10.2.&nbsp;
                Custom Discriminator and Version Strategies
            </h3></div></div></div><p>
To define a custom discriminator or version strategy, implement the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/DiscriminatorStrategy.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.meta.DiscriminatorStrategy</code>
</a> or
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/VersionStrategy.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.meta.VersionStrategy</code></a>
interface, respectively. You might extend one of the existing abstract or
concrete strategies in the <code class="literal">org.apache.openjpa.jdbc.meta.strats
</code> package.
            </p><p>
OpenJPA includes the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/DiscriminatorStrategy.html" target="_top">
<code class="classname">org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy</code>
</a> and
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/VersionStrategy.html" target="_top">
<code class="classname">org.apache.openjpa.persistence.jdbc.VersionStrategy</code>
</a> class annotations for declaring a custom discriminator or version
strategy in JPA mapping metadata. Set the string value of these annotations to
the full class name of your implementation, or to the class name or alias of an
existing OpenJPA implementation.
            </p><p>
As with custom class mappings, you can configure your strategy class' bean
properties using OpenJPA's plugin syntax, detailed in
<a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a>.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_mapping_custom_field"></a>10.3.&nbsp;
                Custom Field Mapping
            </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_vhandler">10.3.1. 
                    Value Handlers
                </a></span></dt><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_fieldstrat">10.3.2. 
                    Field Strategies
                </a></span></dt><dt><span class="section"><a href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_field_conf">10.3.3. 
                    Configuration
                </a></span></dt></dl></div><a class="indexterm" name="d0e26529"></a><p>
While custom class, discriminator, and version mapping can be useful, custom
field mappings are far more common. OpenJPA offers two types of custom field
mappings: value handlers, and full custom field strategies. The following
sections examine each.
            </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_custom_vhandler"></a>10.3.1.&nbsp;
                    Value Handlers
                </h4></div></div></div><a class="indexterm" name="d0e26539"></a><p>
Value handlers make it trivial to map any type that you can break down into one
or more simple values. All value handlers implement the <code class="classname">
org.apache.openjpa.jdbc.meta.ValueHandler</code> interface; see its
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/ValueHandler.html" target="_top"> Javadoc
</a> for details.  Also, examine the built-in handlers in the <code class="filename">
src/openjpa/jdbc/meta/strats</code> directory of your OpenJPA source
distribution.  Use these functional implementations as examples when you
create your own value handlers.
                </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_custom_fieldstrat"></a>10.3.2.&nbsp;
                    Field Strategies
                </h4></div></div></div><a class="indexterm" name="d0e26560"></a><p>
OpenJPA interacts with persistent fields through the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/meta/FieldStrategy" target="_top"><code class="classname">
org.apache.openjpa.jdbc.meta.FieldStrategy</code></a> interface. You
can implement this interface yourself to create a custom field strategy, or
extend one of the existing abstract or concrete strategies in the <code class="literal">
org.apache.openjpa.jdbc.meta.strats</code> package. Creating a custom field
strategy is more difficult than writing a custom value handler, but gives you
more freedom in how you interact with the database.
                </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ref_guide_mapping_custom_field_conf"></a>10.3.3.&nbsp;
                    Configuration
                </h4></div></div></div><a class="indexterm" name="d0e26579"></a><p>
OpenJPA gives you two ways to configure your custom field mappings. The
<code class="literal">FieldStrategies</code> property of the built-in <code class="classname">
MappingDefaults</code> implementations allows you to globally associate
field types with their corresponding custom value handler or strategy. OpenJPA
will automatically use your custom strategies when it encounters a field of the
associated type. OpenJPA will use your custom value handlers whenever it
encounters a field of the associated type.
<a href="ref_guide_mapping_defaults.html" title="4.&nbsp; Mapping Defaults">Section&nbsp;4, &#8220;
            Mapping Defaults
        &#8221;</a> described mapping
defaults in detail.
                </p><p>
Your other option is to explicitly install a custom value handler or strategy on
a particular field. To do so, specify the full name of your implementation class
in the proper mapping metadata extension. OpenJPA includes the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/jdbc/Strategy.html" target="_top">
<code class="classname">org.apache.openjpa.persistence.jdbc.Strategy</code></a>
annotation. You can configure the named strategy or handler's bean
properties in these extensions using 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>).
                </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_mapping_ext.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_orphan.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.&nbsp;
            Mapping Extensions
        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;11.&nbsp;
            Orphaned Keys
        </td></tr></table></div></body></html>