From 5fb4b036bb05f09d4c920aaf8f0f6bd0455436d0 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Tue, 17 Mar 2020 10:57:15 +0100 Subject: [PATCH] DATAMONGO-1026 - Include documentation about custom conversions. We now include the documentations partial about custom conversions that explains default converter registrations, overrides and system setting timezone-sensitivity. --- src/main/asciidoc/reference/mapping.adoc | 43 +------------- .../reference/mongo-custom-conversions.adoc | 59 ++----------------- src/main/asciidoc/reference/mongodb.adoc | 2 - 3 files changed, 6 insertions(+), 98 deletions(-) diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc index 35d7b8387..48eee558d 100644 --- a/src/main/asciidoc/reference/mapping.adoc +++ b/src/main/asciidoc/reference/mapping.adoc @@ -771,45 +771,4 @@ Events are fired throughout the lifecycle of the mapping process. This is descri Declaring these beans in your Spring ApplicationContext causes them to be invoked whenever the event is dispatched. -[[mapping-explicit-converters]] -=== Overriding Mapping with Explicit Converters - -When storing and querying your objects, it is convenient to have a `MongoConverter` instance handle the mapping of all Java types to `Document` instances. However, sometimes you may want the `MongoConverter` 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 `MongoConverter`. - -NOTE: Spring 3.0 introduced a core.convert package that provides a general type conversion system. This is described in detail in the Spring reference documentation section entitled https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#validation["`Spring Type Conversion`"]. - -You can use the `customConversions` method in `AbstractMongoClientConfiguration` to configure converters. The examples <> show how to perform the configuration using Java and XML. - -The following example of a Spring Converter implementation converts from a `Document` to a `Person` POJO: - -[source,java] ----- -@ReadingConverter - public class PersonReadConverter implements Converter { - - public Person convert(Document source) { - Person p = new Person((ObjectId) source.get("_id"), (String) source.get("name")); - p.setAge((Integer) source.get("age")); - return p; - } -} ----- - -The following example converts from a `Person` to a `Document`: - -[source,java] ----- -@WritingConverter -public class PersonWriteConverter implements Converter { - - public Document convert(Person source) { - Document document = new Document(); - document.put("_id", source.getId()); - document.put("name", source.getFirstName()); - document.put("age", source.getAge()); - return document; - } -} ----- +include::mongo-custom-conversions.adoc[] diff --git a/src/main/asciidoc/reference/mongo-custom-conversions.adoc b/src/main/asciidoc/reference/mongo-custom-conversions.adoc index c4707f389..003248755 100644 --- a/src/main/asciidoc/reference/mongo-custom-conversions.adoc +++ b/src/main/asciidoc/reference/mongo-custom-conversions.adoc @@ -1,7 +1,7 @@ [[mongo.custom-converters]] == Custom Conversions - Overriding Default Mapping -The most trivial way of influencing the the mapping result is by specifying the desired native MongoDB target type via the +The most trivial way of influencing the mapping result is by specifying the desired native MongoDB target type via the `@Field` annotation. This allows to work with non MongoDB types like `BigDecimal` in the domain model while persisting values in native `org.bson.types.Decimal128` format. @@ -101,60 +101,11 @@ class MyMongoConfiguration extends AbstractMongoClientConfiguration { } @Override - public CustomConversions customConversions() { - - List> converters = new ArrayList<>(2); - converters.add(new com.example.PersonReadConverter()); - converters.add(new com.example.PersonWriteConverter()); - return new MongoCustomConversions(converters); + protected void configureConverters(MongoConverterConfigurationAdapter adapter) { + adapter.registerConverter(new com.example.PersonReadConverter()); + adapter.registerConverter(new com.example.PersonWriteConverter()); } } ---- -The Mongo Spring namespace provides a convenient way to register Spring `Converter` instances with the `MappingMongoConverter`. The following configuration snippet shows how to manually register converter beans as well as configure the wrapping `MappingMongoConverter` into a `MongoTemplate`: - -[source,xml] ----- - - - - - - - - - - - - - - - - - ----- - -You can also use the `base-package` attribute of the `custom-converters` element to enable classpath scanning for all `Converter` and `GenericConverter` implementations below the given package, as the following example shows: - -[source,xml] ----- - - - ----- - -[[mongo.converter-disambiguation]] -=== Converter Disambiguation - -Generally, we inspect the `Converter` implementations for the source and target types they convert from and to. Depending on whether one of those is a type MongoDB can handle natively, we register the converter instance as a reading or a writing converter. The following examples show a writer converter and a read converter (note the difference is in the order of the qualifiers on `Converter`): - -[source,java] ----- -// Write converter as only the target type is one Mongo can handle natively -class MyConverter implements Converter { … } - -// Read converter as only the source type is one Mongo can handle natively -class MyConverter implements Converter { … } ----- - -If you write a `Converter` whose source and target type are native Mongo types, we 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 let you force the infrastructure to register a converter for only one way, we provide `@ReadingConverter` and `@WritingConverter` annotations to be used in the converter implementation. +include::../{spring-data-commons-docs}/custom-conversions.adoc[leveloffset=+3] diff --git a/src/main/asciidoc/reference/mongodb.adoc b/src/main/asciidoc/reference/mongodb.adoc index 7d849dfe1..a29aefe76 100644 --- a/src/main/asciidoc/reference/mongodb.adoc +++ b/src/main/asciidoc/reference/mongodb.adoc @@ -3072,8 +3072,6 @@ TypedAggregation agg = Aggregation.newAggregation(Book.class, <4> Otherwise, add the field value of `author.middle`. ==== -include::mongo-custom-conversions.adoc[leveloffset=+1] - [[mongo-template.index-and-collections]] == Index and Collection Management