#59 - Consider custom conversion in MappingR2dbcConverter.

MappingR2dbcConverter now considers custom conversions for inbound and outbound conversion of top-level types (Row to Entity, Entity to OutboundRow) and on property level (e.g. convert an object to String and vice versa). Original pull request: #70.

Author: mp911de

src/main/asciidoc/reference/mapping.adoc

@@ -28,6 +28,47 @@ Public `JavaBean` properties are not used.
 Otherwise, the zero-argument constructor is used.
 If there is more than one non-zero-argument constructor, an exception will be thrown.
 
+[[mapping-configuration]]
+== Mapping Configuration
+
+Unless explicitly configured, an instance of `MappingR2dbcConverter` is created by default when you create a `DatabaseClient`.
+You can create your own instance of the `MappingR2dbcConverter`.
+By creating your own instance, you can register Spring converters to map specific classes to and from the database.
+
+You can configure the `MappingR2dbcConverter` as well as `DatabaseClient` and `ConnectionFactory` by using Java-based metadata. The following example uses Spring's Java-based configuration:
+
+.@Configuration class to configure R2DBC mapping support
+====
+[source,java]
+----
+@Configuration
+public class MyAppConfig extends AbstractR2dbcConfiguration {
+
+ public ConnectionFactory connectionFactory() {
+ return ConnectionFactories.get("r2dbc:…");
+ }
+
+ // the following are optional
+
+ @Bean
+ @Override
+ public R2dbcCustomConversions r2dbcCustomConversions() {
+
+ List<Converter<?, ?>> converterList = new ArrayList<Converter<?, ?>>();
+ converterList.add(new org.springframework.data.r2dbc.test.PersonReadConverter());
+ converterList.add(new org.springframework.data.r2dbc.test.PersonWriteConverter());
+ return new R2dbcCustomConversions(getStoreConversions(), converterList);
+ }
+}
+----
+====
+
+`AbstractR2dbcConfiguration` requires you to implement a method that defines a `ConnectionFactory`.
+
+You can add additional converters to the converter by overriding the `r2dbcCustomConversions` method.
+
+NOTE: `AbstractR2dbcConfiguration` creates a `DatabaseClient` instance and registers it with the container under the name `databaseClient`.
+
 [[mapping-usage]]
 == Metadata-based Mapping
 
@@ -52,7 +93,6 @@ public class Person {
 
  private String firstName;
 
- @Indexed
  private String lastName;
 }
 ----
@@ -103,3 +143,47 @@ class OrderItem {
 
 ----
 
+[[mapping-explicit-converters]]
+=== Overriding Mapping with Explicit Converters
+
+When storing and querying your objects, it is convenient to have a `R2dbcConverter` instance handle the mapping of all Java types to `OutboundRow` instances.
+However, sometimes you may want the `R2dbcConverter` instances do most of the work but let you selectively handle the conversion for a particular type -- perhaps to optimize performance.
+
+To selectively handle the conversion yourself, register one or more one or more `org.springframework.core.convert.converter.Converter` instances with the `R2dbcConverter`.
+
+You can use the `r2dbcCustomConversions` method in `AbstractR2dbcConfiguration` to configure converters. The examples <<mapping-configuration, at the beginning of this chapter>> show how to perform the configuration using Java.
+
+NOTE: Custom top-level entity conversion requires asymmetric types for conversion. Inbound data is extracted from R2DBC's `Row`.
+Outbound data (to be used with `INSERT`/`UPDATE` statements) is represented as `OutboundRow` and later assembled to a statement.
+
+The following example of a Spring Converter implementation converts from a `Row` to a `Person` POJO:
+
+[source,java]
+----
+@ReadingConverter
+ public class PersonReadConverter implements Converter<Row, Person> {
+
+ public Person convert(Row source) {
+ Person p = new Person(source.get("id", String.class),source.get("name", String.class));
+ p.setAge(source.get("age", Integer.class));
+ return p;
+ }
+}
+----
+
+The following example converts from a `Person` to a `OutboundRow`:
+
+[source,java]
+----
+@WritingConverter
+public class PersonWriteConverter implements Converter<Person, OutboundRow> {
+
+ public OutboundRow convert(Person source) {
+ OutboundRow row = new OutboundRow();
+ row.put("_d", source.getId());
+ row.put("name", source.getFirstName());
+ row.put("age", source.getAge());
+ return row;
+ }
+}
+----

src/main/java/org/springframework/data/r2dbc/dialect/R2dbcSimpleTypeHolder.java

@@ -17,10 +17,13 @@
 
 import io.r2dbc.spi.Row;
 
+import java.util.Arrays;
 import java.util.Collections;
+import java.util.HashSet;
 import java.util.Set;
 
 import org.springframework.data.mapping.model.SimpleTypeHolder;
+import org.springframework.data.r2dbc.domain.OutboundRow;
 
 /**
  * Simple constant holder for a {@link SimpleTypeHolder} enriched with R2DBC specific simple types.
@@ -32,7 +35,8 @@ public class R2dbcSimpleTypeHolder extends SimpleTypeHolder {
 /**
  * Set of R2DBC simple types.
  */
-public static final Set<Class<?>> R2DBC_SIMPLE_TYPES = Collections.singleton(Row.class);
+public static final Set<Class<?>> R2DBC_SIMPLE_TYPES = Collections
+.unmodifiableSet(new HashSet<>(Arrays.asList(OutboundRow.class, Row.class)));
 
 public static final SimpleTypeHolder HOLDER = new R2dbcSimpleTypeHolder();
 

src/main/java/org/springframework/data/r2dbc/function/convert/OutboundRow.java renamed to src/main/java/org/springframework/data/r2dbc/domain/OutboundRow.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.springframework.data.r2dbc.function.convert;
+package org.springframework.data.r2dbc.domain;
 
 import io.r2dbc.spi.Row;
 

src/main/java/org/springframework/data/r2dbc/function/convert/SettableValue.java renamed to src/main/java/org/springframework/data/r2dbc/domain/SettableValue.java

@@ -13,12 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.springframework.data.r2dbc.function.convert;
+package org.springframework.data.r2dbc.domain;
 
 import java.util.Objects;
 
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
+import org.springframework.util.ClassUtils;
 
 /**
  * A database value that can be set in a statement.
@@ -31,18 +32,48 @@ public class SettableValue {
 private final @Nullable Object value;
 private final Class<?> type;
 
+private SettableValue(@Nullable Object value, Class<?> type) {
+
+Assert.notNull(type, "Type must not be null");
+
+this.value = value;
+this.type = type;
+}
+
+/**
+ * Creates a new {@link SettableValue} from {@code value}.
+ *
+ * @param value must not be {@literal null}.
+ * @return the {@link SettableValue} value for {@code value}.
+ */
+public static SettableValue from(Object value) {
+
+Assert.notNull(value, "Value must not be null");
+
+return new SettableValue(value, ClassUtils.getUserClass(value));
+}
+
 /**
- * Create a {@link SettableValue}.
+ * Creates a new {@link SettableValue} from {@code value} and {@code type}.
  *
- * @param value
- * @param type
+ * @param value can be {@literal null}.
+ * @param type must not be {@literal null}.
+ * @return the {@link SettableValue} value for {@code value}.
  */
-public SettableValue(@Nullable Object value, Class<?> type) {
+public static SettableValue fromOrEmpty(@Nullable Object value, Class<?> type) {
+return value == null ? empty(type) : new SettableValue(value, ClassUtils.getUserClass(value));
+}
+
+/**
+ * Creates a new empty {@link SettableValue} for {@code type}.
+ *
+ * @return the empty {@link SettableValue} value for {@code type}.
+ */
+public static SettableValue empty(Class<?> type) {
 
 Assert.notNull(type, "Type must not be null");
 
-this.value = value;
-this.type = type;
+return new SettableValue(null, type);
 }
 
 /**
@@ -74,6 +105,15 @@ public boolean hasValue() {
 return value != null;
 }
 
+/**
+ * Returns whether this {@link SettableValue} has a empty.
+ *
+ * @return whether this {@link SettableValue} is empty. {@literal true} if {@link #getValue()} is {@literal null}.
+ */
+public boolean isEmpty() {
+return value == null;
+}
+
 @Override
 public boolean equals(Object o) {
 if (this == o)
@@ -92,8 +132,8 @@ public int hashCode() {
 @Override
 public String toString() {
 final StringBuffer sb = new StringBuffer();
-sb.append(getClass().getSimpleName());
-sb.append(" [value=").append(value);
+sb.append("SettableValue");
+sb.append("[value=").append(value);
 sb.append(", type=").append(type);
 sb.append(']');
 return sb.toString();

src/main/java/org/springframework/data/r2dbc/domain/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Domain objects for R2DBC.
+ */
+@NonNullApi
+package org.springframework.data.r2dbc.domain;
+
+import org.springframework.lang.NonNullApi;

src/main/java/org/springframework/data/r2dbc/function/BindableOperation.java

@@ -2,7 +2,7 @@
 
 import io.r2dbc.spi.Statement;
 
-import org.springframework.data.r2dbc.function.convert.SettableValue;
+import org.springframework.data.r2dbc.domain.SettableValue;
 
 /**
  * Extension to {@link QueryOperation} for operations that allow parameter substitution by binding parameter values.

src/main/java/org/springframework/data/r2dbc/function/DefaultDatabaseClient.java

@@ -52,10 +52,10 @@
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.r2dbc.UncategorizedR2dbcException;
+import org.springframework.data.r2dbc.domain.OutboundRow;
+import org.springframework.data.r2dbc.domain.SettableValue;
 import org.springframework.data.r2dbc.function.connectionfactory.ConnectionProxy;
 import org.springframework.data.r2dbc.function.convert.ColumnMapRowMapper;
-import org.springframework.data.r2dbc.function.convert.OutboundRow;
-import org.springframework.data.r2dbc.function.convert.SettableValue;
 import org.springframework.data.r2dbc.support.R2dbcExceptionTranslator;
 import org.springframework.jdbc.core.SqlProvider;
 import org.springframework.lang.Nullable;
@@ -370,15 +370,15 @@ public ExecuteSpecSupport bind(int index, Object value) {
 Assert.notNull(value, () -> String.format("Value at index %d must not be null. Use bindNull(…) instead.", index));
 
 Map<Integer, SettableValue> byIndex = new LinkedHashMap<>(this.byIndex);
-byIndex.put(index, new SettableValue(value, value.getClass()));
+byIndex.put(index, SettableValue.fromOrEmpty(value, value.getClass()));
 
 return createInstance(byIndex, this.byName, this.sqlSupplier);
 }
 
 public ExecuteSpecSupport bindNull(int index, Class<?> type) {
 
 Map<Integer, SettableValue> byIndex = new LinkedHashMap<>(this.byIndex);
-byIndex.put(index, new SettableValue(null, type));
+byIndex.put(index, SettableValue.empty(type));
 
 return createInstance(byIndex, this.byName, this.sqlSupplier);
 }
@@ -390,7 +390,7 @@ public ExecuteSpecSupport bind(String name, Object value) {
 () -> String.format("Value for parameter %s must not be null. Use bindNull(…) instead.", name));
 
 Map<String, SettableValue> byName = new LinkedHashMap<>(this.byName);
-byName.put(name, new SettableValue(value, value.getClass()));
+byName.put(name, SettableValue.fromOrEmpty(value, value.getClass()));
 
 return createInstance(this.byIndex, byName, this.sqlSupplier);
 }
@@ -400,7 +400,7 @@ public ExecuteSpecSupport bindNull(String name, Class<?> type) {
 Assert.hasText(name, "Parameter name must not be null or empty!");
 
 Map<String, SettableValue> byName = new LinkedHashMap<>(this.byName);
-byName.put(name, new SettableValue(null, type));
+byName.put(name, SettableValue.empty(type));
 
 return createInstance(this.byIndex, byName, this.sqlSupplier);
 }
@@ -842,7 +842,7 @@ public GenericInsertSpec value(String field, Object value) {
 () -> String.format("Value for field %s must not be null. Use nullValue(…) instead.", field));
 
 Map<String, SettableValue> byName = new LinkedHashMap<>(this.byName);
-byName.put(field, new SettableValue(value, value.getClass()));
+byName.put(field, SettableValue.fromOrEmpty(value, value.getClass()));
 
 return new DefaultGenericInsertSpec<>(this.table, byName, this.mappingFunction);
 }
@@ -853,7 +853,7 @@ public GenericInsertSpec nullValue(String field, Class<?> type) {
 Assert.notNull(field, "Field must not be null!");
 
 Map<String, SettableValue> byName = new LinkedHashMap<>(this.byName);
-byName.put(field, new SettableValue(null, type));
+byName.put(field, SettableValue.empty(type));
 
 return new DefaultGenericInsertSpec<>(this.table, byName, this.mappingFunction);
 }

src/main/java/org/springframework/data/r2dbc/function/DefaultReactiveDataAccessStrategy.java

@@ -41,12 +41,12 @@
 import org.springframework.data.r2dbc.dialect.BindMarkers;
 import org.springframework.data.r2dbc.dialect.BindMarkersFactory;
 import org.springframework.data.r2dbc.dialect.Dialect;
+import org.springframework.data.r2dbc.domain.OutboundRow;
+import org.springframework.data.r2dbc.domain.SettableValue;
 import org.springframework.data.r2dbc.function.convert.EntityRowMapper;
 import org.springframework.data.r2dbc.function.convert.MappingR2dbcConverter;
-import org.springframework.data.r2dbc.function.convert.OutboundRow;
 import org.springframework.data.r2dbc.function.convert.R2dbcConverter;
 import org.springframework.data.r2dbc.function.convert.R2dbcCustomConversions;
-import org.springframework.data.r2dbc.function.convert.SettableValue;
 import org.springframework.data.r2dbc.support.StatementRenderUtil;
 import org.springframework.data.relational.core.mapping.RelationalMappingContext;
 import org.springframework.data.relational.core.mapping.RelationalPersistentEntity;
@@ -182,7 +182,7 @@ private SettableValue getArrayValue(SettableValue value, RelationalPersistentPro
 "Dialect " + dialect.getClass().getName() + " does not support array columns");
 }
 
-return new SettableValue(converter.getArrayValue(arrayColumns, property, value.getValue()),
+return SettableValue.fromOrEmpty(converter.getArrayValue(arrayColumns, property, value.getValue()),
 property.getActualType());
 }
 

src/main/java/org/springframework/data/r2dbc/function/MapBindParameterSource.java

@@ -18,7 +18,7 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
-import org.springframework.data.r2dbc.function.convert.SettableValue;
+import org.springframework.data.r2dbc.domain.SettableValue;
 import org.springframework.util.Assert;
 
 /**
@@ -65,7 +65,7 @@ MapBindParameterSource addValue(String paramName, Object value) {
 Assert.notNull(paramName, "Parameter name must not be null!");
 Assert.notNull(value, "Value must not be null!");
 
-this.values.put(paramName, new SettableValue(value, value.getClass()));
+this.values.put(paramName, SettableValue.fromOrEmpty(value, value.getClass()));
 return this;
 }
 

src/main/java/org/springframework/data/r2dbc/function/ReactiveDataAccessStrategy.java

@@ -26,9 +26,9 @@
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.r2dbc.dialect.BindMarkersFactory;
-import org.springframework.data.r2dbc.function.convert.OutboundRow;
+import org.springframework.data.r2dbc.domain.OutboundRow;
+import org.springframework.data.r2dbc.domain.SettableValue;
 import org.springframework.data.r2dbc.function.convert.R2dbcConverter;
-import org.springframework.data.r2dbc.function.convert.SettableValue;
 
 /**
  * Draft of a data access strategy that generalizes convenience operations using mapped entities. Typically used