Javadoc for SessionFactoryBuilder and lots of crossrefs

This commit is contained in:
Gavin King 2022-01-28 19:46:39 +01:00
parent 77137f7407
commit f388b2fb2b
11 changed files with 259 additions and 95 deletions

View File

@ -19,6 +19,7 @@ import org.hibernate.type.Type;
* The purpose of this contract then is to allow applications such a plug-in point.
*
* @see org.hibernate.cfg.AvailableSettings#CUSTOM_ENTITY_DIRTINESS_STRATEGY
* @see org.hibernate.boot.SessionFactoryBuilder#applyCustomEntityDirtinessStrategy(CustomEntityDirtinessStrategy)
*
* @author Steve Ebersole
*/

View File

@ -9,6 +9,8 @@ package org.hibernate;
/**
* Contract for resolving an entity-name from a given entity instance.
*
* @see org.hibernate.boot.SessionFactoryBuilder#addEntityNameResolver(EntityNameResolver...)
*
* @author Steve Ebersole
*/
public interface EntityNameResolver {

View File

@ -37,6 +37,9 @@ import org.hibernate.type.Type;
* @see SharedSessionBuilder#interceptor()
* @see org.hibernate.cfg.Configuration#setInterceptor(Interceptor)
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyInterceptor(Interceptor)
* @see org.hibernate.boot.SessionFactoryBuilder#applyStatelessInterceptor(Class)
*
* @author Gavin King
*/
public interface Interceptor {

View File

@ -14,6 +14,9 @@ import java.io.Serializable;
* A {@code SessionFactoryObserver} may be registered using the configuration property
* {@value org.hibernate.cfg.AvailableSettings#SESSION_FACTORY_OBSERVER}.
*
* @see org.hibernate.cfg.AvailableSettings#SESSION_FACTORY_OBSERVER
* @see org.hibernate.boot.SessionFactoryBuilder#addSessionFactoryObservers(SessionFactoryObserver...)
*
* @author Steve Ebersole
*/
public interface SessionFactoryObserver extends Serializable {

View File

@ -8,7 +8,6 @@ package org.hibernate.boot;
import java.util.function.Supplier;
import org.hibernate.ConnectionReleaseMode;
import org.hibernate.CustomEntityDirtinessStrategy;
import org.hibernate.EntityNameResolver;
import org.hibernate.Interceptor;
@ -35,31 +34,35 @@ import org.hibernate.resource.jdbc.spi.StatementInspector;
@SuppressWarnings("UnusedReturnValue")
public interface SessionFactoryBuilder {
/**
* Apply a Bean Validation ValidatorFactory to the SessionFactory being built.
* Specifies a Bean Validation {@link jakarta.validation.ValidatorFactory}.
*
* NOTE : De-typed to avoid hard dependency on Bean Validation jar at runtime.
* @apiNote De-typed to avoid a hard dependency on the Bean Validation jar
*
* @param validatorFactory The Bean Validation ValidatorFactory to use
* @param validatorFactory The Bean Validation {@code ValidatorFactory} to use
*
* @return {@code this}, for method chaining
*
* @see org.hibernate.cfg.AvailableSettings#JAKARTA_VALIDATION_FACTORY
*/
SessionFactoryBuilder applyValidatorFactory(Object validatorFactory);
/**
* Apply a CDI BeanManager to the SessionFactory being built.
* Specifies a CDI {@link jakarta.enterprise.inject.spi.BeanManager}.
*
* NOTE : De-typed to avoid hard dependency on CDI jar at runtime.
* @apiNote De-typed to avoid a hard dependency on the CDI jar
*
* @param beanManager The CDI BeanManager to use
* @param beanManager The CDI {@code BeanManager} to use
*
* @return {@code this}, for method chaining
*
* @see org.hibernate.cfg.AvailableSettings#JAKARTA_CDI_BEAN_MANAGER
*/
SessionFactoryBuilder applyBeanManager(Object beanManager);
/**
* Applies a SessionFactory name.
* Specifies a name for the {@link SessionFactory}.
*
* @param sessionFactoryName The name to use for the SessionFactory being built
* @param sessionFactoryName The name to use
*
* @return {@code this}, for method chaining
*
@ -68,7 +71,8 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyName(String sessionFactoryName);
/**
* Applies a SessionFactory name.
* Specifies that the {@link SessionFactory} should be registered in JNDI,
* under the name specified using {@link #applyName(String)}.
*
* @param isJndiName {@code true} indicates that the name specified in
* {@link #applyName} will be used for binding the SessionFactory into JNDI.
@ -80,7 +84,8 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyNameAsJndiName(boolean isJndiName);
/**
* Applies whether Sessions should be automatically closed at the end of the transaction.
* Specifies whether {@link org.hibernate.Session}s should be automatically
* closed at the end of the transaction.
*
* @param enabled {@code true} indicates they should be auto-closed; {@code false} indicates not.
*
@ -91,7 +96,8 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyAutoClosing(boolean enabled);
/**
* Applies whether Sessions should be automatically flushed at the end of the transaction.
* Applies whether {@link org.hibernate.Session}s should be automatically
* flushed at the end of the transaction.
*
* @param enabled {@code true} indicates they should be auto-flushed; {@code false} indicates not.
*
@ -102,7 +108,7 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyAutoFlushing(boolean enabled);
/**
* Applies whether statistics gathering is enabled.
* Specifies whether statistics gathering is enabled.
*
* @param enabled {@code true} indicates that statistics gathering should be enabled; {@code false} indicates not.
*
@ -113,8 +119,9 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyStatisticsSupport(boolean enabled);
/**
* Names an interceptor to be applied to the SessionFactory, which in turn means it will be used by all
* Sessions unless one is explicitly specified in {@link org.hibernate.SessionBuilder#interceptor}
* Specifies an {@link Interceptor} associated with the {@link SessionFactory},
* which will be used by all sessions unless an interceptor is explicitly
* specified using {@link org.hibernate.SessionBuilder#interceptor}.
*
* @param interceptor The interceptor
*
@ -125,8 +132,10 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyInterceptor(Interceptor interceptor);
/**
* Names an interceptor Class to be applied to the SessionFactory, which in turn means it will be used by all
* Sessions unless one is explicitly specified in {@link org.hibernate.SessionBuilder#interceptor}
* Specifies an interceptor {@link Class} associated with the
* {@link SessionFactory}, which is used to instantiate a new interceptor
* for each session, unless an interceptor is explicitly specified using
* {@link org.hibernate.SessionBuilder#interceptor}.
*
* @param statelessInterceptorClass The interceptor class
*
@ -137,9 +146,10 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyStatelessInterceptor(Class<? extends Interceptor> statelessInterceptorClass);
/**
* Names a {@link Supplier} instance which is used to retrieve the interceptor to be applied to the SessionFactory,
* which in turn means it will be used by all Sessions unless one is explicitly specified in
* {@link org.hibernate.SessionBuilder#interceptor}
* Specifies an interceptor {@link Supplier} associated with the
* {@link SessionFactory}, which is used to obtain an interceptor for
* each session, unless an interceptor is explicitly specified using
* {@link org.hibernate.SessionBuilder#interceptor}.
*
* @param statelessInterceptorSupplier {@link Supplier} instance which is used to retrieve the interceptor
*
@ -150,8 +160,10 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyStatelessInterceptor(Supplier<? extends Interceptor> statelessInterceptorSupplier);
/**
* Names a StatementInspector to be applied to the SessionFactory, which in turn means it will be used by all
* Sessions unless one is explicitly specified in {@link org.hibernate.SessionBuilder#statementInspector}
* Specifies a {@link StatementInspector} associated with the
* {@link SessionFactory}, which will be used by all sessions unless a
* statement inspector is explicitly specified using
* {@link org.hibernate.SessionBuilder#statementInspector}
*
* @param statementInspector The StatementInspector
*
@ -162,18 +174,19 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyStatementInspector(StatementInspector statementInspector);
/**
* Specifies one or more observers to be applied to the SessionFactory. Can be called multiple times to add
* additional observers.
* Specifies one or more {@linkplain SessionFactoryObserver observers}.
* May be called multiple times to add additional observers.
*
* @param observers The observers to add
*
* @return {@code this}, for method chaining
*
* @see org.hibernate.cfg.AvailableSettings#SESSION_FACTORY_OBSERVER
*/
SessionFactoryBuilder addSessionFactoryObservers(SessionFactoryObserver... observers);
/**
* Specifies a custom entity dirtiness strategy to be applied to the SessionFactory. See the contract
* of {@link CustomEntityDirtinessStrategy} for details.
* Specifies a {@link CustomEntityDirtinessStrategy}.
*
* @param strategy The custom strategy to be used.
*
@ -184,8 +197,8 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyCustomEntityDirtinessStrategy(CustomEntityDirtinessStrategy strategy);
/**
* Specifies one or more entity name resolvers to be applied to the SessionFactory (see the {@link EntityNameResolver}
* contract for more information.. Can be called multiple times to add additional resolvers..
* Specifies one or more {@linkplain EntityNameResolver entity name resolvers}.
* May be called multiple times to add additional resolvers.
*
* @param entityNameResolvers The entityNameResolvers to add
*
@ -194,8 +207,9 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder addEntityNameResolver(EntityNameResolver... entityNameResolvers);
/**
* Names the {@link EntityNotFoundDelegate} to be applied to the SessionFactory. EntityNotFoundDelegate is a
* strategy that accounts for different exceptions thrown between Hibernate and JPA when an entity cannot be found.
* Specifies an {@link EntityNotFoundDelegate}. An {@code EntityNotFoundDelegate}
* is a strategy that accounts for different exceptions thrown between Hibernate
* and JPA when an entity cannot be found.
*
* @param entityNotFoundDelegate The delegate/strategy to use.
*
@ -215,7 +229,8 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyIdentifierRollbackSupport(boolean enabled);
/**
* Should attributes using columns marked as not-null be checked (by Hibernate) for nullness?
* Should attributes using columns marked as not-null be checked (by Hibernate)
* for nullness, or should this be left as a job for the database?
*
* @param enabled {@code true} indicates that Hibernate should perform nullness checking; {@code false} indicates
* it should not.
@ -227,10 +242,11 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyNullabilityChecking(boolean enabled);
/**
* Should the application be allowed to initialize uninitialized lazy state outside the bounds of a transaction?
* Should the application be allowed to initialize uninitialized lazy state
* outside the bounds of a transaction?
*
* @param enabled {@code true} indicates initialization outside the transaction should be allowed; {@code false}
* indicates it should not.
* @param enabled {@code true} indicates initialization outside the transaction
* should be allowed; {@code false} indicates it should not.
*
* @return {@code this}, for method chaining
*
@ -255,16 +271,16 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyBatchFetchStyle(BatchFetchStyle style);
/**
* Should entity Loaders be generated immediately? Or should the creation
* be delayed until first need?
* Should entity {@linkplain org.hibernate.loader.ast.spi.Loader loaders} be
* generated immediately? Or should the creation be delayed until first need?
*
* @see org.hibernate.cfg.AvailableSettings#DELAY_ENTITY_LOADER_CREATIONS
*/
SessionFactoryBuilder applyDelayedEntityLoaderCreations(boolean delay);
/**
* Allows specifying a default batch-fetch size for all entities and collections
* which do not otherwise specify a batch-fetch size.
* Specifies a default batch fetch size for all entities and collections which
* do not otherwise specify a batch fetch size.
*
* @param size The size to use for batch fetching for entities/collections which
* do not specify an explicit batch fetch size.
@ -276,8 +292,9 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyDefaultBatchFetchSize(int size);
/**
* Apply a limit to the depth Hibernate will use for outer joins. Note that this is different than an
* overall limit on the number of joins...
* Apply a limit to the depth Hibernate will use for outer joins.
* <p>
* Note that this is different to an overall limit on the number of joins.
*
* @param depth The depth for limiting joins.
*
@ -288,8 +305,8 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyMaximumFetchDepth(int depth);
/**
* Apply a null precedence (NULLS FIRST, NULLS LAST) to be applied order-by clauses rendered into
* SQL queries.
* Apply a null precedence (NULLS FIRST, NULLS LAST) to be applied to
* order by clauses rendered in SQL queries.
*
* @param nullPrecedence The default null precedence to use.
*
@ -300,9 +317,11 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyDefaultNullPrecedence(NullPrecedence nullPrecedence);
/**
* Apply whether ordering of inserts should be enabled. This allows more efficient SQL
* generation via the use of batching for the inserts; the cost is that the determination of the
* ordering is far more inefficient than not ordering.
* Specify whether ordering of inserts should be enabled.
* <p>
* This allows more efficient SQL execution via the use of batching
* for the inserts; the cost is that the determination of the ordering
* is far less efficient than not ordering.
*
* @param enabled {@code true} indicates that ordering should be enabled; {@code false} indicates not
*
@ -313,9 +332,11 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyOrderingOfInserts(boolean enabled);
/**
* Apply whether ordering of updates should be enabled. This allows more efficient SQL
* generation via the use of batching for the updates; the cost is that the determination of the
* ordering is far more inefficient than not ordering.
* Specify whether ordering of updates should be enabled.
* <p>
* This allows more efficient SQL execution via the use of batching for
* the updates; the cost is that the determination of the ordering is far
* less efficient than not ordering.
*
* @param enabled {@code true} indicates that ordering should be enabled; {@code false} indicates not
*
@ -326,7 +347,7 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyOrderingOfUpdates(boolean enabled);
/**
* Apply the form of multi-tenancy used by the application
* Specifies whether multi-tenancy is enabled
*
* @param enabled True if multi-tenancy in use.
*
@ -335,8 +356,9 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyMultiTenancy(boolean enabled);
/**
* Specifies a strategy for resolving the notion of a "current" tenant-identifier when using multi-tenancy
* together with current sessions
* Specifies a {@link CurrentTenantIdentifierResolver} that is responsible for
* resolving the current tenant identifier when
* {@link org.hibernate.SessionFactory#getCurrentSession()} is used.
*
* @param resolver The resolution strategy to use.
*
@ -347,8 +369,10 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyCurrentTenantIdentifierResolver(CurrentTenantIdentifierResolver resolver);
/**
* If using the built-in Hibernate JTA-based TransactionCoordinator/Builder, should it track JTA
* transactions by thread in an attempt to detect timeouts?
* If using the built-in JTA-based
* {@link org.hibernate.resource.transaction.spi.TransactionCoordinator} or
* {@link org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder},
* should it track JTA transactions by thread in an attempt to detect timeouts?
*
* @param enabled {@code true} indicates we should track by thread; {@code false} indicates not
*
@ -359,11 +383,15 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyJtaTrackingByThread(boolean enabled);
/**
* If using the built-in Hibernate JTA-based TransactionCoordinator/Builder, should it prefer to use
* {@link jakarta.transaction.UserTransaction} over {@link jakarta.transaction.Transaction}?
* If using the built-in JTA-based
* {@link org.hibernate.resource.transaction.spi.TransactionCoordinator} or
* {@link org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder},
* should it prefer to use {@link jakarta.transaction.UserTransaction} in
* preference to {@link jakarta.transaction.Transaction}?
*
* @param preferUserTransactions {@code true} indicates we should prefer {@link jakarta.transaction.UserTransaction};
* {@code false} indicates we should prefer {@link jakarta.transaction.Transaction}
* @param preferUserTransactions {@code true} indicates we should prefer
* {@link jakarta.transaction.UserTransaction}; {@code false} indicates we
* should prefer {@link jakarta.transaction.Transaction}
*
* @return {@code this}, for method chaining
*
@ -385,8 +413,8 @@ public interface SessionFactoryBuilder {
/**
* Should second level caching support be enabled?
*
* @param enabled {@code true} indicates we should enable the use of second level caching; {@code false}
* indicates we should disable the use of second level caching.
* @param enabled {@code true} indicates we should enable the use of second level caching;
* {@code false} indicates we should disable the use of second level caching.
*
* @return {@code this}, for method chaining
*
@ -407,9 +435,9 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyQueryCacheSupport(boolean enabled);
/**
* Specifies a QueryCacheFactory to use for building query cache handlers.
* Specifies a {@link org.hibernate.cache.spi.TimestampsCacheFactory}.
*
* @param factory The QueryCacheFactory to use
* @param factory The {@link org.hibernate.cache.spi.TimestampsCacheFactory} to use
*
* @return {@code this}, for method chaining
*
@ -418,7 +446,7 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applyTimestampsCacheFactory(TimestampsCacheFactory factory);
/**
* Apply a prefix to prepended to all cache region names for this SessionFactory.
* Specify a prefix to prepended to all cache region names.
*
* @param prefix The prefix.
*
@ -557,21 +585,24 @@ public interface SessionFactoryBuilder {
*
* @return {@code this}, for method chaining
*
* @see org.hibernate.cfg.AvailableSettings#USE_GET_GENERATED_KEYS
* @see org.hibernate.cfg.AvailableSettings#STATEMENT_FETCH_SIZE
* @see java.sql.Statement#setFetchSize(int)
*/
SessionFactoryBuilder applyJdbcFetchSize(int size);
/**
* Apply the specified handling mode for JDBC connections
* Specifies the {@linkplain PhysicalConnectionHandlingMode connection handling mode}
* for JDBC connections.
*
* @param connectionHandlingMode The handling mode to apply
*
* @return {@code this}, for method chaining
*
* @see org.hibernate.cfg.AvailableSettings#CONNECTION_HANDLING
* @see PhysicalConnectionHandlingMode
*
* @see org.hibernate.ConnectionAcquisitionMode
* @see ConnectionReleaseMode
* @see org.hibernate.ConnectionReleaseMode
*/
SessionFactoryBuilder applyConnectionHandlingMode(PhysicalConnectionHandlingMode connectionHandlingMode);
@ -592,10 +623,11 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applySqlComments(boolean enabled);
/**
* Apply a SQLFunction to the underlying {@link org.hibernate.query.sqm.function.SqmFunctionRegistry}.
* Register a {@link SqmFunctionDescriptor SQL function} with the underlying
* {@link org.hibernate.query.sqm.function.SqmFunctionRegistry}.
*
* @param registrationName The name to register it under.
* @param functionDescriptor The SQLFunction impl
* @param registrationName The function name to register it under
* @param functionDescriptor The {@link SqmFunctionDescriptor}
*
* @return {@code this}, for method chaining
*/
@ -604,7 +636,8 @@ public interface SessionFactoryBuilder {
SessionFactoryBuilder applySqlFunction(String registrationName, SqmFunctionDescriptor functionDescriptor);
/**
* Should collections be included in the default fetch group when bytecode enhancement is used?
* Should collections be included in the default fetch group when bytecode
* enhancement is used?
*
* @param enabled {@code true} collections should be included
*
@ -612,35 +645,46 @@ public interface SessionFactoryBuilder {
*/
SessionFactoryBuilder applyCollectionsInDefaultFetchGroup(boolean enabled);
/**
* @see org.hibernate.cfg.AvailableSettings#ALLOW_UPDATE_OUTSIDE_TRANSACTION
*/
SessionFactoryBuilder allowOutOfTransactionUpdateOperations(boolean allow);
/**
* Should resources held by {@link jakarta.persistence.EntityManager} instance be released immediately on close?
* Should resources held by an {@link jakarta.persistence.EntityManager} be
* released immediately on close?
* <p/>
* The other option is to release them as part of an after-transaction callback.
*
* The other option is to release them as part of an after transaction callback.
*/
SessionFactoryBuilder enableReleaseResourcesOnCloseEnabled(boolean enable);
/**
* @see JpaCompliance#isJpaQueryComplianceEnabled()
*
* @see org.hibernate.cfg.AvailableSettings#JPA_QUERY_COMPLIANCE
*/
SessionFactoryBuilder enableJpaQueryCompliance(boolean enabled);
/**
* @see JpaCompliance#isJpaQueryComplianceEnabled()
*
* @see org.hibernate.cfg.AvailableSettings#JPA_ORDER_BY_MAPPING_COMPLIANCE
*/
SessionFactoryBuilder enableJpaOrderByMappingCompliance(boolean enabled);
/**
* @see JpaCompliance#isJpaTransactionComplianceEnabled()
*
* @see org.hibernate.cfg.AvailableSettings#JPA_TRANSACTION_COMPLIANCE
*/
SessionFactoryBuilder enableJpaTransactionCompliance(boolean enabled);
/**
* @see JpaCompliance#isJpaListComplianceEnabled()
*
* @see org.hibernate.cfg.AvailableSettings#JPA_LIST_COMPLIANCE
*
* @deprecated Use {@link org.hibernate.cfg.AvailableSettings#DEFAULT_LIST_SEMANTICS} instead
*/
@Deprecated( since = "6.0" )
@ -648,6 +692,8 @@ public interface SessionFactoryBuilder {
/**
* @see JpaCompliance#isJpaClosedComplianceEnabled()
*
* @see org.hibernate.cfg.AvailableSettings#JPA_CLOSED_COMPLIANCE
*/
SessionFactoryBuilder enableJpaClosedCompliance(boolean enabled);

View File

@ -18,6 +18,7 @@ import org.hibernate.boot.cfgxml.internal.ConfigLoader;
import org.hibernate.boot.cfgxml.spi.LoadedConfig;
import org.hibernate.boot.registry.classloading.spi.ClassLoaderService;
import org.hibernate.boot.registry.internal.StandardServiceRegistryImpl;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.cfg.Environment;
import org.hibernate.integrator.spi.Integrator;
import org.hibernate.integrator.spi.IntegratorService;
@ -33,6 +34,8 @@ import static org.hibernate.boot.cfgxml.spi.CfgXmlAccessService.LOADED_CONFIG_KE
/**
* Builder for standard {@link ServiceRegistry} instances.
* <p>
* Configuration properties are enumerated by {@link AvailableSettings}.
*
* @author Steve Ebersole
*

View File

@ -8,12 +8,28 @@ package org.hibernate.cfg;
import java.util.function.Supplier;
import org.hibernate.CustomEntityDirtinessStrategy;
import org.hibernate.Interceptor;
import org.hibernate.SessionFactoryObserver;
import org.hibernate.cache.spi.TimestampsCacheFactory;
import org.hibernate.context.spi.CurrentTenantIdentifierResolver;
import org.hibernate.jpa.LegacySpecHints;
import org.hibernate.query.spi.QueryPlan;
import org.hibernate.query.sqm.NullPrecedence;
import org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode;
import org.hibernate.resource.jdbc.spi.StatementInspector;
/**
* Enumerates the configuration properties supported by Hibernate, including
* properties defined by the JPA specification.
* <p>
* The settings defined here may be specified at configuration time:
* <ul>
* <li>in a configuration file, for example, in {@code persistence.xml} or
* {@code hibernate.cfg.xml},
* <li>via {@link Configuration#setProperty(String, String)}, or
* <li>via {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder#applySetting(String, Object)}.
* </ul>
*
* @author Steve Ebersole
*/
@ -130,6 +146,8 @@ public interface AvailableSettings {
/**
* Used to pass along any discovered {@link jakarta.validation.ValidatorFactory}.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyValidatorFactory(Object)
*/
String JAKARTA_VALIDATION_FACTORY = "jakarta.persistence.validation.factory";
@ -194,6 +212,8 @@ public interface AvailableSettings {
* This setting is used to configure access to the {@code BeanManager},
* either directly, or via
* {@link org.hibernate.resource.beans.container.spi.ExtendedBeanManager}.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyBeanManager(Object)
*/
String JAKARTA_CDI_BEAN_MANAGER = "jakarta.persistence.bean.manager";
@ -345,6 +365,8 @@ public interface AvailableSettings {
* By default, Hibernate calls {@link java.sql.Connection#setAutoCommit(boolean)} on
* newly-obtained connections.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyConnectionProviderDisablesAutoCommit(boolean)
*
* @since 5.2.10
*/
String CONNECTION_PROVIDER_DISABLES_AUTOCOMMIT= "hibernate.connection.provider_disables_autocommit";
@ -520,6 +542,8 @@ public interface AvailableSettings {
* @see org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform#retrieveUserTransaction
* @see org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform#retrieveTransactionManager
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyPreferUserTransactions(boolean)
*
* @since 5.0
*/
String PREFER_USER_TRANSACTION = "hibernate.jta.prefer_user_transaction";
@ -819,6 +843,7 @@ public interface AvailableSettings {
*
* @see #SESSION_FACTORY_NAME_IS_JNDI
* @see org.hibernate.internal.SessionFactoryRegistry
* @see org.hibernate.boot.SessionFactoryBuilder#applyName(String)
*/
String SESSION_FACTORY_NAME = "hibernate.session_factory_name";
@ -833,6 +858,7 @@ public interface AvailableSettings {
* not want JNDI to be used.
*
* @see #SESSION_FACTORY_NAME
* @see org.hibernate.boot.SessionFactoryBuilder#applyNameAsJndiName(boolean)
*/
String SESSION_FACTORY_NAME_IS_JNDI = "hibernate.session_factory_name_is_jndi";
@ -853,11 +879,15 @@ public interface AvailableSettings {
/**
* Specifies that comments should be added to the generated SQL.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applySqlComments(boolean)
*/
String USE_SQL_COMMENTS = "hibernate.use_sql_comments";
/**
* Specifies the maximum depth of nested outer join fetching.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyMaximumFetchDepth(int)
*/
String MAX_FETCH_DEPTH = "hibernate.max_fetch_depth";
@ -865,6 +895,7 @@ public interface AvailableSettings {
* Specifies the default batch size for batch fetching.
*
* @see org.hibernate.annotations.BatchSize
* @see org.hibernate.boot.SessionFactoryBuilder#applyDefaultBatchFetchSize(int)
*/
String DEFAULT_BATCH_FETCH_SIZE = "hibernate.default_batch_fetch_size";
@ -872,6 +903,8 @@ public interface AvailableSettings {
* When enabled, specifies that JDBC scrollable {@code ResultSet}s may be used.
* This property is only necessary when there is no {@code ConnectionProvider},
* that is, when the client is supplying JDBC connections.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyScrollableResultsSupport(boolean)
*/
String USE_SCROLLABLE_RESULTSET = "hibernate.jdbc.use_scrollable_resultset";
@ -883,6 +916,7 @@ public interface AvailableSettings {
* the JDBC driver supports {@code getGeneratedKeys()}.
*
* @see java.sql.PreparedStatement#getGeneratedKeys
* @see org.hibernate.boot.SessionFactoryBuilder#applyGetGeneratedKeysSupport(boolean)
*/
String USE_GET_GENERATED_KEYS = "hibernate.jdbc.use_get_generated_keys";
@ -892,6 +926,7 @@ public interface AvailableSettings {
* default settings will be used.
*
* @see java.sql.ResultSet#setFetchSize(int)
* @see org.hibernate.boot.SessionFactoryBuilder#applyJdbcFetchSize(int)
*/
String STATEMENT_FETCH_SIZE = "hibernate.jdbc.fetch_size";
@ -899,6 +934,7 @@ public interface AvailableSettings {
* Specifies the maximum JDBC batch size. A nonzero value enables batch updates.
*
* @see java.sql.PreparedStatement#executeBatch()
* @see org.hibernate.boot.SessionFactoryBuilder#applyJdbcBatchSize(int)
*/
String STATEMENT_BATCH_SIZE = "hibernate.jdbc.batch_size";
@ -910,6 +946,8 @@ public interface AvailableSettings {
/**
* When enabled, specifies that {@link jakarta.persistence.Version versioned}
* data should be included in batching.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyJdbcBatchingForVersionedEntities(boolean)
*/
String BATCH_VERSIONED_DATA = "hibernate.jdbc.batch_versioned_data";
@ -929,12 +967,16 @@ public interface AvailableSettings {
/**
* When enabled, specifies that the {@link org.hibernate.Session} should be
* closed automatically at the end of each transaction.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyAutoClosing(boolean)
*/
String AUTO_CLOSE_SESSION = "hibernate.transaction.auto_close_session";
/**
* When enabled, specifies that automatic flushing should occur during the JTA
* {@link jakarta.transaction.Synchronization#beforeCompletion()} callback.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyAutoFlushing(boolean)
*/
String FLUSH_BEFORE_COMPLETION = "hibernate.transaction.flush_before_completion";
@ -943,6 +985,7 @@ public interface AvailableSettings {
* and release.
*
* @see org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode
* @see org.hibernate.boot.SessionFactoryBuilder#applyConnectionHandlingMode(PhysicalConnectionHandlingMode)
*
* @since 5.2
*/
@ -955,6 +998,9 @@ public interface AvailableSettings {
*/
String CURRENT_SESSION_CONTEXT_CLASS = "hibernate.current_session_context_class";
/**
* @see org.hibernate.boot.SessionFactoryBuilder#applyIdentifierRollbackSupport(boolean)
*/
String USE_IDENTIFIER_ROLLBACK = "hibernate.use_identifier_rollback";
/**
@ -1005,16 +1051,22 @@ public interface AvailableSettings {
* By default, named queries are checked at startup.
* <p>
* Mainly intended for use in test environments.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyNamedQueryCheckingOnStartup(boolean)
*/
String QUERY_STARTUP_CHECKING = "hibernate.query.startup_check";
/**
* Enable ordering of update statements by primary key value.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyOrderingOfUpdates(boolean)
*/
String ORDER_UPDATES = "hibernate.order_updates";
/**
* Enable ordering of insert statements for the purpose of more efficient JDBC batching.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyOrderingOfInserts(boolean)
*/
String ORDER_INSERTS = "hibernate.order_inserts";
@ -1034,6 +1086,8 @@ public interface AvailableSettings {
* Default precedence of null values in {@code ORDER BY} clause.
* <p>
* Supported options: {@code none} (default), {@code first}, {@code last}.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyDefaultNullPrecedence(NullPrecedence)
*/
String DEFAULT_NULL_ORDERING = "hibernate.order_by.default_null_ordering";
@ -1198,32 +1252,44 @@ public interface AvailableSettings {
* By default, if the configured {@link org.hibernate.cache.spi.RegionFactory}
* is not the {@link org.hibernate.cache.internal.NoCachingRegionFactory}, then
* the second-level cache is enabled. Otherwise, the second-level cache is disabled.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applySecondLevelCacheSupport(boolean)
*/
String USE_SECOND_LEVEL_CACHE = "hibernate.cache.use_second_level_cache";
/**
* Enable the query cache (disabled by default).
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyQueryCacheSupport(boolean)
*/
String USE_QUERY_CACHE = "hibernate.cache.use_query_cache";
/**
* Specifies the {@link org.hibernate.cache.spi.TimestampsCacheFactory} to use.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyTimestampsCacheFactory(TimestampsCacheFactory)
*/
String QUERY_CACHE_FACTORY = "hibernate.cache.query_cache_factory";
/**
* The {@code CacheProvider} region name prefix
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyCacheRegionPrefix(String)
*/
String CACHE_REGION_PREFIX = "hibernate.cache.region_prefix";
/**
* Optimize interaction with the second-level cache to minimize writes, at the cost
* of more frequent database reads.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyMinimalPutsForCaching(boolean)
*/
String USE_MINIMAL_PUTS = "hibernate.cache.use_minimal_puts";
/**
* Enables the use of structured second-level cache entries.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyStructuredCacheEntries(boolean)
*/
String USE_STRUCTURED_CACHE = "hibernate.cache.use_structured_entries";
@ -1232,6 +1298,8 @@ public interface AvailableSettings {
* cache when an element in the {@link jakarta.persistence.ManyToOne} collection
* is added, updated, or removed without properly managing the change on the
* {@link jakarta.persistence.OneToMany} side.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyAutomaticEvictionOfCollectionCaches(boolean)
*/
String AUTO_EVICT_COLLECTION_CACHE = "hibernate.cache.auto_evict_collection_cache";
@ -1240,6 +1308,8 @@ public interface AvailableSettings {
* applicable. This is appropriate only for immutable entities.
* <p>
* By default, entities are always stored in a "disassembled" form.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyDirectReferenceCaching(boolean)
*/
String USE_DIRECT_REFERENCE_CACHE_ENTRIES = "hibernate.cache.use_reference_entries";
@ -1273,6 +1343,8 @@ public interface AvailableSettings {
* <p>
* Defaults to disabled if Bean Validation is present in the classpath and
* annotations are used, or enabled otherwise.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyNullabilityChecking(boolean)
*/
String CHECK_NULLABILITY = "hibernate.check_nullability";
@ -1772,6 +1844,8 @@ public interface AvailableSettings {
/**
* Setting to identify a {@link org.hibernate.CustomEntityDirtinessStrategy} to use.
* May specify either a class name or an instance.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyCustomEntityDirtinessStrategy(CustomEntityDirtinessStrategy)
*/
String CUSTOM_ENTITY_DIRTINESS_STRATEGY = "hibernate.entity_dirtiness_strategy";
@ -1813,6 +1887,8 @@ public interface AvailableSettings {
* <li>the name of a class that implements {@code CurrentTenantIdentifierResolver}.
* </ul>
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyCurrentTenantIdentifierResolver(CurrentTenantIdentifierResolver)
*
* @since 4.1
*/
String MULTI_TENANT_IDENTIFIER_RESOLVER = "hibernate.tenant_identifier_resolver";
@ -1831,6 +1907,8 @@ public interface AvailableSettings {
* 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.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyInterceptor(Interceptor)
*
* @since 5.0
*/
@ -1851,6 +1929,9 @@ public interface AvailableSettings {
* applied to every {@code Session} opened from the {@code SessionFactory}, but
* unlike {@link #INTERCEPTOR}, a separate instance created for each {@code Session}.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyStatelessInterceptor(Class)
* @see org.hibernate.boot.SessionFactoryBuilder#applyStatelessInterceptor(Supplier)
*
* @since 5.2
*/
String SESSION_SCOPED_INTERCEPTOR = "hibernate.session_factory.session_scoped_interceptor";
@ -1865,10 +1946,15 @@ public interface AvailableSettings {
* <li>the name of a class that implements {@code StatementInspector}.
* </ul>
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyStatementInspector(StatementInspector)
*
* @since 5.0
*/
String STATEMENT_INSPECTOR = "hibernate.session_factory.statement_inspector";
/**
* @see org.hibernate.boot.SessionFactoryBuilder#applyLazyInitializationOutsideTransaction(boolean)
*/
String ENABLE_LAZY_LOAD_NO_TRANS = "hibernate.enable_lazy_load_no_trans";
/**
@ -1898,6 +1984,8 @@ public interface AvailableSettings {
* this will consume more memory but ensures all necessary memory is
* allocated right away.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyDelayedEntityLoaderCreations(boolean)
*
* @since 5.3
*/
String DELAY_ENTITY_LOADER_CREATIONS = "hibernate.loader.delay_entity_loader_creations";
@ -1910,6 +1998,8 @@ public interface AvailableSettings {
* Session is called. This can certainly have performance considerations.
*
* Default is {@code true} (enabled).
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyJtaTrackingByThread(boolean)
*/
String JTA_TRACK_BY_THREAD = "hibernate.jta.track_by_thread";
@ -1956,6 +2046,8 @@ public interface AvailableSettings {
/**
* When enabled, specifies that {@linkplain org.hibernate.stat.Statistics statistics}
* should be collected.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyStatisticsSupport(boolean)
*/
String GENERATE_STATISTICS = "hibernate.generate_statistics";
@ -2019,6 +2111,8 @@ public interface AvailableSettings {
* <p>
* The default behavior is to disallow update operations outside a transaction.
*
* @see org.hibernate.boot.SessionFactoryBuilder#allowOutOfTransactionUpdateOperations(boolean)
*
* @since 5.2
*/
String ALLOW_UPDATE_OUTSIDE_TRANSACTION = "hibernate.allow_update_outside_transaction";
@ -2110,6 +2204,7 @@ public interface AvailableSettings {
* an {@link jakarta.persistence.EntityTransaction}.
*
* @see org.hibernate.jpa.spi.JpaCompliance#isJpaTransactionComplianceEnabled()
* @see org.hibernate.boot.SessionFactoryBuilder#enableJpaTransactionCompliance(boolean)
*
* @since 5.3
*/
@ -2129,28 +2224,32 @@ public interface AvailableSettings {
* useful features of HQL.
*
* @see org.hibernate.jpa.spi.JpaCompliance#isJpaQueryComplianceEnabled()
* @see org.hibernate.boot.SessionFactoryBuilder#enableJpaQueryCompliance(boolean)
*
* @since 5.3
*/
String JPA_QUERY_COMPLIANCE = "hibernate.jpa.compliance.query";
/**
* 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.
* Controls whether Hibernate should treat what it would usually consider a
* {@linkplain org.hibernate.collection.spi.PersistentBag "bag"}, that is, a
* list with no index column, whose element order is not persistent, as a true
* {@link org.hibernate.collection.spi.PersistentList list} with an index column
* and a persistent element order.
* <p>
* If enabled, Hibernate will recognize it as a list where the
* {@link jakarta.persistence.OrderColumn} annotation is simply missing
* (and its defaults will apply).
*
* @see org.hibernate.jpa.spi.JpaCompliance#isJpaListComplianceEnabled()
* @see org.hibernate.boot.SessionFactoryBuilder#enableJpaListCompliance(boolean)
*
* @since 5.3
*
* @deprecated Use {@link org.hibernate.cfg.AvailableSettings#DEFAULT_LIST_SEMANTICS} instead.
* The specification is actually undefined in terms of how this should be handled. It actually
* says that portable applications should not rely on a specific behavior in terms of a List
* with no `@OrderColumn`
* @deprecated Use {@link #DEFAULT_LIST_SEMANTICS} instead. The specification
* actually leaves this behavior undefined, saying that portable applications
* should not rely on any specific behavior for a {@link java.util.List} with
* no {@code @OrderColumn}.
*/
@Deprecated( since = "6.0" )
String JPA_LIST_COMPLIANCE = "hibernate.jpa.compliance.list";
@ -2164,6 +2263,7 @@ public interface AvailableSettings {
* references.
*
* @see org.hibernate.jpa.spi.JpaCompliance#isJpaOrderByMappingComplianceEnabled()
* @see org.hibernate.boot.SessionFactoryBuilder#enableJpaOrderByMappingCompliance(boolean)
*
* @since 6.0
*/
@ -2180,6 +2280,7 @@ public interface AvailableSettings {
* {@code close()} is called on an instance that was already closed.
*
* @see org.hibernate.jpa.spi.JpaCompliance#isJpaClosedComplianceEnabled()
* @see org.hibernate.boot.SessionFactoryBuilder#enableJpaClosedCompliance(boolean)
*
* @since 5.3
*/
@ -2386,10 +2487,8 @@ public interface AvailableSettings {
* Specifies the default strategy for storage of the timezone information
* for zoned datetime types:
* <ul>
* <li>{@link org.hibernate.annotations.TimeZoneStorageType#NORMALIZE},
* <li>{@link org.hibernate.annotations.TimeZoneStorageType#COLUMN},
* <li>{@link org.hibernate.annotations.TimeZoneStorageType#NATIVE}, or
* <li>{@link org.hibernate.annotations.TimeZoneStorageType#AUTO}.
* <li>{@link org.hibernate.annotations.TimeZoneStorageType#NORMALIZE}, or
* <li>{@link org.hibernate.annotations.TimeZoneStorageType#NATIVE}.
* </ul>
* The default is {@link org.hibernate.annotations.TimeZoneStorageType#NORMALIZE},
* meaning that timezone information is not stored by default, but timestamps are
@ -2708,6 +2807,8 @@ public interface AvailableSettings {
/**
* Specifies a class which implements {@link org.hibernate.SessionFactoryObserver} and has
* a constructor with no parameters.
*
* @see org.hibernate.boot.SessionFactoryBuilder#addSessionFactoryObservers(SessionFactoryObserver...)
*/
String SESSION_FACTORY_OBSERVER = "hibernate.session_factory_observer";

View File

@ -7,9 +7,9 @@
package org.hibernate.context.spi;
/**
* A callback registered with the {@link org.hibernate.SessionFactory} that is responsible for resolving the
* current tenant identifier for use with {@link CurrentSessionContext} and
* {@link org.hibernate.SessionFactory#getCurrentSession()}
* A callback registered with the {@link org.hibernate.SessionFactory} that is responsible
* for resolving the current tenant identifier for use with {@link CurrentSessionContext}
* and {@link org.hibernate.SessionFactory#getCurrentSession()}.
*
* @author Steve Ebersole
*/

View File

@ -7,7 +7,6 @@
package org.hibernate.jpa.spi;
import org.hibernate.Transaction;
import org.hibernate.cfg.AvailableSettings;
/**
* Encapsulates settings controlling whether Hibernate complies strictly
@ -44,14 +43,16 @@ public interface JpaCompliance {
boolean isJpaTransactionComplianceEnabled();
/**
* Controls how Hibernate interprets a mapped List without an
* "order column" specified. Historically Hibernate defines this as
* a "bag", which is a concept JPA does not have.
* <p>
* If enabled, Hibernate will recognize this condition as defining
* a {@link org.hibernate.collection.spi.PersistentList}, otherwise
* Hibernate will treat is as a
* {@link org.hibernate.collection.spi.PersistentBag}
* Controls how Hibernate interprets a mapped {@link java.util.List}
* without no {@linkplain jakarta.persistence.OrderColumn order column}
* specified. Historically Hibernate treats this as a "bag", which is a
* concept JPA does not have.
* <ul>
* <li>If enabled, Hibernate will recognize this case as a
* {@linkplain org.hibernate.collection.spi.PersistentList list}.
* <li>Otherwise, if disabled, Hibernate will treat it as a
* {@linkplain org.hibernate.collection.spi.PersistentBag "bag"}.
* </ul>
*
* @return {@code true} indicates to behave in the spec-defined way,
* interpreting the mapping as a "list", rather than a "bag"

View File

@ -9,6 +9,8 @@ package org.hibernate.proxy;
/**
* Delegate to handle the scenario of an entity not found by a specified id.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyEntityNotFoundDelegate(EntityNotFoundDelegate)
*
* @author Steve Ebersole
*/
public interface EntityNotFoundDelegate {

View File

@ -14,6 +14,8 @@ import java.io.Serializable;
* An implementation may be specified via the configuration property
* {@value org.hibernate.cfg.AvailableSettings#STATEMENT_INSPECTOR}.
*
* @see org.hibernate.boot.SessionFactoryBuilder#applyStatementInspector(StatementInspector)
*
* @author Steve Ebersole
*/
public interface StatementInspector extends Serializable {