[[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.

NOTE: Please refer to the driver and database specific documentation for major differences between those.

NOTE: Operations that are no longer valid 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

[[mongo.mongo-3.configuration]]
=== Configuration Options

Some of the configuration options have been changed / removed for the _mongo-java-driver_. The following options will be ignored using the generation 3 driver:

 * autoConnectRetry
 * maxAutoConnectRetryTime
 * slaveOk

Generally it is recommended to use the `<mongo:mongo-client ... />` and `<mongo:client-options ... />` elements instead of `<mongo:mongo ... />` when doing XML based configuration, since those elements will only provide you with attributes valid for the 3 generation java driver.

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:mongo="http://www.springframework.org/schema/data/mongo"
	xsi:schemaLocation="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.xsd">

  <mongo:mongo-client host="127.0.0.1" port="27017">
    <mongo:client-options write-concern="NORMAL" />
  </mongo:mongo-client>

</beans>
----

[[mongo.mongo-3.write-concern]]
=== WriteConcern and WriteConcernChecking

The `WriteConcern.NONE`, which had been used as default by Spring Data MongoDB, was removed in 3.0. Therefore in a MongoDB 3 environment the `WriteConcern` will be defaulted to `WriteConcern.UNACKNOWLEGED`. In case `WriteResultChecking.EXCEPTION` is enabled the `WriteConcern` will be altered to `WriteConcern.ACKNOWLEDGED` for write operations, as otherwise errors during execution would not be throw correctly, since simply not raised by the driver.

[[mongo.mongo-3.authentication]]
=== Authentication

MongoDB Server generation 3 changed the authentication model when connecting to the DB. Therefore some of the configuration options available for authentication are no longer valid. Please use the `MongoClient` specific options for setting credentials via `MongoCredential` to provide authentication data.

[source,java]
----
@Configuration
public class ApplicationContextEventTestsAppConfig extends AbstractMongoConfiguration {

  @Override
  public String getDatabaseName() {
    return "database";
  }

  @Override
  @Bean
  public MongoClient mongoClient() {
    return new MongoClient(singletonList(new ServerAddress("127.0.0.1", 27017)),
      singletonList(MongoCredential.createCredential("name", "db", "pwd".toCharArray())));
  }
}
----

In order to use authentication with XML configuration use the `credentials` attribue on `<mongo-client>`.

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:mongo="http://www.springframework.org/schema/data/mongo"
	xsi:schemaLocation="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.xsd">

  <mongo:mongo-client credentials="user:password@database" />

</beans>
----

[[mongo.mongo-3.validation]]
=== Server-side Validation

MongoDB supports https://docs.mongodb.com/manual/core/schema-validation/[Schema Validation] as of version 3.2 with query operators
and as of version 3.6 JSON-schema based validation.

This chapter will point out the specialties for validation in MongoDB and how to apply JSON schema validation.

[[mongo.mongo-3.validation.json-schema]]
==== JSON Schema Validation

MongoDB 3.6 allows validation and querying of documents using JSON schema draft 4 including core specification and validation specification, with some differences. `$jsonSchema` can be used in a document validator (when creating a collection), which enforces that inserted or updated documents are valid against the schema. It can also be used to query for documents with the `find` command or `$match` aggregation stage.

Spring Data MongoDB supports MongoDB's specific JSON schema implementation to define and use schemas. See <<mongo.jsonSchema,JSON Schema>> for further details.

[[mongo.mongo-3.validation.query-expression]]
==== Query Expression Validation

Next to the <<mongo.mongo-3.validation.json-schema>>, MongoDB supports  as of version 3.2 validating documents against a given structure described by a query. The structure can be built using `Criteria` objects just the same way as they are used for defining queries.

[source,java]
----
Criteria queryExpression = Criteria.where("lastname").ne(null).type(2)
    .and("age").ne(null).type(16).gt(0).lte(150);

Validator validator = Validator.criteria(queryExpression);

template.createCollection(Person.class, CollectionOptions.empty().validator(validator));
----

NOTE: Field names used within the query expression are mapped to the domain types property names taking potential `@Field` annotations into account.

[[mongo.mongo-3.misc]]
=== Other things to be aware of

This section covers additional things to keep in mind when using the 3.0 driver.

* `IndexOperations.resetIndexCache()` is no longer supported.
* Any `MapReduceOptions.extraOption` is silently ignored.
* `WriteResult` does not longer hold error information but throws an Exception.
* `MongoOperations.executeInSession(…)` no longer calls `requestStart` / `requestDone`.
* Index name generation has become a driver internal operations, still we use the 2.x schema to generate names.
* Some Exception messages differ between the generation 2 and 3 servers as well as between _MMap.v1_ and _WiredTiger_ storage engine.

