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'