improve some JDBC related Javadocs (#9195)

improve some JDBC related Javadocs

Co-authored-by: nathan.xu <nathan.xu@procor.com>
This commit is contained in:
Nathan Xu 2024-11-08 06:27:35 -05:00 committed by GitHub
parent b33890b38b
commit 019cbf5ed9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
43 changed files with 62 additions and 57 deletions

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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> {

View File

@ -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.

View File

@ -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>

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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

View File

@ -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
*/

View File

@ -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 {

View File

@ -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 {

View File

@ -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
*/

View File

@ -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

View File

@ -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

View File

@ -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
*/

View File

@ -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
* building of the immutable (after instantiation) IdentifierHelper.
* Builder for {@link IdentifierHelper} instances. Mainly here to allow progressive
* building of the immutable (after instantiation) {@link IdentifierHelper}.
*
* @author Steve Ebersole
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
* signified by a BatchKey of {@code null}
* A form of {@link BatchKeyAccess} for cases where batching is not wanted, which is
* signified by a {@link BatchKey} of {@code null}
*
* @author Steve Ebersole
*/

View File

@ -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
*/

View File

@ -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

View File

@ -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
*

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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.
*

View File

@ -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
*/

View File

@ -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

View File

@ -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.
* However the forEach/lambda combination is able to dodge allocating
* Iterators on HashMap and ArrayList, but not on HashSet (at least on JDK8 and 11).
* Therefore some types which should ideally be modelled as a Set have
* been implemented using HashMap.
* resource cost, so we decided to use "for each" and lambdas in this case.
* However, the "for each"/lambda combination is able to dodge allocating
* {@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 {@code Set} have
* been implemented using {@code HashMap}.
*
* @author Steve Ebersole
* @author Sanne Grinovero

View File

@ -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
*

View File

@ -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}

View File

@ -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

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/

View File

@ -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
*/