7.9. Mapping Extensions

7.9.1. Class Extensions
7.9.1.1. Subclass Fetch Mode
7.9.1.2. Strategy
7.9.1.3. Discriminator Strategy
7.9.1.4. Version Strategy
7.9.2. Field Extensions
7.9.2.1. Eager Fetch Mode
7.9.2.2. Nonpolymorphic
7.9.2.3. Class Criteria
7.9.2.4. Strategy
7.9.3. Column Extensions
7.9.3.1. insertable
7.9.3.2. updatable
7.9.3.3. lock-group

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.FetchMode 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.FetchMode 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]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:

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:

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:

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

 

Skip navigation bar   Back to Top