improve some JDBC related Javadocs (#9195)

improve some JDBC related Javadocs

Co-authored-by: nathan.xu <nathan.xu@procor.com>

hibernate-core/src/main/java/org/hibernate/engine/jdbc/BlobImplementer.java

@@ -7,7 +7,7 @@ package org.hibernate.engine.jdbc;
 import java.sql.SQLException;
 
 /**
- * Marker interface for non-contextually created {@link java.sql.Blob} instances..
+ * Marker interface for non-contextually created {@link java.sql.Blob} instances.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/ClobImplementer.java

@@ -5,7 +5,7 @@
 package org.hibernate.engine.jdbc;
 
 /**
- * Marker interface for non-contextually created {@link java.sql.Clob} instances..
+ * Marker interface for non-contextually created {@link java.sql.Clob} instances.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/NClobImplementer.java

@@ -5,9 +5,9 @@
 package org.hibernate.engine.jdbc;
 
 /**
- * Marker interface for non-contextually created java.sql.NClob instances..
+ * Marker interface for non-contextually created {@link java.sql.NClob} instances.
  * <p>
- * java.sql.NClob is a new type introduced in JDK 1.6 (JDBC 4)
+ * {@link java.sql.NClob} is a new type introduced in JDK 1.6 (JDBC 4)
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/Size.java

@@ -9,11 +9,11 @@ import org.hibernate.Length;
 import java.io.Serializable;
 
 /**
- * Models size restrictions/requirements on a column's datatype.
+ * Models size restrictions/requirements on a column's data type.
  *
- * @implNote Since we do not necessarily know the datatype up front, and therefore do not necessarily know
+ * @implNote Since we do not necessarily know the data type up front, and therefore do not necessarily know
  * whether length or precision/scale sizing is needed, we simply account for both here. Additionally, LOB
- * sizes, by standard, are allowed a "multiplier", {@code K} (Kb), {@code M} (Mb) or {@code G} (Gb).
+ * sizes, by standard, are allowed a "multiplier": {@code K} (Kb), {@code M} (Mb), or {@code G} (Gb).
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/batch/internal/BasicBatchKey.java

@@ -8,7 +8,7 @@ import org.hibernate.engine.jdbc.batch.spi.BatchKey;
 import org.hibernate.jdbc.Expectations;
 
 /**
- * Normal implementation of BatchKey
+ * Normal implementation of {@link BatchKey}
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/internal/DatabaseConnectionInfoImpl.java

@@ -20,7 +20,7 @@ import static org.hibernate.engine.jdbc.connections.internal.ConnectionProviderI
 import static org.hibernate.internal.util.StringHelper.nullIfEmpty;
 
 /**
- * Standard implementation of DatabaseConnectionInfo
+ * Standard implementation of {@link DatabaseConnectionInfo}
  *
  * @author Jan Schatteman
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/AbstractDataSourceBasedMultiTenantConnectionProviderImpl.java

@@ -11,7 +11,8 @@ import javax.sql.DataSource;
 import org.hibernate.service.UnknownUnwrapTypeException;
 
 /**
- * Basic support for implementations of {@link MultiTenantConnectionProvider} based on DataSources.
+ * Basic support for implementations of {@link MultiTenantConnectionProvider} based on {@link DataSource}s.
+ *
  * @author Steve Ebersole
  */
 public abstract class AbstractDataSourceBasedMultiTenantConnectionProviderImpl<T> implements MultiTenantConnectionProvider<T> {

hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/AbstractMultiTenantConnectionProvider.java

@@ -11,7 +11,7 @@ import org.hibernate.service.UnknownUnwrapTypeException;
 
 /**
  * Basic support for {@link MultiTenantConnectionProvider} implementations using
- * individual {@link ConnectionProvider} instances per tenant behind the scenes.
+ * an individual {@link ConnectionProvider} instance per tenant behind the scenes.
  * <p>
  * This class is meant to be subclassed to implement application-specific
  * requirements.

hibernate-core/src/main/java/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.java

@@ -19,7 +19,7 @@ import org.hibernate.service.spi.Wrapped;
  * A {@code ConnectionProvider} may be selected using the configuration property
  * {@value org.hibernate.cfg.AvailableSettings#CONNECTION_PROVIDER}.
  * <p>
- * It's not usual for an applications to implement its on {@code ConnectionProvider}.
+ * It's not usual for an application to implement its own {@code ConnectionProvider}.
  * Instead, the Hibernate project provides pre-built implementations for a variety of
  * connection pools as add-on modules.
  * <p>

hibernate-core/src/main/java/org/hibernate/engine/jdbc/cursor/internal/RefCursorSupportInitiator.java

@@ -12,7 +12,7 @@ import org.hibernate.engine.jdbc.spi.JdbcServices;
 import org.hibernate.service.spi.ServiceRegistryImplementor;
 
 /**
- * Service initiator for RefCursorSupport service
+ * Service initiator for the {@link RefCursorSupport} service
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/cursor/internal/StandardRefCursorSupport.java

@@ -17,7 +17,7 @@ import org.hibernate.engine.jdbc.spi.JdbcServices;
 import org.jboss.logging.Logger;
 
 /**
- * Standard implementation of RefCursorSupport
+ * Standard implementation of {@link RefCursorSupport}
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/dialect/internal/StandardDialectResolver.java

@@ -10,7 +10,7 @@ import org.hibernate.engine.jdbc.dialect.spi.DialectResolutionInfo;
 import org.hibernate.engine.jdbc.dialect.spi.DialectResolver;
 
 /**
- * The standard DialectResolver implementation
+ * The standard {@link DialectResolver} implementation
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/dialect/spi/DatabaseMetaDataDialectResolutionInfoAdapter.java

@@ -8,9 +8,9 @@ import java.sql.DatabaseMetaData;
 import java.sql.SQLException;
 
 /**
- * An implementation of DialectResolutionInfo that delegates calls to a wrapped {@link DatabaseMetaData}.
+ * An implementation of {@link DialectResolutionInfo} that delegates calls to a wrapped {@link DatabaseMetaData}.
  * <p>
- * All {@link SQLException}s resulting from calls on the DatabaseMetaData are converted to the Hibernate
+ * All {@link SQLException}s resulting from calls on the {@link DatabaseMetaData} are converted to the Hibernate
  * {@link org.hibernate.JDBCException} hierarchy.
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/engine/jdbc/dialect/spi/DialectFactory.java

@@ -11,7 +11,7 @@ import org.hibernate.dialect.Dialect;
 import org.hibernate.service.Service;
 
 /**
- * A factory for generating Dialect instances.
+ * A factory for generating {@link Dialect} instances.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/dialect/spi/DialectResolutionInfoSource.java

@@ -5,7 +5,7 @@
 package org.hibernate.engine.jdbc.dialect.spi;
 
 /**
- * Contract for the source of DialectResolutionInfo.
+ * Contract for the source of {@link DialectResolutionInfo}.
  */
 @FunctionalInterface
 public interface DialectResolutionInfoSource {

hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/internal/BlobAndClobCreator.java

@@ -22,9 +22,9 @@ import org.hibernate.engine.jdbc.proxy.NClobProxy;
  * {@link LobCreator} which can use {@link Connection#createBlob} and {@link Connection#createClob},
  * but {@link java.sql.NClob} references are created locally.
  *
- * @see NClobProxy
- *
  * @author Steve Ebersole
+ *
+ * @see NClobProxy
  */
 public class BlobAndClobCreator extends AbstractLobCreator implements LobCreator {
 

hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/internal/ExtractedDatabaseMetaDataImpl.java

@@ -24,7 +24,7 @@ import org.hibernate.tool.schema.extract.spi.SequenceInformation;
 import static java.util.stream.StreamSupport.stream;
 
 /**
- * Standard implementation of ExtractedDatabaseMetaData
+ * Standard implementation of {@link ExtractedDatabaseMetaData}
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/internal/NonContextualLobCreator.java

@@ -17,7 +17,7 @@ import java.sql.NClob;
 
 /**
  * {@link LobCreator} implementation using non-contextual or local creation, meaning that we generate the LOB
- * references ourselves as opposed to delegating to the JDBC {@link java.sql.Connection}.
+ * references ourselves as opposed to delegating to the {@linkplain java.sql.Connection JDBC connection}.
  *
  * @author Steve Ebersole
  * @author Gail Badner

hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/internal/QualifiedObjectNameFormatterStandardImpl.java

@@ -16,7 +16,7 @@ import org.hibernate.engine.jdbc.env.spi.NameQualifierSupport;
 import org.hibernate.engine.jdbc.env.spi.QualifiedObjectNameFormatter;
 
 /**
- * Standard implementation of QualifiedObjectNameFormatter which uses information reported
+ * Standard implementation of {@link QualifiedObjectNameFormatter} which uses information reported
  * by {@link DatabaseMetaData} to render qualified names.
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/spi/IdentifierCaseStrategy.java

@@ -5,7 +5,7 @@
 package org.hibernate.engine.jdbc.env.spi;
 
 /**
- * An enumeration of the way DatabaseMetaData might store and return identifiers
+ * An enumeration of the way {@link java.sql.DatabaseMetaData} might store and return identifiers
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/spi/IdentifierHelperBuilder.java

@@ -20,8 +20,8 @@ import static java.util.Collections.addAll;
 import static org.hibernate.internal.util.StringHelper.splitAtCommas;
 
 /**
- * Builder for IdentifierHelper instances.  Mainly here to allow progressive
+ * Builder for {@link IdentifierHelper} instances.  Mainly here to allow progressive
- * building of the immutable (after instantiation) IdentifierHelper.
+ * building of the immutable (after instantiation) {@link IdentifierHelper}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/internal/ResultSetReturnImpl.java

@@ -20,7 +20,7 @@ import org.hibernate.resource.jdbc.spi.JdbcEventHandler;
 import org.hibernate.resource.jdbc.spi.JdbcSessionContext;
 
 /**
- * Standard implementation of the ResultSetReturn contract
+ * Standard implementation of the {@link ResultSetReturn} contract
  *
  * @author Brett Meyer
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/AbstractMutationExecutor.java

@@ -24,7 +24,7 @@ import static org.hibernate.engine.jdbc.mutation.internal.ModelMutationHelper.ch
 import static org.hibernate.sql.model.ModelMutationLogging.MODEL_MUTATION_LOGGER;
 
 /**
- * Base support for MutationExecutor implementations
+ * Base support for {@link MutationExecutor} implementations
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/JdbcValueDescriptorImpl.java

@@ -11,7 +11,7 @@ import org.hibernate.sql.model.ast.ColumnValueParameter;
 import org.hibernate.sql.model.jdbc.JdbcValueDescriptor;
 
 /**
- * Standard JdbcValueDescriptor implementation
+ * Standard {@link JdbcValueDescriptor} implementation
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/MutationExecutorStandard.java

@@ -36,7 +36,7 @@ import org.hibernate.sql.model.jdbc.JdbcValueDescriptor;
 import static org.hibernate.internal.util.collections.CollectionHelper.isNotEmpty;
 
 /**
- * Standard MutationExecutor implementation
+ * Standard {@link org.hibernate.engine.jdbc.mutation.MutationExecutor}
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/NoBatchKeyAccess.java

@@ -8,8 +8,8 @@ import org.hibernate.engine.jdbc.batch.spi.BatchKey;
 import org.hibernate.engine.jdbc.mutation.spi.BatchKeyAccess;
 
 /**
- * A form of BatchKeyAccess for cases where batching is not wanted, which is
+ * A form of {@link BatchKeyAccess} for cases where batching is not wanted, which is
- * signified by a BatchKey of {@code null}
+ * signified by a {@link BatchKey} of {@code null}
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/PreparedStatementDetailsStandard.java

@@ -17,7 +17,7 @@ import org.hibernate.sql.model.PreparableMutationOperation;
 import org.hibernate.sql.model.TableMapping;
 
 /**
- * Describes a particular PreparedStatement within a {@linkplain PreparedStatementGroup group}
+ * Describes a particular {@link PreparedStatement} within a {@linkplain PreparedStatementGroup group}
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/PreparedStatementGroupSingleTable.java

@@ -15,7 +15,7 @@ import org.hibernate.sql.model.PreparableMutationOperation;
 import org.hibernate.sql.model.TableMapping;
 
 /**
- * PreparedStatementGroup implementation for cases where we
+ * {@link PreparedStatementGroup} implementation for cases where we
  * have just a single operation
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/StandardMutationExecutorService.java

@@ -19,7 +19,7 @@ import org.hibernate.sql.model.PreparableMutationOperation;
 import org.hibernate.sql.model.SelfExecutingUpdateOperation;
 
 /**
- * Standard MutationExecutorService implementation
+ * Standard {@link MutationExecutorService} implementation
  *
  * @see MutationExecutorServiceInitiator
  *

hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/spi/BatchKeyAccess.java

@@ -7,7 +7,8 @@ package org.hibernate.engine.jdbc.mutation.spi;
 import org.hibernate.engine.jdbc.batch.spi.BatchKey;
 
 /**
- * Provides access to a BatchKey as part of creating an {@linkplain MutationExecutorService#createExecutor executor}.
+ * Provides access to a {@link BatchKey} as part of creating an
+ * {@linkplain MutationExecutorService#createExecutor executor}.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/proxy/SerializableNClobProxy.java

@@ -11,7 +11,7 @@ import java.sql.Clob;
 import java.sql.NClob;
 
 /**
- * Manages aspects of proxying java.sql.NClobs to add serializability.
+ * Manages aspects of proxying {@link NClob}s to add serializability.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/engine/jdbc/spi/SqlExceptionHelper.java

@@ -24,7 +24,7 @@ import org.jboss.logging.Logger;
 import org.jboss.logging.Logger.Level;
 
 /**
- * Helper for handling SQLExceptions in various manners.
+ * Helper for handling {@link SQLException}s in various manners.
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/jdbc/TooManyRowsAffectedException.java

@@ -6,7 +6,7 @@ package org.hibernate.jdbc;
 import org.hibernate.HibernateException;
 
 /**
- * Indicates that more rows were affected then we were expecting to be.
+ * Indicates that more rows were affected than we were expecting to be.
  * Typically indicates presence of duplicate "PK" values in the
  * given table.
  *

hibernate-core/src/main/java/org/hibernate/resource/jdbc/internal/AbstractLogicalConnectionImplementor.java

@@ -8,6 +8,7 @@ import java.sql.Connection;
 import java.sql.SQLException;
 
 import org.hibernate.TransactionException;
+import org.hibernate.resource.jdbc.LogicalConnection;
 import org.hibernate.resource.jdbc.ResourceRegistry;
 import org.hibernate.resource.jdbc.spi.LogicalConnectionImplementor;
 import org.hibernate.resource.jdbc.spi.PhysicalJdbcTransaction;
@@ -16,7 +17,7 @@ import org.hibernate.resource.transaction.spi.TransactionStatus;
 import org.jboss.logging.Logger;
 
 /**
- * Base support for LogicalConnection implementations
+ * Base support for {@link LogicalConnection} implementations
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/resource/jdbc/internal/LogicalConnectionManagedImpl.java

@@ -14,6 +14,7 @@ import org.hibernate.ResourceClosedException;
 import org.hibernate.engine.jdbc.connections.spi.JdbcConnectionAccess;
 import org.hibernate.engine.jdbc.spi.JdbcServices;
 import org.hibernate.engine.jdbc.spi.SqlExceptionHelper;
+import org.hibernate.resource.jdbc.LogicalConnection;
 import org.hibernate.resource.jdbc.ResourceRegistry;
 import org.hibernate.resource.jdbc.spi.JdbcEventHandler;
 import org.hibernate.resource.jdbc.spi.JdbcSessionContext;
@@ -28,9 +29,9 @@ import static org.hibernate.ConnectionReleaseMode.ON_CLOSE;
 import static org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode.DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION;
 
 /**
- * Represents a LogicalConnection where we manage obtaining and releasing the Connection as needed.
+ * Represents a {@link LogicalConnection} where we manage obtaining and releasing the {@link Connection} as needed.
  * This implementation does not claim to be thread-safe and is not designed to be used by multiple
- * threads, yet we do apply a limited amount of care to be able to void obscure exceptions when
+ * threads, yet we do apply a limited amount of care to be able to avoid obscure exceptions when
  * this class is used in the wrong way.
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/resource/jdbc/internal/ResourceRegistryStandardImpl.java

@@ -21,16 +21,16 @@ import org.hibernate.resource.jdbc.ResourceRegistry;
 import org.hibernate.resource.jdbc.spi.JdbcEventHandler;
 
 /**
- * Helps to track statements and resultsets which need being closed.
+ * Helps to track {@link Statement}s and {@link ResultSet}s which need to be closed.
  * This class is not threadsafe.
  * <p>
- * Note regarding performance: we had evidence that allocating Iterators
+ * Note regarding performance: we had evidence that allocating {@code Iterator}s
  * to implement the cleanup on each element recursively was the dominant
- * resource cost, so we decided using "forEach" and lambdas in this case.
+ * resource cost, so we decided to use "for each" and lambdas in this case.
- * However the forEach/lambda combination is able to dodge allocating
+ * However, the "for each"/lambda combination is able to dodge allocating
- * Iterators on HashMap and ArrayList, but not on HashSet (at least on JDK8 and 11).
+ * {@code Iterator}s on {@code HashMap} and {@code ArrayList}, but not on {@code HashSet} (at least on JDK8 and 11).
- * Therefore some types which should ideally be modelled as a Set have
+ * Therefore some types which should ideally be modelled as a {@code Set} have
- * been implemented using HashMap.
+ * been implemented using {@code HashMap}.
  *
  * @author Steve Ebersole
  * @author Sanne Grinovero

hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jdbc/internal/JdbcResourceLocalTransactionCoordinatorImpl.java

@@ -4,6 +4,7 @@
  */
 package org.hibernate.resource.transaction.backend.jdbc.internal;
 
+import java.sql.Connection;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -28,7 +29,7 @@ import static org.hibernate.internal.CoreLogging.messageLogger;
 
 /**
  * An implementation of {@link TransactionCoordinator} based on managing a
- * transaction through the JDBC Connection via {@link JdbcResourceTransaction}.
+ * transaction through the JDBC {@link Connection} via {@link JdbcResourceTransaction}.
  *
  * @author Steve Ebersole
  *

hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jdbc/package-info.java

@@ -10,7 +10,7 @@
  * "data store" specific notion of a transaction.  In Hibernate ORM uses this
  * correlates to the JDBC notion of a transaction, which (unfortunately) is
  * not modeled by an actual contract.  Instead, JDBC models transaction control
- * via its Connection contract.
+ * via its {@link java.sql.Connection} contract.
  * <p>
  * Here we use
  * {@link org.hibernate.resource.transaction.backend.jdbc.spi.JdbcResourceTransaction}

hibernate-core/src/main/java/org/hibernate/sql/model/jdbc/JdbcMutationOperation.java

@@ -8,7 +8,7 @@ import org.hibernate.sql.exec.spi.JdbcOperation;
 import org.hibernate.sql.model.PreparableMutationOperation;
 
 /**
- * JdbcOperation extension for model mutations stemming from
+ * {@link JdbcOperation} extension for model mutations stemming from
  * persistence context flushes
  *
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/sql/model/jdbc/MergeOperation.java

@@ -13,7 +13,7 @@ import org.hibernate.sql.model.MutationType;
 import org.hibernate.sql.model.TableMapping;
 
 /**
- * JdbcMutation implementation for MERGE handling
+ * {@link JdbcMutationOperation} implementation for MERGE handling
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/sql/model/jdbc/UpsertOperation.java

@@ -13,7 +13,7 @@ import org.hibernate.sql.model.MutationType;
 import org.hibernate.sql.model.TableMapping;
 
 /**
- * JdbcMutation implementation for UPSERT handling
+ * {@link JdbcMutationOperation} implementation for UPSERT handling
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/sql/results/jdbc/internal/JdbcValuesMappingProducerProviderStandard.java

@@ -18,7 +18,7 @@ import org.hibernate.type.descriptor.jdbc.NullJdbcType;
 import java.util.List;
 
 /**
- * Standard JdbcValuesMappingProducerProvider implementation
+ * Standard {@link JdbcValuesMappingProducerProvider} implementation
  *
  * @author Steve Ebersole
  */

hibernate-core/src/main/java/org/hibernate/sql/results/jdbc/internal/ResultSetAccess.java

@@ -21,7 +21,7 @@ import org.hibernate.type.spi.TypeConfiguration;
 import jakarta.persistence.EnumType;
 
 /**
- * Access to a JDBC ResultSet and information about it.
+ * Access to a JDBC {@link ResultSet} and information about it.
  *
  * @author Steve Ebersole
  */