Package org.hibernate.cfg

Interface MappingSettings

public interface MappingSettings

Field Summary

Fields

Modifier and Type	Field	Description
static String	ARTIFACT_PROCESSING_ORDER	Deprecated, for removal: This API element is subject to removal in a future version. hbm.xml mappings are no longer supported, making this attribute irrelevant
static String	COLUMN_ORDERING_STRATEGY	Used to specify the ColumnOrderingStrategy class to use.
static String	CREATE_EMPTY_COMPOSITES_ENABLED	Deprecated. It makes no sense at all to enable this at the global level for a persistence unit.
static String	DEFAULT_CATALOG	A default database catalog name to use for unqualified database object (table, sequence, ...) names
static String	DEFAULT_LIST_SEMANTICS	Specifies the CollectionClassification to use for a plural attribute typed as List with no explicit list index details (OrderColumn, ListIndexBase, etc.).
static String	DEFAULT_SCHEMA	A default database schema (owner) name to use for unqualified database object (table, sequence, ...) names
static String	FORCE_DISCRIMINATOR_IN_SELECTS_BY_DEFAULT
static String	GLOBALLY_QUOTED_IDENTIFIERS	When enabled, all database identifiers are quoted.
static String	GLOBALLY_QUOTED_IDENTIFIERS_SKIP_COLUMN_DEFINITIONS	Controls whether column-definitions (Column.columnDefinition(), JoinColumn.columnDefinition(), etc.) should be auto-quoted as part of global quoting.
static String	ID_DB_STRUCTURE_NAMING_STRATEGY	An implicit naming strategy for database structures (tables, sequences) related to identifier generators.
static String	IGNORE_EXPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS	Controls whether Hibernate should ignore explicit discriminator metadata with joined inheritance.
static String	IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS	Controls whether Hibernate should infer a discriminator for entity hierarchies defined with joined inheritance.
static String	IMPLICIT_NAMING_STRATEGY	Used to specify the ImplicitNamingStrategy class to use.
static String	JPA_METAMODEL_POPULATION	Setting that indicates whether to build the JPA types, either: enabled - Do the build disabled - Do not do the build ignoreUnsupported - Do the build, but ignore any non-JPA features that would otherwise result in a failure.
static String	JSON_FORMAT_MAPPER	Specifies a FormatMapper used for JSON serialization and deserialization, either: an instance of FormatMapper, a Class representing a class that implements FormatMapper, the name of a class that implements FormatMapper, or one of the shorthand constants jackson or jsonb.
static String	KEYWORD_AUTO_QUOTING_ENABLED	Specifies whether to automatically quote any names that are deemed keywords on the underlying database.
static String	PHYSICAL_NAMING_STRATEGY	Specifies the PhysicalNamingStrategy to use.
static String	PREFERRED_BOOLEAN_JDBC_TYPE	Specifies the preferred JDBC type for storing boolean values.
static String	PREFERRED_DURATION_JDBC_TYPE	The preferred JDBC type to use for storing Duration values.
static String	PREFERRED_INSTANT_JDBC_TYPE	Specifies the preferred JDBC type for storing Instant values.
static String	PREFERRED_POOLED_OPTIMIZER	When a generator specifies an increment-size and an optimizer was not explicitly specified, which of the "pooled" optimizers should be preferred? Can specify an optimizer short name or the name of a class which implements Optimizer.
static String	PREFERRED_UUID_JDBC_TYPE	The preferred JDBC type to use for storing UUID values.
static String	SEQUENCE_INCREMENT_SIZE_MISMATCH_STRATEGY	This setting defines the SequenceMismatchStrategy used when Hibernate detects a mismatch between a sequence configuration in an entity mapping and its database sequence object counterpart.
static String	STATIC_METAMODEL_POPULATION	Setting that controls whether we seek out JPA "static metamodel" classes and populate them, either: enabled - Do the population disabled - Do not do the population skipUnsupported - Do the population, but ignore any non-JPA features that would otherwise result in the population failing.
static String	TABLE_GENERATOR_STORE_LAST_USED	Determines if the identifier value stored in the database table backing a table generator is the last value returned by the identifier generator, or the next value to be returned.
static String	TIMEZONE_DEFAULT_STORAGE	Specifies the default strategy for storage of the timezone information for the zoned datetime types OffsetDateTime and ZonedDateTime.
static String	TRANSFORM_HBM_XML	Enables processing hbm.xml mappings by transforming them to mapping.xml and using that processor.
static String	TRANSFORM_HBM_XML_FEATURE_HANDLING	How features in a hbm.xml file which are not supported for transformation should be handled.
static @Remove String	USE_ENTITY_WHERE_CLAUSE_FOR_COLLECTIONS	Deprecated, for removal: This API element is subject to removal in a future version. Originally added as a backwards compatibility flag
static String	USE_NATIONALIZED_CHARACTER_DATA	By default, Hibernate maps character data represented by Strings and Clobs to the JDBC types Types.VARCHAR and Types.CLOB.
static String	VALIDATE_XML	Whether XML should be validated against their schema as Hibernate reads them.
static String	WRAPPER_ARRAY_HANDLING	Configurable control over how to handle Byte[] and Character[] types encountered in the application domain model.
static String	XML_FORMAT_MAPPER	Specifies a FormatMapper used for XML serialization and deserialization, either: an instance of FormatMapper, a Class representing a class that implements FormatMapper, the name of a class that implements FormatMapper, or one of the shorthand constants jackson or jaxb.
static String	XML_MAPPING_ENABLED	Whether XML mappings should be processed.

Field Detail

DEFAULT_CATALOG

static final String DEFAULT_CATALOG

A default database catalog name to use for unqualified database object (table, sequence, ...) names

See Also:

MetadataBuilder.applyImplicitCatalogName(java.lang.String), Constant Field Values

DEFAULT_SCHEMA

static final String DEFAULT_SCHEMA

A default database schema (owner) name to use for unqualified database object (table, sequence, ...) names

See Also:

MetadataBuilder.applyImplicitSchemaName(java.lang.String), Constant Field Values

JPA_METAMODEL_POPULATION

static final String JPA_METAMODEL_POPULATION

Setting that indicates whether to build the JPA types, either:

• enabled - Do the build
• disabled - Do not do the build
• ignoreUnsupported - Do the build, but ignore any non-JPA features that would otherwise result in a failure.

See Also:

Constant Field Values

STATIC_METAMODEL_POPULATION

static final String STATIC_METAMODEL_POPULATION

Setting that controls whether we seek out JPA "static metamodel" classes and populate them, either:

• enabled - Do the population
• disabled - Do not do the population
• skipUnsupported - Do the population, but ignore any non-JPA features that would otherwise result in the population failing.

See Also:

Constant Field Values

GLOBALLY_QUOTED_IDENTIFIERS

static final String GLOBALLY_QUOTED_IDENTIFIERS

When enabled, all database identifiers are quoted.

Corollary to the JPA <delimited-identifiers/> element within the orm.xml <persistence-unit-defaults/> element, but offered as a global flag.

See Also:

Constant Field Values

Default Value:

false

GLOBALLY_QUOTED_IDENTIFIERS_SKIP_COLUMN_DEFINITIONS

static final String GLOBALLY_QUOTED_IDENTIFIERS_SKIP_COLUMN_DEFINITIONS

Controls whether column-definitions (Column.columnDefinition(), JoinColumn.columnDefinition(), etc.) should be auto-quoted as part of global quoting.

When global quoting is enabled, JPA states that column-definitions are subject to quoting. However, this can lead to problems with definitions such as @Column(..., columnDefinition="INTEGER DEFAULT 20").

See Also:

Constant Field Values

Default Value:

false to avoid the potential problems quoting non-trivial column-definitions.

KEYWORD_AUTO_QUOTING_ENABLED

static final String KEYWORD_AUTO_QUOTING_ENABLED

Specifies whether to automatically quote any names that are deemed keywords on the underlying database.

Since:

5.0

See Also:

Constant Field Values

Default Value:

false - auto-quoting of SQL keywords is disabled by default.

PREFERRED_POOLED_OPTIMIZER

static final String PREFERRED_POOLED_OPTIMIZER

When a generator specifies an increment-size and an optimizer was not explicitly specified, which of the "pooled" optimizers should be preferred? Can specify an optimizer short name or the name of a class which implements Optimizer.

See Also:

Constant Field Values

Default Value:

StandardOptimizerDescriptor.POOLED

TABLE_GENERATOR_STORE_LAST_USED

static final String TABLE_GENERATOR_STORE_LAST_USED

Determines if the identifier value stored in the database table backing a table generator is the last value returned by the identifier generator, or the next value to be returned.

Since:

5.3

See Also:

Constant Field Values

Default Value:

The value stored in the database table is the last generated value

SEQUENCE_INCREMENT_SIZE_MISMATCH_STRATEGY

static final String SEQUENCE_INCREMENT_SIZE_MISMATCH_STRATEGY

This setting defines the SequenceMismatchStrategy used when Hibernate detects a mismatch between a sequence configuration in an entity mapping and its database sequence object counterpart.

Possible values are SequenceMismatchStrategy.EXCEPTION, SequenceMismatchStrategy.LOG, SequenceMismatchStrategy.FIX and SequenceMismatchStrategy.NONE.

Since:

5.4

See Also:

Constant Field Values

Default Value:

SequenceMismatchStrategy.EXCEPTION, meaning that an exception is thrown when such a conflict is detected.

PREFERRED_BOOLEAN_JDBC_TYPE

@Incubating
static final String PREFERRED_BOOLEAN_JDBC_TYPE

Specifies the preferred JDBC type for storing boolean values.

Can be overridden locally using JdbcType, JdbcTypeCode, and friends.

Can also specify the name of the SqlTypes constant field, for example, hibernate.type.preferred_boolean_jdbc_type=BIT.

Since:

6.0

See Also:

Constant Field Values

Default Value:

dialect-specific type code

PREFERRED_UUID_JDBC_TYPE

@Incubating
static final String PREFERRED_UUID_JDBC_TYPE

The preferred JDBC type to use for storing UUID values.

Can be overridden locally using JdbcType, JdbcTypeCode, and friends.

Can also specify the name of the SqlTypes constant field, for example, hibernate.type.preferred_uuid_jdbc_type=CHAR.

Since:

6.0

See Also:

Constant Field Values

Default Value:

SqlTypes.UUID.

PREFERRED_DURATION_JDBC_TYPE

@Incubating
static final String PREFERRED_DURATION_JDBC_TYPE

The preferred JDBC type to use for storing Duration values.

Can be overridden locally using JdbcType, JdbcTypeCode, and friends.

Can also specify the name of the SqlTypes constant field, for example, hibernate.type.preferred_duration_jdbc_type=INTERVAL_SECOND.

Since:

6.0

See Also:

Constant Field Values

Default Value:

SqlTypes.NUMERIC

PREFERRED_INSTANT_JDBC_TYPE

@Incubating
static final String PREFERRED_INSTANT_JDBC_TYPE

Specifies the preferred JDBC type for storing Instant values.

Can be overridden locally using JdbcType, JdbcTypeCode, and friends.

Can also specify the name of the SqlTypes constant field, for example, hibernate.type.preferred_instant_jdbc_type=TIMESTAMP.

Since:

6.0

See Also:

Constant Field Values

Default Value:

SqlTypes.TIMESTAMP_UTC.

JSON_FORMAT_MAPPER

@Incubating
static final String JSON_FORMAT_MAPPER

Specifies a FormatMapper used for JSON serialization and deserialization, either:

• an instance of FormatMapper,
• a Class representing a class that implements FormatMapper,
• the name of a class that implements FormatMapper, or
• one of the shorthand constants jackson or jsonb.

By default, the first of the possible providers that is available at runtime is used, according to the listing order.

Since:

6.0

See Also:

SessionFactoryBuilder.applyJsonFormatMapper(FormatMapper), Constant Field Values

XML_FORMAT_MAPPER

@Incubating
static final String XML_FORMAT_MAPPER

Specifies a FormatMapper used for XML serialization and deserialization, either:

• an instance of FormatMapper,
• a Class representing a class that implements FormatMapper,
• the name of a class that implements FormatMapper, or
• one of the shorthand constants jackson or jaxb.

By default, the first of the possible providers that is available at runtime is used, according to the listing order.

Since:

6.0.1

See Also:

SessionFactoryBuilder.applyXmlFormatMapper(FormatMapper), Constant Field Values

WRAPPER_ARRAY_HANDLING

@Incubating
static final String WRAPPER_ARRAY_HANDLING

Configurable control over how to handle Byte[] and Character[] types encountered in the application domain model. Allowable semantics are defined by WrapperArrayHandling. Accepted values include:

1. WrapperArrayHandling instance
2. case-insensitive name of a WrapperArrayHandling instance (e.g. allow)

Since:

6.2

See Also:

Constant Field Values

TIMEZONE_DEFAULT_STORAGE

static final String TIMEZONE_DEFAULT_STORAGE

Specifies the default strategy for storage of the timezone information for the zoned datetime types OffsetDateTime and ZonedDateTime. The possible options for this setting are enumerated by TimeZoneStorageType.

Since:

6.0

See Also:

TimeZoneStorageType, TimeZoneStorage, Constant Field Values

API Note:

For backward compatibility with older versions of Hibernate, set this property to NORMALIZE.

Default Value:

DEFAULT, which guarantees that the instant represented by a zoned datetime type is preserved by a round trip to the database. It does not guarantee that the time zone or offset is preserved.

IMPLICIT_NAMING_STRATEGY

static final String IMPLICIT_NAMING_STRATEGY

Used to specify the ImplicitNamingStrategy class to use. The following shortcut names are defined for this setting:

• "default" and "jpa" are an abbreviations for ImplicitNamingStrategyJpaCompliantImpl
• "legacy-jpa" is an abbreviation for ImplicitNamingStrategyLegacyJpaImpl
• "legacy-hbm" is an abbreviation for ImplicitNamingStrategyLegacyHbmImpl
• "component-path" is an abbreviation for ImplicitNamingStrategyComponentPathImpl

Since:

5.0

See Also:

MetadataBuilder.applyImplicitNamingStrategy(org.hibernate.boot.model.naming.ImplicitNamingStrategy), Constant Field Values

Default Value:

"default"

PHYSICAL_NAMING_STRATEGY

static final String PHYSICAL_NAMING_STRATEGY

Specifies the PhysicalNamingStrategy to use.

Since:

5.0

See Also:

MetadataBuilder.applyPhysicalNamingStrategy(org.hibernate.boot.model.naming.PhysicalNamingStrategy), Constant Field Values

Default Value:

PhysicalNamingStrategyStandardImpl, in which case physical names are taken to be identical to logical names.

ID_DB_STRUCTURE_NAMING_STRATEGY

@Incubating
static final String ID_DB_STRUCTURE_NAMING_STRATEGY

An implicit naming strategy for database structures (tables, sequences) related to identifier generators.

Resolution uses the StrategySelector service and accepts any of the forms discussed on StrategySelector.resolveDefaultableStrategy(Class, Object, java.util.concurrent.Callable).

The recognized short names being:

• "single"
• "legacy"
• "standard"

Since:

6

See Also:

ImplicitDatabaseObjectNamingStrategy, Constant Field Values

Default Value:

StandardNamingStrategy

COLUMN_ORDERING_STRATEGY

static final String COLUMN_ORDERING_STRATEGY

Used to specify the ColumnOrderingStrategy class to use. The following shortcut names are defined for this setting:

• "default" is an abbreviations for ColumnOrderingStrategyStandard
• "legacy" is an abbreviation for ColumnOrderingStrategyLegacy

Since:

6.2

See Also:

MetadataBuilder.applyColumnOrderingStrategy(org.hibernate.boot.model.relational.ColumnOrderingStrategy), Constant Field Values

Default Value:

"default"

ARTIFACT_PROCESSING_ORDER

@Deprecated(since="6",
            forRemoval=true)
static final String ARTIFACT_PROCESSING_ORDER

Deprecated, for removal: This API element is subject to removal in a future version.

hbm.xml mappings are no longer supported, making this attribute irrelevant

Specifies the order in which metadata sources should be processed, is a delimited list of values defined by MetadataSourceType.

See Also:

MetadataSourceType, MetadataBuilder.applySourceProcessOrdering(MetadataSourceType...), Constant Field Values

Default Value:

"hbm,class", which indicates that hbm.xml files should be processed first, followed by annotations and orm.xml files.

XML_MAPPING_ENABLED

static final String XML_MAPPING_ENABLED

Whether XML mappings should be processed.

Since:

5.4.1

See Also:

Constant Field Values

API Note:

This is a performance optimization appropriate when mapping details are defined exclusively using annotations.

Default Value:

true - XML mappings are processed

DEFAULT_LIST_SEMANTICS

static final String DEFAULT_LIST_SEMANTICS

Specifies the CollectionClassification to use for a plural attribute typed as List with no explicit list index details (OrderColumn, ListIndexBase, etc.).

Accepts any of:

• an instance of CollectionClassification
• the (case insensitive) name of a CollectionClassification (list e.g.)
• a Class representing either List or Collection

Since:

6.0

See Also:

Bag, Constant Field Values

Default Value:

CollectionClassification.BAG

CREATE_EMPTY_COMPOSITES_ENABLED

@Incubating
@Deprecated(since="6")
static final String CREATE_EMPTY_COMPOSITES_ENABLED

Deprecated.

It makes no sense at all to enable this at the global level for a persistence unit. If anything, it could be a setting specific to a given embeddable class. But, four years after the introduction of this feature, it's still marked experimental and has multiple known unresolved bugs. It's therefore time for those who advocated for this feature to accept defeat.

Enable instantiation of composite/embedded objects when all attribute values are null. The default (and historical) behavior is that a null reference will be used to represent the composite value when all of its attributes are null.

Since:

5.1

See Also:

Constant Field Values

API Note:

This is an experimental feature that has known issues. It should not be used in production until it is stabilized. See Hibernate JIRA issue HHH-11936 for details.

USE_ENTITY_WHERE_CLAUSE_FOR_COLLECTIONS

@Remove
@Deprecated(forRemoval=true,
            since="6.2")
static final @Remove String USE_ENTITY_WHERE_CLAUSE_FOR_COLLECTIONS

Deprecated, for removal: This API element is subject to removal in a future version.

Originally added as a backwards compatibility flag

The @Where annotation specifies a restriction on the table rows which are visible as entity class instances or collection elements.

This setting controls whether the restriction applied to an entity should be applied to association fetches (for one-to-one, many-to-one, one-to-many, and many-to-many associations) which target the entity.

See Also:

Constant Field Values

API Note:

The setting is very misnamed - it applies across all entity associations, not only to collections.

Implementation Specification:

Enabled (true) by default, meaning the restriction is applied. When this setting is explicitly disabled (false), the restriction is not applied.

VALIDATE_XML

static final String VALIDATE_XML

Whether XML should be validated against their schema as Hibernate reads them.

Since:

6.1

See Also:

Constant Field Values

Default Value:

true

TRANSFORM_HBM_XML

static final String TRANSFORM_HBM_XML

Enables processing hbm.xml mappings by transforming them to mapping.xml and using that processor.

Since:

6.1

See Also:

Constant Field Values

Default Value:

false (opt-in).

TRANSFORM_HBM_XML_FEATURE_HANDLING

static final String TRANSFORM_HBM_XML_FEATURE_HANDLING

How features in a hbm.xml file which are not supported for transformation should be handled. Valid values are defined by UnsupportedFeatureHandling

Since:

6.1

See Also:

Constant Field Values

Default Value:

UnsupportedFeatureHandling.ERROR

FORCE_DISCRIMINATOR_IN_SELECTS_BY_DEFAULT

static final String FORCE_DISCRIMINATOR_IN_SELECTS_BY_DEFAULT

See Also:

MetadataBuilder.enableImplicitForcingOfDiscriminatorsInSelect(boolean), Constant Field Values

Default Value:

false

IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS

static final String IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS

Controls whether Hibernate should infer a discriminator for entity hierarchies defined with joined inheritance.

Hibernate does not need a discriminator with joined inheritance. Therefore, its legacy behavior is to not infer a discriminator. However, some JPA providers do require discriminators with joined inheritance, so in the interest of portability this option has been added to Hibernate. When enabled (true), Hibernate will treat the absence of discriminator metadata as an indication to use the JPA defined defaults for discriminators.

See Also:

MetadataBuilder.enableImplicitDiscriminatorsForJoinedSubclassSupport(boolean), IGNORE_EXPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS, Constant Field Values

Implementation Note:

See Hibernate Jira issue HHH-6911 for additional background info.

Default Value:

false

IGNORE_EXPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS

static final String IGNORE_EXPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS

Controls whether Hibernate should ignore explicit discriminator metadata with joined inheritance.

Hibernate does not need a discriminator with joined inheritance. Historically it simply ignored discriminator metadata. When enabled (true), any discriminator metadata (DiscriminatorColumn, e.g.) is ignored allowing for backwards compatibility.

See Also:

MetadataBuilder.enableExplicitDiscriminatorsForJoinedSubclassSupport(boolean), IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS, Constant Field Values

Implementation Note:

See Hibernate Jira issue HHH-6911 for additional background info.

Default Value:

false

USE_NATIONALIZED_CHARACTER_DATA

static final String USE_NATIONALIZED_CHARACTER_DATA

By default, Hibernate maps character data represented by Strings and Clobs to the JDBC types Types.VARCHAR and Types.CLOB. This setting, when enabled, turns on the use of explicit nationalized character support for mappings involving character data, specifying that the JDBC types Types.NVARCHAR and Types.NCLOB should be used instead.

This setting is relevant for use with databases with explicit nationalization support, and it is not needed for databases whose native varchar and clob types support Unicode data. (If you're not sure how your database handles Unicode, check out the implementation of Dialect.getNationalizationSupport() for its SQL dialect.)

Enabling this setting has two effects:

1. when interacting with JDBC, Hibernate uses operations like PreparedStatement.setNString(int, String) PreparedStatement.setNClob(int, java.sql.NClob) to pass character data, and
2. when generating DDL, the schema export tool uses nchar, nvarchar, or nclob as the generated column type when no column type is explicitly specified using Column.columnDefinition().

See Also:

MetadataBuilder.enableGlobalNationalizedCharacterDataSupport(boolean), Dialect.getNationalizationSupport(), Nationalized, Constant Field Values

API Note:

This is a global setting applying to all mappings associated with a given SessionFactory. The Nationalized annotation may be used to selectively enable nationalized character support for specific columns.

Default Value:

false (disabled)