14.  Custom Mappings

14.1. Custom Class Mapping
14.2. Custom Discriminator and Version Strategies
14.3. Custom Field Mapping
14.3.1. Value Handlers
14.3.2. Field Strategies
14.3.3. Configuration

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.

14.1.  Custom Class Mapping

To create a custom class mapping, write an implementation of the org.apache.openjpa.jdbc.meta.ClassStrategy interface. You will probably want to extend one of the existing abstract or concrete strategies in the org.apache.openjpa.jdbc.meta.strats package.

The org.apache.openjpa.persistence.jdbc.Strategy 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 Section 4, “ Plugin Configuration ”.

14.2.  Custom Discriminator and Version Strategies

To define a custom discriminator or version strategy, implement the org.apache.openjpa.jdbc.meta.DiscriminatorStrategy or org.apache.openjpa.jdbc.meta.VersionStrategy interface, respectively. You might extend one of the existing abstract or concrete strategies in the org.apache.openjpa.jdbc.meta.strats package.

OpenJPA includes the org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy and org.apache.openjpa.persistence.jdbc.VersionStrategy 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.

As with custom class mappings, you can configure your strategy class' bean properties using OpenJPA's plugin syntax, detailed in Section 4, “ Plugin Configuration ”.

14.3.  Custom Field Mapping

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.

14.3.1.  Value Handlers

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 org.apache.openjpa.jdbc.meta.ValueHandler interface; see its Javadoc for details. Also, examine the built-in handlers in the src/openjpa/jdbc/meta/strats directory of your OpenJPA source distribution. Use these functional implementations as examples when you create your own value handlers.

14.3.2.  Field Strategies

OpenJPA interacts with persistent fields through the org.apache.openjpa.jdbc.meta.FieldStrategy 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 org.apache.openjpa.jdbc.meta.strats 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.

14.3.3.  Configuration

OpenJPA gives you two ways to configure your custom field mappings. The FieldStrategies property of the built-in MappingDefaults 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. Section 4, “ Mapping Defaults ” described mapping defaults in detail.

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 org.apache.openjpa.persistence.jdbc.Strategy annotation. You can configure the named strategy or handler's bean properties in these extensions using OpenJPA's plugin format (see Section 4, “ Plugin Configuration ”).