add applySubselectFetchEnabled() to builder

improve some Javadoc

hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java

@@ -304,8 +304,19 @@ public interface SessionFactoryBuilder {
 	SessionFactoryBuilder applyMaximumFetchDepth(int depth);
 
 	/**
-	 * Apply a null precedence (NULLS FIRST, NULLS LAST) to be applied to
+	 * Enable the use of subselect fetching.
-	 * order by clauses rendered in SQL queries.
+	 *
+	 * @param enabled {@code true} indicates that subselect fetching is enabled
+	 *
+	 * @return {@code this}, for method chaining
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#USE_SUBSELECT_FETCH
+	 */
+	SessionFactoryBuilder applySubselectFetchEnabled(boolean enabled);
+
+	/**
+	 * Apply a null precedence, {@code NULLS FIRST} or {@code NULLS LAST},
+	 * to {@code order by} clauses rendered in SQL queries.
 	 *
 	 * @param nullPrecedence The default null precedence to use.
 	 *

hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryBuilderImpl.java

@@ -230,6 +230,12 @@ public class SessionFactoryBuilderImpl implements SessionFactoryBuilderImplement
 		return this;
 	}
 
+	@Override
+	public SessionFactoryBuilder applySubselectFetchEnabled(boolean enabled) {
+		this.optionsBuilder.applySubselectFetchEnabled( enabled );
+		return this;
+	}
+
 	@Override
 	public SessionFactoryBuilder applyDefaultNullPrecedence(NullPrecedence nullPrecedence) {
 		this.optionsBuilder.applyDefaultNullPrecedence( nullPrecedence );

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingSessionFactoryBuilder.java

@@ -178,6 +178,12 @@ public abstract class AbstractDelegatingSessionFactoryBuilder<T extends SessionF
 		return getThis();
 	}
 
+	@Override
+	public SessionFactoryBuilder applySubselectFetchEnabled(boolean enabled) {
+		delegate.applySubselectFetchEnabled( enabled );
+		return getThis();
+	}
+
 	@Override
 	public T applyDefaultNullPrecedence(NullPrecedence nullPrecedence) {
 		delegate.applyDefaultNullPrecedence( nullPrecedence );

hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java

@@ -1025,7 +1025,12 @@ public interface AvailableSettings {
 	String MAX_FETCH_DEPTH = "hibernate.max_fetch_depth";
 
 	/**
-	 * Specifies the default batch size for batch fetching.
+	 * Specifies the default batch size for batch fetching. When set to
+	 * a value greater than one, Hibernate will use batch fetching, when
+	 * possible, to fetch any association.
+	 * <p>
+	 * By default, Hibernate only uses batch fetching for associations
+	 * explicitly annotated {@code @BatchSize}.
 	 *
 	 * @see org.hibernate.annotations.BatchSize
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyDefaultBatchFetchSize(int)
@@ -1040,6 +1045,7 @@ public interface AvailableSettings {
 	 * explicitly annotated {@code @Fetch(SUBSELECT)}.
 	 *
 	 * @see org.hibernate.annotations.FetchMode#SUBSELECT
+	 * @see org.hibernate.boot.SessionFactoryBuilder#applySubselectFetchEnabled(boolean)
 	 */
 	String USE_SUBSELECT_FETCH = "hibernate.use_subselect_fetch";