Polish Javadoc and internals of R2DBC support

Author: sbrannen

spring-r2dbc/src/main/java/org/springframework/r2dbc/core/NamedParameterUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -513,14 +513,50 @@ private static class ExpandedQuery implements PreparedOperation<String> {
 
 private final BindParameterSource parameterSource;
 
+
 ExpandedQuery(String expandedSql, NamedParameters parameters, BindParameterSource parameterSource) {
 this.expandedSql = expandedSql;
 this.parameters = parameters;
 this.parameterSource = parameterSource;
 }
 
+
+@Override
+public String toQuery() {
+return this.expandedSql;
+}
+
+@Override
+public String getSource() {
+return this.expandedSql;
+}
+
+@Override
+public void bindTo(BindTarget target) {
+for (String namedParameter : this.parameterSource.getParameterNames()) {
+Parameter parameter = this.parameterSource.getValue(namedParameter);
+if (parameter.getValue() == null) {
+bindNull(target, namedParameter, parameter);
+}
+else {
+bind(target, namedParameter, parameter);
+}
+}
+}
+
+private void bindNull(BindTarget target, String identifier, Parameter parameter) {
+List<BindMarker> bindMarkers = getBindMarkers(identifier);
+if (bindMarkers == null) {
+target.bind(identifier, parameter);
+return;
+}
+for (BindMarker bindMarker : bindMarkers) {
+bindMarker.bind(target, parameter);
+}
+}
+
 @SuppressWarnings({"rawtypes", "unchecked"})
-public void bind(BindTarget target, String identifier, Parameter parameter) {
+private void bind(BindTarget target, String identifier, Parameter parameter) {
 List<BindMarker> bindMarkers = getBindMarkers(identifier);
 if (bindMarkers == null) {
 target.bind(identifier, parameter);
@@ -555,19 +591,8 @@ private void bind(BindTarget target, Iterator<BindMarker> markers, Object valueT
 markers.next().bind(target, valueToBind);
 }
 
-public void bindNull(BindTarget target, String identifier, Parameter parameter) {
-List<BindMarker> bindMarkers = getBindMarkers(identifier);
-if (bindMarkers == null) {
-target.bind(identifier, parameter);
-return;
-}
-for (BindMarker bindMarker : bindMarkers) {
-bindMarker.bind(target, parameter);
-}
-}
-
 @Nullable
-List<BindMarker> getBindMarkers(String identifier) {
+private List<BindMarker> getBindMarkers(String identifier) {
 List<NamedParameters.NamedParameter> parameters = this.parameters.getMarker(identifier);
 if (parameters == null) {
 return null;
@@ -579,28 +604,6 @@ List<BindMarker> getBindMarkers(String identifier) {
 return markers;
 }
 
-@Override
-public String getSource() {
-return this.expandedSql;
-}
-
-@Override
-public void bindTo(BindTarget target) {
-for (String namedParameter : this.parameterSource.getParameterNames()) {
-Parameter parameter = this.parameterSource.getValue(namedParameter);
-if (parameter.getValue() == null) {
-bindNull(target, namedParameter, parameter);
-}
-else {
-bind(target, namedParameter, parameter);
-}
-}
-}
-
-@Override
-public String toQuery() {
-return this.expandedSql;
-}
 }
 
 }

spring-r2dbc/src/main/java/org/springframework/r2dbc/core/binding/AnonymousBindMarkers.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,8 +19,9 @@
 import java.util.concurrent.atomic.AtomicIntegerFieldUpdater;
 
 /**
- * Anonymous, index-based bind marker using a static placeholder.
- * Instances are bound by the ordinal position ordered by the appearance of
+ * Anonymous, index-based bind markers that use a static placeholder.
+ *
+ * <p>Instances are bound by the ordinal position ordered by the appearance of
  * the placeholder. This implementation creates indexed bind markers using
  * an anonymous placeholder that correlates with an index.
  *
@@ -46,7 +47,7 @@ class AnonymousBindMarkers implements BindMarkers {
 
 
 /**
- * Create a new {@link AnonymousBindMarkers} instance given {@code placeholder}.
+ * Create a new {@link AnonymousBindMarkers} instance for the given {@code placeholder}.
  * @param placeholder parameter bind marker
  */
 AnonymousBindMarkers(String placeholder) {

spring-r2dbc/src/main/java/org/springframework/r2dbc/core/binding/BindMarker.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,7 +20,8 @@
 
 /**
  * A bind marker represents a single bindable parameter within a query.
- * Bind markers are dialect-specific and provide a
+ *
+ * <p>Bind markers are dialect-specific and provide a
  * {@link #getPlaceholder() placeholder} that is used in the actual query.
  *
  * @author Mark Paluch
@@ -37,7 +38,8 @@ public interface BindMarker {
 String getPlaceholder();
 
 /**
- * Bind the given {@code value} to the {@link Statement} using the underlying binding strategy.
+ * Bind the given {@code value} to the {@link Statement} using the underlying
+ * binding strategy.
  * @param bindTarget the target to bind the value to
  * @param value the actual value (must not be {@code null};
  * use {@link #bindNull(BindTarget, Class)} for {@code null} values)
@@ -46,7 +48,8 @@ public interface BindMarker {
 void bind(BindTarget bindTarget, Object value);
 
 /**
- * Bind a {@code null} value to the {@link Statement} using the underlying binding strategy.
+ * Bind a {@code null} value to the {@link Statement} using the underlying
+ * binding strategy.
  * @param bindTarget the target to bind the value to
  * @param valueType the value type (must not be {@code null})
  * @see Statement#bindNull

spring-r2dbc/src/main/java/org/springframework/r2dbc/core/binding/BindMarkers.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,10 +20,10 @@
  * Bind markers represent placeholders in SQL queries for substitution
  * for an actual parameter. Using bind markers allows creating safe queries
  * so query strings are not required to contain escaped values but rather
- * the driver encodes parameter in the appropriate representation.
+ * the driver encodes the parameter in the appropriate representation.
  *
  * <p>{@link BindMarkers} is stateful and can be only used for a single binding
- * pass of one or more parameters. It maintains bind indexes/bind parameter names.
+ * pass of one or more parameters. It maintains bind indexes or bind parameter names.
  *
  * @author Mark Paluch
  * @since 5.3
@@ -41,7 +41,7 @@ public interface BindMarkers {
 
 /**
  * Create a new {@link BindMarker} that accepts a {@code hint}.
- * Implementations are allowed to consider/ignore/filter
+ * <p>Implementations are allowed to consider/ignore/filter
  * the name hint to create more expressive bind markers.
  * @param hint an optional name hint that can be used as part of the bind marker
  * @return a new {@link BindMarker}

spring-r2dbc/src/main/java/org/springframework/r2dbc/core/binding/BindMarkersFactoryResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,8 +30,8 @@
 
 /**
  * Resolves a {@link BindMarkersFactory} from a {@link ConnectionFactory} using
- * {@link BindMarkerFactoryProvider}. Dialect resolution uses Spring's
- * {@link SpringFactoriesLoader spring.factories} to determine available extensions.
+ * a {@link BindMarkerFactoryProvider}. Dialect resolution uses Spring's
+ * {@link SpringFactoriesLoader spring.factories} file to determine available extensions.
  *
  * @author Mark Paluch
  * @since 5.3
@@ -45,8 +45,8 @@ public final class BindMarkersFactoryResolver {
 
 
 /**
- * Retrieve a {@link BindMarkersFactory} by inspecting {@link ConnectionFactory}
- * and its metadata.
+ * Retrieve a {@link BindMarkersFactory} by inspecting the supplied
+ * {@link ConnectionFactory} and its metadata.
  * @param connectionFactory the connection factory to inspect
  * @return the resolved {@link BindMarkersFactory}
  * @throws NoBindMarkersFactoryException if no {@link BindMarkersFactory} can be resolved
@@ -69,18 +69,21 @@ private BindMarkersFactoryResolver() {
 
 
 /**
- * SPI to extend Spring's default R2DBC BindMarkersFactory discovery mechanism.
- * Implementations of this interface are discovered through Spring's
+ * SPI to extend Spring's default R2DBC {@link BindMarkersFactory} discovery
+ * mechanism.
+ *
+ * <p>Implementations of this interface are discovered through Spring's
  * {@link SpringFactoriesLoader} mechanism.
+ *
  * @see SpringFactoriesLoader
  */
 @FunctionalInterface
 public interface BindMarkerFactoryProvider {
 
 /**
- * Return a {@link BindMarkersFactory} for a {@link ConnectionFactory}.
- * @param connectionFactory the connection factory to be used with the {@link BindMarkersFactory}
- * @return the {@link BindMarkersFactory} if the {@link BindMarkerFactoryProvider}
+ * Return a {@link BindMarkersFactory} for the given {@link ConnectionFactory}.
+ * @param connectionFactory the connection factory to be used with the {@code BindMarkersFactory}
+ * @return the {@code BindMarkersFactory} if this {@code BindMarkerFactoryProvider}
  * can provide a bind marker factory object, otherwise {@code null}
  */
 @Nullable
@@ -89,7 +92,7 @@ public interface BindMarkerFactoryProvider {
 
 
 /**
- * Exception thrown when {@link BindMarkersFactoryResolver} cannot resolve a
+ * Exception thrown when a {@link BindMarkersFactoryResolver} cannot resolve a
  * {@link BindMarkersFactory}.
  */
 @SuppressWarnings("serial")
@@ -106,8 +109,11 @@ public NoBindMarkersFactoryException(String msg) {
 
 
 /**
- * Built-in bind maker factories. Used typically as last {@link BindMarkerFactoryProvider}
- * when other providers register with a higher precedence.
+ * Built-in bind marker factories.
+ *
+ * <p>Typically used as the last {@link BindMarkerFactoryProvider} when other
+ * providers are registered with a higher precedence.
+ *
  * @see org.springframework.core.Ordered
  * @see org.springframework.core.annotation.AnnotationAwareOrderComparator
  */

spring-r2dbc/src/main/java/org/springframework/r2dbc/core/binding/IndexedBindMarkers.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,7 +19,7 @@
 import java.util.concurrent.atomic.AtomicIntegerFieldUpdater;
 
 /**
- * Index-based bind marker. This implementation creates indexed bind
+ * Index-based bind markers. This implementation creates indexed bind
  * markers using a numeric index and an optional prefix for bind markers
  * to be represented within the query string.
  *
@@ -43,14 +43,15 @@ class IndexedBindMarkers implements BindMarkers {
 
 
 /**
- * Create a new {@link IndexedBindMarker} instance given {@code prefix} and {@code beginWith}.
- * @param prefix bind parameter prefix
- * @param beginWith the first index to use
+ * Create a new {@link IndexedBindMarker} instance for the given {@code prefix}
+ * and {@code beginWith} value.
+ * @param prefix the bind parameter prefix
+ * @param beginIndex the first index to use
  */
-IndexedBindMarkers(String prefix, int beginWith) {
+IndexedBindMarkers(String prefix, int beginIndex) {
 this.counter = 0;
 this.prefix = prefix;
-this.offset = beginWith;
+this.offset = beginIndex;
 }