10. Custom Mappings
Prev | Chapter 7. Mapping | Next

## 10. Custom Mappings

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.

### 10.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 ”.

### 10.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 ”.

### 10.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.

#### 10.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.

#### 10.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.

#### 10.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 ”).

Prev | Up | Next
9. Mapping Extensions | Home | 11. Orphaned Keys