Improving the documentation.

Author: schauder

src/main/asciidoc/jdbc-custom-conversions.adoc

@@ -1,4 +1,6 @@
 [[jdbc.custom-converters]]
+// for backward compatibility only:
+[[jdbc.entity-persistence.custom-converters]]
 == Custom Conversions
 
 Spring Data JDBC allows registration of custom converters to influence how values are mapped in the database.
@@ -55,12 +57,26 @@ class MyJdbcConfiguration extends AbstractJdbcConfiguration {
 
  // …
 
- @Overwrite
- @Bean
- public JdbcCustomConversions jdbcCustomConversions() {
- return new JdbcCustomConversions(Arrays.asList(new BooleanToStringConverter(), new StringToBooleanConverter()));
- }
+@Override
+ protected List<?> userConverters() {
+return Arrays.asList(new BooleanToStringConverter(), new StringToBooleanConverter());
+}
+
 }
 ----
 
+NOTE: In previous versions of Spring Data JDBC it was recommended to directly overwrite `AbstractJdbcConfiguration.jdbcCustomConversions()`.
+This is no longer necessary or even recommended, since that method assembles conversions intended for all databases, conversions registered by the `Dialect` used and conversions registered by the user.
+If you are migrating from an older version of Spring Data JDBC and have `AbstractJdbcConfiguration.jdbcCustomConversions()` overwritten conversions from your `Dialect` will not get registered.
+
+[[jdbc.custom-converters.jdbc-value]]
+// for backward compatibility only:
+[[jdbc.entity-persistence.custom-converters.jdbc-value]]
+=== JdbcValue
+
+Value conversion uses `JdbcValue` to enrich values propagated to JDBC operations with a `java.sql.Types` type.
+Register a custom write converter if you need to specify a JDBC-specific type instead of using type derivation.
+This converter should convert the value to `JdbcValue` which has a field for the value and for the actual `JDBCType`.
+
+
 include::{spring-data-commons-docs}/custom-conversions.adoc[leveloffset=+3]

src/main/asciidoc/jdbc.adoc

@@ -263,48 +263,7 @@ p1.bestFriend = AggregateReference.to(p2.id);
 ----
 ====
 
-[[jdbc.entity-persistence.custom-converters]]
-=== Custom converters
-
-Custom converters can be registered, for types that are not supported by default, by inheriting your configuration from `AbstractJdbcConfiguration` and overwriting the method `jdbcCustomConversions()`.
-
-====
-[source,java]
-----
-@Configuration
-class DataJdbcConfiguration extends AbstractJdbcConfiguration {
-
- @Override
- public JdbcCustomConversions jdbcCustomConversions() {
- return new JdbcCustomConversions(Collections.singletonList(TimestampTzToDateConverter.INSTANCE));
- }
-
- @ReadingConverter
- enum TimestampTzToDateConverter implements Converter<TIMESTAMPTZ, Date> {
-
- INSTANCE;
-
- @Override
- public Date convert(TIMESTAMPTZ source) {
- //...
- }
- }
-}
-----
-====
-
-The constructor of `JdbcCustomConversions` accepts a list of `org.springframework.core.convert.converter.Converter`.
-
-Converters should be annotated with `@ReadingConverter` or `@WritingConverter` in order to control their applicability to only reading from or to writing to the database.
-
-`TIMESTAMPTZ` in the example is a database specific data type that needs conversion into something more suitable for a domain model.
-
-[[jdbc.entity-persistence.custom-converters.jdbc-value]]
-==== JdbcValue
-
-Value conversion uses `JdbcValue` to enrich values propagated to JDBC operations with a `java.sql.Types` type.
-Register a custom write converter if you need to specify a JDBC-specific type instead of using type derivation.
-This converter should convert the value to `JdbcValue` which has a field for the value and for the actual `JDBCType`.
+* Types for which you registered suitable [[jdbc.custom-converters, custom conversions]].
 
 [[jdbc.entity-persistence.naming-strategy]]
 === `NamingStrategy`