mindol1004/spring-data-mongodb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Editing pass for new content in reference documentation.

Browse Source 
Closes: #4049
This commit is contained in:
Jay Bryant
2022-05-10 10:37:43 -05:00
committed by Christoph Strobl
parent 8d54cae54d
commit b571c8958d
2 changed files with 28 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
src/main/asciidoc/reference/mongo-property-converters.adoc
View File

@@ -1,11 +1,11 @@
[[mongo.property-converters]] [[mongo.property-converters]]
== Property Converters - Mapping specific fields == Property Converters - Mapping specific fields
While <<mongo.custom-converters, type-based conversion>> already offers ways to influence the conversion and representation of certain types within the target store it has its limitations when only certain values or properties of a particular type should be considered for conversion. While <<mongo.custom-converters, type-based conversion>> already offers ways to influence the conversion and representation of certain types within the target store, it has limitations when only certain values or properties of a particular type should be considered for conversion.
Property-based converters allow configuring conversion rules on a per-property basis, either declarative, via `@ValueConverter`, or programmatic by registering a `PropertyValueConverter` for a specific property. Property-based converters allow configuring conversion rules on a per-property basis, either declaratively (via `@ValueConverter`) or programmatically (by registering a `PropertyValueConverter` for a specific property).
A `PropertyValueConverter` can transform a given value into its store representation (**write**) and back (**read**) as shown in the snippet below. A `PropertyValueConverter` can transform a given value into its store representation (write) and back (read) as the following listing shows.
The additional `ValueConversionContext` provides additional information, such as mapping metadata and direct `read`/`write` methods. The additional `ValueConversionContext` provides additional information, such as mapping metadata and direct `read` and `write` methods.
.A simple PropertyValueConverter .A simple PropertyValueConverter
==== ====
@@ -26,18 +26,18 @@ class ReversingValueConverter implements PropertyValueConverter<String, String,
---- ----
==== ====
`PropertyValueConverter` instances can be obtained via `CustomConversions#getPropertyValueConverter(…)` delegating to `PropertyValueConversions`, typically using a `PropertyValueConverterFactory` providing the actual converter. You can obtain `PropertyValueConverter` instances from `CustomConversions#getPropertyValueConverter(…)` by delegating to `PropertyValueConversions`, typically by using a `PropertyValueConverterFactory` to provide the actual converter.
Depending on the applications needs, multiple instances of `PropertyValueConverterFactory` can be chained or decorated, for example to apply caching. Depending on your application's needs, you can chain or decorate multiple instances of `PropertyValueConverterFactory` -- for example, to apply caching.
By default, a caching implementation is used that is capable of serving types with a default constructor or enum values. By default, Spring Data MongoDB uses a caching implementation that can serve types with a default constructor or enum values.
A set of predefined factories is available through `PropertyValueConverterFactory` factory methods. A set of predefined factories is available through the factory methods in `PropertyValueConverterFactory`.
Use `PropertyValueConverterFactory.beanFactoryAware(…)` to obtain a `PropertyValueConverter` instances from an `ApplicationContext`. You can use `PropertyValueConverterFactory.beanFactoryAware(…)` to obtain a `PropertyValueConverter` instance from an `ApplicationContext`.
You can change the default behavior through `ConverterConfiguration`. You can change the default behavior through `ConverterConfiguration`.
[[mongo.property-converters.declarative]] [[mongo.property-converters.declarative]]
=== Declarative Value Converter === Declarative Value Converter
The most straight forward usage of a `PropertyValueConverter` is by annotating properties with the `@ValueConverter` annotation that defines the converter type. The most straight forward usage of a `PropertyValueConverter` is by annotating properties with the `@ValueConverter` annotation that defines the converter type:
.Declarative PropertyValueConverter .Declarative PropertyValueConverter
==== ====
@@ -54,8 +54,8 @@ class Person {
[[mongo.property-converters.programmatic]] [[mongo.property-converters.programmatic]]
=== Programmatic Value Converter Registration === Programmatic Value Converter Registration
Programmatic registration registers `PropertyValueConverter` instances for properties within an entity model using a `PropertyValueConverterRegistrar` as shown below. Programmatic registration registers `PropertyValueConverter` instances for properties within an entity model by using a `PropertyValueConverterRegistrar`, as the following example shows.
The difference to declarative registration is that programmatic registration happens entirely outside of the entity model. The difference between declarative registration and programmatic registration is that programmatic registration happens entirely outside of the entity model.
Such an approach is useful if you cannot or do not want to annotate the entity model. Such an approach is useful if you cannot or do not want to annotate the entity model.
.Programmatic PropertyValueConverter registration .Programmatic PropertyValueConverter registration
@@ -76,25 +76,22 @@ registrar.registerConverter(Person.class, Person::getSsn())
<2> Type safe variant that allows to register a converter and its conversion functions. <2> Type safe variant that allows to register a converter and its conversion functions.
==== ====
[WARNING] WARNING: Dot notation (such as `registerConverter(Person.class, "address.street", …)`) for nagivating across properties into subdocuments is *not* supported when registering converters.
====
Dot-notation (such as `registerConverter(Person.class, "address.street", …)`) nagivating across properties into subdocuments is *not* supported when registering converters.
====
[[mongo.property-converters.value-conversions]] [[mongo.property-converters.value-conversions]]
=== MongoDB property value conversions === MongoDB property value conversions
The above sections outlined the purpose an overall structure of `PropertyValueConverters`. The preceding sections outlined the purpose an overall structure of `PropertyValueConverters`.
This section will focus on MongoDB specific aspects. This section focuses on MongoDB specific aspects.
==== MongoValueConverter and MongoConversionContext ==== MongoValueConverter and MongoConversionContext
`MongoValueConverter` offers a pre typed `PropertyValueConverter` interface leveraging the `MongoConversionContext`. `MongoValueConverter` offers a pre-typed `PropertyValueConverter` interface that uses `MongoConversionContext`.
==== MongoCustomConversions configuration ==== MongoCustomConversions configuration
`MongoCustomConversions` are by default capable of handling declarative value converters depending on the configured `PropertyValueConverterFactory`. By default, `MongoCustomConversions` can handle declarative value converters, depending on the configured `PropertyValueConverterFactory`.
`MongoConverterConfigurationAdapter` is there to help set up programmatic value conversions or define the `PropertyValueConverterFactory` to be used. `MongoConverterConfigurationAdapter` helps to set up programmatic value conversions or define the `PropertyValueConverterFactory` to be used.
.Configuration Sample .Configuration Sample
==== ====

25
src/main/asciidoc/reference/mongo-repositories.adoc
View File

@@ -2,8 +2,6 @@
= MongoDB Repositories = MongoDB Repositories
[[mongo-repo-intro]] [[mongo-repo-intro]]
== Introduction
This chapter points out the specialties for repository support for MongoDB. This chapter builds on the core repository support explained in <<repositories>>. You should have a sound understanding of the basic concepts explained there. This chapter points out the specialties for repository support for MongoDB. This chapter builds on the core repository support explained in <<repositories>>. You should have a sound understanding of the basic concepts explained there.
[[mongo-repo-usage]] [[mongo-repo-usage]]
@@ -292,13 +290,13 @@ NOTE: If the property criterion compares a document, the order of the fields and
[[mongodb.repositories.queries.update]] [[mongodb.repositories.queries.update]]
=== Repository Update Methods === Repository Update Methods
The keywords in the preceding table can also be used to create queries that identify matching documents for running updates on them. You can also use the keywords in the preceding table to create queries that identify matching documents for running updates on them.
The actual update action is defined via the `@Update` annotation on the method itself as shown in the snippet below. + The actual update action is defined by the `@Update` annotation on the method itself, as the following listing shows.
Please note that the naming schema for derived queries starts with `find`. Note that the naming schema for derived queries starts with `find`.
Using _update_ (as in `updateAllByLastname(...)`) is only allowed in combination with `@Query`. Using `update` (as in `updateAllByLastname(...)`) is allowed only in combination with `@Query`.
The update is applied to *all* matching documents and it is *not* possible to limit the scope by passing in a `Page` nor using any of the <<repositories.limit-query-result,limiting keywords>>. + The update is applied to *all* matching documents and it is *not* possible to limit the scope by passing in a `Page` or by using any of the <<repositories.limit-query-result,limiting keywords>>.
The return type can be either `void` or a _numeric_ type, such as `long` which holds the number of modified documents. The return type can be either `void` or a _numeric_ type, such as `long`, to hold the number of modified documents.
.Update Methods .Update Methods
==== ====
@@ -326,18 +324,15 @@ public interface PersonRepository extends CrudRepository<Person, String> {
void updateAllByLastname(String lastname, int increment); <6> void updateAllByLastname(String lastname, int increment); <6>
} }
---- ----
<1> The filter query for the update is derived from the method name. The update is as is and does not bind any parameters. <1> The filter query for the update is derived from the method name. The update is "`as is`" and does not bind any parameters.
<2> The actual increment value is defined by the _increment_ method argument that is bound to the `?1` placeholder. <2> The actual increment value is defined by the `increment` method argument that is bound to the `?1` placeholder.
<3> It is possible to use SpEL for parameter binding. <3> Use the Spring Expression Language (SpEL) for parameter binding.
<4> Use the `pipeline` attribute to issue <<mongo-template.aggregation-update,aggregation pipeline updates>>. <4> Use the `pipeline` attribute to issue <<mongo-template.aggregation-update,aggregation pipeline updates>>.
<5> The update may contain complex objects. <5> The update may contain complex objects.
<6> Combine a <<mongodb.repositories.queries.json-based,string based query>> with an update. <6> Combine a <<mongodb.repositories.queries.json-based,string based query>> with an update.
==== ====
[WARNING] WARNING: Repository updates do not emit persistence nor mapping lifecycle events.
====
Repository updates do not emit persistence nor mapping lifecycle events.
====
[[mongodb.repositories.queries.delete]] [[mongodb.repositories.queries.delete]]
=== Repository Delete Queries === Repository Delete Queries