Package org.hibernate.cfg

Interface MappingSettings

All Known Subinterfaces:

AvailableSettings

All Known Implementing Classes:

Environment

public interface MappingSettings

Field Summary

Fields

Modifier and Type	Field	Description
static final String	COLUMN_ORDERING_STRATEGY	Used to specify the ColumnOrderingStrategy class to use.
static final String	DEFAULT_CATALOG	A default database catalog name to use for unqualified database object (table, sequence, ...) names
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.).
static final String	DEFAULT_SCHEMA	A default database schema (owner) name to use for unqualified database object (table, sequence, ...) names
static final String	FORCE_DISCRIMINATOR_IN_SELECTS_BY_DEFAULT	Specifies that Hibernate should always restrict by discriminator values in SQL select statements, even when querying the root entity of an entity inheritance hierarchy.
static final String	GLOBALLY_QUOTED_IDENTIFIERS	When enabled, all database identifiers are quoted.
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.
static final String	ID_DB_STRUCTURE_NAMING_STRATEGY	An implicit naming strategy for database structures (tables, sequences) related to identifier generators.
static final String	IGNORE_EXPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS	Controls whether Hibernate should ignore explicit discriminator metadata with joined inheritance.
static final String	IMPLICIT_DISCRIMINATOR_COLUMNS_FOR_JOINED_SUBCLASS	Controls whether Hibernate should infer a discriminator for entity hierarchies defined with joined inheritance.
static final String	IMPLICIT_NAMING_STRATEGY	Used to specify the ImplicitNamingStrategy class to use.
static final String	JAVA_TIME_USE_DIRECT_JDBC	Indicates whether to use Java Time references at the JDBC boundary for binding and extracting temporal values to/from the database using the support added in JDBC 4.2 via PreparedStatement.setObject(int, Object, int) and ResultSet.getObject(int, Class).
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.
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.
static final String	KEYWORD_AUTO_QUOTING_ENABLED	Specifies whether to automatically quote any names that are deemed keywords on the underlying database.
static final String	PHYSICAL_NAMING_STRATEGY	Specifies the PhysicalNamingStrategy to use.
static final String	PREFER_NATIVE_ENUM_TYPES	Indicates that named SQL enum types should be used by default instead of varchar on databases which support named enum types.
static final String	PREFERRED_ARRAY_JDBC_TYPE	Specifies the preferred JDBC type for storing plural i.e.
static final String	PREFERRED_BOOLEAN_JDBC_TYPE	Specifies the preferred JDBC type for storing boolean values.
static final String	PREFERRED_DURATION_JDBC_TYPE	The preferred JDBC type to use for storing Duration values.
static final String	PREFERRED_INSTANT_JDBC_TYPE	Specifies the preferred JDBC type for storing Instant values.
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.
static final String	PREFERRED_UUID_JDBC_TYPE	The preferred JDBC type to use for storing UUID values.
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.
static final String	STATIC_METAMODEL_POPULATION	Setting that controls whether we seek out JPA static metamodel classes and populate them, either: enabled — do populate the static metamodel, disabled — do not populate the static metamodel, or skipUnsupported — do populate the static metamodel, but ignore any non-JPA features that would otherwise result in the process failing.
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.
static final String	TIMEZONE_DEFAULT_STORAGE	Specifies the default strategy for storage of the timezone information for the zoned datetime types OffsetDateTime and ZonedDateTime.
static final String	TRANSFORM_HBM_XML	Enables processing hbm.xml mappings by transforming them to mapping.xml and using that processor.
static final String	TRANSFORM_HBM_XML_FEATURE_HANDLING	How features in a hbm.xml file which are not supported for transformation should be handled.
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.
static final String	VALIDATE_XML	Whether XML should be validated against their schema as Hibernate reads them.
static final String	WRAPPER_ARRAY_HANDLING	Configurable control over how to handle Byte[] and Character[] types encountered in the application domain model.
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.
static final String	XML_FORMAT_MAPPER_LEGACY_FORMAT	Specifies whether to use the legacy provider specific and non-portable XML format for collections and byte arrays for XML serialization/deserialization.
static final String	XML_MAPPING_ENABLED	Whether XML mappings should be processed.

Field Details

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

Default Value:

ignoreUnsupported

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 populate the static metamodel,
• disabled — do not populate the static metamodel, or
• skipUnsupported — do populate the static metamodel, but ignore any non-JPA features that would otherwise result in the process failing.

See Also:

• Constant Field Values

Default Value:

skipUnsupported

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 or hibernate.type.preferred_instant_jdbc_type=INSTANT.

Since:

6.0

See Also:

• Constant Field Values

Default Value:

SqlTypes.TIMESTAMP_UTC.

JAVA_TIME_USE_DIRECT_JDBC

@Incubating
static final String JAVA_TIME_USE_DIRECT_JDBC

Indicates whether to use Java Time references at the JDBC boundary for binding and extracting temporal values to/from the database using the support added in JDBC 4.2 via PreparedStatement.setObject(int, Object, int) and ResultSet.getObject(int, Class).

Used to set the value across the entire system as opposed to scattered, individual JdbcTypeCode and JdbcType naming specific JavaTimeJdbcType implementations.

Since:

6.5

See Also:

• Constant Field Values

Implementation Note:

JDBC 4.2 does not define support for Instant, so Instant is not included in this. Some drivers do implement support for this even though not explicitly part of the JDBC specification. To use direct binding and extracting of Instant references, use hibernate.type.preferred_instant_jdbc_type=INSTANT. See PREFERRED_INSTANT_JDBC_TYPE, SqlTypes.INSTANT and InstantJdbcType.

Default Value:

false

PREFER_NATIVE_ENUM_TYPES

@Incubating
static final String PREFER_NATIVE_ENUM_TYPES

Indicates that named SQL enum types should be used by default instead of varchar on databases which support named enum types.

A named enum type is declared in DDL using create type ... as enum or create type ... as domain.

This configuration property is used to specify a global preference, as an alternative to the use of @JdbcTypeCode(SqlTypes.NAMED_ENUM) at the field or property level.

Since:

6.5

See Also:

• SqlTypes.NAMED_ENUM
• PostgreSQLEnumJdbcType
• OracleEnumJdbcType
• Constant Field Values

Default Value:

false

PREFERRED_ARRAY_JDBC_TYPE

@Incubating
static final String PREFERRED_ARRAY_JDBC_TYPE

Specifies the preferred JDBC type for storing plural i.e. array/collection 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_array_jdbc_type=ARRAY or hibernate.type.preferred_array_jdbc_type=TABLE.

Since:

6.6

See Also:

• SqlTypes.ARRAY
• SqlTypes.TABLE
• Constant Field Values

Default Value:

Dialect.getPreferredSqlTypeCodeForArray().

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

XML_FORMAT_MAPPER_LEGACY_FORMAT

@Incubating
static final String XML_FORMAT_MAPPER_LEGACY_FORMAT

Specifies whether to use the legacy provider specific and non-portable XML format for collections and byte arrays for XML serialization/deserialization.

false by default. This property only exists for backwards compatibility.

Since:

7.0

See Also:

• 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"

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

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

Specifies that Hibernate should always restrict by discriminator values in SQL select statements, even when querying the root entity of an entity inheritance hierarchy.

By default, Hibernate only restricts by discriminator values when querying a subtype, or when the root entity is explicitly annotated DiscriminatorOptions(force=true).

See Also:

• MetadataBuilder.enableImplicitForcingOfDiscriminatorsInSelect(boolean)
• DiscriminatorOptions.force()
• 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)