From 2a20fb8aa1969a58b08ba94efe0961ed3d3d9d80 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Tue, 17 Mar 2020 10:41:21 +0100 Subject: [PATCH] DATACASS-739 - Include custom conversions documentation from Commons. --- .../cassandra/example/mapping/Person.java | 2 +- src/main/asciidoc/index.adoc | 1 - src/main/asciidoc/reference/converters.adoc | 36 +++---------------- src/main/asciidoc/reference/mapping.adoc | 23 ++---------- 4 files changed, 7 insertions(+), 55 deletions(-) diff --git a/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/mapping/Person.java b/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/mapping/Person.java index 7e8ce71ae..bd993d774 100644 --- a/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/mapping/Person.java +++ b/spring-data-cassandra/src/test/java/org/springframework/data/cassandra/example/mapping/Person.java @@ -48,7 +48,7 @@ public class Person { @PrimaryKeyColumn(name = "correlated_type", ordinal = 2, type = PrimaryKeyType.CLUSTERED) private String correlatedType; - // other getters/setters ommitted + // other getters/setters omitted } @PrimaryKey diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 95843636e..1a0a8651e 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -26,7 +26,6 @@ include::{spring-data-commons-docs}/repositories.adoc[leveloffset=+1] include::reference/introduction.adoc[leveloffset=+1] include::reference/cassandra.adoc[leveloffset=+1] -include::reference/converters.adoc[leveloffset=+1] include::reference/reactive-cassandra.adoc[leveloffset=+1] include::reference/cassandra-repositories.adoc[leveloffset=+1] include::reference/reactive-cassandra-repositories.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/reference/converters.adoc b/src/main/asciidoc/reference/converters.adoc index 3814bf91a..22dfa2058 100644 --- a/src/main/asciidoc/reference/converters.adoc +++ b/src/main/asciidoc/reference/converters.adoc @@ -10,10 +10,7 @@ of the `MappingCassandraConverter` (perhaps for increased performance or other c need to create an implementation of the Spring `Converter` interface and register it with the `MappingCassandraConverter`. -NOTE: For more information on Spring's type conversion service, see the reference docs -{spring-framework-docs}core.html#core-convert[here]. - -[[cassandra.custom-converters.writer]] +[[customconversions.writer]] === Saving by Using a Registered Spring Converter You can combine converting and saving in a single process, basically using the converter to do the saving. @@ -26,7 +23,7 @@ with Jackson 2: include::../{example-root}/PersonWriteConverter.java[tags=class] ---- -[[cassandra.custom-converters.reader]] +[[customconversions.reader]] === Reading by Using a Spring Converter Similar to how you can combine saving and converting, you can also combine reading and converting. @@ -39,7 +36,7 @@ with Jackson 2: include::../{example-root}/PersonReadConverter.java[tags=class] ---- -[[cassandra.custom-converters.java]] +[[customconversions.java]] === Registering Spring Converters with `CassandraConverter` Spring Data for Apache Cassandra Java configuration provides a convenient way to register Spring `Converter` instances: @@ -51,29 +48,4 @@ as well as configure `CustomConversions`: include::../{example-root}/ConverterConfiguration.java[tags=class] ---- -[[cassandra.converter-disambiguation]] -=== Converter Disambiguation - -Generally, we inspect the `Converter` implementations for both the source and target types they convert from and to. -Depending on whether one of those is a type Cassandra can handle natively, Spring Data registers the `Converter` -instance as a reading or a writing converter. - -Consider the following samples: - -[source,java] ----- -// Write converter as only the target type is one cassandra can handle natively -class MyConverter implements Converter { … } - -// Read converter as only the source type is one cassandra can handle natively -class MyConverter implements Converter { … } ----- - -If you implement a `Converter` whose source and target types are native Cassandra types, -Spring Data cannot determine whether we should consider it as a reading or a writing `Converter`. -Registering the `Converter` instance as both might lead to unwanted results. - -For example, a `Converter` is ambiguous, although it probably does not make sense to try to convert all `String` -instances into `Long` instances when writing. To generally be able to force the infrastructure to register a `Converter` -for one way only, we provide `@ReadingConverter` as well as `@WritingConverter` to indicate the appropriate -`Converter` implementation. +include::../{spring-data-commons-docs}/custom-conversions.adoc[leveloffset=+3] diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc index 4f08a17fd..87430ec63 100644 --- a/src/main/asciidoc/reference/mapping.adoc +++ b/src/main/asciidoc/reference/mapping.adoc @@ -406,6 +406,7 @@ include::../{example-root}/mapping/Coordinates.java[tags=class] ---- ==== +[[mapping.index-creation]] ==== Index Creation You can annotate particular entity properties with `@Indexed` or `@SASI` if you wish to create secondary indexes @@ -428,27 +429,7 @@ include::../{example-root}/mapping/PersonWithIndexes.java[tags=class] CAUTION: Index creation on session initialization may have a severe performance impact on application startup. -[[cassandra.mapping.explicit-converters]] -=== Overriding Mapping with Explicit Converters - -When storing and querying objects, it is often convenient to have a `CassandraConverter` instance handle the mapping -of all Java types to rows. However, sometimes you may want the `CassandraConverter` to do most of the work -but still let you selectively handle the conversion for a particular type. Other times, you may want to optimize performance. - -To selectively handle the conversion yourself, register one or more `org.springframework.core.convert.converter.Converter` -instances with `CassandraConverter`. - -NOTE: Spring 3.0 introduced a `o.s.core.convert` package that provides a general type conversion system. -This system is described in detail in the Spring reference documentation section titled -{spring-framework-docs}core.html#core-convert[`Spring Type Conversion`]. - -The following example of a Spring `Converter` implementation converts from a row to a `Person` POJO: - -[source,java] ----- -include::../{example-root}/mapping/PersonReadConverter.java[tags=class] ----- - +include::./converters.adoc[] [[cassandra.mapping-usage.events]] == Lifecycle Events