Introduce JdbcClient as a fluent facade for query/update execution

Delegates to JdbcTemplate/NamedParameterJdbcTemplate underneath the covers.
Supports parameter objects/records through SimplePropertySqlParameterSource.

Closes gh-30931

Author: jhoeller

spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcOperations.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2023 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.
@@ -35,12 +35,19 @@
  * <p>Alternatively, the standard JDBC infrastructure can be mocked.
  * However, mocking this interface constitutes significantly less work.
  * As an alternative to a mock objects approach to testing data access code,
- * consider the powerful integration testing support provided via the <em>Spring
- * TestContext Framework</em>, in the {@code spring-test} artifact.
+ * consider the powerful integration testing support provided via the
+ * <em>Spring TestContext Framework</em>, in the {@code spring-test} artifact.
+ *
+ * <p><b>NOTE: As of 6.1, there is a unified JDBC access facade available in
+ * the form of {@link org.springframework.jdbc.core.simple.JdbcClient}.</b>
+ * {@code JdbcClient} provides a fluent API style for common JDBC queries/updates
+ * with flexible use of indexed or named parameters. It delegates to
+ * {@code JdbcOperations}/{@code NamedParameterJdbcOperations} for actual execution.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller
  * @see JdbcTemplate
+ * @see org.springframework.jdbc.core.namedparam.NamedParameterJdbcOperations
  */
 public interface JdbcOperations {
 

spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcTemplate.java

@@ -65,8 +65,7 @@
  * It executes core JDBC workflow, leaving application code to provide SQL
  * and extract results. This class executes SQL queries or updates, initiating
  * iteration over ResultSets and catching JDBC exceptions and translating
- * them to the generic, more informative exception hierarchy defined in the
- * {@code org.springframework.dao} package.
+ * them to the common {@code org.springframework.dao} exception hierarchy.
  *
  * <p>Code using this class need only implement callback interfaces, giving
  * them a clearly defined contract. The {@link PreparedStatementCreator} callback
@@ -75,7 +74,8 @@
  * values from a ResultSet. See also {@link PreparedStatementSetter} and
  * {@link RowMapper} for two popular alternative callback interfaces.
  *
- * <p>Can be used within a service implementation via direct instantiation
+ * <p>An instance of this template class is thread-safe once configured.
+ * Can be used within a service implementation via direct instantiation
  * with a DataSource reference, or get prepared in an application context
  * and given to services as bean reference. Note: The DataSource should
  * always be configured as a bean in the application context, in the first case
@@ -88,12 +88,17 @@
  * <p>All SQL operations performed by this class are logged at debug level,
  * using "org.springframework.jdbc.core.JdbcTemplate" as log category.
  *
- * <p><b>NOTE: An instance of this class is thread-safe once configured.</b>
+ * <p><b>NOTE: As of 6.1, there is a unified JDBC access facade available in
+ * the form of {@link org.springframework.jdbc.core.simple.JdbcClient}.</b>
+ * {@code JdbcClient} provides a fluent API style for common JDBC queries/updates
+ * with flexible use of indexed or named parameters. It delegates to a
+ * {@code JdbcTemplate}/{@code NamedParameterJdbcTemplate} for actual execution.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller
  * @author Thomas Risberg
  * @since May 3, 2001
+ * @see JdbcOperations
  * @see PreparedStatementCreator
  * @see PreparedStatementSetter
  * @see CallableStatementCreator
@@ -103,6 +108,7 @@
  * @see RowCallbackHandler
  * @see RowMapper
  * @see org.springframework.jdbc.support.SQLExceptionTranslator
+ * @see org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate
  */
 public class JdbcTemplate extends JdbcAccessor implements JdbcOperations {
 

spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/BeanPropertySqlParameterSource.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2023 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.
@@ -32,15 +32,16 @@
 /**
  * {@link SqlParameterSource} implementation that obtains parameter values
  * from bean properties of a given JavaBean object. The names of the bean
- * properties have to match the parameter names.
+ * properties have to match the parameter names. Supports components of
+ * record classes as well, with accessor methods matching parameter names.
  *
- * <p>Uses a Spring BeanWrapper for bean property access underneath.
+ * <p>Uses a Spring {@link BeanWrapper} for bean property access underneath.
  *
  * @author Thomas Risberg
  * @author Juergen Hoeller
  * @since 2.0
  * @see NamedParameterJdbcTemplate
- * @see org.springframework.beans.BeanWrapper
+ * @see SimplePropertySqlParameterSource
  */
 public class BeanPropertySqlParameterSource extends AbstractSqlParameterSource {
 

spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/MapSqlParameterSource.java

@@ -143,6 +143,14 @@ public MapSqlParameterSource addValues(@Nullable Map<String, ?> values) {
 		return this;
 	}
 
+	/**
+	 * Return whether this parameter source has been configured with any values.
+	 * @since 6.1
+	 */
+	public boolean hasValues() {
+		return !this.values.isEmpty();
+	}
+
 	/**
 	 * Expose the current parameter values as read-only Map.
 	 */

spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcOperations.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2023 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.
@@ -40,6 +40,12 @@
  * often used directly, but provides a useful option to enhance testability,
  * as it can easily be mocked or stubbed.
  *
+ * <p><b>NOTE: As of 6.1, there is a unified JDBC access facade available in
+ * the form of {@link org.springframework.jdbc.core.simple.JdbcClient}.</b>
+ * {@code JdbcClient} provides a fluent API style for common JDBC queries/updates
+ * with flexible use of indexed or named parameters. It delegates to
+ * {@code JdbcOperations}/{@code NamedParameterJdbcOperations} for actual execution.
+ *
  * @author Thomas Risberg
  * @author Juergen Hoeller
  * @since 2.0

spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcTemplate.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 the original author or authors.
+ * Copyright 2002-2023 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.
@@ -55,16 +55,25 @@
  * done at execution time. It also allows for expanding a {@link java.util.List}
  * of values to the appropriate number of placeholders.
  *
- * <p>The underlying {@link org.springframework.jdbc.core.JdbcTemplate} is
+ * <p>An instance of this template class is thread-safe once configured.
+ * The underlying {@link org.springframework.jdbc.core.JdbcTemplate} is
  * exposed to allow for convenient access to the traditional
  * {@link org.springframework.jdbc.core.JdbcTemplate} methods.
  *
- * <p><b>NOTE: An instance of this class is thread-safe once configured.</b>
+ * <p><b>NOTE: As of 6.1, there is a unified JDBC access facade available in
+ * the form of {@link org.springframework.jdbc.core.simple.JdbcClient}.</b>
+ * {@code JdbcClient} provides a fluent API style for common JDBC queries/updates
+ * with flexible use of indexed or named parameters. It delegates to a
+ * {@code JdbcTemplate}/{@code NamedParameterJdbcTemplate} for actual execution.
  *
  * @author Thomas Risberg
  * @author Juergen Hoeller
  * @since 2.0
  * @see NamedParameterJdbcOperations
+ * @see SqlParameterSource
+ * @see ResultSetExtractor
+ * @see RowCallbackHandler
+ * @see RowMapper
  * @see org.springframework.jdbc.core.JdbcTemplate
  */
 public class NamedParameterJdbcTemplate implements NamedParameterJdbcOperations {

spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/SimplePropertySqlParameterSource.java

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2002-2023 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.jdbc.core.namedparam;
+
+import java.beans.PropertyDescriptor;
+import java.lang.reflect.Field;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.beans.BeanUtils;
+import org.springframework.jdbc.core.StatementCreatorUtils;
+import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
+import org.springframework.util.ReflectionUtils;
+
+/**
+ * {@link SqlParameterSource} implementation that obtains parameter values
+ * from bean properties of a given JavaBean object, from component accessors
+ * of a record class, or from raw field access.
+ *
+ * <p>This is a more flexible variant of {@link BeanPropertySqlParameterSource},
+ * with the limitation that it is not able to enumerate its
+ * {@link #getParameterNames() parameter names}.
+ *
+ * <p>In terms of its fallback property discovery algorithm, this class is
+ * similar to {@link org.springframework.validation.SimpleErrors} which is
+ * also just used for property retrieval purposes (rather than binding).
+ *
+ * @author Juergen Hoeller
+ * @since 6.1
+ * @see NamedParameterJdbcTemplate
+ * @see BeanPropertySqlParameterSource
+ */
+public class SimplePropertySqlParameterSource extends AbstractSqlParameterSource {
+
+	private final Object paramObject;
+
+	private final Map<String, Object> descriptorMap = new HashMap<>();
+
+
+	/**
+	 * Create a new SqlParameterSource for the given bean, record or field holder.
+	 * @param paramObject the bean, record or field holder instance to wrap
+	 */
+	public SimplePropertySqlParameterSource(Object paramObject) {
+		Assert.notNull(paramObject, "Parameter object must not be null");
+		this.paramObject = paramObject;
+	}
+
+
+	@Override
+	public boolean hasValue(String paramName) {
+		return (getDescriptor(paramName) != null);
+	}
+
+	@Override
+	@Nullable
+	public Object getValue(String paramName) throws IllegalArgumentException {
+		Object desc = getDescriptor(paramName);
+		if (desc instanceof PropertyDescriptor pd) {
+			ReflectionUtils.makeAccessible(pd.getReadMethod());
+			return ReflectionUtils.invokeMethod(pd.getReadMethod(), this.paramObject);
+		}
+		else if (desc instanceof Field field) {
+			ReflectionUtils.makeAccessible(field);
+			return ReflectionUtils.getField(field, this.paramObject);
+		}
+		throw new IllegalArgumentException("Cannot retrieve value for parameter '" + paramName +
+				"' - neither a getter method nor a raw field found");
+	}
+
+	/**
+	 * Derives a default SQL type from the corresponding property type.
+	 * @see StatementCreatorUtils#javaTypeToSqlParameterType
+	 */
+	@Override
+	public int getSqlType(String paramName) {
+		int sqlType = super.getSqlType(paramName);
+		if (sqlType != TYPE_UNKNOWN) {
+			return sqlType;
+		}
+		Object desc = getDescriptor(paramName);
+		if (desc instanceof PropertyDescriptor pd) {
+			return StatementCreatorUtils.javaTypeToSqlParameterType(pd.getPropertyType());
+		}
+		else if (desc instanceof Field field) {
+			return StatementCreatorUtils.javaTypeToSqlParameterType(field.getType());
+		}
+		return TYPE_UNKNOWN;
+	}
+
+	@Nullable
+	private Object getDescriptor(String paramName) {
+		return this.descriptorMap.computeIfAbsent(paramName, name -> {
+			Object pd = BeanUtils.getPropertyDescriptor(this.paramObject.getClass(), name);
+			if (pd == null) {
+				pd = ReflectionUtils.findField(this.paramObject.getClass(), name);
+			}
+			return pd;
+		});
+	}
+
+}