javadoc improvements to Sessionfactory, Filter, FilterDefinition

hibernate-core/src/main/java/org/hibernate/Filter.java

@@ -5,13 +5,23 @@
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
 package org.hibernate;
+
 import java.util.Collection;
 
 import org.hibernate.engine.spi.FilterDefinition;
 
 /**
- * Type definition of Filter.  Filter defines the user's view into enabled dynamic filters,
+ * Allows control over an enabled filter at runtime. In particular, allows
- * allowing them to set filter parameter values.
+ * {@linkplain #setParameter(String, Object) arguments} to be assigned to
+ * parameters declared by the filter.
+ * <p>
+ * A filter may be defined using {@link org.hibernate.annotations.FilterDef}
+ * and {@link org.hibernate.annotations.Filter}, and must be explicitly
+ * enabled at runtime by calling {@link Session#enableFilter(String)}.
+ *
+ * @see org.hibernate.annotations.FilterDef
+ * @see Session#enableFilter(String)
+ * @see FilterDefinition
  *
  * @author Steve Ebersole
  */
@@ -25,8 +35,8 @@ public interface Filter {
 	String getName();
 
 	/**
-	 * Get the filter definition containing additional information about the
+	 * Get the associated {@link FilterDefinition definition} of
-	 * filter (such as default-condition and expected parameter names/types).
+	 * this named filter.
 	 *
 	 * @return The filter definition
 	 */
@@ -63,8 +73,8 @@ public interface Filter {
 	Filter setParameterList(String name, Object[] values);
 
 	/**
-	 * Perform validation of the filter state.  This is used to verify the
+	 * Perform validation of the filter state.  This is used to verify
-	 * state of the filter after its enablement and before its use.
+	 * the state of the filter after its enablement and before its use.
 	 *
 	 * @throws HibernateException If the state is not currently valid.
 	 */

hibernate-core/src/main/java/org/hibernate/SessionBuilder.java

@@ -13,7 +13,7 @@ import org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode;
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
 /**
- * Represents a consolidation of all session creation options into a builder style delegate.
+ * Allows creation of a new {@link Session} with specific options.
  * 
  * @author Steve Ebersole
  */
@@ -37,18 +37,18 @@ public interface SessionBuilder<T extends SessionBuilder> {
 	/**
 	 * Signifies that no {@link Interceptor} should be used.
 	 * <p/>
-	 * By default the {@link Interceptor} associated with the {@link SessionFactory} is passed to the
+	 * By default, if no {@code Interceptor} is explicitly specified, the
-	 * {@link Session} whenever we open one without the user having specified a specific interceptor to
+	 * {@code Interceptor} associated with the {@link SessionFactory} is
-	 * use.
+	 * inherited by the new {@link Session}.
 	 * <p/>
-	 * Calling {@link #interceptor(Interceptor)} with null has the same net effect.
+	 * Calling {@link #interceptor(Interceptor)} with null has the same effect.
 	 *
 	 * @return {@code this}, for method chaining
 	 */
 	T noInterceptor();
 
 	/**
-	 * Applies a specific StatementInspector to the session options.
+	 * Applies the given {@link StatementInspector} to the session.
 	 *
 	 * @param statementInspector The StatementInspector to use.
 	 *
@@ -66,7 +66,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
 	T connection(Connection connection);
 
 	/**
-	 * Signifies that the connection release mode from the original session should be used to create the new session.
+	 * Signifies that the connection release mode from the original session
+	 * should be used to create the new session.
 	 *
 	 * @param mode The connection handling mode to use.
 	 *
@@ -116,7 +117,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
 	T tenantIdentifier(String tenantIdentifier);
 
 	/**
-	 * Apply one or more SessionEventListener instances to the listeners for the Session to be built.
+	 * Add one or more {@link SessionEventListener} instances to the list of
+	 * listeners for the new session to be built.
 	 *
 	 * @param listeners The listeners to incorporate into the built Session
 	 *
@@ -125,8 +127,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
 	T eventListeners(SessionEventListener... listeners);
 
 	/**
-	 * Remove all listeners intended for the built Session currently held here, including any auto-apply ones; in other
+	 * Remove all listeners intended for the built session currently held here,
-	 * words, start with a clean slate.
+	 * including any auto-apply ones; in other words, start with a clean slate.
 	 *
 	 * {@code this}, for method chaining
 	 */
@@ -143,8 +145,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
 	 *
 	 * @see jakarta.persistence.PersistenceContextType
 	 *
-	 * @deprecated Only integrations can specify autoClosing behavior of individual sessions.  See
+	 * @deprecated Only integrations can specify autoClosing behavior of
-	 * {@link org.hibernate.engine.spi.SessionOwner}
+	 * individual sessions. See {@link org.hibernate.engine.spi.SessionOwner}.
 	 */
 	@Deprecated
 	T autoClose(boolean autoClose);
@@ -162,7 +164,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
 	T connectionReleaseMode(ConnectionReleaseMode connectionReleaseMode);
 
 	/**
-	 * Should the session be automatically flushed during the "before completion" phase of transaction handling.
+	 * Should the session be automatically flushed during the "before completion"
+	 * phase of transaction handling.
 	 *
 	 * @param flushBeforeCompletion Should the session be automatically flushed
 	 *

hibernate-core/src/main/java/org/hibernate/SessionFactory.java

@@ -68,7 +68,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	SessionFactoryOptions getSessionFactoryOptions();
 
 	/**
-	 * Obtain a {@link Session} builder.
+	 * Obtain a {@linkplain SessionBuilder session builder} for creating
+	 * new {@link Session}s with certain customized options.
 	 *
 	 * @return The session builder
 	 */
@@ -77,9 +78,9 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	/**
 	 * Open a {@link Session}.
 	 * <p/>
-	 * JDBC {@link Connection connection(s} will be obtained from the
+	 * Any JDBC {@link Connection connection} will be obtained lazily from the
-	 * configured {@link org.hibernate.engine.jdbc.connections.spi.ConnectionProvider} as needed
+	 * {@link org.hibernate.engine.jdbc.connections.spi.ConnectionProvider}
-	 * to perform requested work.
+	 * as needed to perform requested work.
 	 *
 	 * @return The created session.
 	 *
@@ -88,14 +89,21 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	Session openSession() throws HibernateException;
 
 	/**
-	 * Obtains the current session.  The definition of what exactly "current"
+	 * Obtains the <em>current session</em>, an instance of {@link Session}
-	 * means controlled by the {@link org.hibernate.context.spi.CurrentSessionContext} impl configured
+	 * implicitly associated with some context. For example, the session
-	 * for use.
+	 * might be associated with the current thread, or with the current
-	 * <p/>
+	 * JTA transaction.
-	 * Note that for backwards compatibility, if a {@link org.hibernate.context.spi.CurrentSessionContext}
+	 * <p>
-	 * is not configured but JTA is configured this will default to the
+	 * The context used for scoping the current session (that is, the
-	 * {@link org.hibernate.context.internal.JTASessionContext}
+	 * definition of what precisely "current" means here) is determined
-	 * impl.
+	 * by an implementation of
+	 * {@link org.hibernate.context.spi.CurrentSessionContext}. An
+	 * implementation may be selected using the configuration property
+	 * {@value org.hibernate.cfg.AvailableSettings#CURRENT_SESSION_CONTEXT_CLASS}.
+	 * <p>
+	 * If no {@link org.hibernate.context.spi.CurrentSessionContext} is
+	 * explicitly configured, but JTA is configured, then
+	 * {@link org.hibernate.context.internal.JTASessionContext} is used.
 	 *
 	 * @return The current session.
 	 *
@@ -137,7 +145,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	}
 
 	/**
-	 * Open a Session and perform a action using it within the bounds of a transaction
+	 * Open a {@link Session} and perform an action using the session
+	 * within the bounds of a transaction.
 	 */
 	default void inTransaction(Consumer<Session> action) {
 		inSession(
@@ -148,7 +157,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 						action.accept( session );
 
 						if ( !txn.isActive() ) {
-							throw new TransactionManagementException( "Execution of action caused managed transaction to be completed" );
+							throw new TransactionManagementException(
+									"Execution of action caused managed transaction to be completed" );
 						}
 					}
 					catch (RuntimeException e) {
@@ -180,7 +190,7 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	}
 
 	/**
-	 * Open a Session and perform a action using it
+	 * Open a Session and perform an action using it.
 	 */
 	default <R> R fromSession(Function<Session,R> action) {
 		try (Session session = openSession()) {
@@ -189,7 +199,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	}
 
 	/**
-	 * Open a Session and perform a action using it within the bounds of a transaction
+	 * Open a {@link Session} and perform an action using the session
+	 * within the bounds of a transaction.
 	 */
 	default <R> R fromTransaction(Function<Session,R> action) {
 		return fromSession(
@@ -199,7 +210,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 						R result = action.apply( session );
 
 						if ( !txn.isActive() ) {
-							throw new TransactionManagementException( "Execution of action caused managed transaction to be completed" );
+							throw new TransactionManagementException(
+									"Execution of action caused managed transaction to be completed" );
 						}
 
 						// action completed with no errors - attempt to commit the transaction allowing
@@ -227,19 +239,19 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	}
 
 	/**
-	 * Retrieve the statistics for this factory.
+	 * Retrieve the {@linkplain Statistics statistics} for this factory.
 	 *
 	 * @return The statistics.
 	 */
 	Statistics getStatistics();
 
 	/**
-	 * Destroy this {@code SessionFactory} and release all resources (caches,
+	 * Destroy this {@code SessionFactory} and release all its resources,
-	 * connection pools, etc).
+	 * including caches and connection pools.
 	 * <p/>
-	 * It is the responsibility of the application to ensure that there are no
+	 * It is the responsibility of the application to ensure that there are
-	 * open {@linkplain Session sessions} before calling this method as the impact
+	 * no open {@linkplain Session sessions} before calling this method as
-	 * on those {@linkplain Session sessions} is indeterminate.
+	 * the impact on those {@linkplain Session sessions} is indeterminate.
 	 * <p/>
 	 * No-ops if already {@linkplain #isClosed() closed}.
 	 *
@@ -263,14 +275,14 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	Cache getCache();
 
 	/**
-	 * Get all EntityGraphs registered for a particular entity type
+	 * Return all {@link EntityGraph}s registered for the given entity type.
 	 * 
 	 * @see #addNamedEntityGraph 
 	 */
 	<T> List<EntityGraph<? super T>> findEntityGraphsByType(Class<T> entityClass);
 
 	/**
-	 * Obtain a set of the names of all filters defined on this SessionFactory.
+	 * Obtain the set of names of all {@link FilterDefinition defined filters}.
 	 *
 	 * @return The set of filter names.
 	 */

hibernate-core/src/main/java/org/hibernate/engine/spi/FilterDefinition.java

@@ -14,8 +14,14 @@ import java.util.Set;
 import org.hibernate.type.Type;
 
 /**
- * A FilterDefinition defines the global attributes of a dynamic filter.  This
+ * Represents the definition of a {@link org.hibernate.Filter filter}.
- * information includes its name as well as its defined parameters (name and type).
+ * This information includes the {@linkplain #filterName name} of the
+ * filter, along with the {@linkplain #parameterTypes name and type}
+ * of every parameter of the filter. A filter may optionally have a
+ * {@linkplain #defaultFilterCondition default condition}.
+ *
+ * @see org.hibernate.annotations.FilterDef
+ * @see org.hibernate.Filter
  *
  * @author Steve Ebersole
  */