Spring/spring-data-mongodb
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DATAMONGO-1026 - Include documentation about custom conversions.

Browse Source 
We now include the documentations partial about custom conversions that explains default converter registrations, overrides and system setting timezone-sensitivity.
This commit is contained in:
Mark Paluch
2020-03-17 10:57:15 +01:00
parent 4f0dc04a81
commit 5fb4b036bb
3 changed files with 6 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
src/main/asciidoc/reference/mapping.adoc
View File

@@ -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 <<mapping-configuration, at the beginning of this chapter>> 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<Document, Person> {
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<Person, Document> {
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[]

59
src/main/asciidoc/reference/mongo-custom-conversions.adoc
View File

@@ -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<Converter<?, ?>> 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]
----
<mongo:db-factory dbname="database"/>
<mongo:mapping-converter>
<mongo:custom-converters>
<mongo:converter ref="readConverter"/>
<mongo:converter>
<bean class="com.example.PersonWriteConverter"/>
</mongo:converter>
</mongo:custom-converters>
</mongo:mapping-converter>
<bean id="readConverter" class="com.example.PersonReadConverter"/>
<bean id="mongoTemplate" class="org.springframework.data.mongodb.core.MongoTemplate">
<constructor-arg name="mongoDbFactory" ref="mongoDbFactory"/>
<constructor-arg name="mongoConverter" ref="mappingConverter"/>
</bean>
----
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:mapping-converter>
<mongo:custom-converters base-package="com.acme.**.converters" />
</mongo:mapping-converter>
----
[[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<Person, String> { … }
// Read converter as only the source type is one Mongo can handle natively
class MyConverter implements Converter<String, Person> { … }
----
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<String, Long>` 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]

2
src/main/asciidoc/reference/mongodb.adoc
View File

@@ -3072,8 +3072,6 @@ TypedAggregation<Book> 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