Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

more work on javadoc of settings

This commit is contained in:
Gavin King 2022-01-22 19:27:11 +01:00
parent b3b8ef6073
commit 6ddb12412c
13 changed files with 355 additions and 254 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
hibernate-core/src/main/java/org/hibernate/Interceptor.java
View File

@ -14,22 +14,25 @@ import org.hibernate.metamodel.spi.EntityRepresentationStrategy;
import org.hibernate.type.Type; import org.hibernate.type.Type;
/** /**
* Allows user code to inspect and/or change property values. * Allows user code to inspect and/or change entity property values before they are
* * written to the database, or after the are read from the database.
* Inspection occurs before property values are written and after they are read * <p>
* from the database. * The {@code Session} may not be invoked from a callback (nor may a callback cause a
* * collection or proxy to be lazily initialized).
* There might be a single instance of {@code Interceptor} for a {@code SessionFactory}, or a new instance * <p>
* might be specified for each {@code Session}. Whichever approach is used, the interceptor must be * There might be a single instance of {@code Interceptor} for a {@link SessionFactory},
* serializable if the {@code Session} is to be serializable. This means that {@code SessionFactory}-scoped * or a new instance might be created for each {@link Session}. Use:
* <ul>
* <li>{@link org.hibernate.cfg.AvailableSettings#INTERCEPTOR} to specify an
* interceptor shared between sessions, or
* <li>{@link org.hibernate.cfg.AvailableSettings#SESSION_SCOPED_INTERCEPTOR} to
* specify that there is a dedicated instance of the interceptor for each
* session.
* </ul>
* Whichever approach is used, the interceptor must be serializable for the
* {@code Session} to be serializable. This means that {@code SessionFactory}-scoped
* interceptors should implement {@code readResolve()}. * interceptors should implement {@code readResolve()}.
* *
* The {@code Session} may not be invoked from a callback (nor may a callback cause a collection or proxy to
* be lazily initialized).
*
* Instead of implementing this interface directly, it is usually better to extend {@code EmptyInterceptor}
* and override only the callback methods of interest.
*
* @see SessionBuilder#interceptor(Interceptor) * @see SessionBuilder#interceptor(Interceptor)
* @see SharedSessionBuilder#interceptor() * @see SharedSessionBuilder#interceptor()
* @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor) * @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor)

2
hibernate-core/src/main/java/org/hibernate/SessionEventListener.java
View File

@ -11,6 +11,8 @@ import java.io.Serializable;
/** /**
* NOTE : Consider this an incubating API, likely to change as wider usage indicates changes that need to be made * NOTE : Consider this an incubating API, likely to change as wider usage indicates changes that need to be made
* *
* @see org.hibernate.cfg.AvailableSettings#AUTO_SESSION_EVENTS_LISTENER
*
* @author Steve Ebersole * @author Steve Ebersole
*/ */
public interface SessionEventListener extends Serializable { public interface SessionEventListener extends Serializable {

19
hibernate-core/src/main/java/org/hibernate/annotations/TimeZoneStorageType.java
View File

@ -10,7 +10,7 @@ import org.hibernate.Incubating;
import org.hibernate.dialect.Dialect; import org.hibernate.dialect.Dialect;
/** /**
* Describes the storage for the time zone information for time zone based types. * Describes the storage of timezone information for zoned datetime types.
* *
* @author Christian Beikov * @author Christian Beikov
* @author Steve Ebersole * @author Steve Ebersole
@ -19,19 +19,28 @@ import org.hibernate.dialect.Dialect;
@Incubating @Incubating
public enum TimeZoneStorageType { public enum TimeZoneStorageType {
/** /**
* Stores the time zone by using the "with time zone" type. Error if {@link Dialect#getTimeZoneSupport()} is not {@link org.hibernate.dialect.TimeZoneSupport#NATIVE}. * Stores the timezone by using the {@code with time zone}
* SQL column type.
*
* Error if {@link Dialect#getTimeZoneSupport()} is not
* {@link org.hibernate.dialect.TimeZoneSupport#NATIVE}.
*/ */
NATIVE, NATIVE,
/** /**
* Does not store the time zone, and instead normalizes timestamps to UTC. * Does not store the time zone, and instead normalizes
* timestamps to UTC.
*/ */
NORMALIZE, NORMALIZE,
/** /**
* Stores the time zone in a separate column; works in conjunction with {@link TimeZoneColumn}. * Stores the time zone in a separate column; works in
* conjunction with {@link TimeZoneColumn}.
*/ */
COLUMN, COLUMN,
/** /**
* Stores the time zone either with {@link #NATIVE} if {@link Dialect#getTimeZoneSupport()} is {@link org.hibernate.dialect.TimeZoneSupport#NATIVE}, otherwise uses the {@link #COLUMN} strategy. * Stores the time zone either with {@link #NATIVE} if
* {@link Dialect#getTimeZoneSupport()} is
* {@link org.hibernate.dialect.TimeZoneSupport#NATIVE},
* otherwise uses the {@link #COLUMN} strategy.
*/ */
AUTO AUTO

501
hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
View File

@ -9,6 +9,7 @@ package org.hibernate.cfg;
import java.util.function.Supplier; import java.util.function.Supplier;
import org.hibernate.jpa.LegacySpecHints; import org.hibernate.jpa.LegacySpecHints;
import org.hibernate.query.spi.QueryPlan;
/** /**
* Enumerates the configuration properties supported by Hibernate, including * Enumerates the configuration properties supported by Hibernate, including
@ -137,6 +138,7 @@ public interface AvailableSettings {
* <p/> * <p/>
* See JPA 2 section 8.2.1.9 * See JPA 2 section 8.2.1.9
*/ */
@SuppressWarnings("unused")
String JAKARTA_PERSIST_VALIDATION_GROUP = "jakarta.persistence.validation.group.pre-persist"; String JAKARTA_PERSIST_VALIDATION_GROUP = "jakarta.persistence.validation.group.pre-persist";
/** /**
@ -144,6 +146,7 @@ public interface AvailableSettings {
* <p/> * <p/>
* See JPA 2 section 8.2.1.9 * See JPA 2 section 8.2.1.9
*/ */
@SuppressWarnings("unused")
String JAKARTA_UPDATE_VALIDATION_GROUP = "jakarta.persistence.validation.group.pre-update"; String JAKARTA_UPDATE_VALIDATION_GROUP = "jakarta.persistence.validation.group.pre-update";
/** /**
@ -151,6 +154,7 @@ public interface AvailableSettings {
* <p/> * <p/>
* See JPA 2 section 8.2.1.9 * See JPA 2 section 8.2.1.9
*/ */
@SuppressWarnings("unused")
String JAKARTA_REMOVE_VALIDATION_GROUP = "jakarta.persistence.validation.group.pre-remove"; String JAKARTA_REMOVE_VALIDATION_GROUP = "jakarta.persistence.validation.group.pre-remove";
/** /**
@ -200,7 +204,7 @@ public interface AvailableSettings {
/** /**
* Specifies a {@link java.util.Collection collection} of the {@link ClassLoader} * Specifies a {@link java.util.Collection collection} of the {@link ClassLoader}
* instances Hibernate should use for classloading and resource lookups. * instances Hibernate should use for classloading and resource loading.
* *
* @since 5.0 * @since 5.0
*/ */
@ -322,7 +326,8 @@ public interface AvailableSettings {
String POOL_SIZE = " hibernate.connection.pool_size"; String POOL_SIZE = " hibernate.connection.pool_size";
/** /**
* Specifies a {@link javax.sql.DataSource}, either:<ul> * Specifies a {@link javax.sql.DataSource}, either:
* <ul>
* <li>an instance of {@link javax.sql.DataSource}, or * <li>an instance of {@link javax.sql.DataSource}, or
* <li>a JNDI name under which to obtain the {@link javax.sql.DataSource}. * <li>a JNDI name under which to obtain the {@link javax.sql.DataSource}.
* </ul> * </ul>
@ -403,6 +408,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_HBM2DDL_DB_NAME} instead * @deprecated Use {@link #JAKARTA_HBM2DDL_DB_NAME} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String DIALECT_DB_NAME = "javax.persistence.database-product-name"; String DIALECT_DB_NAME = "javax.persistence.database-product-name";
/** /**
@ -421,6 +427,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_HBM2DDL_DB_VERSION} instead * @deprecated Use {@link #JAKARTA_HBM2DDL_DB_VERSION} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String DIALECT_DB_VERSION = "javax.persistence.database-product-version"; String DIALECT_DB_VERSION = "javax.persistence.database-product-version";
/** /**
@ -436,6 +443,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_HBM2DDL_DB_MAJOR_VERSION} instead * @deprecated Use {@link #JAKARTA_HBM2DDL_DB_MAJOR_VERSION} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String DIALECT_DB_MAJOR_VERSION = "javax.persistence.database-major-version"; String DIALECT_DB_MAJOR_VERSION = "javax.persistence.database-major-version";
/** /**
@ -450,6 +458,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_HBM2DDL_DB_MINOR_VERSION} instead * @deprecated Use {@link #JAKARTA_HBM2DDL_DB_MINOR_VERSION} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String DIALECT_DB_MINOR_VERSION = "javax.persistence.database-minor-version"; String DIALECT_DB_MINOR_VERSION = "javax.persistence.database-minor-version";
/** /**
@ -1192,7 +1201,7 @@ public interface AvailableSettings {
/** /**
* Enable direct storage of entity references into the second level cache when * Enable direct storage of entity references into the second level cache when
* applicable (immutable data, etc). * applicable. This is appropriate only for immutable entities.
* <p> * <p>
* By default, entities are always stored in a "disassembled" form. * By default, entities are always stored in a "disassembled" form.
*/ */
@ -1249,9 +1258,12 @@ public interface AvailableSettings {
String PREFERRED_POOLED_OPTIMIZER = "hibernate.id.optimizer.pooled.preferred"; String PREFERRED_POOLED_OPTIMIZER = "hibernate.id.optimizer.pooled.preferred";
/** /**
* Should query plan caching be enabled at all? Default is {@code false} unless * When enabled, specifies that {@linkplain QueryPlan query plans} should be
* one of {@link #QUERY_PLAN_CACHE_MAX_SIZE} or * {@linkplain org.hibernate.query.spi.QueryPlanCache cached}.
* {@link #QUERY_PLAN_CACHE_PARAMETER_METADATA_MAX_SIZE} is specified. * <p>
* By default, the query plan cache is disabled, unless one of the configuration
* properties {@value #QUERY_PLAN_CACHE_MAX_SIZE} or
* {@value #QUERY_PLAN_CACHE_PARAMETER_METADATA_MAX_SIZE} is set.
*/ */
String QUERY_PLAN_CACHE_ENABLED = "hibernate.query.plan_cache_enabled"; String QUERY_PLAN_CACHE_ENABLED = "hibernate.query.plan_cache_enabled";
@ -1322,6 +1334,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_HBM2DDL_CONNECTION} instead * @deprecated Use {@link #JAKARTA_HBM2DDL_CONNECTION} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String HBM2DDL_CONNECTION = "javax.persistence.schema-generation-connection"; String HBM2DDL_CONNECTION = "javax.persistence.schema-generation-connection";
/** /**
@ -1329,11 +1342,12 @@ public interface AvailableSettings {
* on object/relational mapping metadata, DDL scripts, or a combination of the two. See * on object/relational mapping metadata, DDL scripts, or a combination of the two. See
* {@link org.hibernate.tool.schema.SourceType} for the list of legal values. * {@link org.hibernate.tool.schema.SourceType} for the list of legal values.
* <p> * <p>
* If no value is specified, a default is inferred as follows:<ul> * If no value is specified, a default is inferred as follows:
* <ul>
* <li>if source scripts are specified via {@value #HBM2DDL_CREATE_SCRIPT_SOURCE}, then * <li>if source scripts are specified via {@value #HBM2DDL_CREATE_SCRIPT_SOURCE}, then
* {@link org.hibernate.tool.schema.SourceType#SCRIPT "script"} is assumed, or * {@link org.hibernate.tool.schema.SourceType#SCRIPT "script"} is assumed, or
* <li>otherwise, {@link org.hibernate.tool.schema.SourceType#SCRIPT "metadata"} is * <li>otherwise, {@link org.hibernate.tool.schema.SourceType#SCRIPT "metadata"} is
* assumed. * assumed.
* </ul> * </ul>
* *
* @see org.hibernate.tool.schema.SourceType * @see org.hibernate.tool.schema.SourceType
@ -1341,15 +1355,16 @@ public interface AvailableSettings {
String HBM2DDL_CREATE_SOURCE = "javax.persistence.schema-generation.create-source"; String HBM2DDL_CREATE_SOURCE = "javax.persistence.schema-generation.create-source";
/** /**
* Specifies whether schema generation commands for schema dropping are to be determined based * Specifies whether schema generation commands for schema dropping are to be determined
* on object/relational mapping metadata, DDL scripts, or a combination of the two. See * based on object/relational mapping metadata, DDL scripts, or a combination of the two.
* {@link org.hibernate.tool.schema.SourceType} for the list of legal values. * See {@link org.hibernate.tool.schema.SourceType} for the list of legal values.
* <p> * <p>
* If no value is specified, a default is inferred as follows:<ul> * If no value is specified, a default is inferred as follows:
* <ul>
* <li>if source scripts are specified via {@value #HBM2DDL_DROP_SCRIPT_SOURCE}, then * <li>if source scripts are specified via {@value #HBM2DDL_DROP_SCRIPT_SOURCE}, then
* {@link org.hibernate.tool.schema.SourceType#SCRIPT "script"} is assumed, or * {@link org.hibernate.tool.schema.SourceType#SCRIPT "script"} is assumed, or
* <li>otherwise, {@link org.hibernate.tool.schema.SourceType#SCRIPT "metadata"} is * <li>otherwise, {@link org.hibernate.tool.schema.SourceType#SCRIPT "metadata"} is
* assumed. * assumed.
* </ul> * </ul>
* *
* @see org.hibernate.tool.schema.SourceType * @see org.hibernate.tool.schema.SourceType
@ -1428,6 +1443,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_HBM2DDL_LOAD_SCRIPT_SOURCE} instead * @deprecated Use {@link #JAKARTA_HBM2DDL_LOAD_SCRIPT_SOURCE} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String HBM2DDL_LOAD_SCRIPT_SOURCE = "javax.persistence.sql-load-script-source"; String HBM2DDL_LOAD_SCRIPT_SOURCE = "javax.persistence.sql-load-script-source";
/** /**
@ -1454,6 +1470,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_HBM2DDL_CREATE_SCHEMAS} instead * @deprecated Use {@link #JAKARTA_HBM2DDL_CREATE_SCHEMAS} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String HBM2DDL_CREATE_SCHEMAS = "javax.persistence.create-database-schemas"; String HBM2DDL_CREATE_SCHEMAS = "javax.persistence.create-database-schemas";
/** /**
@ -1566,13 +1583,14 @@ public interface AvailableSettings {
String JAKARTA_HBM2DDL_DB_MINOR_VERSION = "jakarta.persistence.database-minor-version"; String JAKARTA_HBM2DDL_DB_MINOR_VERSION = "jakarta.persistence.database-minor-version";
/** /**
* Specifies whether schema generation commands for schema creation are to be determined based * Specifies whether schema generation commands for schema creation are to be determined
* on object/relational mapping metadata, DDL scripts, or a combination of the two. See * based on object/relational mapping metadata, DDL scripts, or a combination of the two.
* {@link org.hibernate.tool.schema.SourceType} for the list of legal values. * See {@link org.hibernate.tool.schema.SourceType} for the list of legal values.
* <p> * <p>
* If no value is specified, a default is inferred as follows:<ul> * If no value is specified, a default is inferred as follows:
* <li>if source scripts are specified via {@value #HBM2DDL_CREATE_SCRIPT_SOURCE}, then * <ul>
* {@link org.hibernate.tool.schema.SourceType#SCRIPT "script"} is assumed, or * <li>if source scripts are specified via {@value #HBM2DDL_CREATE_SCRIPT_SOURCE},
* then {@link org.hibernate.tool.schema.SourceType#SCRIPT "script"} is assumed, or
* <li>otherwise, {@link org.hibernate.tool.schema.SourceType#SCRIPT "metadata"} is * <li>otherwise, {@link org.hibernate.tool.schema.SourceType#SCRIPT "metadata"} is
* assumed. * assumed.
* </ul> * </ul>
@ -1582,15 +1600,16 @@ public interface AvailableSettings {
String JAKARTA_HBM2DDL_CREATE_SOURCE = "jakarta.persistence.schema-generation.create-source"; String JAKARTA_HBM2DDL_CREATE_SOURCE = "jakarta.persistence.schema-generation.create-source";
/** /**
* Specifies whether schema generation commands for schema dropping are to be determined based * Specifies whether schema generation commands for schema dropping are to be determined
* on object/relational mapping metadata, DDL scripts, or a combination of the two. See * based on object/relational mapping metadata, DDL scripts, or a combination of the two.
* {@link org.hibernate.tool.schema.SourceType} for the list of legal values. * See {@link org.hibernate.tool.schema.SourceType} for the list of legal values.
* <p> * <p>
* If no value is specified, a default is inferred as follows:<ul> * If no value is specified, a default is inferred as follows:
* <ul>
* <li>if source scripts are specified via {@value #HBM2DDL_DROP_SCRIPT_SOURCE}, then * <li>if source scripts are specified via {@value #HBM2DDL_DROP_SCRIPT_SOURCE}, then
* {@linkplain org.hibernate.tool.schema.SourceType#SCRIPT "script"} is assumed, or * {@linkplain org.hibernate.tool.schema.SourceType#SCRIPT "script"} is assumed, or
* <li>otherwise, {@linkplain org.hibernate.tool.schema.SourceType#SCRIPT "metadata"} is * <li>otherwise, {@linkplain org.hibernate.tool.schema.SourceType#SCRIPT "metadata"}
* assumed. * is assumed.
* </ul> * </ul>
* *
* @see org.hibernate.tool.schema.SourceType * @see org.hibernate.tool.schema.SourceType
@ -1721,18 +1740,22 @@ public interface AvailableSettings {
String CUSTOM_ENTITY_DIRTINESS_STRATEGY = "hibernate.entity_dirtiness_strategy"; String CUSTOM_ENTITY_DIRTINESS_STRATEGY = "hibernate.entity_dirtiness_strategy";
/** /**
* Controls whether an entity's "where" clause, mapped using {@code @Where(clause="....")} * The {@link org.hibernate.annotations.Where} annotation specifies a restriction
* or {@code &lt;entity ... where="..."&gt;}, is taken into account when loading one-to-many * on the table rows which are visible as entity class instances or collection
* or many-to-many collections of that type of entity. * elements.
* <p/> * <p>
* This setting has no affect on collections of embeddable values containing an association * This setting controls whether the restriction is applied when loading a
* to that type of entity. * {@link jakarta.persistence.OneToMany one-to-many} or
* <p/> * or {@link jakarta.persistence.ManyToMany many-to-many} association whose target
* When {@code true}, the default, the entity's "where" clause will be taken into account * type defines the restriction.
* when loading one-to-many or many-to-many collections of that type of entity. * <p>
* <p/> * By default, the restriction is not applied. When this setting is enabled, the
* `false` indicates that the entity's "where" clause will be ignored when loading * restriction is applied.
* one-to-many or many-to-many collections of that type of entity. * <p>
* The setting has no effect on a collection of {@link jakarta.persistence.Embeddable
* embeddable} values containing a {@link jakarta.persistence.ManyToOne many-to-one}
* association to the entity.
*
*/ */
String USE_ENTITY_WHERE_CLAUSE_FOR_COLLECTIONS = "hibernate.use_entity_where_clause_for_collections"; String USE_ENTITY_WHERE_CLAUSE_FOR_COLLECTIONS = "hibernate.use_entity_where_clause_for_collections";
@ -1746,9 +1769,9 @@ public interface AvailableSettings {
String MULTI_TENANT_CONNECTION_PROVIDER = "hibernate.multi_tenant_connection_provider"; String MULTI_TENANT_CONNECTION_PROVIDER = "hibernate.multi_tenant_connection_provider";
/** /**
* Specifies a {@link org.hibernate.context.spi.CurrentTenantIdentifierResolver} to use. * Specifies a {@link org.hibernate.context.spi.CurrentTenantIdentifierResolver} to use,
* <p/> * either:
* Can be<ul> * <ul>
* <li>an instance of {@code CurrentTenantIdentifierResolver}, * <li>an instance of {@code CurrentTenantIdentifierResolver},
* <li>a {@link Class} representing an class that implements {@code CurrentTenantIdentifierResolver}, or * <li>a {@link Class} representing an class that implements {@code CurrentTenantIdentifierResolver}, or
* <li>the name of a class that implements {@code CurrentTenantIdentifierResolver}. * <li>the name of a class that implements {@code CurrentTenantIdentifierResolver}.
@ -1759,44 +1782,47 @@ public interface AvailableSettings {
String MULTI_TENANT_IDENTIFIER_RESOLVER = "hibernate.tenant_identifier_resolver"; String MULTI_TENANT_IDENTIFIER_RESOLVER = "hibernate.tenant_identifier_resolver";
/** /**
* Names a {@link org.hibernate.Interceptor} implementation associated with the * Specifies an {@link org.hibernate.Interceptor} implementation associated with
* {@link org.hibernate.SessionFactory} and propagated to each Session created from the SessionFactory. * the {@link org.hibernate.SessionFactory} and propagated to each {@code Session}
* This setting identifies an Interceptor which is effectively a singleton across all the Sessions * created from the {@code SessionFactory}. Either:
* opened from the SessionFactory to which it is applied; the same instance will be passed to each Session. * <ul>
* <p/>
* See {@link #SESSION_SCOPED_INTERCEPTOR} for an approach to create unique Interceptor instances for each Session
* <p/>
* Can reference<ul>
* <li>an instance of {@code Interceptor}, * <li>an instance of {@code Interceptor},
* <li>a {@link Class} representing an class that implements {@code Interceptor}, or * <li>a {@link Class} representing a class that implements {@code Interceptor}, or
* <li>the name of a class that implements {@code Interceptor}. * <li>the name of a class that implements {@code Interceptor}.
* </ul> * </ul>
* This setting identifies an {@code Interceptor} which is effectively a singleton
* across all the sessions opened from the {@code SessionFactory} to which it is
* applied; the same instance will be passed to each {@code Session}. If there
* should be a separate instance of {@code Interceptor} for each {@code Session},
* use {@link #SESSION_SCOPED_INTERCEPTOR} instead.
* *
* @since 5.0 * @since 5.0
*/ */
String INTERCEPTOR = "hibernate.session_factory.interceptor"; String INTERCEPTOR = "hibernate.session_factory.interceptor";
/** /**
* Specifies a {@link org.hibernate.Interceptor} implementation associated with the * Specifies an {@link org.hibernate.Interceptor} implementation associated with
* {@link org.hibernate.SessionFactory} and propagated to each Session created from the SessionFactory. * the {@link org.hibernate.SessionFactory} and propagated to each {@code Session}
* This setting identifies an Interceptor implementation that is to be applied to every Session opened * created from the {@code SessionFactory}. Either:
* from the SessionFactory, but unlike {@link #INTERCEPTOR} a unique instance of the Interceptor is * <ul>
* used for each Session. * <li>a {@link Class} representing a class that implements {@code Interceptor},
* <p/>
* Can reference<ul>
* <li>a {@link Class} representing an class that implements {@code Interceptor},
* <li>the name of a class that implements {@code Interceptor}, or * <li>the name of a class that implements {@code Interceptor}, or
* <li>a {@link Supplier} used to obtain the interceptor. * <li>an instance of {@link Supplier} used to obtain the interceptor.
* </ul> * </ul>
* Note that this setting cannot specify an {@code Interceptor} instance. * Note that this setting cannot specify an {@code Interceptor} instance.
* <p>
* This setting identifies an {@code Interceptor} implementation that is to be
* applied to every {@code Session} opened from the {@code SessionFactory}, but
* unlike {@link #INTERCEPTOR}, a separate instance created for each {@code Session}.
* *
* @since 5.2 * @since 5.2
*/ */
String SESSION_SCOPED_INTERCEPTOR = "hibernate.session_factory.session_scoped_interceptor"; String SESSION_SCOPED_INTERCEPTOR = "hibernate.session_factory.session_scoped_interceptor";
/** /**
* Specifies a {@link org.hibernate.resource.jdbc.spi.StatementInspector} implementation * Specifies a {@link org.hibernate.resource.jdbc.spi.StatementInspector}
* associated with the {@link org.hibernate.SessionFactory}, either: * implementation associated with the {@link org.hibernate.SessionFactory},
* either:
* <ul> * <ul>
* <li>an instance of {@code StatementInspector}, * <li>an instance of {@code StatementInspector},
* <li>a {@link Class} representing an class that implements {@code StatementInspector}, or * <li>a {@link Class} representing an class that implements {@code StatementInspector}, or
@ -1810,20 +1836,20 @@ public interface AvailableSettings {
String ENABLE_LAZY_LOAD_NO_TRANS = "hibernate.enable_lazy_load_no_trans"; String ENABLE_LAZY_LOAD_NO_TRANS = "hibernate.enable_lazy_load_no_trans";
/** /**
* Names the {@link org.hibernate.loader.BatchFetchStyle} to use. Can specify either the * Specifies the {@link org.hibernate.loader.BatchFetchStyle} to use,
* {@link org.hibernate.loader.BatchFetchStyle} name (insensitively), or a * either the name of a {code BatchFetchStyle} instance, or an instance
* {@link org.hibernate.loader.BatchFetchStyle} instance. * of {@code BatchFetchStyle}.
*
* {@code LEGACY} is the default value.
* *
* @deprecated (since 6.0) : An appropriate batch-fetch style is selected automatically * @deprecated (since 6.0) : An appropriate batch-fetch style is selected automatically
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String BATCH_FETCH_STYLE = "hibernate.batch_fetch_style"; String BATCH_FETCH_STYLE = "hibernate.batch_fetch_style";
/** /**
* Controls how the individual Loaders for an entity are created. * Controls how {@linkplain org.hibernate.loader.ast.spi.Loader entity loaders}
* * are created.
* <p>
* When {@code true}, the default, the loaders are only created on first * When {@code true}, the default, the loaders are only created on first
* access; this ensures that all access patterns which are not useful * access; this ensures that all access patterns which are not useful
* to the application are never instantiated, possibly saving a * to the application are never instantiated, possibly saving a
@ -1832,8 +1858,8 @@ public interface AvailableSettings {
* which will always be eagerly initialized; this is necessary to * which will always be eagerly initialized; this is necessary to
* detect mapping errors. * detect mapping errors.
* <p> * <p>
* {@code false} indicates that all loaders should be created up front; this * {@code false} indicates that all loaders should be created up front;
* will consume more memory but ensures all necessary memory is * this will consume more memory but ensures all necessary memory is
* allocated right away. * allocated right away.
* *
* @since 5.3 * @since 5.3
@ -1852,16 +1878,16 @@ public interface AvailableSettings {
String JTA_TRACK_BY_THREAD = "hibernate.jta.track_by_thread"; String JTA_TRACK_BY_THREAD = "hibernate.jta.track_by_thread";
/** /**
* If enabled, allows schema update and validation to support synonyms. Due * If enabled, allows schema update and validation to support synonyms. Due
* to the possibility that this would return duplicate tables (especially in * to the possibility that this would return duplicate tables (especially in
* Oracle), this is disabled by default. * Oracle), this is disabled by default.
*/ */
String ENABLE_SYNONYMS = "hibernate.synonyms"; String ENABLE_SYNONYMS = "hibernate.synonyms";
/** /**
* Identifies a comma-separate list of values to specify extra table types, * Specifies a comma-separated list of extra table types, in addition to the
* other than the default "TABLE" value, to recognize as defining a physical table * default types {@code "TABLE"} and {@code "VIEW"}, to recognize as physical
* by schema update, creation and validation. * tables when performing schema update, creation and validation.
* *
* @since 5.0 * @since 5.0
*/ */
@ -1873,58 +1899,72 @@ public interface AvailableSettings {
* finding existing constraints is extremely inconsistent. Worse, unique constraints * finding existing constraints is extremely inconsistent. Worse, unique constraints
* without explicit names are assigned names with randomly generated characters. * without explicit names are assigned names with randomly generated characters.
* <p> * <p>
* Therefore, select from these strategies:<ul> * Therefore, select from these strategies:
* <li>{@link org.hibernate.tool.schema.UniqueConstraintSchemaUpdateStrategy#DROP_RECREATE_QUIETLY}: * <ul>
* Attempt to drop, then (re-)create each unique constraint, * <li>{@link org.hibernate.tool.schema.UniqueConstraintSchemaUpdateStrategy#DROP_RECREATE_QUIETLY
* ignoring any exceptions thrown. * DROP_RECREATE_QUIETLY}:
* This is the default. * Attempt to drop, then (re-)create each unique constraint,
* <li>{@link org.hibernate.tool.schema.UniqueConstraintSchemaUpdateStrategy#RECREATE_QUIETLY}: * ignoring any exceptions thrown.
* attempt to (re-)create unique constraints, * This is the default.
* ignoring exceptions thrown if the constraint already existed. * <li>{@link org.hibernate.tool.schema.UniqueConstraintSchemaUpdateStrategy#RECREATE_QUIETLY
* <li>{@link org.hibernate.tool.schema.UniqueConstraintSchemaUpdateStrategy#SKIP}: * RECREATE_QUIETLY}:
* do not attempt to create unique constraints on a schema update. * attempt to (re-)create unique constraints,
* ignoring exceptions thrown if the constraint already existed.
* <li>{@link org.hibernate.tool.schema.UniqueConstraintSchemaUpdateStrategy#SKIP
* SKIP}:
* do not attempt to create unique constraints on a schema update.
* </ul> * </ul>
*/ */
String UNIQUE_CONSTRAINT_SCHEMA_UPDATE_STRATEGY = "hibernate.schema_update.unique_constraint_strategy"; String UNIQUE_CONSTRAINT_SCHEMA_UPDATE_STRATEGY = "hibernate.schema_update.unique_constraint_strategy";
/** /**
* Enable statistics collection * When enabled, specifies that {@linkplain org.hibernate.stat.Statistics statistics}
* should be collected.
*/ */
String GENERATE_STATISTICS = "hibernate.generate_statistics"; String GENERATE_STATISTICS = "hibernate.generate_statistics";
/** /**
* A setting to control whether to {@link org.hibernate.engine.internal.StatisticalLoggingSessionEventListener} * Controls whether {@linkplain org.hibernate.stat.SessionStatistics session metrics}
* is enabled on all sessions (unless explicitly disabled for a given session). The default value of this * should be {@linkplain org.hibernate.engine.internal.StatisticalLoggingSessionEventListener
* setting is determined by the value for {@link #GENERATE_STATISTICS}, meaning that if collection of * logged} for any session in which statistics are being collected.
* statistics is enabled logging of session metrics is enabled by default too. * <p>
* By default, logging of session metrics is disabled unless {@link #GENERATE_STATISTICS}
* is enabled.
*/ */
String LOG_SESSION_METRICS = "hibernate.session.events.log"; String LOG_SESSION_METRICS = "hibernate.session.events.log";
/** /**
* Setting that logs query which executed slower than specified milliseconds. Default is 0 (disabled). * Specifies a duration in milliseconds defining the minimum query execution time that
* characterizes a "slow" query. Any SQL query which takes longer than this amount of
* time to execute will be logged.
* <p>
* A value of {@code 0}, the default, disables logging of "slow" queries.
*/ */
String LOG_SLOW_QUERY = "hibernate.session.events.log.LOG_QUERIES_SLOWER_THAN_MS"; String LOG_SLOW_QUERY = "hibernate.session.events.log.LOG_QUERIES_SLOWER_THAN_MS";
/** /**
* Defines a default {@link org.hibernate.SessionEventListener} to be applied to newly-opened * Defines a default {@link org.hibernate.SessionEventListener} to be applied to
* {@link org.hibernate.Session}s. * newly-opened {@link org.hibernate.Session}s.
*/ */
String AUTO_SESSION_EVENTS_LISTENER = "hibernate.session.events.auto"; String AUTO_SESSION_EVENTS_LISTENER = "hibernate.session.events.auto";
/** /**
* [EXPERIMENTAL] Enable instantiation of composite/embedded objects when all of its attribute * [EXPERIMENTAL] Enable instantiation of composite/embedded objects when all
* values are {@code null}. The default (and historical) behavior is that a {@code null} * attribute values are {@code null}. The default (and historical) behavior is
* reference will be used to represent the composite when all of its attributes are {@code null}. * that a {@code null} reference will be used to represent the composite when
* all of its attributes are {@code null}.
* <p> * <p>
* This is an experimental feature that has known issues. It should not be used in production * This is an experimental feature that has known issues. It should not be used
* until it is stabilized. See Hibernate Jira issue HHH-11936 for details. * in production until it is stabilized. See Hibernate JIRA issue HHH-11936 for
* details.
* *
* @since 5.1 * @since 5.1
*/ */
String CREATE_EMPTY_COMPOSITES_ENABLED = "hibernate.create_empty_composites.enabled"; String CREATE_EMPTY_COMPOSITES_ENABLED = "hibernate.create_empty_composites.enabled";
/** /**
* When enabled, allows access to the {@link org.hibernate.Transaction} even when using a JTA. * When enabled, allows access to the {@link org.hibernate.Transaction} even when
* using a JTA for transaction management.
* <p> * <p>
* Values are {@code true}, which grants access, and {@code false}, which does not. * Values are {@code true}, which grants access, and {@code false}, which does not.
* <p> * <p>
@ -1935,11 +1975,11 @@ public interface AvailableSettings {
/** /**
* When enabled, allows update operations outside a transaction. * When enabled, allows update operations outside a transaction.
* <p> * <p>
* Since version 5.2 Hibernate conforms with the JPA specification and disallows flushing any * Since version 5.2 Hibernate conforms with the JPA specification and disallows
* update outside a transaction. * flushing any update outside a transaction.
* <p> * <p>
* Values are {@code true}, which allows flushing outside a transaction, and {@code false}, * Values are {@code true}, which allows flushing outside a transaction, and
* which does not. * {@code false}, which does not.
* <p> * <p>
* The default behavior is to disallow update operations outside a transaction. * The default behavior is to disallow update operations outside a transaction.
* *
@ -1952,54 +1992,54 @@ public interface AvailableSettings {
* and {@link org.hibernate.Session#refresh(Object)} on a detached entity instance. * and {@link org.hibernate.Session#refresh(Object)} on a detached entity instance.
* <p> * <p>
* Values are {@code true}, which allows refreshing a detached instance and {@code false}, * Values are {@code true}, which allows refreshing a detached instance and {@code false},
* which does not. When refreshing is disallowed, an {@link IllegalArgumentException} is * which does not. When refreshing is disallowed, an {@link IllegalArgumentException}
* thrown. * is thrown.
* <p> * <p>
* The default behavior is to allow refreshing a detached instance unless Hibernate is * The default behavior is to allow refreshing a detached instance unless Hibernate
* bootstrapped via JPA. * is bootstrapped via JPA.
* *
* @since 5.2 * @since 5.2
*/ */
String ALLOW_REFRESH_DETACHED_ENTITY = "hibernate.allow_refresh_detached_entity"; String ALLOW_REFRESH_DETACHED_ENTITY = "hibernate.allow_refresh_detached_entity";
/** /**
* Setting that specifies how Hibernate will respond when multiple representations of the * Setting that specifies how Hibernate will respond when multiple representations of
* same persistent entity ("entity copy") are detected while merging. * the same persistent entity ("entity copy") are detected while merging.
* <p> * <p>
* The possible values are: * The possible values are:
* <ul> * <ul>
* <li>disallow (the default): throws {@link IllegalStateException} if an entity copy * <li>disallow (the default): throws {@link IllegalStateException} if an entity
* is detected * copy is detected
* <li>allow: performs the merge operation on each entity copy that is detected * <li>allow: performs the merge operation on each entity copy that is detected
* <li>log: (provided for testing only) performs the merge operation on each entity copy * <li>log: (provided for testing only) performs the merge operation on each entity
* that is detected and logs information about the entity copies. This setting requires * copy that is detected and logs information about the entity copies. This
* DEBUG logging be enabled for * setting requires DEBUG logging be enabled for
* {@link org.hibernate.event.internal.EntityCopyAllowedLoggedObserver}. * {@link org.hibernate.event.internal.EntityCopyAllowedLoggedObserver}.
* </li>
* </ul> * </ul>
* Alternatively, the application may customize the behavior by providing an implementation * Alternatively, the application may customize the behavior by providing an
* of {@link org.hibernate.event.spi.EntityCopyObserver} and setting the property * implementation of {@link org.hibernate.event.spi.EntityCopyObserver} and setting
* {@value #MERGE_ENTITY_COPY_OBSERVER} to the class name. * the property {@value #MERGE_ENTITY_COPY_OBSERVER} to the class name.
* <p> * <p>
* When this property is set to {@code allow} or {@code log}, Hibernate will merge each entity * When this property is set to {@code allow} or {@code log}, Hibernate will merge
* copy detected while cascading the merge operation. In the process of merging each entity copy, * each entity copy detected while cascading the merge operation. In the process of
* Hibernate will cascade the merge operation from each entity copy to its associations with * merging each entity copy, Hibernate will cascade the merge operation from each
* {@link jakarta.persistence.CascadeType#MERGE} or {@link jakarta.persistence.CascadeType#ALL}. * entity copy to its associations with {@link jakarta.persistence.CascadeType#MERGE}
* The entity state resulting from merging an entity copy will be overwritten when another entity * or {@link jakarta.persistence.CascadeType#ALL}. The entity state resulting from
* copy is merged. * merging an entity copy will be overwritten when another entity copy is merged.
* *
* @since 4.3 * @since 4.3
*/ */
@SuppressWarnings("JavaDoc")
String MERGE_ENTITY_COPY_OBSERVER = "hibernate.event.merge.entity_copy_observer"; String MERGE_ENTITY_COPY_OBSERVER = "hibernate.event.merge.entity_copy_observer";
/** /**
* By default, {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria} queries use * By default, {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria}
* bind parameters for any value passed via the JPA Criteria API. * queries use bind parameters for any value passed via the JPA Criteria API.
* <ul> * <ul>
* <li>The {@link org.hibernate.query.criteria.ValueHandlingMode#BIND "bind"} mode uses bind * <li>The {@link org.hibernate.query.criteria.ValueHandlingMode#BIND "bind"}
* variables for any literal value. * mode uses bind variables for any literal value.
* <li>The {@link org.hibernate.query.criteria.ValueHandlingMode#INLINE "inline"} mode will * <li>The {@link org.hibernate.query.criteria.ValueHandlingMode#INLINE "inline"}
* inline values as SQL literals. * mode inlines values as SQL literals.
* </ul> * </ul>
* The default value is {@link org.hibernate.query.criteria.ValueHandlingMode#BIND}. * The default value is {@link org.hibernate.query.criteria.ValueHandlingMode#BIND}.
* *
@ -2010,8 +2050,9 @@ public interface AvailableSettings {
String CRITERIA_VALUE_HANDLING_MODE = "hibernate.criteria.value_handling_mode"; String CRITERIA_VALUE_HANDLING_MODE = "hibernate.criteria.value_handling_mode";
/** /**
* Allows setting default value for all {@link org.hibernate.jpa.spi.JpaCompliance} flags. * Specifies a default value for all {@link org.hibernate.jpa.spi.JpaCompliance}
* Each individual flags may still be overridden using its specific configuration property. * flags. Each individual flag may still be overridden by explicitly specifying
* its specific configuration property.
* *
* @see #JPA_TRANSACTION_COMPLIANCE * @see #JPA_TRANSACTION_COMPLIANCE
* @see #JPA_QUERY_COMPLIANCE * @see #JPA_QUERY_COMPLIANCE
@ -2039,13 +2080,17 @@ public interface AvailableSettings {
String JPA_TRANSACTION_COMPLIANCE = "hibernate.jpa.compliance.transaction"; String JPA_TRANSACTION_COMPLIANCE = "hibernate.jpa.compliance.transaction";
/** /**
* Controls whether Hibernate's handling of {@link jakarta.persistence.Query} * When enabled, specifies that every {@linkplain org.hibernate.query.Query query}
* (JPQL, Criteria and native-query) should strictly follow the JPA spec. * must strictly follow the specified behavior of {@link jakarta.persistence.Query}.
* This includes both in terms of parsing or translating a query as well * The affects JPQL queries, criteria queries, and native SQL queries.
* as calls to the {@link jakarta.persistence.Query} methods throwing spec * <p>
* defined exceptions where as Hibernate might not. * This setting modifies the behavior of the JPQL query translator, and of the
* * {@code Query} interface itself. In particular, it forces all methods of
* Deviations result in an exception if enabled * {@code Query} to throw the exception types defined by the JPA specification.
* <p>
* If enabled, any deviations from the JPQL specification results in an exception.
* Therefore, this setting is not recommended, since it prohibits the use of many
* useful features of HQL.
* *
* @see org.hibernate.jpa.spi.JpaCompliance#isJpaQueryComplianceEnabled() * @see org.hibernate.jpa.spi.JpaCompliance#isJpaQueryComplianceEnabled()
* *
@ -2072,7 +2117,7 @@ public interface AvailableSettings {
* Controls whether Hibernate should recognize what it considers a "bag" * Controls whether Hibernate should recognize what it considers a "bag"
* ({@link org.hibernate.collection.spi.PersistentBag}) as a list * ({@link org.hibernate.collection.spi.PersistentBag}) as a list
* ({@link org.hibernate.collection.spi.PersistentList}) or as a bag. * ({@link org.hibernate.collection.spi.PersistentList}) or as a bag.
* * <p>
* If enabled, Hibernate will recognize it as a list where the * If enabled, Hibernate will recognize it as a list where the
* {@link jakarta.persistence.OrderColumn} annotation is simply missing * {@link jakarta.persistence.OrderColumn} annotation is simply missing
* (and its defaults will apply). * (and its defaults will apply).
@ -2086,7 +2131,7 @@ public interface AvailableSettings {
/** /**
* JPA defines specific exception types that must be thrown by specific * JPA defines specific exception types that must be thrown by specific
* methods of {@link jakarta.persistence.EntityManager} and * methods of {@link jakarta.persistence.EntityManager} and
* {@link jakarta.persistence.EntityManagerFactory} when the objects has * {@link jakarta.persistence.EntityManagerFactory} when the object has
* been closed. When enabled, this setting specifies that Hibernate should * been closed. When enabled, this setting specifies that Hibernate should
* comply with the specification. * comply with the specification.
* *
@ -2097,16 +2142,19 @@ public interface AvailableSettings {
String JPA_CLOSED_COMPLIANCE = "hibernate.jpa.compliance.closed"; String JPA_CLOSED_COMPLIANCE = "hibernate.jpa.compliance.closed";
/** /**
* The JPA spec insists that a {@link jakarta.persistence.EntityNotFoundException} * The JPA specification insists that an
* should be thrown when accessing an entity proxy which does not have an associated * {@link jakarta.persistence.EntityNotFoundException} must be thrown whenever
* table row in the database. * an uninitialized entity proxy with no corresponding row in the database is
* accessed. For most programs, this results in many completely unnecessary
* round trips to the database.
* <p> * <p>
* Traditionally, Hibernate does not initialize an entity proxy when accessing its * Traditionally, Hibernate does not initialize an entity proxy when its
* identifier since it already knows the identifier value, and saves a database * identifier attribute is accessed, since the identifier value is already
* round trip. * known and held in the proxy instance. This behavior saves the round trip
* to the database.
* <p> * <p>
* If enabled Hibernate will initialize the entity proxy even when accessing its * When enabled, this setting forces Hibernate to initialize the entity proxy
* identifier. * when its identifier is accessed. Clearly, this setting is not recommended.
* *
* @see org.hibernate.jpa.spi.JpaCompliance#isJpaProxyComplianceEnabled() * @see org.hibernate.jpa.spi.JpaCompliance#isJpaProxyComplianceEnabled()
* *
@ -2122,13 +2170,15 @@ public interface AvailableSettings {
String JPA_CACHING_COMPLIANCE = "hibernate.jpa.compliance.caching"; String JPA_CACHING_COMPLIANCE = "hibernate.jpa.compliance.caching";
/** /**
* Determines whether the scope of {@link jakarta.persistence.TableGenerator#name()} * Determines whether the scope of any identifier generator name specified via
* and {@link jakarta.persistence.SequenceGenerator#name()} should be considered global * {@link jakarta.persistence.TableGenerator#name()} or
* or local. * {@link jakarta.persistence.SequenceGenerator#name()} is considered global to
* the persistence unit, or local to the entity in which identifier generator
* is defined.
* <p> * <p>
* If enabled, the names will be considered globally scoped, so defining two different * If enabled, the name will be considered globally scoped, and so the existence
* generators with the same name will cause a name collision and an exception will be * of two different generators with the same name will be considered a collision,
* thrown during the bootstrap phase. * and will result in an exception during bootstrap.
* *
* @see org.hibernate.jpa.spi.JpaCompliance#isGlobalGeneratorScopeEnabled() * @see org.hibernate.jpa.spi.JpaCompliance#isGlobalGeneratorScopeEnabled()
* *
@ -2144,21 +2194,27 @@ public interface AvailableSettings {
String JPA_LOAD_BY_ID_COMPLIANCE = "hibernate.jpa.compliance.load_by_id"; String JPA_LOAD_BY_ID_COMPLIANCE = "hibernate.jpa.compliance.load_by_id";
/** /**
* True/False setting indicating if the value stored in the table used by the * Determines if the identifier value stored in the database table backing a
* {@link jakarta.persistence.TableGenerator} is the last value generated or the * {@linkplain jakarta.persistence.TableGenerator table generator} is the last
* next value to be used. * value returned by the identifier generator, or the next value to be returned.
* * <p>
* The default value is true. * By default, the value stored in the database table is the last generated value.
* *
* @since 5.3 * @since 5.3
*/ */
String TABLE_GENERATOR_STORE_LAST_USED = "hibernate.id.generator.stored_last_used"; String TABLE_GENERATOR_STORE_LAST_USED = "hibernate.id.generator.stored_last_used";
/** /**
* Raises an exception when in-memory pagination over collection fetch is about to * When {@linkplain org.hibernate.query.Query#setMaxResults(int) pagination} is used
* be performed. * in combination with a {@code fetch join} applied to a collection or many-valued
* * association, the limit must be applied in-memory instead of on the database. This
* Disabled by default. Set to true to enable. * typically has terrible performance characteristics, and should be avoided.
* <p>
* When enabled, this setting specifies that an exception should be thrown for any
* query which would result in the limit being applied in-memory.
* <p>
* By default, the exception is <em>disabled</em>, and the possibility of terrible
* performance is left as a problem for the client to avoid.
* *
* @since 5.2.13 * @since 5.2.13
*/ */
@ -2166,17 +2222,17 @@ public interface AvailableSettings {
/** /**
* This setting defines how {@link org.hibernate.annotations.Immutable} entities * This setting defines how {@link org.hibernate.annotations.Immutable} entities
* are handled when executing a bulk update query. Valid options are defined by the * are handled when executing a bulk update query. Valid options are enumerated
* enumeration {@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode}: * by {@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode}:
* <ul> * <ul>
* <li>{@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#WARNING "warning"} * <li>{@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#WARNING "warning"}
* specifies that a warning log message is issued when an * specifies that a warning log message is issued when an
* {@linkplain org.hibernate.annotations.Immutable immutable} entity is to * {@linkplain org.hibernate.annotations.Immutable immutable} entity is to be
* be updated via a bulk update statement, and * updated via a bulk update statement, and
* <li {@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#EXCEPTION "exception"} * <li>{@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#EXCEPTION "exception"}
* specifies that a {@link org.hibernate.HibernateException} should be thrown. * specifies that a {@link org.hibernate.HibernateException} should be thrown.
* </ul> * </ul>
* The default value is {@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#WARNING "warning"}. * By default, a warning is logged.
* *
* @since 5.2.17 * @since 5.2.17
* *
@ -2185,20 +2241,18 @@ public interface AvailableSettings {
String IMMUTABLE_ENTITY_UPDATE_QUERY_HANDLING_MODE = "hibernate.query.immutable_entity_update_query_handling_mode"; String IMMUTABLE_ENTITY_UPDATE_QUERY_HANDLING_MODE = "hibernate.query.immutable_entity_update_query_handling_mode";
/** /**
* By default, the IN clause expands to include all bind parameter values. * Determines how parameters occurring in a SQL {@code IN} predicate are expanded.
* </p> * By default, the {@code IN} predicate expands to include sufficient bind parameters
* However, for database systems supporting execution plan caching, there's * to accommodate the specified arguments.
* a better chance of hitting the cache if the number of possible IN clause * <p>
* parameters lowers. * However, for database systems supporting execution plan caching, there's a
* </p> * better chance of hitting the cache if the number of possible {@code IN} clause
* For this reason, we can expand the bind parameters to power-of-two: * parameters is smaller.
* 4, 8, 16, 32, 64. This way, an IN clause with 5, 6, or 7 bind parameters * <p>
* will use the 8 IN clause, therefore reusing its execution plan. * When this setting is enabled, we expand the number of bind parameters to an
* </p> * integer power of two: 4, 8, 16, 32, 64. Thus, if 5, 6, or 7 arguments are bound
* If you want to activate this feature, you need to set this property to * to a parameter, a SQL statement with 8 bind parameters in the {@code IN} clause
* {@code true}. * will be used, and null will be bound to the left-over parameters.
* </p>
* The default value is {@code false}.
* *
* @since 5.2.17 * @since 5.2.17
*/ */
@ -2216,9 +2270,9 @@ public interface AvailableSettings {
String QUERY_STATISTICS_MAX_SIZE = "hibernate.statistics.query_max_size"; String QUERY_STATISTICS_MAX_SIZE = "hibernate.statistics.query_max_size";
/** /**
* This setting defines the {@link org.hibernate.id.SequenceMismatchStrategy} used when * This setting defines the {@link org.hibernate.id.SequenceMismatchStrategy} used
* Hibernate detects a mismatch between a sequence configuration in an entity mapping * when Hibernate detects a mismatch between a sequence configuration in an entity
* and its database sequence object counterpart. * mapping and its database sequence object counterpart.
* <p> * <p>
* Possible values are {@link org.hibernate.id.SequenceMismatchStrategy#EXCEPTION}, * Possible values are {@link org.hibernate.id.SequenceMismatchStrategy#EXCEPTION},
* {@link org.hibernate.id.SequenceMismatchStrategy#LOG}, * {@link org.hibernate.id.SequenceMismatchStrategy#LOG},
@ -2245,43 +2299,43 @@ public interface AvailableSettings {
String OMIT_JOIN_OF_SUPERCLASS_TABLES = "hibernate.query.omit_join_of_superclass_tables"; String OMIT_JOIN_OF_SUPERCLASS_TABLES = "hibernate.query.omit_join_of_superclass_tables";
/** /**
* Global setting identifying the preferred JDBC type code for storing boolean * Specifies the preferred JDBC type code for storing boolean values. When no
* values. The fallback is to ask the {@link org.hibernate.dialect.Dialect}. * type code is explicitly specified, a sensible
* {@link org.hibernate.dialect.Dialect#getPreferredSqlTypeCodeForBoolean()
* dialect-specific default type code} is used.
* *
* @since 6.0 * @since 6.0
*/ */
String PREFERRED_BOOLEAN_JDBC_TYPE_CODE = "hibernate.type.preferred_boolean_jdbc_type_code"; String PREFERRED_BOOLEAN_JDBC_TYPE_CODE = "hibernate.type.preferred_boolean_jdbc_type_code";
/** /**
* Names a {@link org.hibernate.type.FormatMapper} implementation to be applied to * Specifies a {@link org.hibernate.type.FormatMapper} used for for JSON serialization
* the {@link org.hibernate.SessionFactory} for JSON serialization and deserialization. * and deserialization, either:
* Can reference<ul> * <ul>
* <li>FormatMapper instance</li> * <li>an instance of {@code FormatMapper},
* <li>FormatMapper implementation {@link Class} reference</li> * <li>a {@link Class} representing a class that implements {@code FormatMapper},
* <li>FormatMapper implementation class name (FQN)</li> * <li>the name of a class that implements {@code FormatMapper}, or
* <li>one of the short hand constants<ul> * <li>one of the short hand constants {@code jackson} or {@code jsonb}.
* <li>jackson</li>
* <li>jsonb</li>
* </ul>
* </li>
* </ul> * </ul>
* By default the first of the possible providers that is available in the runtime is used, * By default, the first of the possible providers that is available in the runtime is
* according to the listing order. * used, according to the listing order.
* *
* @since 6.0 * @since 6.0
*/ */
String JSON_FORMAT_MAPPER = "hibernate.type.json_format_mapper"; String JSON_FORMAT_MAPPER = "hibernate.type.json_format_mapper";
/** /**
* Global setting for configuring the default storage for the time zone information for time zone based types. * Specifies the default strategy for storage of the timezone information
* </p> * for zoned datetime types:
* Possible values are {@link org.hibernate.annotations.TimeZoneStorageType#NORMALIZE}, * <ul>
* {@link org.hibernate.annotations.TimeZoneStorageType#COLUMN}, * <li>{@link org.hibernate.annotations.TimeZoneStorageType#NORMALIZE},
* {@link org.hibernate.annotations.TimeZoneStorageType#NATIVE} * <li>{@link org.hibernate.annotations.TimeZoneStorageType#COLUMN},
* and {@link org.hibernate.annotations.TimeZoneStorageType#AUTO}. * <li>{@link org.hibernate.annotations.TimeZoneStorageType#NATIVE}, or
* </p> * <li>{@link org.hibernate.annotations.TimeZoneStorageType#AUTO}.
* The default value is given by the {@link org.hibernate.annotations.TimeZoneStorageType#NORMALIZE}, * </ul>
* meaning that time zone information is not stored by default, but timestamps are normalized instead. * The default is {@link org.hibernate.annotations.TimeZoneStorageType#NORMALIZE},
* meaning that timezone information is not stored by default, but timestamps are
* normalized to UTC instead.
* *
* @since 6.0 * @since 6.0
*/ */
@ -2292,13 +2346,14 @@ public interface AvailableSettings {
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/** /**
* The name of the {@link jakarta.persistence.spi.PersistenceProvider} implementor * Specifies a class implementing {@link jakarta.persistence.spi.PersistenceProvider}.
* <p/> * <p/>
* See JPA 2 sections 9.4.3 and 8.2.1.4 * See JPA 2 sections 9.4.3 and 8.2.1.4
* *
* @deprecated Use {@link #JAKARTA_PERSISTENCE_PROVIDER} instead * @deprecated Use {@link #JAKARTA_PERSISTENCE_PROVIDER} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_PERSISTENCE_PROVIDER = "javax.persistence.provider"; String JPA_PERSISTENCE_PROVIDER = "javax.persistence.provider";
/** /**
@ -2319,6 +2374,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_JTA_DATASOURCE} instead * @deprecated Use {@link #JAKARTA_JTA_DATASOURCE} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_JTA_DATASOURCE = "javax.persistence.jtaDataSource"; String JPA_JTA_DATASOURCE = "javax.persistence.jtaDataSource";
/** /**
@ -2329,6 +2385,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_NON_JTA_DATASOURCE} instead * @deprecated Use {@link #JAKARTA_NON_JTA_DATASOURCE} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_NON_JTA_DATASOURCE = "javax.persistence.nonJtaDataSource"; String JPA_NON_JTA_DATASOURCE = "javax.persistence.nonJtaDataSource";
/** /**
@ -2345,6 +2402,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_JDBC_DRIVER} instead * @deprecated Use {@link #JAKARTA_JDBC_DRIVER} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_JDBC_DRIVER = "javax.persistence.jdbc.driver"; String JPA_JDBC_DRIVER = "javax.persistence.jdbc.driver";
/** /**
@ -2361,6 +2419,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_JDBC_URL} instead * @deprecated Use {@link #JAKARTA_JDBC_URL} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_JDBC_URL = "javax.persistence.jdbc.url"; String JPA_JDBC_URL = "javax.persistence.jdbc.url";
/** /**
@ -2374,6 +2433,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_JDBC_USER} instead * @deprecated Use {@link #JAKARTA_JDBC_USER} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_JDBC_USER = "javax.persistence.jdbc.user"; String JPA_JDBC_USER = "javax.persistence.jdbc.user";
/** /**
@ -2387,6 +2447,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_JDBC_PASSWORD} instead * @deprecated Use {@link #JAKARTA_JDBC_PASSWORD} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_JDBC_PASSWORD = "javax.persistence.jdbc.password"; String JPA_JDBC_PASSWORD = "javax.persistence.jdbc.password";
/** /**
@ -2399,6 +2460,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_SHARED_CACHE_MODE} instead * @deprecated Use {@link #JAKARTA_SHARED_CACHE_MODE} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_SHARED_CACHE_MODE = "javax.persistence.sharedCache.mode"; String JPA_SHARED_CACHE_MODE = "javax.persistence.sharedCache.mode";
/** /**
@ -2411,6 +2473,7 @@ public interface AvailableSettings {
*/ */
//NOTE : Not a valid EMF property //NOTE : Not a valid EMF property
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_SHARED_CACHE_RETRIEVE_MODE = "javax.persistence.cache.retrieveMode"; String JPA_SHARED_CACHE_RETRIEVE_MODE = "javax.persistence.cache.retrieveMode";
/** /**
@ -2423,6 +2486,7 @@ public interface AvailableSettings {
*/ */
//NOTE: Not a valid EMF property //NOTE: Not a valid EMF property
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_SHARED_CACHE_STORE_MODE = "javax.persistence.cache.storeMode"; String JPA_SHARED_CACHE_STORE_MODE = "javax.persistence.cache.storeMode";
/** /**
@ -2436,6 +2500,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_VALIDATION_MODE} instead * @deprecated Use {@link #JAKARTA_VALIDATION_MODE} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_VALIDATION_MODE = "javax.persistence.validation.mode"; String JPA_VALIDATION_MODE = "javax.persistence.validation.mode";
/** /**
@ -2444,6 +2509,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_VALIDATION_FACTORY} instead * @deprecated Use {@link #JAKARTA_VALIDATION_FACTORY} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_VALIDATION_FACTORY = "javax.persistence.validation.factory"; String JPA_VALIDATION_FACTORY = "javax.persistence.validation.factory";
/** /**
@ -2484,6 +2550,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_LOCK_SCOPE} instead * @deprecated Use {@link #JAKARTA_LOCK_SCOPE} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_LOCK_SCOPE = LegacySpecHints.HINT_JAVAEE_LOCK_SCOPE; String JPA_LOCK_SCOPE = LegacySpecHints.HINT_JAVAEE_LOCK_SCOPE;
/** /**
@ -2494,6 +2561,7 @@ public interface AvailableSettings {
* @deprecated Use {@link #JAKARTA_LOCK_TIMEOUT} instead * @deprecated Use {@link #JAKARTA_LOCK_TIMEOUT} instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String JPA_LOCK_TIMEOUT = LegacySpecHints.HINT_JAVAEE_LOCK_TIMEOUT; String JPA_LOCK_TIMEOUT = LegacySpecHints.HINT_JAVAEE_LOCK_TIMEOUT;
/** /**
@ -2593,6 +2661,7 @@ public interface AvailableSettings {
* instead * instead
*/ */
@Deprecated @Deprecated
@SuppressWarnings("DeprecatedIsStillUsed")
String IDENTIFIER_GENERATOR_STRATEGY_PROVIDER = "hibernate.identifier_generator_strategy_provider"; String IDENTIFIER_GENERATOR_STRATEGY_PROVIDER = "hibernate.identifier_generator_strategy_provider";
/** /**

2
hibernate-core/src/main/java/org/hibernate/engine/internal/StatisticalLoggingSessionEventListener.java
View File

@ -11,6 +11,8 @@ import org.hibernate.BaseSessionEventListener;
import org.jboss.logging.Logger; import org.jboss.logging.Logger;
/** /**
* @see org.hibernate.cfg.AvailableSettings#LOG_SESSION_METRICS
*
* @author Steve Ebersole * @author Steve Ebersole
*/ */
public class StatisticalLoggingSessionEventListener extends BaseSessionEventListener { public class StatisticalLoggingSessionEventListener extends BaseSessionEventListener {

2
hibernate-core/src/main/java/org/hibernate/id/SequenceMismatchStrategy.java
View File

@ -12,6 +12,8 @@ import org.hibernate.HibernateException;
* Describes the strategy for handling the mismatch between a database sequence configuration and * Describes the strategy for handling the mismatch between a database sequence configuration and
* the one defined by the entity mapping. * the one defined by the entity mapping.
* *
* @see org.hibernate.cfg.AvailableSettings#SEQUENCE_INCREMENT_SIZE_MISMATCH_STRATEGY
*
* @author Vlad Mihalcea * @author Vlad Mihalcea
*/ */
public enum SequenceMismatchStrategy { public enum SequenceMismatchStrategy {

6
hibernate-core/src/main/java/org/hibernate/loader/BatchFetchStyle.java
View File

@ -10,9 +10,9 @@ import java.util.Locale;
import org.jboss.logging.Logger; import org.jboss.logging.Logger;
/** /**
* Defines the style that should be used to perform batch loading. Which style to use is declared using * Defines a type of batch loading.
* the "{@value org.hibernate.cfg.AvailableSettings#BATCH_FETCH_STYLE}" *
* ({@value org.hibernate.cfg.AvailableSettings#BATCH_FETCH_STYLE}) setting * @see org.hibernate.cfg.AvailableSettings#BATCH_FETCH_STYLE
* *
* @author Steve Ebersole * @author Steve Ebersole
* *

24
hibernate-core/src/main/java/org/hibernate/query/ImmutableEntityUpdateQueryHandlingMode.java
View File

@ -9,15 +9,17 @@ package org.hibernate.query;
import org.hibernate.HibernateException; import org.hibernate.HibernateException;
/** /**
* This enum defines how {@link org.hibernate.annotations.Immutable} entities are handled when executing a * This enum defines how {@link org.hibernate.annotations.Immutable} entities are handled when
* bulk update statement. * executing a bulk update statement.
* <ul>
* <li>By default, the {@link ImmutableEntityUpdateQueryHandlingMode#WARNING} mode is used,
* and a warning log message is issued when an {@link org.hibernate.annotations.Immutable}
* entity is to be updated via a bulk update statement.
* <li>If the {@link ImmutableEntityUpdateQueryHandlingMode#EXCEPTION} mode is used, then a
* {@link HibernateException} is thrown instead.
* </ul>
* *
* By default, the ({@link ImmutableEntityUpdateQueryHandlingMode#WARNING}) mode is used, meaning that * @see org.hibernate.cfg.AvailableSettings#IMMUTABLE_ENTITY_UPDATE_QUERY_HANDLING_MODE
* a warning log message is issued when an {@link org.hibernate.annotations.Immutable} entity
* is to be updated via a bulk update statement.
*
* If the ({@link ImmutableEntityUpdateQueryHandlingMode#EXCEPTION}) mode is used, then a
* {@link HibernateException} is thrown instead.
* *
* @author Vlad Mihalcea * @author Vlad Mihalcea
*/ */
@ -28,9 +30,9 @@ public enum ImmutableEntityUpdateQueryHandlingMode {
/** /**
* Interpret the configured {@link ImmutableEntityUpdateQueryHandlingMode} value. * Interpret the configured {@link ImmutableEntityUpdateQueryHandlingMode} value.
* Valid values are either a {@link ImmutableEntityUpdateQueryHandlingMode} object or its String representation. * Valid values are either a {@link ImmutableEntityUpdateQueryHandlingMode} object or
* For string values, the matching is case insensitive, * its string representation. For string values, the matching is case-insensitive,
* so you can use either {@code warning} or {@code exception} (case insensitive). * so you can use either {@code warning} or {@code exception}.
* *
* @param mode configured {@link ImmutableEntityUpdateQueryHandlingMode} representation * @param mode configured {@link ImmutableEntityUpdateQueryHandlingMode} representation
* @return associated {@link ImmutableEntityUpdateQueryHandlingMode} object * @return associated {@link ImmutableEntityUpdateQueryHandlingMode} object

8
hibernate-core/src/main/java/org/hibernate/query/criteria/ValueHandlingMode.java
View File

@ -10,10 +10,12 @@ import org.hibernate.HibernateException;
/** /**
* This enum defines how values passed to JPA Criteria API are handled. * This enum defines how values passed to JPA Criteria API are handled.
* <ul>
* <li>The {@code BIND} mode (default) will use bind variables for any value.
* <li> The {@code INLINE} mode inlines values as literals.
* </ul>
* *
* The {@code BIND} mode (default) will use bind variables for any value. * @see org.hibernate.cfg.AvailableSettings#CRITERIA_VALUE_HANDLING_MODE
*
* The {@code INLINE} mode will inline values as literals.
* *
* @author Christian Beikov * @author Christian Beikov
*/ */

2
hibernate-core/src/main/java/org/hibernate/query/spi/QueryInterpretationCache.java
View File

@ -16,6 +16,8 @@ import org.hibernate.query.sqm.tree.SqmStatement;
/** /**
* Cache for various parts of translating or interpreting queries. * Cache for various parts of translating or interpreting queries.
* *
* @see org.hibernate.cfg.AvailableSettings#QUERY_PLAN_CACHE_MAX_SIZE
*
* @author Steve Ebersole * @author Steve Ebersole
*/ */
@Incubating @Incubating

5
hibernate-core/src/main/java/org/hibernate/query/spi/QueryPlanCache.java
View File

@ -9,9 +9,12 @@ package org.hibernate.query.spi;
import org.hibernate.query.sqm.tree.SqmStatement; import org.hibernate.query.sqm.tree.SqmStatement;
/** /**
* A cache for QueryPlans used (and produced) by the translation * A cache for {@link QueryPlan}s used (and produced) by the translation
* and execution of a query. * and execution of a query.
* *
* @see org.hibernate.cfg.AvailableSettings#QUERY_PLAN_CACHE_ENABLED
* @see org.hibernate.cfg.AvailableSettings#QUERY_PLAN_CACHE_MAX_SIZE
*
* @author Steve Ebersole * @author Steve Ebersole
*/ */
public interface QueryPlanCache { public interface QueryPlanCache {

5
hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/StatementInspector.java
View File

@ -9,7 +9,10 @@ package org.hibernate.resource.jdbc.spi;
import java.io.Serializable; import java.io.Serializable;
/** /**
* Contract to allow inspection (and swapping) of SQL to be prepared * Contract to allow inspection (and swapping) of SQL to be prepared.
* <p>
* An implementation may be specified via the configuration property
* {@value org.hibernate.cfg.AvailableSettings#STATEMENT_INSPECTOR}.
* *
* @author Steve Ebersole * @author Steve Ebersole
*/ */

2
hibernate-core/src/main/java/org/hibernate/type/FormatMapper.java
View File

@ -12,6 +12,8 @@ import org.hibernate.type.descriptor.java.JavaType;
/** /**
* A mapper for mapping objects to and from a format. * A mapper for mapping objects to and from a format.
* *
* @see org.hibernate.cfg.AvailableSettings#JSON_FORMAT_MAPPER
*
* @author Christian Beikov * @author Christian Beikov
*/ */
public interface FormatMapper { public interface FormatMapper {