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

DATAMONGO-1974 - Polishing.

Browse Source 
Fix typos, links, and code fences.

Original pull request: #559.
This commit is contained in:
Mark Paluch
2018-05-11 15:20:02 +02:00
parent 1b5ce651be
commit 489d637a00
9 changed files with 72 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java
View File

@@ -894,7 +894,7 @@ public interface MongoOperations extends FluentMongoOperations {
* Insert a mixed Collection of objects into a database collection determining the collection name to use based on the
* class.
*
* @param collectionToSave the list of objects to save. Must not be {@literal null}.
* @param objectsToSave the list of objects to save. Must not be {@literal null}.
*/
void insertAll(Collection<? extends Object> objectsToSave);

6
src/main/asciidoc/index.adoc
View File

@@ -2,11 +2,11 @@
Mark Pollack; Thomas Risberg; Oliver Gierke; Costin Leau; Jon Brisbin; Thomas Darimont; Christoph Strobl; Mark Paluch; Jay Bryant
:revnumber: {version}
:revdate: {localdate}
:toc:
:toc-placement!:
:linkcss:
:doctype: book
:docinfo: shared
:toc: left
:toclevels: 4
:source-highlighter: prettify
:icons: font
:imagesdir: images
@@ -17,6 +17,8 @@ ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1
NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
toc::[]
include::preface.adoc[]
include::new-features.adoc[leveloffset=+1]

6
src/main/asciidoc/preface.adoc
View File

@@ -3,7 +3,7 @@
The Spring Data MongoDB project applies core Spring concepts to the development of solutions that use the MongoDB document style data store. We provide a "`template`" as a high-level abstraction for storing and querying documents. You may notice similarities to the JDBC support provided by the Spring Framework.
This document is the reference guide for Spring Data - Document Support. It explains Document module concepts and semantics and syntax for various store namespaces.
This document is the reference guide for Spring Data - MongoDB Support. It explains MongoDB module concepts and semantics and syntax for various store namespaces.
This section provides some basic introduction to Spring and Document databases. The rest of the document refers only to Spring Data MongoDB features and assumes the user is familiar with MongoDB and Spring concepts.
@@ -39,7 +39,7 @@ The starting point for learning about MongoDB is http://www.mongodb.org/[www.mon
[[requirements]]
== Requirements
The Spring Data MongoDB 1.x binaries require JDK level 6.0 and above and http://spring.io/docs[Spring Framework] {springVersion} and above.
The Spring Data MongoDB 2.x binaries require JDK level 8.0 and above and http://spring.io/docs[Spring Framework] {springVersion} and above.
In terms of document stores, you need at least version 2.6 of http://www.mongodb.org/[MongoDB].
@@ -57,4 +57,4 @@ Professional Support :: Professional, from-the-source support, with guaranteed r
[[get-started:up-to-date]]
== Following Development
For information on the Spring Data Mongo source code repository, nightly builds, and snapshot artifacts, see the Spring Data Mongo http://projects.spring.io/spring-data-mongodb/[homepage]. You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Community on http://stackoverflow.com/questions/tagged/spring-data[Stack Overflow]. To follow developer activity, look for the mailing list information on the Spring Data Mongo https://projects.spring.io/spring-data-mongodb/[homepage]. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATAMONGO[tracker]. To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community http://spring.io[Portal]. You can also follow the Spring http://spring.io/blog[blog ]or the project team on Twitter (http://twitter.com/SpringData[SpringData]).
For information on the Spring Data Mongo source code repository, nightly builds, and snapshot artifacts, see the Spring Data Mongo http://projects.spring.io/spring-data-mongodb/[homepage]. You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Community on http://stackoverflow.com/questions/tagged/spring-data[Stack Overflow]. To follow developer activity, look for the mailing list information on the Spring Data Mongo https://projects.spring.io/spring-data-mongodb/[homepage]. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATAMONGO[tracker]. To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community http://spring.io[Portal]. You can also follow the Spring http://spring.io/blog[blog] or the project team on Twitter (http://twitter.com/SpringData[SpringData]).

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

@@ -246,7 +246,7 @@ calling `get()` before the actual conversion
[[mapping-configuration]]
== Mapping Configuration
Unless explicitly configured, an instance of `MappingMongoConverter` is created by default when you create a `MongoTemplate`. You can create your own instance of the `MappingMongoConverter`. Doing so lets you dictate where to in the classpath your domain classes can be found, so that Spring Data MongoDB can extract metadata and construct indexes. Also, by creating your own instance, you can register Spring converters to map specific classes to and from the database.
Unless explicitly configured, an instance of `MappingMongoConverter` is created by default when you create a `MongoTemplate`. You can create your own instance of the `MappingMongoConverter`. Doing so lets you dictate where in the classpath your domain classes can be found, so that Spring Data MongoDB can extract metadata and construct indexes. Also, by creating your own instance, you can register Spring converters to map specific classes to and from the database.
You can configure the `MappingMongoConverter` as well as `com.mongodb.MongoClient` and MongoTemplate by using either Java-based or XML-based metadata. The following example uses Spring's Java-based configuration:
@@ -294,12 +294,10 @@ public class GeoSpatialAppConfig extends AbstractMongoConfiguration {
`AbstractMongoConfiguration` requires you to implement methods that define a `com.mongodb.MongoClient` as well as provide a database name. `AbstractMongoConfiguration` also has a method named `getMappingBasePackage(…)` that you can override to tell the converter where to scan for classes annotated with the `@Document` annotation.
You can add additional converters to the converter by overriding the `afterMappingMongoConverterCreation` method. Also shown in the preceding example is a `LoggingEventListener`, which logs `MongoMappingEvent` instances that are posted onto Spring's `ApplicationContextEvent` infrastructure.
You can add additional converters to the converter by overriding the `customConversions` method. Also shown in the preceding example is a `LoggingEventListener`, which logs `MongoMappingEvent` instances that are posted onto Spring's `ApplicationContextEvent` infrastructure.
NOTE: `AbstractMongoConfiguration` creates a `MongoTemplate` instance and registers it with the container under the name `mongoTemplate`.
You can also override the `UserCredentials getUserCredentials()` method to provide the username and password information to connect to the database.
Spring's MongoDB namespace lets you enable mapping functionality in XML, as the following example shows:
.XML schema to configure MongoDB mapping support
@@ -585,7 +583,7 @@ public class Person {
----
====
You need not use `@OneToMany` or similar mechanisms because the List of objects tells the mapping framework sees that you want a one-to-many relationship. When the object is stored in MongoDB, there is a list of DBRefs rather than the `Account` objects themselves.
You need not use `@OneToMany` or similar mechanisms because the List of objects tells the mapping framework that you want a one-to-many relationship. When the object is stored in MongoDB, there is a list of DBRefs rather than the `Account` objects themselves.
IMPORTANT: The mapping framework does not handle cascading saves. If you change an `Account` object that is referenced by a `Person` object, you must save the `Account` object separately. Calling `save` on the `Person` object does not automatically save the `Account` objects in the `accounts` property.

2
src/main/asciidoc/reference/mongo-3.adoc
View File

@@ -1,7 +1,7 @@
[[mongo.mongo-3]]
= MongoDB 3.0 Support
Spring Data MongoDB allows usage of both MongoDB Java driver generations 2 and 3 when connecting to a MongoDB 2.6/3.0 server running MMap.v1 or a MongoDB server 3.0 using MMap.v1 or the WiredTiger storage engine.
Spring Data MongoDB requires MongoDB Java driver generations 3 when connecting to a MongoDB 2.6/3.0 server running MMap.v1 or a MongoDB server 3.0 using MMap.v1 or the WiredTiger storage engine.
NOTE: See the driver- and database-specific documentation for major differences between those engines.

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

@@ -9,7 +9,7 @@ This chapter points out the specialties for repository support for MongoDB. This
[[mongo-repo-usage]]
== Usage
To access domain entities stored in a MongoDBm, you can use our sophisticated repository support that eases implementation quite significantly. To do so, create an interface for your repository, as the following example shows:
To access domain entities stored in a MongoDB, you can use our sophisticated repository support that eases implementation quite significantly. To do so, create an interface for your repository, as the following example shows:
.Sample Person entity
====
@@ -36,7 +36,7 @@ Note that the domain type shown in the preceding example has a property named `i
----
public interface PersonRepository extends PagingAndSortingRepository<Person, Long> {
// additional custom finder methods go here
// additional custom query methods go here
}
----
====
@@ -152,7 +152,7 @@ public interface PersonRepository extends PagingAndSortingRepository<Person, Str
<5> Uses a Java 8 `Stream` that reads and converts individual elements while iterating the stream.
====
NOTE: For version 1.0, we currently do not support referring to parameters that are mapped as `DBRef` in the domain class.
NOTE: We do not support referring to parameters that are mapped as `DBRef` in the domain class.
The following table shows the keywords that are supported for query methods:
@@ -317,7 +317,7 @@ public interface PersonRepository extends MongoRepository<Person, String>
----
====
Adding a `Distance` parameter to the query method allows restricting results to those within the given distance. If the `Distance` was set up containing a `Metric`, we transparently use `$nearSphere` instead of $code, as the following example shows:
Adding a `Distance` parameter to the query method allows restricting results to those within the given distance. If the `Distance` was set up containing a `Metric`, we transparently use `$nearSphere` instead of `$code`, as the following example shows:
.Using `Distance` with `Metrics`
====
@@ -365,7 +365,7 @@ public interface PersonRepository extends MongoRepository<Person, String>
[[mongodb.repositories.queries.json-based]]
=== MongoDB JSON-based Query Methods and Field Restriction
By adding the `org.springframework.data.mongodb.repository.Query` annotation to your repository finder methods, you can specify a MongoDB JSON query string to use instead of having the query be derived from the method name, as the following example shows:
By adding the `org.springframework.data.mongodb.repository.Query` annotation to your repository query methods, you can specify a MongoDB JSON query string to use instead of having the query be derived from the method name, as the following example shows:
[source,java]
----
@@ -393,7 +393,7 @@ public interface PersonRepository extends MongoRepository<Person, String>
}
----
The query in the preceding example returns only the `firstname`, `lastname` and `Id` properties of the `Person` objects. The `age` property, a java.lang.Integer, is not set and its value is therefore null.
The query in the preceding example returns only the `firstname`, `lastname` and `Id` properties of the `Person` objects. The `age` property, a `java.lang.Integer`, is not set and its value is therefore null.
[[mongodb.repositories.queries.json-spel]]
=== JSON-based Queries with SpEL Expressions
@@ -454,7 +454,7 @@ to pick up Query SPI extensions.
[[mongodb.repositories.queries.type-safe]]
=== Type-safe Query Methods
MongoDB repository support integrates with the http://www.querydsl.com/[QueryDSL] project, which provides a way to perform type-safe queries. To quote from the project description, "Instead of writing queries as inline strings or externalizing them into XML files they are constructed via a fluent API." It provides the following features:
MongoDB repository support integrates with the http://www.querydsl.com/[Querydsl] project, which provides a way to perform type-safe queries. To quote from the project description, "Instead of writing queries as inline strings or externalizing them into XML files they are constructed via a fluent API." It provides the following features:
* Code completion in the IDE (all properties, methods, and operations can be expanded in your favorite Java IDE).
* Almost no syntactically invalid queries allowed (type-safe on all levels).
@@ -477,11 +477,11 @@ Page<Person> page = repository.findAll(person.lastname.contains("a"),
`QPerson` is a class that is generated by the Java annotation post-processing tool. It is a `Predicate` that lets you write type-safe queries. Notice that there are no strings in the query other than the `C0123` value.
You can use the generated `Predicate` class by using the `QueryDslPredicateExecutor` interface, which the following listing shows:
You can use the generated `Predicate` class by using the `QuerydslPredicateExecutor` interface, which the following listing shows:
[source,java]
----
public interface QueryDslPredicateExecutor<T> {
public interface QuerydslPredicateExecutor<T> {
T findOne(Predicate predicate);
@@ -499,9 +499,9 @@ To use this in your repository implementation, add it to the list of repository
[source,java]
----
public interface PersonRepository extends MongoRepository<Person, String>, QueryDslPredicateExecutor<Person> {
public interface PersonRepository extends MongoRepository<Person, String>, QuerydslPredicateExecutor<Person> {
// additional finder methods go here
// additional query methods go here
}
----

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

@@ -3,7 +3,7 @@
The MongoDB support contains a wide range of features:
* Spring configuration support with Java-based @Configuration classes or an XML namespace for a Mongo driver instance and replica sets.
* Spring configuration support with Java-based `@Configuration` classes or an XML namespace for a Mongo driver instance and replica sets.
* `MongoTemplate` helper class that increases productivity when performing common Mongo operations. Includes integrated object mapping between documents and POJOs.
* Exception translation into Spring's portable Data Access Exception hierarchy.
* Feature-rich Object Mapping integrated with Spring's Conversion Service.
@@ -15,14 +15,14 @@ The MongoDB support contains a wide range of features:
* Cross-store persistence support for JPA Entities with fields transparently persisted and retrieved with MongoDB (deprecated - to be removed without replacement).
* GeoSpatial integration.
For most tasks, you should use `MongoTemplate` or the Repository support, which both leverage the rich mapping functionality. `MongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations. `MongoTemplate` also provides callback methods so that it is easy for you to get the low-level API artifacts, such as `com.mongo.DB`, to communicate directly with MongoDB. The goal with naming conventions on various API artifacts is to copy those in the base MongoDB Java driver so you can easily map your existing knowledge onto the Spring APIs.
For most tasks, you should use `MongoTemplate` or the Repository support, which both leverage the rich mapping functionality. `MongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations. `MongoTemplate` also provides callback methods so that it is easy for you to get the low-level API artifacts, such as `com.mongodb.client.MongoDatabase`, to communicate directly with MongoDB. The goal with naming conventions on various API artifacts is to copy those in the base MongoDB Java driver so you can easily map your existing knowledge onto the Spring APIs.
[[mongodb-getting-started]]
== Getting Started
Spring MongoDB support requires MongoDB 2.6 or higher and Java SE 8 or higher. An easy way to bootstrap setting up a working environment is to create a Spring-based project in http://spring.io/tools/sts[STS].
An easy way to bootstrap setting up a working environment is to create a Spring-based project in http://spring.io/tools/sts[STS].
First, you need to set up a running Mongodb server. Refer to the http://docs.mongodb.org/manual/core/introduction/[Mongodb Quick Start guide] for an explanation on how to startup a MongoDB instance. Once installed, starting MongoDB is typically a matter of running the following command: `MONGO_HOME/bin/mongod`
First, you need to set up a running MongoDB server. Refer to the http://docs.mongodb.org/manual/core/introduction/[MongoDB Quick Start guide] for an explanation on how to startup a MongoDB instance. Once installed, starting MongoDB is typically a matter of running the following command: `${MONGO_HOME}/bin/mongod`
To create a Spring project in STS:
@@ -152,7 +152,7 @@ When you run the main program, the preceding examples produce the following outp
Even in this simple example, there are few things to notice:
* You can instantiate the central helper class of Spring Mongo, <<mongo-template,`MongoTemplate`>>, by using the standard `com.mongodb.MongoClient` object and the name of the database to use.
* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See <<mongo.mapping,here>>.).
* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See <<mapping-chapter,here>>.).
* Conventions are used for handling the `id` field, converting it to be an `ObjectId` when stored in the database.
* Mapping conventions can use field access. Notice that the `Person` class has only getters.
* If the constructor argument names match the field names of the stored document, they are used to instantiate the object
@@ -160,7 +160,7 @@ Even in this simple example, there are few things to notice:
[[mongo.examples-repo]]
== Examples Repository
There is a https://github.com/spring-projects/spring-data-examples[Github repository with several examples] that you can download and play around with to get a feel for how the library works.
There is a https://github.com/spring-projects/spring-data-examples[GitHub repository with several examples] that you can download and play around with to get a feel for how the library works.
[[mongodb-connectors]]
== Connecting to MongoDB with Spring
@@ -191,7 +191,7 @@ public class AppConfig {
----
====
This approach lets you use the standard `com.mongodb.MongoClient` instance, with the container using Spring's `MongoClientFactoryBean`. As compared to instantiating a `com.mongodb.MongoClient` instance directly, the FactoryBean has the added advantage of also providing the container with an `ExceptionTranslator` implementation that translates MongoDB exceptions to exceptions in Spring's portable `DataAccessException` hierarchy for data access classes annotated with the `@Repository` annotation. This hierarchy and the use of `@Repository` is described in http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/data-access.html[Spring's DAO support features].
This approach lets you use the standard `com.mongodb.MongoClient` instance, with the container using Spring's `MongoClientFactoryBean`. As compared to instantiating a `com.mongodb.MongoClient` instance directly, the `FactoryBean` has the added advantage of also providing the container with an `ExceptionTranslator` implementation that translates MongoDB exceptions to exceptions in Spring's portable `DataAccessException` hierarchy for data access classes annotated with the `@Repository` annotation. This hierarchy and the use of `@Repository` is described in http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/data-access.html[Spring's DAO support features].
The following example shows an example of a Java-based bean metadata that supports exception translation on `@Repository` annotated classes:
@@ -234,13 +234,13 @@ To use the Mongo namespace elements, you need to reference the Mongo schema, as
xmlns:mongo="http://www.springframework.org/schema/data/mongo"
xsi:schemaLocation=
"http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-3.0.xsd
*http://www.springframework.org/schema/data/mongo http://www.springframework.org/schema/data/mongo/spring-mongo-1.0.xsd*
http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/data/mongo http://www.springframework.org/schema/data/mongo/spring-mongo.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
http://www.springframework.org/schema/beans/spring-beans.xsd">
<!-- Default bean name is 'mongo' -->
*<mongo:mongo-client host="localhost" port="27017"/>*
<mongo:mongo-client host="localhost" port="27017"/>
</beans>
----
@@ -285,7 +285,7 @@ The following example shows a configuration using replica sets:
[[mongo.mongo-db-factory]]
=== The MongoDbFactory Interface
While `com.mongodb.MongoClient` is the entry point to the MongoDB driver API, connecting to a specific MongoDB database instance requires additional information, such as the database name and an optional username and password. With that information, you can obtain a `com.mongodb.DB` object and access all the functionality of a specific MongoDB database instance. Spring provides the `org.springframework.data.mongodb.core.MongoDbFactory` interface, shown in the following listing, to bootstrap connectivity to the database:
While `com.mongodb.MongoClient` is the entry point to the MongoDB driver API, connecting to a specific MongoDB database instance requires additional information, such as the database name and an optional username and password. With that information, you can obtain a `com.mongodb.client.MongoDatabase` object and access all the functionality of a specific MongoDB database instance. Spring provides the `org.springframework.data.mongodb.core.MongoDbFactory` interface, shown in the following listing, to bootstrap connectivity to the database:
[source,java]
----
@@ -309,7 +309,7 @@ public class MongoApp {
public static void main(String[] args) throws Exception {
MongoOperations mongoOps = new MongoTemplate(*new SimpleMongoDbFactory(new MongoClient(), "database")*);
MongoOperations mongoOps = new MongoTemplate(new SimpleMongoDbFactory(new MongoClient(), "database"));
mongoOps.insert(new Person("Joe", 34));
@@ -368,7 +368,6 @@ The following example shows encoded credentials:
See https://tools.ietf.org/html/rfc3986#section-2.2[section 2.2 of RFC 3986] for further details.
[[mongo.mongo-db-factory-xml]]
=== Registering a `MongoDbFactory` Instance by Using XML-based Metadata
@@ -420,20 +419,20 @@ The `MongoTemplate` class implements the interface `MongoOperations`. In as much
NOTE: The preferred way to reference the operations on `MongoTemplate` instance is through its interface, `MongoOperations`.
The default converter implementation used by `MongoTemplate` is `MappingMongoConverter`. While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names. These conventions, as well as the use of mapping annotations, are explained in the "`<<mongo.mapping>`"> chapter.
The default converter implementation used by `MongoTemplate` is `MappingMongoConverter`. While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names. These conventions, as well as the use of mapping annotations, are explained in the "`<<mapping-chapter>>`" chapter.
Another central feature of `MongoTemplate` is translation of exceptions thrown by the MongoDB Java driver into Spring's portable Data Access Exception hierarchy. See "`<<mongo.exception>>`" for more information.
`MongoTemplate` offers many convenience methods to help you easily perform common tasks. However, if you need to directly access the MongoDB driver API, you can use one of several `Execute` callback methods. The execute callbacks gives you a reference to either a `com.mongodb.Collection` or a `com.mongodb.DB` object. See the mongo.executioncallback["`Execution Callbacks`"] section for more information.
`MongoTemplate` offers many convenience methods to help you easily perform common tasks. However, if you need to directly access the MongoDB driver API, you can use one of several `Execute` callback methods. The execute callbacks gives you a reference to either a `com.mongodb.client.MongoCollection` or a `com.mongodb.client.MongoDatabase` object. See the <<mongo.executioncallback,"`Execution Callbacks`">> section for more information.
The next section contains an example of how to work with the `MongoTemplate` in the context of the Spring container.
[[mongo-template.instantiating]]
=== Instantiating MongoTemplate
=== Instantiating `MongoTemplate`
You can use Java to create and register an instance of `MongoTemplate`, as the following example shows:
.Registering a com.mongodb.MongoClient object and enabling Spring's exception translation support
.Registering a `com.mongodb.MongoClient` object and enabling Spring's exception translation support
====
[source,java]
----
@@ -453,8 +452,8 @@ public class AppConfig {
There are several overloaded constructors of `MongoTemplate`:
* `MongoTemplate(MongoClient mongo, String databaseName)`: Takes the `com.mongodb.MongoClient` object and the default database name to operate against.
* `MongoTemplate(MongoDbFactory mongoDbFactory)`: Takes a MongoDbFactory object that encapsulated the `com.mongodb.MongoClient` object, database name, and username and password.
* `MongoTemplate(MongoClient mongo, String databaseName)`: Takes the `MongoClient` object and the default database name to operate against.
* `MongoTemplate(MongoDbFactory mongoDbFactory)`: Takes a MongoDbFactory object that encapsulated the `MongoClient` object, database name, and username and password.
* `MongoTemplate(MongoDbFactory mongoDbFactory, MongoConverter mongoConverter)`: Adds a `MongoConverter` to use for mapping.
You can also configure a MongoTemplate by using Spring's XML <beans/> schema, as the following example shows:
@@ -515,7 +514,7 @@ private class MyAppWriteConcernResolver implements WriteConcernResolver {
[[mongo-template.save-update-remove]]
== Saving, Updating, and Removing Documents
`MongoTemplate` provides lets you save, update, and delete your domain objects and map those objects to documents stored in MongoDB.
`MongoTemplate` lets you save, update, and delete your domain objects and map those objects to documents stored in MongoDB.
Consider the following class:
@@ -901,7 +900,7 @@ template.upsert(query(where("ssn").is(1111).and("firstName").is("Joe").and("Frai
[[mongo-template.find-and-upsert]]
=== Finding and Upserting Documents in a Collection
The `findAndModify(…)` method on `DBCollection` can update a document and return either the old or newly updated document in a single operation. `MongoTemplate` provides four `findAndModify` overloaded methods that take `Query` and `Update` classes and converts from `Document` to your POJOs:
The `findAndModify(…)` method on `MongoCollection` can update a document and return either the old or newly updated document in a single operation. `MongoTemplate` provides four `findAndModify` overloaded methods that take `Query` and `Update` classes and converts from `Document` to your POJOs:
[source,java]
----
@@ -1003,7 +1002,7 @@ template.save(tmp); // throws OptimisticLockingFailureException
<4> Try to update the previously loaded document that still has `version = 0`. The operation fails with an `OptimisticLockingFailureException`, as the current `version` is `1`.
====
IMPORTANT: Using MongoDB driver version 3 requires to set the `WriteConcern` to `ACKNOWLEDGED`. Otherwise `OptimisticLockingFailureException` can be silently swallowed.
IMPORTANT: Optimistic Locking requires to set the `WriteConcern` to `ACKNOWLEDGED`. Otherwise `OptimisticLockingFailureException` can be silently swallowed.
[[mongo.query]]
== Querying Documents
@@ -1096,9 +1095,9 @@ The `Query` class has some additional methods that provide options for the query
[[mongo-template.querying]]
=== Methods for Querying for Documents
The query methods need to specify the target type T that is returned, and they are overloaded with an explicit collection name for queries that should operate on a collection other than the one indicated by the return type. The following query methods let you find one or more documents:
The query methods need to specify the target type `T` that is returned, and they are overloaded with an explicit collection name for queries that should operate on a collection other than the one indicated by the return type. The following query methods let you find one or more documents:
* *findAll*: Query for a list of objects of type T from the collection.
* *findAll*: Query for a list of objects of type `T` from the collection.
* *findOne*: Map the results of an ad-hoc query on the collection to a single instance of an object of the specified type.
* *findById*: Return an object of the given ID and target class.
* *find*: Map the results of an ad-hoc query on the collection to a `List` of the specified type.
@@ -1218,7 +1217,7 @@ NearQuery query = NearQuery.near(location).maxDistance(new Distance(10, Metrics.
GeoResults<Restaurant> = operations.geoNear(query, Restaurant.class);
----
We use the `NearQuery` builder API to set up a query to return all `Restaurant` instances surrounding the given `Point` out to 10 miles. The `Metrics` enum used here actually implements an interface so that other metrics could be plugged into a distance as well. A `Metric` is backed by a multiplier to transform the distance value of the given metric into native distances. The sample shown here would consider the 10 to be miles. Using one of the built-in metrics (miles and kilometers) automatically triggers the spherical flag to be set on the query. If you want to avoid that, pass plain `double` values into `maxDistance(…)`. For more information, see the https://docs.spring.io/spring-data/mongodb/docs/current/api/index.html[JavaDoc] of `NearQuery` and `Distance`.
We use the `NearQuery` builder API to set up a query to return all `Restaurant` instances surrounding the given `Point` out to 10 miles. The `Metrics` enum used here actually implements an interface so that other metrics could be plugged into a distance as well. A `Metric` is backed by a multiplier to transform the distance value of the given metric into native distances. The sample shown here would consider the 10 to be miles. Using one of the built-in metrics (miles and kilometers) automatically triggers the spherical flag to be set on the query. If you want to avoid that, pass plain `double` values into `maxDistance(…)`. For more information, see the https://docs.spring.io/spring-data/mongodb/docs/{version}/api/index.html[JavaDoc] of `NearQuery` and `Distance`.
The geo-near operations return a `GeoResults` wrapper object that encapsulates `GeoResult` instances. Wrapping `GeoResults` allows accessing the average distance of all results. A single `GeoResult` object carries the entity found plus its distance from the origin.
@@ -1593,7 +1592,7 @@ public class ValueObject {
}
----
By default, the output type of INLINE is used so that you need not specify an output collection. To specify additional Map-Reduce options, use an overloaded method that takes an additional `MapReduceOptions` argument. The class `MapReduceOptions` has a fluent API, so adding additional options can be done in a compact syntax. The following example sets the output collection to `jmr1_out` (note that setting only the output collection assumes a default output type of `REPLACE`):
By default, the output type of `INLINE` is used so that you need not specify an output collection. To specify additional Map-Reduce options, use an overloaded method that takes an additional `MapReduceOptions` argument. The class `MapReduceOptions` has a fluent API, so adding additional options can be done in a compact syntax. The following example sets the output collection to `jmr1_out` (note that setting only the output collection assumes a default output type of `REPLACE`):
[source,java]
----
@@ -1643,7 +1642,7 @@ scriptOps.call("echo", "execute script via name"); <3>
[[mongo.group]]
== Group Operations
{JB}
As an alternative to using Map-Reduce to perform data aggregation, you can use the http://www.mongodb.org/display/DOCS/Aggregation#Aggregation-Group[`group` operation] which feels similar to using SQL's group by query style, so it may feel more approachable vs. using Map-Reduce. Using the group operations does have some limitations, for example it is not supported in a shared environment and it returns the full result set in a single BSON object, so the result should be small, less than 10,000 keys.
Spring provides integration with MongoDB's group operation by providing methods on MongoOperations to simplify the creation and execution of group operations. It can convert the results of the group operation to a POJO and also integrates with Spring's http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#resources[Resource abstraction] abstraction. This will let you place your JavaScript files on the file system, classpath, http server or any other Spring Resource implementation and then reference the JavaScript resources via an easy URI style syntax, e.g. 'classpath:reduce.js;. Externalizing JavaScript code in files if often preferable to embedding them as Java strings in your code. Note that you can still pass JavaScript code as Java strings if you prefer.
@@ -1871,11 +1870,11 @@ project("a","b").and("thing1").as("thing2")
// generates {$project: {name: 1, netPrice: 1}}, {$sort: {name: 1}}
project("name", "netPrice"), sort(ASC, "name")
// generates {$project: {thing2: $thing1}}, {$sort: {thing2: 1}}
project().and("thing1").as("thing2"), sort(ASC, "thing2")
// generates {$project: {name: $firstname}}, {$sort: {name: 1}}
project().and("firstname").as("name"), sort(ASC, "name")
// does not work
project().and("thing1").as("thing2"), sort(ASC, "thing1")
project().and("firstname").as("name"), sort(ASC, "firstname")
----
====
@@ -1888,7 +1887,7 @@ As of Version 3.4, MongoDB supports faceted classification by using the Aggregat
==== Buckets
Bucket operations categorize incoming documents into groups, called buckets, based on a specified expression and bucket boundaries. Bucket operations require a grouping field or a grouping expression. You can define them by using the `bucket()` and `bucketAuto()` methods of the `Aggregate` class. `BucketOperation` and `BucketAutoOperation` can expose accumulations based on aggregation expressions for input documents. You can extend the bucket operation with additional parameters through a fluent API by using the `with…()` methods and the `andOutput(String)` method. You can alias alias the operation by using the `as(String)` method. Each bucket is represented as a document in the output.
Bucket operations categorize incoming documents into groups, called buckets, based on a specified expression and bucket boundaries. Bucket operations require a grouping field or a grouping expression. You can define them by using the `bucket()` and `bucketAuto()` methods of the `Aggregate` class. `BucketOperation` and `BucketAutoOperation` can expose accumulations based on aggregation expressions for input documents. You can extend the bucket operation with additional parameters through a fluent API by using the `with…()` methods and the `andOutput(String)` method. You can alias the operation by using the `as(String)` method. Each bucket is represented as a document in the output.
`BucketOperation` takes a defined set of boundaries to group incoming documents into these categories. Boundaries are required to be sorted. The following listing shows some examples of bucket operations:
@@ -1969,7 +1968,7 @@ We support the use of SpEL expressions in projection expressions through the `an
===== Complex Calculations with SpEL expressions
Consier the following SpEL expression:
Consider the following SpEL expression:
[source,java]
----
@@ -2498,7 +2497,7 @@ The following example shows how to create a collection:
====
[source,java]
----
DBCollection collection = null;
MongoCollection<Document> collection = null;
if (!mongoTemplate.getCollectionNames().contains("MyNewCollection")) {
collection = mongoTemplate.createCollection("MyNewCollection");
}
@@ -2509,8 +2508,8 @@ mongoTemplate.dropCollection("MyNewCollection");
* *getCollectionNames*: Returns a set of collection names.
* *collectionExists*: Checks to see if a collection with a given name exists.
* *createCollection*: Creates an uncapped collection
* *dropCollection*: Drops the collection
* *createCollection*: Creates an uncapped collection.
* *dropCollection*: Drops the collection.
* *getCollection*: Gets a collection by name, creating it if it does not exist.
NOTE: Collection creation allows customization with `CollectionOptions` and supports <<mongo.collation,collations>>.
@@ -2530,7 +2529,7 @@ You can get at the MongoDB driver's `MongoDatabase.runCommand( )` method by usin
[[mongodb.mapping-usage.events]]
== Lifecycle Events
The MongoDB mapping framework includes several `org.springframework.context.ApplicationEvent` events that your application can respond to by registering special beans in the `ApplicationContext`. Being based off of Spring's `ApplicationContext` event infrastructure enables other products, such as Spring Integration, to easily receive these events, as they are a well known eventing mechanism in Spring-based applications.
The MongoDB mapping framework includes several `org.springframework.context.ApplicationEvent` events that your application can respond to by registering special beans in the `ApplicationContext`. Being based on Spring's `ApplicationContext` event infrastructure enables other products, such as Spring Integration, to easily receive these events, as they are a well known eventing mechanism in Spring-based applications.
To intercept an object before it goes through the conversion process (which turns your domain object into a `org.bson.Document`), you can register a subclass of `AbstractMongoEventListener` that overrides the `onBeforeConvert` method. When the event is dispatched, your listener is called and passed the domain object before it goes into the converter. The following example shows how to do so:
@@ -2584,7 +2583,7 @@ Some of the mappings performed by the `MongoExceptionTranslator` are `com.mongod
[[mongo.executioncallback]]
== Execution Callbacks
One common design feature of all Spring template classes is that all functionality is routed into one of the template's execute callback methods. Doing so helps to ensure that exceptions and any resource management that may be required are performed consistently. While JDBC and JMS need this feature much more than MongoDB does, it still offers a single spot for exception translation and logging to occur. Consequently, using these execute callbacks is the preferred way to access the MongoDB driver's `DB` and `DBCollection` objects to perform uncommon operations that were not exposed as methods on `MongoTemplate`.
One common design feature of all Spring template classes is that all functionality is routed into one of the template's execute callback methods. Doing so helps to ensure that exceptions and any resource management that may be required are performed consistently. While JDBC and JMS need this feature much more than MongoDB does, it still offers a single spot for exception translation and logging to occur. Consequently, using these execute callbacks is the preferred way to access the MongoDB driver's `MongoDatabase` and `MongoCollection` objects to perform uncommon operations that were not exposed as methods on `MongoTemplate`.
The following list describes the execute callback methods.
@@ -2729,4 +2728,4 @@ class GridFsClient {
----
====
`GridFsOperations` extends `ResourcePatternResolver` and lets the `GridFsTemplate` (for exmaple) to be plugged into an `ApplicationContext` to read Spring Config files from MongoDB database.
`GridFsOperations` extends `ResourcePatternResolver` and lets the `GridFsTemplate` (for example) to be plugged into an `ApplicationContext` to read Spring Config files from MongoDB database.

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

@@ -60,7 +60,7 @@ public interface ReactivePersonRepository extends ReactiveSortingRepository<Pers
Mono<Person> findFirstByLastname(String lastname); <5>
}
----
<1> The method shows a query for all people with the given `lastname`. The query us derived by parsing the method name for constraints that can be concatenated with `And` and `Or`. Thus, the method name results in a query expression of `{"lastname" : lastname}`.
<1> The method shows a query for all people with the given `lastname`. The query is derived by parsing the method name for constraints that can be concatenated with `And` and `Or`. Thus, the method name results in a query expression of `{"lastname" : lastname}`.
<2> The method shows a query for all people with the given `firstname` once the `firstname` is emitted by the given `Publisher`.
<3> Use `Pageable` to pass offset and sorting parameters to the database.
<4> Find a single entity for the given criteria. It completes with `IncorrectResultSizeDataAccessException` on non-unique results.
@@ -69,7 +69,7 @@ public interface ReactivePersonRepository extends ReactiveSortingRepository<Pers
For Java configuration, use the `@EnableReactiveMongoRepositories` annotation. The annotation carries the same attributes as the namespace element. If no base package is configured, the infrastructure scans the package of the annotated configuration class.
NOTE: MongoDB uses two different drivers for blocking and reactive (non-blocking) data access. You must create a connection by using the Reactive Streams driver to provide the required infrastructure for Spring Data's Reactive MongoDB support. Consequently, you must provide a separate configuration for MongoDB's Reactive Streams driver. Note that your application operates on two different connections if you use reactive and blocking Spring Data MongoDB templates and repositories.
NOTE: MongoDB uses two different drivers for imperative (synchronous/blocking) and reactive (non-blocking) data access. You must create a connection by using the Reactive Streams driver to provide the required infrastructure for Spring Data's Reactive MongoDB support. Consequently, you must provide a separate configuration for MongoDB's Reactive Streams driver. Note that your application operates on two different connections if you use reactive and blocking Spring Data MongoDB templates and repositories.
The following listing shows how to use Java configuration for a repository:
@@ -152,7 +152,7 @@ public interface PersonRepository extends ReactiveMongoRepository<Person, String
----
====
Adding a `Distance` parameter to the query method allows restricting results to those within the given distance. If the `Distance` was set up containing a `Metric`, we transparently use `$nearSphere` instead of $code, as the following example shows:
Adding a `Distance` parameter to the query method allows restricting results to those within the given distance. If the `Distance` was set up containing a `Metric`, we transparently use `$nearSphere` instead of `$code`, as the following example shows:
.Using `Distance` with `Metrics`
====
@@ -175,7 +175,7 @@ NOTE: Using `@GeoSpatialIndexed(type = GeoSpatialIndexType.GEO_2DSPHERE)` on the
==== Geo-near Queries
Spring Data MongoDb supports geo-near queries, as the following example shows:
Spring Data MongoDB supports geo-near queries, as the following example shows:
[source,java]
----

14
src/main/asciidoc/reference/reactive-mongodb.adoc
View File

@@ -4,13 +4,13 @@
The reactive MongoDB support contains the following basic set of features:
* Spring configuration support that uses Java-based `@Configuration` classes, a `MongoClient` instance, and replica sets.
* `ReactiveMongoTemplate`, which is a helper class that increases productivity by using `MongoOperations in a reactive manner. It includes integrated object mapping between `Document` instances and POJOs.
* `ReactiveMongoTemplate`, which is a helper class that increases productivity by using `MongoOperations` in a reactive manner. It includes integrated object mapping between `Document` instances and POJOs.
* Exception translation into Spring's portable Data Access Exception hierarchy.
* Feature-rich Object Mapping integrated with Spring's `ConversionService`.
* Annotation-based mapping metadata that is extensible to support other metadata formats.
* Persistence and mapping lifecycle events.
* Java based `Query`, `Criteria`, and `Update` DSLs.
* Automatic implementation of reactive repository interfaces including support for custom finder methods.
* Automatic implementation of reactive repository interfaces including support for custom query methods.
For most tasks, you should use `ReactiveMongoTemplate` or the repository support, both of which use the rich mapping functionality. `ReactiveMongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations. `ReactiveMongoTemplate` also provides callback methods so that you can use the low-level API artifacts (such as `MongoDatabase`) to communicate directly with MongoDB. The goal with naming conventions on various API artifacts is to copy those in the base MongoDB Java driver so that you can map your existing knowledge onto the Spring APIs.
@@ -19,7 +19,7 @@ For most tasks, you should use `ReactiveMongoTemplate` or the repository support
Spring MongoDB support requires MongoDB 2.6 or higher and Java SE 8 or higher.
First, you need to set up a running Mongodb server. Refer to the http://docs.mongodb.org/manual/core/introduction/[Mongodb Quick Start guide] for an explanation on how to startup a MongoDB instance. Once installed, starting MongoDB is typically a matter of executing the following command: `MONGO_HOME/bin/mongod`
First, you need to set up a running MongoDB server. Refer to the http://docs.mongodb.org/manual/core/introduction/[MongoDB Quick Start guide] for an explanation on how to startup a MongoDB instance. Once installed, starting MongoDB is typically a matter of executing the following command: `${MONGO_HOME}/bin/mongod`
To create a Spring project in STS, go to File -> New -> Spring Template Project -> Simple Spring Utility Project and press Yes when prompted. Then enter a project and a package name, such as org.spring.mongodb.example.
@@ -127,13 +127,13 @@ Running the preceding class produces the following output:
Even in this simple example, there are a few things to take notice of:
* You can instantiate the central helper class of Spring Mongo (<<mongo.reactive.template,`MongoTemplate`>>) by using the standard `com.mongodb.reactivestreams.client.MongoClient` object and the name of the database to use.
* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See <<mongo.mapping,here>>.).
* You can instantiate the central helper class of Spring Mongo (<<mongo.reactive.template,`ReactiveMongoTemplate`>>) by using the standard `com.mongodb.reactivestreams.client.MongoClient` object and the name of the database to use.
* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See <<mapping-chapter,here>>.).
* Conventions are used for handling the ID field, converting it to be an `ObjectId` when stored in the database.
* Mapping conventions can use field access. Notice that the `Person` class has only getters.
* If the constructor argument names match the field names of the stored document, they are used to instantiate the object
There is a https://github.com/spring-projects/spring-data-examples[github repository with several examples] that you can download and play around with to get a feel for how the library works.
There is a https://github.com/spring-projects/spring-data-examples[GitHub repository with several examples] that you can download and play around with to get a feel for how the library works.
[[mongo.reactive.driver]]
== Connecting to MongoDB with Spring and the Reactive Streams Driver
@@ -298,7 +298,7 @@ The `ReactiveMongoTemplate` class implements the `ReactiveMongoOperations` inter
NOTE: The preferred way to reference the operations on `ReactiveMongoTemplate` instance is through its `ReactiveMongoOperations` interface.
The default converter implementation used by `ReactiveMongoTemplate` is `MappingMongoConverter`. While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names. These conventions as well as the use of mapping annotations are explained in the <<mongo.mapping,Mapping chapter>>.
The default converter implementation used by `ReactiveMongoTemplate` is `MappingMongoConverter`. While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names. These conventions as well as the use of mapping annotations are explained in the <<mapping-chapter,Mapping chapter>>.
Another central feature of `ReactiveMongoTemplate` is exception translation of exceptions thrown in the MongoDB Java driver into Spring's portable Data Access Exception hierarchy. See the section on <<mongo.exception,exception translation>> for more information.