add some cross-refs to the Javadoc

so we can easily find where these settings ultimately come from

Author: gavinking

hibernate-core/src/main/java/org/hibernate/type/descriptor/ValueBinder.java

@@ -11,7 +11,7 @@
 import java.sql.SQLException;
 
 /**
- * Contract for binding values to a {@link PreparedStatement}.
+ * Contract for binding values to a JDBC {@link PreparedStatement}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/type/descriptor/ValueExtractor.java

@@ -11,8 +11,8 @@
 import java.sql.SQLException;
 
 /**
- * Contract for extracting value via JDBC from {@link ResultSet} or as output
- * param from {@link CallableStatement}.
+ * Contract for extracting values from a JDBC {@link ResultSet} or
+ * from output the parameters of a {@link CallableStatement}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/type/descriptor/WrapperOptions.java

@@ -6,57 +6,82 @@
  */
 package org.hibernate.type.descriptor;
 
-import java.sql.Timestamp;
-import java.util.Calendar;
-import java.util.TimeZone;
-
 import org.hibernate.engine.jdbc.LobCreator;
 import org.hibernate.engine.spi.SessionFactoryImplementor;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 
+import java.util.TimeZone;
+
 /**
- * Gives binding (nullSafeSet) and extracting (nullSafeGet) code access to options.
+ * Options for {@linkplain ValueBinder#bind(java.sql.PreparedStatement, Object, int, WrapperOptions)
+ * binding values to} and {@linkplain ValueExtractor#extract(java.sql.ResultSet, int, WrapperOptions)
+ * extracting values from} JDBC prepared statements and result sets.
  *
  * @author Steve Ebersole
+ *
+ * @see ValueBinder
+ * @see ValueExtractor
  */
 public interface WrapperOptions {
 
 	/**
-	 * Access to the current Session
+	 * Access to the current session.
 	 */
 	SharedSessionContractImplementor getSession();
 
 	/**
-	 * Access to the current Session
+	 * Access to the current session factory.
 	 */
 	SessionFactoryImplementor getSessionFactory();
 
 	/**
-	 * Should streams be used for binding LOB values.
+	 * Determines whether streams should be used for binding LOB values.
 	 *
 	 * @return {@code true}/{@code false}
+	 *
+	 * @see org.hibernate.dialect.Dialect#useInputStreamToInsertBlob()
 	 */
 	boolean useStreamForLobBinding();
 
 	/**
-	 * Get the JDBC {@link java.sql.Types type code} used to bind a null boolean value
+	 * The JDBC {@link java.sql.Types type code} used to bind a null boolean value.
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#PREFERRED_BOOLEAN_JDBC_TYPE
+	 * @see org.hibernate.dialect.Dialect#getPreferredSqlTypeCodeForBoolean()
 	 */
 	int getPreferredSqlTypeCodeForBoolean();
 
 	/**
-	 * Obtain access to the {@link LobCreator}
+	 * Obtain access to the {@link LobCreator}.
 	 *
 	 * @return The LOB creator
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#NON_CONTEXTUAL_LOB_CREATION
+	 * @see org.hibernate.dialect.Dialect#getDefaultNonContextualLobCreation()
 	 */
 	LobCreator getLobCreator();
 
 	/**
-	 * The JDBC {@link TimeZone} used when persisting Timestamp and DateTime properties into the database.
-	 * This setting is used when storing timestamps using the {@link java.sql.PreparedStatement#setTimestamp(int, Timestamp, Calendar)} method.
+	 * The JDBC {@link TimeZone} used when writing a value of type {@link java.sql.Time}
+	 * or {@link java.sql.Timestamp} to a JDBC {@link java.sql.PreparedStatement}, or
+	 * when reading from a JDBC {@link java.sql.ResultSet}.
+	 * <ul>
+	 * <li>When {@code getJdbcTimeZone()} is null, the method
+	 *     {@link java.sql.PreparedStatement#setTimestamp(int, java.sql.Timestamp)} is
+	 *     called to write a timestamp, and
+	 *     {@link java.sql.ResultSet#getTimestamp(int)} is called to read a timestamp.
+	 * <li>But when not null, the method
+	 *     {@link java.sql.PreparedStatement#setTimestamp(int, java.sql.Timestamp, java.util.Calendar)}
+	 *     is called to write a timestamp, and
+	 *     {@link java.sql.ResultSet#getTimestamp(int, java.util.Calendar)} is called to
+	 *     read a timestamp.
+	 </ul>
+	 * Thus, the storage {@link TimeZone} can differ from the default JVM TimeZone given
+	 * by {@link TimeZone#getDefault()}.
 	 *
-	 * This way, the storage {@link TimeZone} can differ from the default JVM TimeZone given by {@link TimeZone#getDefault()}.
+	 * @return the JDBC {@link TimeZone}, or null if no JDBC timezone was explicitly set
 	 *
-	 * @return JDBC {@link TimeZone}
+	 * @see org.hibernate.cfg.AvailableSettings#JDBC_TIME_ZONE
 	 */
 	TimeZone getJdbcTimeZone();
 }

hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/JdbcTypeIndicators.java

@@ -15,7 +15,7 @@
 import org.hibernate.type.spi.TypeConfiguration;
 
 /**
- * A parameter object that helps in determine the {@link java.sql.Types SQL/JDBC type}
+ * A parameter object that helps determine the {@link java.sql.Types SQL/JDBC type}
  * recommended by the JDBC spec (explicitly or implicitly) for a given Java type.
  *
  * @see BasicJavaType#getRecommendedJdbcType
@@ -67,6 +67,9 @@ default TemporalType getTemporalPrecision() {
 	 * When mapping a boolean type to the database what is the preferred SQL type code to use?
 	 * <p/>
 	 * Returns a key into the {@link JdbcTypeRegistry}.
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#PREFERRED_BOOLEAN_JDBC_TYPE
+	 * @see org.hibernate.dialect.Dialect#getPreferredSqlTypeCodeForBoolean()
 	 */
 	default int getPreferredSqlTypeCodeForBoolean() {
 		return getCurrentBaseSqlTypeIndicators().getPreferredSqlTypeCodeForBoolean();
@@ -76,6 +79,8 @@ default int getPreferredSqlTypeCodeForBoolean() {
 	 * When mapping a duration type to the database what is the preferred SQL type code to use?
 	 * <p/>
 	 * Returns a key into the {@link JdbcTypeRegistry}.
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#PREFERRED_DURATION_JDBC_TYPE
 	 */
 	default int getPreferredSqlTypeCodeForDuration() {
 		return getCurrentBaseSqlTypeIndicators().getPreferredSqlTypeCodeForDuration();
@@ -85,6 +90,8 @@ default int getPreferredSqlTypeCodeForDuration() {
 	 * When mapping an uuid type to the database what is the preferred SQL type code to use?
 	 * <p/>
 	 * Returns a key into the {@link JdbcTypeRegistry}.
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#PREFERRED_UUID_JDBC_TYPE
 	 */
 	default int getPreferredSqlTypeCodeForUuid() {
 		return getCurrentBaseSqlTypeIndicators().getPreferredSqlTypeCodeForUuid();
@@ -94,6 +101,8 @@ default int getPreferredSqlTypeCodeForUuid() {
 	 * When mapping an instant type to the database what is the preferred SQL type code to use?
 	 * <p/>
 	 * Returns a key into the {@link JdbcTypeRegistry}.
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#PREFERRED_INSTANT_JDBC_TYPE
 	 */
 	default int getPreferredSqlTypeCodeForInstant() {
 		return getCurrentBaseSqlTypeIndicators().getPreferredSqlTypeCodeForInstant();
@@ -104,6 +113,8 @@ default int getPreferredSqlTypeCodeForInstant() {
 	 * <p/>
 	 * Returns a key into the {@link JdbcTypeRegistry}.
 	 *
+	 * @see org.hibernate.dialect.Dialect#getPreferredSqlTypeCodeForArray()
+	 *
 	 * @since 6.1
 	 */
 	default int getPreferredSqlTypeCodeForArray() {
@@ -137,6 +148,9 @@ default int getColumnScale() {
 
 	/**
 	 * The default {@link TimeZoneStorageStrategy}.
+	 *
+	 * @see org.hibernate.cfg.AvailableSettings#TIMEZONE_DEFAULT_STORAGE
+	 * @see org.hibernate.dialect.Dialect#getTimeZoneSupport()
 	 */
 	default TimeZoneStorageStrategy getDefaultTimeZoneStorageStrategy() {
 		return getCurrentBaseSqlTypeIndicators().getDefaultTimeZoneStorageStrategy();