| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>10. Custom Mappings</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_mapping.html" title="Chapter 7. Mapping"><link rel="prev" href="ref_guide_mapping_ext.html" title="9. Mapping Extensions"><link rel="next" href="ref_guide_orphan.html" title="11. 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. |
| Custom Mappings |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_mapping_ext.html">Prev</a> </td><th width="60%" align="center">Chapter 7. |
| Mapping |
| </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_orphan.html">Next</a></td></tr></table><hr></div><div class="section" title="10. Custom Mappings"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_mapping_custom">10. |
| 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="d5e14949"></a> |
| <a class="indexterm" name="d5e14951"></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" title="10.1. Custom Class Mapping"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_mapping_custom_class">10.1. |
| Custom Class Mapping |
| </h3></div></div></div> |
| |
| <p> |
| To create a custom class mapping, write an implementation of the |
| <a class="ulink" 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 class="ulink" 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 class="xref" href="ref_guide_conf_plugins.html" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>. |
| </p> |
| </div> |
| <div class="section" title="10.2. Custom Discriminator and Version Strategies"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_mapping_custom_versdiscrim">10.2. |
| Custom Discriminator and Version Strategies |
| </h3></div></div></div> |
| |
| <p> |
| To define a custom discriminator or version strategy, implement the |
| <a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/meta/DiscriminatorStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.jdbc.meta.DiscriminatorStrategy</code> |
| </a> or |
| <a class="ulink" 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 class="ulink" href="../javadoc/org/apache/openjpa/persistence/jdbc/DiscriminatorStrategy.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy</code> |
| </a> and |
| <a class="ulink" 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 class="xref" href="ref_guide_conf_plugins.html" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a>. |
| </p> |
| </div> |
| <div class="section" title="10.3. Custom Field Mapping"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_mapping_custom_field">10.3. |
| 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="d5e14983"></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" title="10.3.1. Value Handlers"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_mapping_custom_vhandler">10.3.1. |
| Value Handlers |
| </h4></div></div></div> |
| |
| <a class="indexterm" name="d5e14989"></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 class="ulink" 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" title="10.3.2. Field Strategies"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_mapping_custom_fieldstrat">10.3.2. |
| Field Strategies |
| </h4></div></div></div> |
| |
| <a class="indexterm" name="d5e14999"></a> |
| <p> |
| OpenJPA interacts with persistent fields through the |
| <a class="ulink" 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" title="10.3.3. Configuration"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_mapping_custom_field_conf">10.3.3. |
| Configuration |
| </h4></div></div></div> |
| |
| <a class="indexterm" name="d5e15009"></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 class="xref" href="ref_guide_mapping_defaults.html" title="4. Mapping Defaults">Section 4, “ |
| Mapping Defaults |
| ”</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 class="ulink" 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 class="xref" href="ref_guide_conf_plugins.html" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_mapping.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_orphan.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9. |
| Mapping Extensions |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 11. |
| Orphaned Keys |
| </td></tr></table></div></body></html> |
