diff --git a/hibernate-core/src/main/java/org/hibernate/Interceptor.java b/hibernate-core/src/main/java/org/hibernate/Interceptor.java index 4a21a07bd9..0144de5751 100644 --- a/hibernate-core/src/main/java/org/hibernate/Interceptor.java +++ b/hibernate-core/src/main/java/org/hibernate/Interceptor.java @@ -14,22 +14,25 @@ import org.hibernate.metamodel.spi.EntityRepresentationStrategy; import org.hibernate.type.Type; /** - * Allows user code to inspect and/or change property values. - * - * Inspection occurs before property values are written and after they are read - * from the database. - * - * There might be a single instance of {@code Interceptor} for a {@code SessionFactory}, or a new instance - * might be specified for each {@code Session}. Whichever approach is used, the interceptor must be - * serializable if the {@code Session} is to be serializable. This means that {@code SessionFactory}-scoped + * 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. + *
+ * 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 {@link SessionFactory}, + * or a new instance might be created for each {@link Session}. Use: + *
* 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"; /** - * Should query plan caching be enabled at all? Default is {@code false} unless - * one of {@link #QUERY_PLAN_CACHE_MAX_SIZE} or - * {@link #QUERY_PLAN_CACHE_PARAMETER_METADATA_MAX_SIZE} is specified. + * When enabled, specifies that {@linkplain QueryPlan query plans} should be + * {@linkplain org.hibernate.query.spi.QueryPlanCache cached}. + *
+ * 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"; @@ -1322,6 +1334,7 @@ public interface AvailableSettings { * @deprecated Use {@link #JAKARTA_HBM2DDL_CONNECTION} instead */ @Deprecated + @SuppressWarnings("DeprecatedIsStillUsed") 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 * {@link org.hibernate.tool.schema.SourceType} for the list of legal values. *
- * If no value is specified, a default is inferred as follows:
- * If no value is specified, a default is inferred as follows:
- * If no value is specified, a default is inferred as follows:
- * If no value is specified, a default is inferred as follows:
+ * This setting controls whether the restriction is applied when loading a + * {@link jakarta.persistence.OneToMany one-to-many} or + * or {@link jakarta.persistence.ManyToMany many-to-many} association whose target + * type defines the restriction. + *
+ * By default, the restriction is not applied. When this setting is enabled, the + * restriction is applied. + *
+ * 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"; @@ -1746,9 +1769,9 @@ public interface AvailableSettings { String MULTI_TENANT_CONNECTION_PROVIDER = "hibernate.multi_tenant_connection_provider"; /** - * Specifies a {@link org.hibernate.context.spi.CurrentTenantIdentifierResolver} to use. - *
- * Can be+ * 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 */ String SESSION_SCOPED_INTERCEPTOR = "hibernate.session_factory.session_scoped_interceptor"; /** - * Specifies a {@link org.hibernate.resource.jdbc.spi.StatementInspector} implementation - * associated with the {@link org.hibernate.SessionFactory}, either: + * Specifies a {@link org.hibernate.resource.jdbc.spi.StatementInspector} + * implementation associated with the {@link org.hibernate.SessionFactory}, + * either: *
* When {@code true}, the default, the loaders are only created on first * access; this ensures that all access patterns which are not useful * 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 * detect mapping errors. *
- * {@code false} indicates that all loaders should be created up front; this - * will consume more memory but ensures all necessary memory is + * {@code false} indicates that all loaders should be created up front; + * this will consume more memory but ensures all necessary memory is * allocated right away. * * @since 5.3 @@ -1852,16 +1878,16 @@ public interface AvailableSettings { 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 * Oracle), this is disabled by default. */ String ENABLE_SYNONYMS = "hibernate.synonyms"; /** - * Identifies a comma-separate list of values to specify extra table types, - * other than the default "TABLE" value, to recognize as defining a physical table - * by schema update, creation and validation. + * Specifies a comma-separated list of extra table types, in addition to the + * default types {@code "TABLE"} and {@code "VIEW"}, to recognize as physical + * tables when performing schema update, creation and validation. * * @since 5.0 */ @@ -1873,58 +1899,72 @@ public interface AvailableSettings { * finding existing constraints is extremely inconsistent. Worse, unique constraints * without explicit names are assigned names with randomly generated characters. *
- * Therefore, select from these strategies:
+ * By default, logging of session metrics is disabled unless {@link #GENERATE_STATISTICS} + * is enabled. */ 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. + *
+ * 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"; /** - * Defines a default {@link org.hibernate.SessionEventListener} to be applied to newly-opened - * {@link org.hibernate.Session}s. + * Defines a default {@link org.hibernate.SessionEventListener} to be applied to + * newly-opened {@link org.hibernate.Session}s. */ String AUTO_SESSION_EVENTS_LISTENER = "hibernate.session.events.auto"; /** - * [EXPERIMENTAL] Enable instantiation of composite/embedded objects when all of its attribute - * values are {@code null}. The default (and historical) behavior is that a {@code null} - * reference will be used to represent the composite when all of its attributes are {@code null}. + * [EXPERIMENTAL] Enable instantiation of composite/embedded objects when all + * attribute values are {@code null}. The default (and historical) behavior is + * that a {@code null} reference will be used to represent the composite when + * all of its attributes are {@code null}. *
- * 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. + * 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. * * @since 5.1 */ 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. *
* Values are {@code true}, which grants access, and {@code false}, which does not. *
@@ -1935,11 +1975,11 @@ public interface AvailableSettings { /** * When enabled, allows update operations outside a transaction. *
- * Since version 5.2 Hibernate conforms with the JPA specification and disallows flushing any - * update outside a transaction. + * Since version 5.2 Hibernate conforms with the JPA specification and disallows + * flushing any update outside a transaction. *
- * Values are {@code true}, which allows flushing outside a transaction, and {@code false}, - * which does not. + * Values are {@code true}, which allows flushing outside a transaction, and + * {@code false}, which does not. *
* 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. *
* Values are {@code true}, which allows refreshing a detached instance and {@code false}, - * which does not. When refreshing is disallowed, an {@link IllegalArgumentException} is - * thrown. + * which does not. When refreshing is disallowed, an {@link IllegalArgumentException} + * is thrown. *
- * The default behavior is to allow refreshing a detached instance unless Hibernate is - * bootstrapped via JPA. + * The default behavior is to allow refreshing a detached instance unless Hibernate + * is bootstrapped via JPA. * * @since 5.2 */ String ALLOW_REFRESH_DETACHED_ENTITY = "hibernate.allow_refresh_detached_entity"; /** - * Setting that specifies how Hibernate will respond when multiple representations of the - * same persistent entity ("entity copy") are detected while merging. + * Setting that specifies how Hibernate will respond when multiple representations of + * the same persistent entity ("entity copy") are detected while merging. *
* The possible values are: *
- * When this property is set to {@code allow} or {@code log}, Hibernate will merge each entity - * copy detected while cascading the merge operation. In the process of merging each entity copy, - * Hibernate will cascade the merge operation from each entity copy to its associations with - * {@link jakarta.persistence.CascadeType#MERGE} or {@link jakarta.persistence.CascadeType#ALL}. - * The entity state resulting from merging an entity copy will be overwritten when another entity - * copy is merged. + * When this property is set to {@code allow} or {@code log}, Hibernate will merge + * each entity copy detected while cascading the merge operation. In the process of + * merging each entity copy, Hibernate will cascade the merge operation from each + * entity copy to its associations with {@link jakarta.persistence.CascadeType#MERGE} + * or {@link jakarta.persistence.CascadeType#ALL}. The entity state resulting from + * merging an entity copy will be overwritten when another entity copy is merged. * * @since 4.3 */ + @SuppressWarnings("JavaDoc") String MERGE_ENTITY_COPY_OBSERVER = "hibernate.event.merge.entity_copy_observer"; /** - * By default, {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria} queries use - * bind parameters for any value passed via the JPA Criteria API. + * By default, {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria} + * queries use bind parameters for any value passed via the JPA Criteria API. *
+ * This setting modifies the behavior of the JPQL query translator, and of the + * {@code Query} interface itself. In particular, it forces all methods of + * {@code Query} to throw the exception types defined by the JPA specification. + *
+ * 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() * @@ -2072,7 +2117,7 @@ public interface AvailableSettings { * Controls whether Hibernate should recognize what it considers a "bag" * ({@link org.hibernate.collection.spi.PersistentBag}) as a list * ({@link org.hibernate.collection.spi.PersistentList}) or as a bag. - * + *
* If enabled, Hibernate will recognize it as a list where the * {@link jakarta.persistence.OrderColumn} annotation is simply missing * (and its defaults will apply). @@ -2086,7 +2131,7 @@ public interface AvailableSettings { /** * JPA defines specific exception types that must be thrown by specific * 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 * comply with the specification. * @@ -2097,16 +2142,19 @@ public interface AvailableSettings { String JPA_CLOSED_COMPLIANCE = "hibernate.jpa.compliance.closed"; /** - * The JPA spec insists that a {@link jakarta.persistence.EntityNotFoundException} - * should be thrown when accessing an entity proxy which does not have an associated - * table row in the database. + * The JPA specification insists that an + * {@link jakarta.persistence.EntityNotFoundException} must be thrown whenever + * 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. *
- * Traditionally, Hibernate does not initialize an entity proxy when accessing its - * identifier since it already knows the identifier value, and saves a database - * round trip. + * Traditionally, Hibernate does not initialize an entity proxy when its + * identifier attribute is accessed, since the identifier value is already + * known and held in the proxy instance. This behavior saves the round trip + * to the database. *
- * If enabled Hibernate will initialize the entity proxy even when accessing its - * identifier. + * When enabled, this setting forces Hibernate to initialize the entity proxy + * when its identifier is accessed. Clearly, this setting is not recommended. * * @see org.hibernate.jpa.spi.JpaCompliance#isJpaProxyComplianceEnabled() * @@ -2122,13 +2170,15 @@ public interface AvailableSettings { String JPA_CACHING_COMPLIANCE = "hibernate.jpa.compliance.caching"; /** - * Determines whether the scope of {@link jakarta.persistence.TableGenerator#name()} - * and {@link jakarta.persistence.SequenceGenerator#name()} should be considered global - * or local. + * Determines whether the scope of any identifier generator name specified via + * {@link jakarta.persistence.TableGenerator#name()} or + * {@link jakarta.persistence.SequenceGenerator#name()} is considered global to + * the persistence unit, or local to the entity in which identifier generator + * is defined. *
- * If enabled, the names will be considered globally scoped, so defining two different - * generators with the same name will cause a name collision and an exception will be - * thrown during the bootstrap phase. + * If enabled, the name will be considered globally scoped, and so the existence + * of two different generators with the same name will be considered a collision, + * and will result in an exception during bootstrap. * * @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"; /** - * True/False setting indicating if the value stored in the table used by the - * {@link jakarta.persistence.TableGenerator} is the last value generated or the - * next value to be used. - * - * The default value is true. + * Determines if the identifier value stored in the database table backing a + * {@linkplain jakarta.persistence.TableGenerator table generator} is the last + * value returned by the identifier generator, or the next value to be returned. + *
+ * By default, the value stored in the database table is the last generated value. * * @since 5.3 */ 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 - * be performed. - * - * Disabled by default. Set to true to enable. + * When {@linkplain org.hibernate.query.Query#setMaxResults(int) pagination} is used + * 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 + * typically has terrible performance characteristics, and should be avoided. + *
+ * When enabled, this setting specifies that an exception should be thrown for any + * query which would result in the limit being applied in-memory. + *
+ * By default, the exception is disabled, and the possibility of terrible + * performance is left as a problem for the client to avoid. * * @since 5.2.13 */ @@ -2166,17 +2222,17 @@ public interface AvailableSettings { /** * This setting defines how {@link org.hibernate.annotations.Immutable} entities - * are handled when executing a bulk update query. Valid options are defined by the - * enumeration {@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode}: + * are handled when executing a bulk update query. Valid options are enumerated + * by {@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode}: *
+ * However, for database systems supporting execution plan caching, there's a + * better chance of hitting the cache if the number of possible {@code IN} clause + * parameters is smaller. + *
+ * When this setting is enabled, we expand the number of bind parameters to an + * integer power of two: 4, 8, 16, 32, 64. Thus, if 5, 6, or 7 arguments are bound + * to a parameter, a SQL statement with 8 bind parameters in the {@code IN} clause + * will be used, and null will be bound to the left-over parameters. * * @since 5.2.17 */ @@ -2216,9 +2270,9 @@ public interface AvailableSettings { String QUERY_STATISTICS_MAX_SIZE = "hibernate.statistics.query_max_size"; /** - * This setting defines the {@link org.hibernate.id.SequenceMismatchStrategy} used when - * Hibernate detects a mismatch between a sequence configuration in an entity mapping - * and its database sequence object counterpart. + * This setting defines the {@link org.hibernate.id.SequenceMismatchStrategy} used + * when Hibernate detects a mismatch between a sequence configuration in an entity + * mapping and its database sequence object counterpart. *
* Possible values are {@link org.hibernate.id.SequenceMismatchStrategy#EXCEPTION}, * {@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"; /** - * Global setting identifying the preferred JDBC type code for storing boolean - * values. The fallback is to ask the {@link org.hibernate.dialect.Dialect}. + * Specifies the preferred JDBC type code for storing boolean values. When no + * type code is explicitly specified, a sensible + * {@link org.hibernate.dialect.Dialect#getPreferredSqlTypeCodeForBoolean() + * dialect-specific default type code} is used. * * @since 6.0 */ 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 - * the {@link org.hibernate.SessionFactory} for JSON serialization and deserialization. - * Can reference
+ * An implementation may be specified via the configuration property + * {@value org.hibernate.cfg.AvailableSettings#STATEMENT_INSPECTOR}. * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/type/FormatMapper.java b/hibernate-core/src/main/java/org/hibernate/type/FormatMapper.java index f95ddcb25f..5c5467a5fe 100644 --- a/hibernate-core/src/main/java/org/hibernate/type/FormatMapper.java +++ b/hibernate-core/src/main/java/org/hibernate/type/FormatMapper.java @@ -12,6 +12,8 @@ import org.hibernate.type.descriptor.java.JavaType; /** * A mapper for mapping objects to and from a format. * + * @see org.hibernate.cfg.AvailableSettings#JSON_FORMAT_MAPPER + * * @author Christian Beikov */ public interface FormatMapper {