#368 - Deprecate API provided by Spring R2DBC.

This commit deprecates API that has been moved to Spring R2DBC.

Original pull request: #412.

Author: mp911de

pom.xml

@@ -107,6 +107,11 @@
 			<version>${springdata.relational}</version>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework</groupId>
+			<artifactId>spring-r2dbc</artifactId>
+		</dependency>
+
 		<dependency>
 			<groupId>org.springframework</groupId>
 			<artifactId>spring-tx</artifactId>

src/main/asciidoc/index.adoc

@@ -52,3 +52,4 @@ include::reference/kotlin.adoc[leveloffset=+1]
 :numbered!:
 include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[leveloffset=+1]
 include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[leveloffset=+1]
+include::reference/r2dbc-upgrading.adoc[leveloffset=+1]

src/main/asciidoc/reference/r2dbc-upgrading.adoc

@@ -0,0 +1,48 @@
+[appendix]
+= Migration Guide
+
+The following sections explain how to migrate to a newer version of Spring Data R2DBC.
+
+[[upgrading.1.1-1.2]]
+== Upgrading from 1.1.x to 1.2.x
+
+Spring Data R2DBC was developed with the intent to evaluate how well R2DBC can integrate with Spring applications.
+One of the main aspects was to move core support into Spring Framework once R2DBC support has proven useful.
+Spring Framework 5.3 ships with a new module: Spring R2DBC.
+
+`spring-r2dbc` ships core R2DBC functionality (a slim variant of `DatabaseClient`, Transaction Manager, Connection Factory initialization, Exception translation) that was initially provided by Spring Data R2DBC. The 1.2.0 release aligns with what's provided in Spring R2DBC by making several changes outlined in the following sections.
+
+[[upgrading.1.1-1.2.deprecation]]
+=== Deprecations
+
+* Deprecation of `o.s.d.r2dbc.core.DatabaseClient` and its support classes `ConnectionAccessor`, `FetchSpec`, `SqlProvider` and a few more.
+Named parameter support classes such as `NamedParameterExpander` are encapsulated by Spring R2DBC's `DatabaseClient` implementation hence we're not providing replacements as this was internal API in the first place.
+Use `o.s.r2dbc.core.DatabaseClient` and their Spring R2DBC replacements available from `org.springframework.r2dbc.core`.
+Entity-based methods (`select`/`insert`/`update`/`delete`) methods are available through `R2dbcEntityTemplate` which was introduced with version 1.1.
+* Deprecation of `o.s.d.r2dbc.connectionfactory`, `o.s.d.r2dbc.connectionfactory.init`, and `o.s.d.r2dbc.connectionfactory.lookup` packages.
+Use Spring R2DBC's variant which you can find at `o.s.r2dbc.connection`.
+* Deprecation of `o.s.d.r2dbc.convert.ColumnMapRowMapper`.
+Use `o.s.r2dbc.core.ColumnMapRowMapper` instead.
+* Deprecation of binding support classes `o.s.d.r2dbc.dialect.Bindings`, `BindMarker`, `BindMarkers`, `BindMarkersFactory` and related types.
+Use replacements from `org.springframework.r2dbc.core.binding`.
+* Deprecation of `BadSqlGrammarException`, `UncategorizedR2dbcException` and exception translation at `o.s.d.r2dbc.support`.
+Spring R2DBC provides a slim exception translation variant without an SPI for now available through `o.s.r2dbc.connection.ConnectionFactoryUtils#convertR2dbcException`.
+
+[[upgrading.1.1-1.2.replacements]]
+=== Usage of replacements provided by Spring R2DBC
+
+To ease migration, several deprecated types are now subtypes of their replacements provided by Spring R2DBC. Spring Data R2DBC has changes several methods or introduced new methods accepting Spring R2DBC types.
+Specifically the following classes are affected:
+
+* `R2dbcEntityTemplate`
+* `R2dbcDialect`
+* Types in `org.springframework.data.r2dbc.query`
+
+We recommend that you review your imports if you work with these types directly.
+
+[[upgrading.1.1-1.2.dependencies]]
+=== Dependency Changes
+
+To make use of Spring R2DBC, make sure to include the following dependency:
+
+* `org.springframework:spring-r2dbc`

src/main/java/org/springframework/data/r2dbc/BadSqlGrammarException.java

@@ -17,8 +17,6 @@
 
 import io.r2dbc.spi.R2dbcException;
 
-import org.springframework.dao.InvalidDataAccessResourceUsageException;
-
 /**
  * Exception thrown when SQL specified is invalid. Such exceptions always have a {@link io.r2dbc.spi.R2dbcException}
  * root cause.
@@ -28,13 +26,13 @@
  * without affecting code using this class.
  *
  * @author Mark Paluch
+ * @deprecated since 1.2, use directly Spring R2DBC's {@link org.springframework.r2dbc.BadSqlGrammarException} instead.
  */
-public class BadSqlGrammarException extends InvalidDataAccessResourceUsageException {
+@Deprecated
+public class BadSqlGrammarException extends org.springframework.r2dbc.BadSqlGrammarException {
 
 	private static final long serialVersionUID = 3814579246913482054L;
 
-	private final String sql;
-
 	/**
 	 * Creates a new {@link BadSqlGrammarException}.
 	 *
@@ -43,10 +41,7 @@ public class BadSqlGrammarException extends InvalidDataAccessResourceUsageExcept
 	 * @param ex the root cause.
 	 */
 	public BadSqlGrammarException(String task, String sql, R2dbcException ex) {
-
-		super(task + "; bad SQL grammar [" + sql + "]", ex);
-
-		this.sql = sql;
+		super(task, sql, ex);
 	}
 
 	/**
@@ -60,6 +55,6 @@ public R2dbcException getR2dbcException() {
 	 * Return the SQL that caused the problem.
 	 */
 	public String getSql() {
-		return this.sql;
+		return super.getSql();
 	}
 }

src/main/java/org/springframework/data/r2dbc/InvalidResultAccessException.java

@@ -24,13 +24,15 @@
  * Exception thrown when a {@link io.r2dbc.spi.Result} has been accessed in an invalid fashion. Such exceptions always
  * have a {@link io.r2dbc.spi.R2dbcException} root cause.
  * <p>
- * This typically happens when an invalid {@link org.springframework.data.r2dbc.core.FetchSpec} column index or name
- * has been specified.
+ * This typically happens when an invalid {@link org.springframework.data.r2dbc.core.FetchSpec} column index or name has
+ * been specified.
  *
  * @author Mark Paluch
  * @see BadSqlGrammarException
+ * @deprecated since 1.2, not in use anymore.
  */
 @SuppressWarnings("serial")
+@Deprecated
 public class InvalidResultAccessException extends InvalidDataAccessResourceUsageException {
 
 	private final @Nullable String sql;

src/main/java/org/springframework/data/r2dbc/UncategorizedR2dbcException.java

@@ -17,23 +17,19 @@
 
 import io.r2dbc.spi.R2dbcException;
 
-import org.springframework.dao.UncategorizedDataAccessException;
 import org.springframework.lang.Nullable;
 
 /**
  * Exception thrown when we can't classify a {@link R2dbcException} into one of our generic data access exceptions.
  *
  * @author Mark Paluch
+ * @deprecated since 1.2, use Spring R2DBC's {@link org.springframework.r2dbc.UncategorizedR2dbcException} instead.
  */
-public class UncategorizedR2dbcException extends UncategorizedDataAccessException {
+@Deprecated
+public class UncategorizedR2dbcException extends org.springframework.r2dbc.UncategorizedR2dbcException {
 
 	private static final long serialVersionUID = 361587356435210266L;
 
-	/**
-	 * SQL that led to the problem
-	 */
-	private final @Nullable String sql;
-
 	/**
 	 * Creates a new {@link UncategorizedR2dbcException}.
 	 *
@@ -42,10 +38,7 @@ public class UncategorizedR2dbcException extends UncategorizedDataAccessExceptio
 	 * @param ex the root cause
 	 */
 	public UncategorizedR2dbcException(String task, @Nullable String sql, R2dbcException ex) {
-
-		super(String.format("%s; uncategorized R2dbcException%s; %s", task, sql != null ? " for SQL [" + sql + "]" : "",
-				ex.getMessage()), ex);
-		this.sql = sql;
+		super(task, sql, ex);
 	}
 
 	/**
@@ -62,6 +55,6 @@ public R2dbcException getR2dbcException() {
 	 */
 	@Nullable
 	public String getSql() {
-		return this.sql;
+		return super.getSql();
 	}
 }

src/main/java/org/springframework/data/r2dbc/config/AbstractR2dbcConfiguration.java

@@ -40,8 +40,6 @@
 import org.springframework.data.r2dbc.dialect.R2dbcDialect;
 import org.springframework.data.r2dbc.mapping.R2dbcMappingContext;
 import org.springframework.data.r2dbc.support.R2dbcExceptionSubclassTranslator;
-import org.springframework.data.r2dbc.support.R2dbcExceptionTranslator;
-import org.springframework.data.r2dbc.support.SqlStateR2dbcExceptionTranslator;
 import org.springframework.data.relational.core.conversion.BasicRelationalConverter;
 import org.springframework.data.relational.core.mapping.NamingStrategy;
 import org.springframework.lang.Nullable;
@@ -100,11 +98,9 @@ public R2dbcDialect getDialect(ConnectionFactory connectionFactory) {
 	 * @throws IllegalArgumentException if any of the required args is {@literal null}.
 	 */
 	@Bean({ "r2dbcDatabaseClient", "databaseClient" })
-	public DatabaseClient databaseClient(ReactiveDataAccessStrategy dataAccessStrategy,
-			R2dbcExceptionTranslator exceptionTranslator) {
+	public DatabaseClient databaseClient(ReactiveDataAccessStrategy dataAccessStrategy) {
 
 		Assert.notNull(dataAccessStrategy, "DataAccessStrategy must not be null!");
-		Assert.notNull(exceptionTranslator, "ExceptionTranslator must not be null!");
 
 		SpelAwareProxyProjectionFactory projectionFactory = new SpelAwareProxyProjectionFactory();
 		if (context != null) {
@@ -115,7 +111,7 @@ public DatabaseClient databaseClient(ReactiveDataAccessStrategy dataAccessStrate
 		return DatabaseClient.builder() //
 				.connectionFactory(lookupConnectionFactory()) //
 				.dataAccessStrategy(dataAccessStrategy) //
-				.exceptionTranslator(exceptionTranslator) //
+				.exceptionTranslator(new R2dbcExceptionSubclassTranslator()) //
 				.projectionFactory(projectionFactory) //
 				.build();
 	}
@@ -200,19 +196,6 @@ protected StoreConversions getStoreConversions() {
 		return StoreConversions.of(dialect.getSimpleTypeHolder(), converters);
 	}
 
-	/**
-	 * Creates a {@link R2dbcExceptionTranslator} using the configured {@link #connectionFactory() ConnectionFactory}.
-	 *
-	 * @return must not be {@literal null}.
-	 * @see #connectionFactory()
-	 * @see R2dbcExceptionSubclassTranslator
-	 * @see SqlStateR2dbcExceptionTranslator
-	 */
-	@Bean
-	public R2dbcExceptionTranslator exceptionTranslator() {
-		return new R2dbcExceptionSubclassTranslator();
-	}
-
 	ConnectionFactory lookupConnectionFactory() {
 
 		ApplicationContext context = this.context;

src/main/java/org/springframework/data/r2dbc/connectionfactory/ConnectionFactoryUtils.java

@@ -39,7 +39,9 @@
  *
  * @author Mark Paluch
  * @author Christoph Strobl
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
+@Deprecated
 public abstract class ConnectionFactoryUtils {
 
 	/**

src/main/java/org/springframework/data/r2dbc/connectionfactory/ConnectionHandle.java

@@ -23,8 +23,10 @@
  * @author Mark Paluch
  * @see SimpleConnectionHandle
  * @see ConnectionHolder
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
 @FunctionalInterface
+@Deprecated
 public interface ConnectionHandle {
 
 	/**

src/main/java/org/springframework/data/r2dbc/connectionfactory/ConnectionHolder.java

@@ -22,8 +22,8 @@
 import org.springframework.util.Assert;
 
 /**
- * Resource holder wrapping a R2DBC {@link Connection}. {@link R2dbcTransactionManager} binds instances of
- * this class to the thread, for a specific {@link ConnectionFactory}.
+ * Resource holder wrapping a R2DBC {@link Connection}. {@link R2dbcTransactionManager} binds instances of this class to
+ * the thread, for a specific {@link ConnectionFactory}.
  * <p>
  * Inherits rollback-only support for nested R2DBC transactions and reference count functionality from the base class.
  * <p>
@@ -33,7 +33,9 @@
  * @author Christoph Strobl
  * @see R2dbcTransactionManager
  * @see ConnectionFactoryUtils
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
+@Deprecated
 public class ConnectionHolder extends ResourceHolderSupport {
 
 	@Nullable private ConnectionHandle connectionHandle;

src/main/java/org/springframework/data/r2dbc/connectionfactory/ConnectionProxy.java

@@ -26,7 +26,9 @@
  *
  * @author Mark Paluch
  * @author Christoph Strobl
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use R2DBC's {@link Wrapped} mechanism instead.
  */
+@Deprecated
 public interface ConnectionProxy extends Connection, Wrapped<Connection> {
 
 	/**

src/main/java/org/springframework/data/r2dbc/connectionfactory/DelegatingConnectionFactory.java

@@ -32,7 +32,9 @@
  *
  * @author Mark Paluch
  * @see #create
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
+@Deprecated
 public class DelegatingConnectionFactory implements ConnectionFactory, Wrapped<ConnectionFactory> {
 
 	private final ConnectionFactory targetConnectionFactory;

src/main/java/org/springframework/data/r2dbc/connectionfactory/R2dbcTransactionManager.java

@@ -73,7 +73,9 @@
  * @see ConnectionFactoryUtils#releaseConnection
  * @see TransactionAwareConnectionFactoryProxy
  * @see DatabaseClient
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
+@Deprecated
 public class R2dbcTransactionManager extends AbstractReactiveTransactionManager implements InitializingBean {
 
 	private ConnectionFactory connectionFactory;
@@ -135,7 +137,7 @@ public ConnectionFactory getConnectionFactory() {
 	 * <p>
 	 * If no custom translator is provided, a default {@link R2dbcExceptionSubclassTranslator} is used which translates
 	 * {@link R2dbcException}'s subclasses into Springs {@link DataAccessException} hierarchy.
-	 * 
+	 *
 	 * @see R2dbcExceptionSubclassTranslator
 	 * @since 1.1
 	 */
@@ -526,7 +528,7 @@ protected IsolationLevel resolveIsolationLevel(int isolationLevel) {
 	 * <p>
 	 * The default implementation throws a {@link TransactionSystemException}. Subclasses may specifically identify
 	 * concurrency failures etc.
-	 * 
+	 *
 	 * @param task the task description (commit or rollback).
 	 * @param ex the SQLException thrown from commit/rollback.
 	 * @return the translated exception to throw, either a {@link org.springframework.dao.DataAccessException} or a

src/main/java/org/springframework/data/r2dbc/connectionfactory/SimpleConnectionHandle.java

@@ -24,7 +24,9 @@
  *
  * @author Mark Paluch
  * @author Christoph Strobl
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
+@Deprecated
 public class SimpleConnectionHandle implements ConnectionHandle {
 
 	private final Connection connection;

src/main/java/org/springframework/data/r2dbc/connectionfactory/SingleConnectionConnectionFactory.java

@@ -53,7 +53,9 @@
  * @see #create()
  * @see io.r2dbc.spi.Connection#close()
  * @see ConnectionFactoryUtils#releaseConnection(io.r2dbc.spi.Connection, ConnectionFactory)
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
+@Deprecated
 public class SingleConnectionConnectionFactory extends DelegatingConnectionFactory
 		implements SmartConnectionFactory, DisposableBean {
 

src/main/java/org/springframework/data/r2dbc/connectionfactory/SmartConnectionFactory.java

@@ -27,7 +27,9 @@
  *
  * @author Mark Paluch
  * @see ConnectionFactoryUtils#closeConnection
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
+@Deprecated
 public interface SmartConnectionFactory extends ConnectionFactory {
 
 	/**

src/main/java/org/springframework/data/r2dbc/connectionfactory/TransactionAwareConnectionFactoryProxy.java

@@ -60,7 +60,9 @@
  * @see Connection#close
  * @see ConnectionFactoryUtils#doGetConnection
  * @see ConnectionFactoryUtils#doReleaseConnection
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection} instead.
  */
+@Deprecated
 public class TransactionAwareConnectionFactoryProxy extends DelegatingConnectionFactory {
 
 	/**

src/main/java/org/springframework/data/r2dbc/connectionfactory/init/CannotReadScriptException.java

@@ -21,7 +21,9 @@
  * Thrown by {@link ScriptUtils} if an SQL script cannot be read.
  *
  * @author Mark Paluch
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection.init} instead.
  */
+@Deprecated
 public class CannotReadScriptException extends ScriptException {
 
 	private static final long serialVersionUID = 7253084944991764250L;

src/main/java/org/springframework/data/r2dbc/connectionfactory/init/CompositeDatabasePopulator.java

@@ -31,7 +31,9 @@
  * executing all scripts.
  *
  * @author Mark Paluch
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection.init} instead.
  */
+@Deprecated
 public class CompositeDatabasePopulator implements DatabasePopulator {
 
 	private final List<DatabasePopulator> populators = new ArrayList<>(4);

src/main/java/org/springframework/data/r2dbc/connectionfactory/init/ConnectionFactoryInitializer.java

@@ -28,7 +28,9 @@
  *
  * @author Mark Paluch
  * @see DatabasePopulator
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection.init} instead.
  */
+@Deprecated
 public class ConnectionFactoryInitializer implements InitializingBean, DisposableBean {
 
 	private @Nullable ConnectionFactory connectionFactory;

src/main/java/org/springframework/data/r2dbc/connectionfactory/init/DatabasePopulator.java

@@ -25,8 +25,10 @@
  * @see ResourceDatabasePopulator
  * @see DatabasePopulatorUtils
  * @see ConnectionFactoryInitializer
+ * @deprecated since 1.2 in favor of Spring R2DBC. Use {@link org.springframework.r2dbc.connection.init} instead.
  */
 @FunctionalInterface
+@Deprecated
 public interface DatabasePopulator {
 
 	/**