Interface MappingSettings
- All Known Subinterfaces:
AvailableSettings
- All Known Implementing Classes:
Environment
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Deprecated, for removal: This API element is subject to removal in a future version.static final String
Used to specify theColumnOrderingStrategy
class to use.static final String
Deprecated.It makes no sense at all to enable this at the global level for a persistence unit.static final String
A default database catalog name to use for unqualified database object (table, sequence, ...) namesstatic final String
Specifies theCollectionClassification
to use for a plural attribute typed asList
with no explicit list index details (OrderColumn
,ListIndexBase
, etc.).static final String
A default database schema (owner) name to use for unqualified database object (table, sequence, ...) namesstatic final String
static final String
When enabled, all database identifiers are quoted.static final String
Controls whether column-definitions (Column.columnDefinition()
,JoinColumn.columnDefinition()
, etc.) should be auto-quoted as part of global quoting.static final String
An implicit naming strategy for database structures (tables, sequences) related to identifier generators.static final String
Controls whether Hibernate should ignore explicit discriminator metadata with joined inheritance.static final String
Controls whether Hibernate should infer a discriminator for entity hierarchies defined with joined inheritance.static final String
Used to specify theImplicitNamingStrategy
class to use.static final String
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
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
Specifies aFormatMapper
used for JSON serialization and deserialization, either: an instance ofFormatMapper
, aClass
representing a class that implementsFormatMapper
, the name of a class that implementsFormatMapper
, or one of the shorthand constantsjackson
orjsonb
.static final String
Specifies whether to automatically quote any names that are deemed keywords on the underlying database.static final String
Specifies thePhysicalNamingStrategy
to use.static final String
Indicates whether to prefer using SQL enums and the respective special JDBC types for binding/extracting of values.static final String
Specifies the preferred JDBC type for storing plural i.e.static final String
Specifies the preferred JDBC type for storing boolean values.static final String
The preferred JDBC type to use for storingDuration
values.static final String
Specifies the preferred JDBC type for storingInstant
values.static final String
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 implementsOptimizer
.static final String
The preferred JDBC type to use for storingUUID
values.static final String
This setting defines theSequenceMismatchStrategy
used when Hibernate detects a mismatch between a sequence configuration in an entity mapping and its database sequence object counterpart.static final String
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 final String
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
Specifies the default strategy for storage of the timezone information for the zoned datetime typesOffsetDateTime
andZonedDateTime
.static final String
Enables processinghbm.xml
mappings by transforming them tomapping.xml
and using that processor.static final String
How features in ahbm.xml
file which are not supported for transformation should be handled.Deprecated, for removal: This API element is subject to removal in a future version.Originally added as a backwards compatibility flagstatic final String
By default, Hibernate maps character data represented byString
s andClob
s to the JDBC typesTypes.VARCHAR
andTypes.CLOB
.static final String
Whether XML should be validated against their schema as Hibernate reads them.static final String
Configurable control over how to handleByte[]
andCharacter[]
types encountered in the application domain model.static final String
Specifies aFormatMapper
used for XML serialization and deserialization, either: an instance ofFormatMapper
, aClass
representing a class that implementsFormatMapper
, the name of a class that implementsFormatMapper
, or one of the shorthand constantsjackson
orjaxb
.static final String
Whether XML mappings should be processed.
-
Field Details
-
DEFAULT_CATALOG
A default database catalog name to use for unqualified database object (table, sequence, ...) names -
DEFAULT_SCHEMA
A default database schema (owner) name to use for unqualified database object (table, sequence, ...) names -
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:
-
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:
-
GLOBALLY_QUOTED_IDENTIFIERS
When enabled, all database identifiers are quoted.Corollary to the JPA
<delimited-identifiers/>
element within theorm.xml
<persistence-unit-defaults/>
element, but offered as a global flag.- See Also:
- Default Value:
false
-
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:
- Default Value:
false
to avoid the potential problems quoting non-trivial column-definitions.
-
KEYWORD_AUTO_QUOTING_ENABLED
Specifies whether to automatically quote any names that are deemed keywords on the underlying database.- Since:
- 5.0
- See Also:
- Default Value:
false
- auto-quoting of SQL keywords is disabled by default.
-
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 implementsOptimizer
.- See Also:
- Default Value:
StandardOptimizerDescriptor.POOLED
-
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:
- Default Value:
- The value stored in the database table is the last generated value
-
SEQUENCE_INCREMENT_SIZE_MISMATCH_STRATEGY
This setting defines theSequenceMismatchStrategy
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
andSequenceMismatchStrategy.NONE
.- Since:
- 5.4
- See Also:
- Default Value:
SequenceMismatchStrategy.EXCEPTION
, meaning that an exception is thrown when such a conflict is detected.
-
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:
- Default Value:
- dialect-specific type code
-
PREFERRED_UUID_JDBC_TYPE
The preferred JDBC type to use for storingUUID
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:
- Default Value:
SqlTypes.UUID
.
-
PREFERRED_DURATION_JDBC_TYPE
The preferred JDBC type to use for storingDuration
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:
- Default Value:
SqlTypes.NUMERIC
-
PREFERRED_INSTANT_JDBC_TYPE
Specifies the preferred JDBC type for storingInstant
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
orhibernate.type.preferred_instant_jdbc_type=INSTANT
.- Since:
- 6.0
- See Also:
- Default Value:
SqlTypes.TIMESTAMP_UTC
.
-
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:
- 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
Indicates whether to prefer using SQL enums and the respective special JDBC types for binding/extracting of values. Used to set the value across the entire system as opposed to scattered, individual JdbcTypeCode and JdbcType naming specific JdbcType implementations.- Since:
- 6.5
- See Also:
- Default Value:
- false
-
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
orhibernate.type.preferred_array_jdbc_type=TABLE
.- Since:
- 6.6
- See Also:
- Default Value:
Dialect.getPreferredSqlTypeCodeForArray()
.
-
JSON_FORMAT_MAPPER
Specifies aFormatMapper
used for JSON serialization and deserialization, either:- an instance of
FormatMapper
, - a
Class
representing a class that implementsFormatMapper
, - the name of a class that implements
FormatMapper
, or - one of the shorthand constants
jackson
orjsonb
.
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:
- an instance of
-
XML_FORMAT_MAPPER
Specifies aFormatMapper
used for XML serialization and deserialization, either:- an instance of
FormatMapper
, - a
Class
representing a class that implementsFormatMapper
, - the name of a class that implements
FormatMapper
, or - one of the shorthand constants
jackson
orjaxb
.
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:
- an instance of
-
WRAPPER_ARRAY_HANDLING
Configurable control over how to handleByte[]
andCharacter[]
types encountered in the application domain model. Allowable semantics are defined byWrapperArrayHandling
. Accepted values include:WrapperArrayHandling
instance- case-insensitive name of a
WrapperArrayHandling
instance (e.g.allow
)
- Since:
- 6.2
- See Also:
-
TIMEZONE_DEFAULT_STORAGE
Specifies the default strategy for storage of the timezone information for the zoned datetime typesOffsetDateTime
andZonedDateTime
. The possible options for this setting are enumerated byTimeZoneStorageType
.- Since:
- 6.0
- See Also:
- 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
Used to specify theImplicitNamingStrategy
class to use. The following shortcut names are defined for this setting:"default"
and"jpa"
are an abbreviations forImplicitNamingStrategyJpaCompliantImpl
"legacy-jpa"
is an abbreviation forImplicitNamingStrategyLegacyJpaImpl
"legacy-hbm"
is an abbreviation forImplicitNamingStrategyLegacyHbmImpl
"component-path"
is an abbreviation forImplicitNamingStrategyComponentPathImpl
- Since:
- 5.0
- See Also:
- Default Value:
"default"
-
PHYSICAL_NAMING_STRATEGY
Specifies thePhysicalNamingStrategy
to use.- Since:
- 5.0
- See Also:
- Default Value:
PhysicalNamingStrategyStandardImpl
, in which case physical names are taken to be identical to logical names.
-
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 onStrategySelector.resolveDefaultableStrategy(Class, Object, java.util.concurrent.Callable)
.The recognized short names being:
- Since:
- 6
- See Also:
- Default Value:
StandardNamingStrategy
-
COLUMN_ORDERING_STRATEGY
Used to specify theColumnOrderingStrategy
class to use. The following shortcut names are defined for this setting:"default"
is an abbreviations forColumnOrderingStrategyStandard
"legacy"
is an abbreviation forColumnOrderingStrategyLegacy
- Since:
- 6.2
- See Also:
- Default Value:
"default"
-
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 irrelevantSpecifies the order in which metadata sources should be processed, is a delimited list of values defined byMetadataSourceType
.- See Also:
- Default Value:
"hbm,class"
, which indicates thathbm.xml
files should be processed first, followed by annotations andorm.xml
files.
-
XML_MAPPING_ENABLED
Whether XML mappings should be processed.- Since:
- 5.4.1
- See Also:
- 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
Specifies theCollectionClassification
to use for a plural attribute typed asList
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 eitherList
orCollection
- Since:
- 6.0
- See Also:
- Default Value:
CollectionClassification.BAG
- an instance of
-
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 arenull
. The default (and historical) behavior is that anull
reference will be used to represent the composite value when all of its attributes arenull
.- Since:
- 5.1
- See Also:
- 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_COLLECTIONSDeprecated, for removal: This API element is subject to removal in a future version.Originally added as a backwards compatibility flagThe@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:
- 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
Whether XML should be validated against their schema as Hibernate reads them.- Since:
- 6.1
- See Also:
- Default Value:
true
-
TRANSFORM_HBM_XML
Enables processinghbm.xml
mappings by transforming them tomapping.xml
and using that processor.- Since:
- 6.1
- See Also:
- Default Value:
false
(opt-in).
-
TRANSFORM_HBM_XML_FEATURE_HANDLING
How features in ahbm.xml
file which are not supported for transformation should be handled. Valid values are defined byUnsupportedFeatureHandling
- Since:
- 6.1
- See Also:
- Default Value:
UnsupportedFeatureHandling.ERROR
-
FORCE_DISCRIMINATOR_IN_SELECTS_BY_DEFAULT
- See Also:
- Default Value:
false
-
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:
- Implementation Note:
- See Hibernate Jira issue HHH-6911 for additional background info.
- Default Value:
false
-
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:
- Implementation Note:
- See Hibernate Jira issue HHH-6911 for additional background info.
- Default Value:
false
-
USE_NATIONALIZED_CHARACTER_DATA
By default, Hibernate maps character data represented byString
s andClob
s to the JDBC typesTypes.VARCHAR
andTypes.CLOB
. This setting, when enabled, turns on the use of explicit nationalized character support for mappings involving character data, specifying that the JDBC typesTypes.NVARCHAR
andTypes.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
andclob
types support Unicode data. (If you're not sure how your database handles Unicode, check out the implementation ofDialect.getNationalizationSupport()
for its SQL dialect.)Enabling this setting has two effects:
- when interacting with JDBC, Hibernate uses operations like
PreparedStatement.setNString(int, String)
PreparedStatement.setNClob(int, java.sql.NClob)
to pass character data, and - when generating DDL, the schema export tool uses
nchar
,nvarchar
, ornclob
as the generated column type when no column type is explicitly specified usingColumn.columnDefinition()
.
- See Also:
- API Note:
- This is a global setting applying to all mappings associated with a given
SessionFactory
. TheNationalized
annotation may be used to selectively enable nationalized character support for specific columns. - Default Value:
false
(disabled)
- when interacting with JDBC, Hibernate uses operations like
-
hbm.xml
mappings are no longer supported, making this attribute irrelevant