4. Mapping Defaults
Prev | Chapter 7. Mapping | Next

## 4. Mapping Defaults

The previous sections showed how to use the mapping tool to generate default mappings. But how does the mapping tool know what mappings to generate? The answer lies in the `org.apache.openjpa.jdbc.meta.MappingDefaults` interface. OpenJPA uses an instance of this interface to decide how to name tables and columns, where to put foreign keys, and generally how to create a schema that matches your object model.

### Important

OpenJPA relies on foreign key constraint information at runtime to order SQL appropriately. Be sure to set your mapping defaults to reflect your existing database constraints, set the schema factory to reflect on the database for constraint information (see Section 12.2, “ Schema Factory ”), or use explicit foreign key mappings as described in Section 7.9.2, “ Foreign Keys ”.

The `openjpa.jdbc.MappingDefaults` configuration property controls the `MappingDefaults` interface implementation in use. This is a plugin property (see Section 4, “ Plugin Configuration ”), so you can substitute your own implementation or configure the existing ones. OpenJPA includes the following standard implementations:

- `jpa`: Provides defaults in compliance with the JPA standard. This is an alias for the `org.apache.openjpa.persistence.jdbc.PersistenceMappingDefaults` class. This class extends the `MappingDefaultsImpl` class described below, so it has all the same properties (though with different default values), as well as:

  - `PrependFieldNameToJoinTableInverseJoinColumns`: Whether to prepend the owning field name to the names of inverse join columns in join tables. Defaults to true per the JPA specification. Set to false for compatibility with older OpenJPA versions which did not prepend the field name.

- `default`: This is an alias for the `org.apache.openjpa.jdbc.meta.MappingDefaultsImpl` class. This default implementation is highly configurable. It has the following properties:

  - `DefaultMissingInfo`: Whether to default missing column and table names rather than throw an exception. If set to false, full explicit mappings are required at runtime and when using mapping tool actions like `buildSchema` and `validate`.

  - `RemoveHungarianNotation`: Switches on/off removal of Hungarian notation when generating column names. Fields such as `mFoobar` and `strBarFoo` would become columns named `foobar` and `barfoo` respectively. OpenJPA will search for the first instance of a uppercase character in the field name and then truncate the column name to remove anything before it.

  - `BaseClassStrategy`: The default mapping strategy for base classes. You can specify a built-in strategy alias or the full class name of a custom class strategy. You can also use OpenJPA's plugin format (see Section 4, “ Plugin Configuration ”) to pass arguments to the strategy instance. See the `org.apache.openjpa.jdbc.meta.strats` package for available strategies.

  - `SubclassStrategy`: The default mapping strategy for subclasses. You can specify a builtin strategy alias or the full class name of a custom class strategy. You can also use OpenJPA's plugin format (see Section 4, “ Plugin Configuration ”) to pass arguments to the strategy instance. Common strategies are `vertical` and `flat`, the default. See the `org.apache.openjpa.jdbc.meta.strats` package for all available strategies.

  - `VersionStrategy`: The default version strategy for classes without a version field. You can specify a builtin strategy alias or the full class name of a custom version strategy. You can also use OpenJPA's plugin format (see Section 4, “ Plugin Configuration ”) to pass arguments to the strategy instance. Common strategies are `none`, `state-comparison`, `timestamp`, and `version-number`, the default. See the `org.apache.openjpa.jdbc.meta.strats` package for all available strategies.

  - `DiscriminatorStrategy`: The default discriminator strategy when no discriminator value is given. You can specify a builtin strategy alias or the full class name of a custom discriminator strategy. You can also use OpenJPA's plugin format (see Section 4, “ Plugin Configuration ”) to pass arguments to the strategy instance. Common strategies are `final` for a base class without subclasses, `none` to use joins to subclass tables rather than a discriminator column, and `class-name`, the default. See the `org.apache.openjpa.jdbc.meta.strats` package for all available strategies.

  - `FieldStrategies`: This property associates field types with custom strategies. The format of this property is similar to that of plugin strings (see Section 4, “ Plugin Configuration ” ), without the class name. It is a comma-separated list of key/value pairs, where each key is a possible field type, and each value is itself a plugin string describing the strategy for that type. We present an example below. See Section 10.3, “ Custom Field Mapping ” for information on custom field strategies.

  - `ForeignKeyDeleteAction`: The default delete action of foreign keys representing relations to other objects. Recognized values include `restrict`, `cascade`, `null` , `default`. These values correspond exactly to the standard database foreign key actions of the same names.

    The value `none` tells OpenJPA not to create database foreign keys on relation columns. This is the default.

  - `JoinForeignKeyDeleteAction`: The default delete action of foreign keys that join secondary, collection, map, or subclass tables to the primary table. Accepts the same values as the `ForeignKeyDeleteAction` property above.

  - `DeferConstraints`: Whether to use deferred database constraints if possible. Defaults to false.

  - `IndexLogicalForeignKeys`: Boolean property controlling whether to create indexes on logical foreign keys. Logical foreign keys are columns that represent a link between tables, but have been configured through the `ForeignKey` properties above not to use a physical database foreign key. Defaults to true.

  - `DataStoreIdColumnName`: The default name of datastore identity columns.

  - `DiscriminatorColumnName`: The default name of discriminator columns.

  - `IndexDiscriminator`: Whether to index the discriminator column. Defaults to true.

  - `VersionColumnName`: The default name of version columns.

  - `IndexVersion`: Whether to index the version column. Defaults to false.

  - `AddNullIndicator`: Whether to create a synthetic null indicator column for embedded mappings. The null indicator column allows OpenJPA to distinguish between a null embedded object and one with default values for all persistent fields.

  - `NullIndicatorColumnName`: The default name of synthetic null indicator columns for embedded objects.

  - `OrderLists`: Whether to create a database ordering column for maintaining the order of persistent lists and arrays.

  - `OrderColumnName`: The default name of collection and array ordering columns.

  - `StoreEnumOrdinal`: Set to true to store enum fields as numeric ordinal values in the database. The default is to store the enum value name as a string, which is more robust if the Java enum declaration might be rearranged.

  - `StoreUnmappedObjectIdString`: Set to true to store the stringified identity of related objects when the declared related type is unmapped. By default, OpenJPA stores the related object's primary key value(s). However, this breaks down if different subclasses of the related type use incompatible primary key structures. In that case, stringifying the identity value is the better choice.

The example below turns on foreign key generation during schema creation and associates the `org.mag.data.InfoStruct` field type with the custom `org.mag.mapping.InfoStructHandler` value handler.

Example 7.12. Configuring Mapping Defaults

    <property name="openjpa.jdbc.MappingDefaults"
        value="ForeignKeyDeleteAction=restrict,
        FieldStrategies='org.mag.data.InfoStruct=org.mag.mapping.InfoStructHandler'"/>

Prev | Up | Next
3. Meet-in-the-Middle Mapping | Home | 5. Mapping Factory