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

## 7.9. Mapping Extensions

Mapping extensions allow you to access Kodo-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.

It is only valid to place these extensions on JDO persistence metadata if you store your mappings in your `.jdo` files, or if you want these extensions to act as mapping hints (see Section 7.1.3, “ JDO Forward Mapping Hints ”). All extension keys use a `vendor-name` of `kodo`.

### 7.9.1. Class Extensions

Kodo recognizes the following class extensions.

#### 7.9.1.1. Subclass Fetch Mode

This extension specifies how to eagerly fetch subclass state. It overrides the global `kodo.jdbc.SubclassFetchMode` property. Set the JPA `org.apache.openjpa.persistence.jdbc.SubclassFetchMode` annotation to a value from the `org.apache.openjpa.persistence.jdbc.EagerFetchType` enum: `JOIN`, `PARALLEL`, or `NONE`. Set the JDO `jdbc-subclass-fetch-mode` XML extension key to `join`, `parallel`, or `none`. See Section 5.7, “Eager Fetching” for a discussion of eager fetching.

#### 7.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 7.10, “Custom Mappings” for information on custom mappings. Note that this extension applies only to JPA mapping; when using JDO mappings you specify custom class strategies using the standard XML `inheritance` element's `strategy` attribute.

#### 7.9.1.3. Discriminator Strategy

The `org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy` class annotation allows you to specify a custom discriminator strategy. See Section 7.10, “Custom Mappings” for information on custom mappings. Note that this extension applies only to JPA mapping; when using JDO mappings you specify custom discriminator strategies using the standard XML `discriminator` element's `strategy` attribute.

#### 7.9.1.4. Version Strategy

The `org.apache.openjpa.persistence.jdbc.VersionStrategy` class annotation allows you to specify a custom version strategy. See Section 7.10, “Custom Mappings” for information on custom mappings. Note that this extension applies only to JPA mapping; when using JDO mappings you specify custom version strategies using the standard XML `version` element's `strategy` attribute.

### 7.9.2. Field Extensions

Kodo recognizes the following field extensions.

#### 7.9.2.1. Eager Fetch Mode

This extension specifies how to eagerly fetch related objects. It overrides the global `kodo.jdbc.EagerFetchMode` property. Set the JPA `org.apache.openjpa.persistence.jdbc.EagerFetchMode` annotation to a value from the `org.apache.openjpa.persistence.jdbc.EagerFetchType` enum: `JOIN`, `PARALLEL`, or `NONE`. Set the JDO `jdbc-eager-fetch-mode` XML extension key to `join`, `parallel`, or `none`. See Section 5.7, “Eager Fetching” for a discussion of eager fetching.

#### 7.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 Kodo about such fields, you can improve the efficiency of your relations.

| Note
Kodo also includes the `type` metadata extension for narrowing the declared type of a field See Section 6.4.2.8, “Type”.

Kodo JPA defines the following extensions for nonpolymorphic values:

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

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

- `kodo.persistence.jdbc.KeyNonpolymorphic`

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.

Kodo JDO defines the following nonpolymorphic mapping extension keys:

- `jdbc-nonpolymorphic`

- `jdbc-element-nonpolymorphic`

- `jdbc-key-nonpolymorphic`

- `jdbc-value-nonpolymorphic`

These keys apply to field values, collection or array elements, map keys, and map values, respectively. Set the extension value to `exact` to indicate that the relation is always to the exact declared type. Set it to `joinable` if the relation can be to any joinable subclass of the declared type. A value of `joinable` only excludes table-per-class subclasses.

#### 7.9.2.3. Class Criteria

This family of boolean extensions determines whether Kodo 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 critera extension to `true` to force Kodo to append class criteria to its select SQL.

Kodo JPA defines the following class criteria annotations for field relations, array, collection, and map element relations, and map key relations, respectively:

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

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

- `kodo.persistence.jdbc.KeyClassCriteria`

Kodo JDO defines the following class criteria mapping extension keys for field relations, collection and array element relations, map key relations, and map value relations, respectively:

- `jdbc-class-criteria`

- `jdbc-element-class-criteria`

- `jdbc-key-class-criteria`

- `jdbc-value-class-criteria`

#### 7.9.2.4. Strategy

Kodo's family of strategy extensions allow you to specify a custom mapping strategy or value handler for a field. See Section 7.10, “Custom Mappings” for information on custom mappings.

Kodo includes the following JPA strategy annotations:

- `org.apache.openjpa.persistence.jdbc.Strategy` : Field strategy or value handler plugin string.

- `kodo.persistence.jdbc.ElementStrategy` : Array, collection, or map element value handler plugin string.

- `kodo.persistence.jdbc.KeyStrategy` : Map key value handler plugin string.

Kodo recognizes the following JDO strategy extension keys:

- `jdbc-strategy`: Field strategy or value handler plugin string.

- `jdbc-element-strategy`: Collection or array element value handler plugin string.

- `jdbc-key-strategy`: Map key value handler plugin string.

- `jdbc-value-strategy`: Map value handler plugin string.

### 7.9.3. Column Extensions

Kodo recognizes the following extensions within JDO `column` elements:

#### 7.9.3.1. insertable

Boolean extension dictating whether the current mapping can insert into this column.

#### 7.9.3.2. updatable

Boolean extension dictating whether the current mapping can update this column value.

#### 7.9.3.3. lock-group

This extension is only valid on version columns. When you use custom lock groups, it allows you to declare which version column is for which lock group. See Section 5.8, “Lock Groups”.

Prev | Up | Next
7.8. Mapping Limitations | Home | 7.10. Custom Mappings