Replace leftovers to Mongo 2.x API with Document and MongoDatabase references and tweak Javadoc. Reorder field declarations to class header. Reflect 3.0 versions in schema configuration. Add TODO markers to disabled tests.
Reflect changes in documentation.
Enable disabled test.
Original pull request: #823.
@ -39,20 +39,23 @@ The starting point for learning about MongoDB is https://www.mongodb.org/[www.mo
[[requirements]]
[[requirements]]
== Requirements
== Requirements
The Spring Data MongoDB 2.x binaries require JDK level 8.0 and above and https://spring.io/docs[Spring Framework] {springVersion} and above.
The Spring Data MongoDB 3.x binaries require JDK level 8.0 and above and https://spring.io/docs[Spring Framework] {springVersion} and above.
In terms of document stores, you need at least version 2.6 of https://www.mongodb.org/[MongoDB].
In terms of document stores, you need at least version 2.6 of https://www.mongodb.org/[MongoDB].
[[get-started:help]]
[[get-started:help]]
== Additional Help Resources
== Additional Help Resources
Learning a new framework is not always straightforward. In this section, we try to provide what we think is an easy-to-follow guide for starting with the Spring Data MongoDB module. However, if you encounter issues or you need advice, feel free to use one of the following links:
Learning a new framework is not always straightforward.
In this section, we try to provide what we think is an easy-to-follow guide for starting with the Spring Data MongoDB module.
However, if you encounter issues or you need advice, feel free to use one of the following links:
[[get-started:help:community]]
[[get-started:help:community]]
Community Forum :: Spring Data on https://stackoverflow.com/questions/tagged/spring-data[Stack Overflow] is a tag for all Spring Data (not just Document) users to share information and help each other. Note that registration is needed only for posting.
Community Forum :: Spring Data on https://stackoverflow.com/questions/tagged/spring-data[Stack Overflow] is a tag for all Spring Data (not just Document) users to share information and help each other.
Note that registration is needed only for posting.
[[get-started:help:professional]]
[[get-started:help:professional]]
Professional Support :: Professional, from-the-source support, with guaranteed response time, is available from https://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring.
Professional Support :: Professional, from-the-source support, with guaranteed response time, is available from https://pivotal.io/[Pivotal Software, Inc.], the company behind Spring Data and Spring.
@ -769,7 +767,7 @@ To selectively handle the conversion yourself, register one or more one or more
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`"].
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 `AbstractMongoConfiguration` to configure converters. The examples <<mapping-configuration, at the beginning of this chapter>> show how to perform the configuration using Java and XML.
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:
The following example of a Spring Converter implementation converts from a `Document` to a `Person` POJO:
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.
Spring Data MongoDB requires MongoDB Java driver generations 4 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.
NOTE: See the driver- and database-specific documentation for major differences between those engines.
NOTE: Operations that are no longer valid when using a 3.x MongoDB Java driver have been deprecated within Spring Data and will be removed in a subsequent release.
== Using Spring Data MongoDB with MongoDB 3.0
== Using Spring Data MongoDB with MongoDB 3.0
The rest of this section describes how to use Spring Data MongoDB with MongoDB 3.0.
The rest of this section describes how to use Spring Data MongoDB with MongoDB 3.0.
@ -51,7 +49,7 @@ MongoDB Server generation 3 changed the authentication model when connecting to
[source,java]
[source,java]
----
----
@Configuration
@Configuration
public class ApplicationContextEventTestsAppConfig extends AbstractMongoConfiguration {
public class ApplicationContextEventTestsAppConfig extends AbstractMongoClientConfiguration {
@Override
@Override
public String getDatabaseName() {
public String getDatabaseName() {
@ -118,11 +116,12 @@ NOTE: The field names used within the query expression are mapped to the domain
[[mongo.mongo-3.misc]]
[[mongo.mongo-3.misc]]
=== Miscellaneous Details
=== Miscellaneous Details
This section covers briefly lists additional things to keep in mind when using the 3.0 driver:
This section covers briefly lists additional things to keep in mind when using the 4.0 driver:
* `IndexOperations.resetIndexCache()` is no longer supported.
* `IndexOperations.resetIndexCache()` is no longer supported.
* Any `MapReduceOptions.extraOption` is silently ignored.
* Any `MapReduceOptions.extraOption` is silently ignored.
* `WriteResult` no longer holds error information but, instead, throws an `Exception`.
* `WriteResult` no longer holds error information but, instead, throws an `Exception`.
* `MongoOperations.executeInSession(…)` no longer calls `requestStart` and `requestDone`.
* `MongoOperations.executeInSession(…)` no longer calls `requestStart` and `requestDone`.
* Index name generation has become a driver-internal operation. Spring Data MongoDB still uses the 2.x schema to generate names.
* Index name generation has become a driver-internal operation.
Spring Data MongoDB still uses the 2.x schema to generate names.
* Some `Exception` messages differ between the generation 2 and 3 servers as well as between the MMap.v1 and WiredTiger storage engines.
* Some `Exception` messages differ between the generation 2 and 3 servers as well as between the MMap.v1 and WiredTiger storage engines.
@ -165,7 +165,7 @@ There is a https://github.com/spring-projects/spring-data-examples[GitHub reposi
[[mongodb-connectors]]
[[mongodb-connectors]]
== Connecting to MongoDB with Spring
== Connecting to MongoDB with Spring
One of the first tasks when using MongoDB and Spring is to create a `com.mongodb.client.MongoClient` or `com.mongodb.client.MongoClient` object using the IoC container. There are two main ways to do this, either by using Java-based bean metadata or by using XML-based bean metadata. Both are discussed in the following sections.
One of the first tasks when using MongoDB and Spring is to create a `com.mongodb.client.MongoClient` object using the IoC container. There are two main ways to do this, either by using Java-based bean metadata or by using XML-based bean metadata. Both are discussed in the following sections.
NOTE: For those not familiar with how to configure the Spring container using Java-based bean metadata instead of XML-based metadata, see the high-level introduction in the reference docs https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/new-in-3.0.html#new-java-configuration[here] as well as the detailed documentation https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#beans-java-instantiating-container[here].
NOTE: For those not familiar with how to configure the Spring container using Java-based bean metadata instead of XML-based metadata, see the high-level introduction in the reference docs https://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/new-in-3.0.html#new-java-configuration[here] as well as the detailed documentation https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#beans-java-instantiating-container[here].
@ -230,11 +230,9 @@ To use the Mongo namespace elements, you need to reference the Mongo schema, as
@ -281,21 +279,21 @@ The following example shows a configuration using replica sets:
====
====
[[mongo.mongo-db-factory]]
[[mongo.mongo-db-factory]]
=== The MongoDbFactory Interface
=== The MongoDatabaseFactory Interface
While `com.mongodb.client.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:
While `com.mongodb.client.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.MongoDatabaseFactory` interface, shown in the following listing, to bootstrap connectivity to the database:
The following sections show how you can use the container with either Java-based or XML-based metadata to configure an instance of the `MongoDbFactory` interface. In turn, you can use the `MongoDbFactory` instance to configure `MongoTemplate`.
The following sections show how you can use the container with either Java-based or XML-based metadata to configure an instance of the `MongoDatabaseFactory` interface. In turn, you can use the `MongoDatabaseFactory` instance to configure `MongoTemplate`.
Instead of using the IoC container to create an instance of MongoTemplate, you can use them in standard Java code, as follows:
Instead of using the IoC container to create an instance of MongoTemplate, you can use them in standard Java code, as follows:
@ -307,7 +305,7 @@ public class MongoApp {
public static void main(String[] args) throws Exception {
public static void main(String[] args) throws Exception {
MongoOperations mongoOps = new MongoTemplate(new SimpleMongoClientDbFactory(MongoClients.create(), "database"));
MongoOperations mongoOps = new MongoTemplate(new SimpleMongoClientDatabaseFactory(MongoClients.create(), "database"));
mongoOps.insert(new Person("Joe", 34));
mongoOps.insert(new Person("Joe", 34));
@ -323,17 +321,17 @@ The code in bold highlights the use of `SimpleMongoClientDbFactory` and is the o
NOTE: Use `SimpleMongoClientDbFactory` when choosing `com.mongodb.client.MongoClient` as the entrypoint of choice.
NOTE: Use `SimpleMongoClientDbFactory` when choosing `com.mongodb.client.MongoClient` as the entrypoint of choice.
[[mongo.mongo-db-factory-java]]
[[mongo.mongo-db-factory-java]]
=== Registering a `MongoDbFactory` Instance by Using Java-based Metadata
=== Registering a `MongoDatabaseFactory` Instance by Using Java-based Metadata
To register a `MongoDbFactory` instance with the container, you write code much like what was highlighted in the previous code listing. The following listing shows a simple example:
To register a `MongoDatabaseFactory` instance with the container, you write code much like what was highlighted in the previous code listing. The following listing shows a simple example:
[source,java]
[source,java]
----
----
@Configuration
@Configuration
public class MongoConfiguration {
public class MongoConfiguration {
public @Bean MongoDbFactory mongoDbFactory() {
public @Bean MongoDatabaseFactory mongoDatabaseFactory() {
return new SimpleMongoClientDbFactory(MongoClients.create(), "database");
return new SimpleMongoClientDatabaseFactory(MongoClients.create(), "database");
}
}
}
}
----
----
@ -391,7 +389,7 @@ public class MongoClientConfiguration extends AbstractMongoClientConfiguration {
----
----
[[mongo.mongo-db-factory-xml]]
[[mongo.mongo-db-factory-xml]]
=== Registering a `MongoDbFactory` Instance by Using XML-based Metadata
=== Registering a `MongoDatabaseFactory` Instance by Using XML-based Metadata
The `mongo` namespace provides a convenient way to create a `SimpleMongoClientDbFactory`, as compared to using the `<beans/>` namespace, as shown in the following example:
The `mongo` namespace provides a convenient way to create a `SimpleMongoClientDbFactory`, as compared to using the `<beans/>` namespace, as shown in the following example:
@ -470,12 +468,12 @@ public class AppConfig {
There are several overloaded constructors of `MongoTemplate`:
There are several overloaded constructors of `MongoTemplate`:
* `MongoTemplate(MongoClient mongo, String databaseName)`: Takes the `MongoClient` object and the default database name to operate against.
* `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(MongoDatabaseFactory 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.
* `MongoTemplate(MongoDatabaseFactory 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:
You can also configure a MongoTemplate by using Spring's XML <beans/> schema, as the following example shows:
@ -3270,7 +3268,7 @@ boolean hasIndex = template.execute("geolocation", new CollectionCallbackBoolean
[[gridfs]]
[[gridfs]]
== GridFS Support
== GridFS Support
MongoDB supports storing binary files inside its filesystem, GridFS. Spring Data MongoDB provides a `GridFsOperations` interface as well as the corresponding implementation, `GridFsTemplate`, to let you interact with the filesystem. You can set up a `GridFsTemplate` instance by handing it a `MongoDbFactory` as well as a `MongoConverter`, as the following example shows:
MongoDB supports storing binary files inside its filesystem, GridFS. Spring Data MongoDB provides a `GridFsOperations` interface as well as the corresponding implementation, `GridFsTemplate`, to let you interact with the filesystem. You can set up a `GridFsTemplate` instance by handing it a `MongoDatabaseFactory` as well as a `MongoConverter`, as the following example shows:
Mark Paluch
6 years ago