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

## 7.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 `kodo.jdbc.meta.MappingDefaults` interface. Kodo 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
Kodo 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, or use explicit foreign key mappings as described in Section 7.7.9.2, “Foreign Keys” for JPA, and Section 15.12, “Foreign Keys” of the JDO Overview .

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

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

- `jdo`: This is an alias for the `kodo.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. Defaults to false, meaning full mappings are required at runtime and when using mapping tool actions like `buildSchema` and `validate`.

    When this property is false and you use mapping tool actions like `refresh` or `add` to create new mappings, Kodo ensures that the table and column names it generates do not conflict among mappings. If you have set this property to true, however, Kodo does not attempt to avoid conflicts, because doing so would make mapping non-deterministic.

    The `jpa` plugin above sets this property to true to meet the JPA specification.

  - `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 Kodo's plugin format (see Section 2.5, “Plugin Configuration”) to pass arguments to the strategy instance. See the `kodo.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 Kodo's plugin format (see Section 2.5, “Plugin Configuration”) to pass arguments to the strategy instance. Common strategies are `vertical` and `flat`, the default. See the `kodo.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 Kodo's plugin format (see Section 2.5, “Plugin Configuration”) to pass arguments to the strategy instance. Common strategies are `none`, `state-comparison`, `timestamp`, and `version-number`, the default. See the `kodo.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 Kodo's plugin format (see Section 2.5, “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 `kodo.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 2.5, “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 7.10.3, “Custom Field Mapping” for information on custum 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 Kodo not to create database foreign keys on relation columns. This is the default.

  - `JoinForeignKeyDeleteAction`: The defualt delete action of foreign keys that join 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. If you use custom lock groups, this name may be combined with lock group names. See Section 5.8, “Lock Groups” for more information on lock groups.

  - `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 Kodo 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. Defaults to true.

    The `jpa` plugin above sets this property to false in accordance with the JPA specification.

  - `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, Kodo 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.18. Configuring Mapping Defaults

JPA XML format:

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

JDO properties format:

    kodo.jdbc.MappingDefaults: ForeignKeyDeleteAction=restrict, \
        FieldStrategies='org.mag.data.InfoStruct=org.mag.mapping.InfoStructHandler'

Prev | Up | Next
7.3. Meet-in-the-Middle Mapping | Home | 7.5. Mapping Factory