9. Mapping Extensions
Prev | Chapter 7. Mapping | Next

## 9. Mapping Extensions

Mapping extensions allow you to access OpenJPA-specific functionality from your mappings. Note that all extensions below are specific to mappings. If you store your mappings separately from your persistence metadata, these extensions must be specified along with the mapping information, not the persistence metadata information.

### 9.1. Class Extensions

OpenJPA recognizes the following class extensions.

#### 9.1.1. Subclass Fetch Mode

This extension specifies how to eagerly fetch subclass state. It overrides the global `openjpa.jdbc.SubclassFetchMode` property. Set the OpenJPA `org.apache.openjpa.persistence.jdbc.SubclassFetchMode` annotation to a value from the `org.apache.openjpa.persistence.jdbc.FetchMode` enum: `JOIN`, `PARALLEL`, or `NONE`. See Section 8, “ Eager Fetching ” for a discussion of eager fetching.

#### 9.1.2. Strategy

The `org.apache.openjpa.persistence.jdbc.Strategy` class annotation allows you to specify a custom mapping strategy for your class. See Section 10, “ Custom Mappings ” for information on custom mappings.

#### 9.1.3. Discriminator Strategy

The `org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy` class annotation allows you to specify a custom discriminator strategy. See Section 10, “ Custom Mappings ” for information on custom mappings.

#### 9.1.4. Version Strategy

The `org.apache.openjpa.persistence.jdbc.VersionStrategy` class annotation allows you to specify a custom version strategy. See Section 10, “ Custom Mappings ” for information on custom mappings.

### 9.2. Field Extensions

OpenJPA recognizes the following field extensions.

#### 9.2.1. Eager Fetch Mode

This extension specifies how to eagerly fetch related objects. It overrides the global `openjpa.jdbc.EagerFetchMode` property. Set the OpenJPA `org.apache.openjpa.persistence.jdbc.EagerFetchMode` annotation to a value from the `org.apache.openjpa.persistence.jdbc.FetchMode` enum: `JOIN`, `PARALLEL`, or `NONE`. See Section 8, “ Eager Fetching ” for a discussion of eager fetching.

#### 9.2.2. Nonpolymorphic

All fields in Java are polymorphic. If you declare a field of type `T` , you can assign any subclass of `T` to the field as well. This is very convenient, but can make relation traversal very inefficient under some inheritance strategies. It can even make querying across the field impossible. Often, you know that certain fields do not need to be entirely polymorphic. By telling OpenJPA about such fields, you can improve the efficiency of your relations.

### Note

OpenJPA also includes the `type` metadata extension for narrowing the declared type of a field. See Section 4.2.6, “ Type ”.

OpenJPA defines the following extensions for nonpolymorphic values:

- `org.apache.openjpa.persistence.jdbc.Nonpolymorphic`

- `org.apache.openjpa.persistence.jdbc.ElementNonpolymorphic`

The value of these extensions is a constant from the `org.apache.openjpa.persistence.jdbc.NonpolymorphicType` enumeration. The default value, `EXACT`, indicates that the relation will always be of the exact declared type. A value of `JOINABLE`, on the other hand, means that the relation might be to any joinable subclass of the declared type. This value only excludes table-per-class subclasses.

#### 9.2.3. Class Criteria

This family of boolean extensions determines whether OpenJPA will use the expected class of related objects as criteria in the SQL it issues to load a relation field. Typically, this is not needed. The foreign key values uniquely identify the record for the related object. Under some rare mappings, however, you may need to consider both foreign key values and the expected class of the related object - for example, if you have an inverse relation that shares the foreign key with another inverse relation to an object of a different subclass. In these cases, set the proper class criteria extension to `true` to force OpenJPA to append class criteria to its select SQL.

OpenJPA defines the following class criteria annotations for field relations and array or collection element relations, respectively:

- `org.apache.openjpa.persistence.jdbc.ClassCriteria`

- `org.apache.openjpa.persistence.jdbc.ElementClassCriteria`

#### 9.2.4. Strategy

OpenJPA's `org.apache.openjpa.persistence.jdbc.Strategy` extension allows you to specify a custom mapping strategy or value handler for a field. See Section 10, “ Custom Mappings ” for information on custom mappings.

Prev | Up | Next
8. Mapping Limitations | Home | 10. Custom Mappings