Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Replace upgrading section in documentation with links to the release …
…notes. Closes: #4228
- Loading branch information
1 parent
cbc718e
commit 62f3656
Showing
2 changed files
with
12 additions
and
364 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,231 +1,10 @@ | ||
| [[upgrading.2-3]] | ||
| = Upgrading from 2.x to 3.x | ||
| [[upgrading.data-mongo]] | ||
| = Upgrading | ||
|
|
||
| Spring Data MongoDB 3.x requires the MongoDB Java Driver 4.x. + | ||
| The 4.0 MongoDB Java Driver does no longer support certain features that have already been deprecated in one of the last minor versions. | ||
| Some of the changes affect the initial setup configuration as well as compile/runtime features. | ||
| We summarized the most typical changes one might encounter. | ||
| include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1] | ||
|
|
||
| Things to keep in mind when using the 4.0 driver: | ||
| [[upgrading.3-4]] | ||
| == Upgrading MongoDB Drivers | ||
|
|
||
| * `IndexOperations.resetIndexCache()` is no longer supported. | ||
| * Any `MapReduceOptions.extraOption` is silently ignored. | ||
| * `WriteResult` no longer holds error information but, instead, throws an `Exception`. | ||
| * `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. | ||
| * Some `Exception` messages differ between the generation 2 and 3 servers as well as between the MMap.v1 and WiredTiger storage engines. | ||
|
|
||
| == Dependency Changes | ||
|
|
||
| Instead of the single artifact uber-jar `mongo-java-driver`, imports are now split to include separate artifacts: | ||
|
|
||
| * `org.mongodb:mongodb-driver-core` (required) | ||
| * `org.mongodb:mongodb-driver-sync` (optional) | ||
| * `org.mongodb:mongodb-driver-reactivestreams` (optional) | ||
|
|
||
| Depending on the application one of the `mongodb-driver-sync`, `mongodb-driver-reactivestreams` artifacts is is required next to the mandatory `mongodb-driver-core`. | ||
| It is possible to combine the sync and reactive drivers in one application if needed. | ||
|
|
||
| == Java Configuration | ||
|
|
||
| .Java API changes | ||
| |=== | ||
| Type | Comment | ||
|
|
||
| | `MongoClientFactoryBean` | ||
| | Creates `com.mongodb.client.MongoClient` instead of `com.mongodb.MongoClient` + | ||
| Uses `MongoClientSettings` instead of `MongoClientOptions`. | ||
|
|
||
| | `MongoDataIntegrityViolationException` | ||
| | Uses `WriteConcernResult` instead of `WriteResult`. | ||
|
|
||
| | `BulkOperationException` | ||
| | Uses `MongoBulkWriteException` and `com.mongodb.bulk.BulkWriteError` instead of `BulkWriteException` and `com.mongodb.BulkWriteError` | ||
|
|
||
| | `ReactiveMongoClientFactoryBean` | ||
| | Uses `com.mongodb.MongoClientSettings` instead of `com.mongodb.async.client.MongoClientSettings` | ||
|
|
||
| | `ReactiveMongoClientSettingsFactoryBean` | ||
| | Now produces `com.mongodb.MongoClientSettings` instead of `com.mongodb.async.client.MongoClientSettings` | ||
|
|
||
| | `AbstractMongoClientConfiguration`, `AbstractReactiveMongoConfiguration` | ||
| | Configuration methods use parameter injection instead of calling local methods to avoid the need for cglib proxies | ||
| |=== | ||
|
|
||
| .Removed Java API: | ||
| |=== | ||
| 2.x | Replacement in 3.x | Comment | ||
|
|
||
| | `MongoClientOptionsFactoryBean` | ||
| | `MongoClientSettingsFactoryBean` | ||
| | Creating a `com.mongodb.MongoClientSettings`. | ||
|
|
||
| | `AbstractMongoConfiguration` | ||
| | `AbstractMongoClientConfiguration` + | ||
| (Available since 2.1) | ||
| | Using `com.mongodb.client.MongoClient`. | ||
|
|
||
| | `MongoDbFactory#getLegacyDb()` | ||
| | - | ||
| | - | ||
|
|
||
| | `SimpleMongoDbFactory` | ||
| | `SimpleMongoClientDbFactory` + | ||
| (Available since 2.1) | ||
| | | ||
|
|
||
| | `MapReduceOptions#getOutputType()` | ||
| | `MapReduceOptions#getMapReduceAction()` | ||
| | Returns `MapReduceAction` instead of `MapReduceCommand.OutputType`. | ||
|
|
||
| | `Meta\|Query` maxScan & snapshot | ||
| | | ||
| | | ||
| |=== | ||
|
|
||
| == XML Namespace | ||
|
|
||
| .Changed XML Namespace Elements and Attributes: | ||
| |=== | ||
| Element / Attribute | 2.x | 3.x | ||
|
|
||
| | `<mongo:mongo-client />` | ||
| | Used to create a `com.mongodb.MongoClient` | ||
| | Now exposes a `com.mongodb.client.MongoClient` | ||
|
|
||
| | `<mongo:mongo-client replica-set="..." />` | ||
| | Was a comma delimited list of replica set members (host/port) | ||
| | Now defines the replica set name. + | ||
| Use `<mongo:client-settings cluster-hosts="..." />` instead | ||
|
|
||
| | `<mongo:db-factory writeConcern="..." />` | ||
| | NONE, NORMAL, SAFE, FSYNC_SAFE, REPLICAS_SAFE, MAJORITY | ||
| | W1, W2, W3, UNAKNOWLEDGED, AKNOWLEDGED, JOURNALED, MAJORITY | ||
| |=== | ||
|
|
||
| .Removed XML Namespace Elements and Attributes: | ||
| |=== | ||
| Element / Attribute | Replacement in 3.x | Comment | ||
|
|
||
| | `<mongo:db-factory mongo-ref="..." />` | ||
| | `<mongo:db-factory mongo-client-ref="..." />` | ||
| | Referencing a `com.mongodb.client.MongoClient`. | ||
|
|
||
| | `<mongo:mongo-client credentials="..." />` | ||
| | `<mongo:mongo-client credential="..." />` | ||
| | Single authentication data instead of list. | ||
|
|
||
| | `<mongo:client-options />` | ||
| | `<mongo:client-settings />` | ||
| | See `com.mongodb.MongoClientSettings` for details. | ||
| |=== | ||
|
|
||
| .New XML Namespace Elements and Attributes: | ||
| |=== | ||
| Element | Comment | ||
|
|
||
| | `<mongo:db-factory mongo-client-ref="..." />` | ||
| | Replacement for `<mongo:db-factory mongo-ref="..." />` | ||
|
|
||
| | `<mongo:db-factory connection-string="..." />` | ||
| | Replacement for `uri` and `client-uri`. | ||
|
|
||
| | `<mongo:mongo-client connection-string="..." />` | ||
| | Replacement for `uri` and `client-uri`. | ||
|
|
||
| | `<mongo:client-settings />` | ||
| | Namespace element for `com.mongodb.MongoClientSettings`. | ||
|
|
||
| |=== | ||
|
|
||
| .Deprecations: | ||
| |=== | ||
| 2.x | Replacement in 3.x | Comment | ||
|
|
||
| | `MongoDbFactorySupport` | ||
| | `MongoDatabaseFactorySupport` | ||
| | | ||
|
|
||
| | `SimpleMongoClientDbFactory` | ||
| | `SimpleMongoClientDatabaseFactory` | ||
| | | ||
|
|
||
| | `MongoDbFactory` | ||
| | `MongoDatabaseFactory` | ||
| | | ||
|
|
||
| |=== | ||
|
|
||
| == Other Changes | ||
|
|
||
| === Auto Index Creation | ||
|
|
||
| Annotation based index creation is now turned **OFF** by default and needs to be enabled eg. when relying on `@GeoSpatialIndexed`. | ||
| Please refer to <<mapping.index-creation>> on how to create indexes programmatically. | ||
|
|
||
| .Enable Auto Index Creation | ||
| ==== | ||
| .Java | ||
| [source,java,role="primary"] | ||
| ---- | ||
| @Configuration | ||
| public class Config extends AbstractMongoClientConfiguration { | ||
| @Override | ||
| protected boolean autoIndexCreation() { | ||
| return true; | ||
| } | ||
| // ... | ||
| } | ||
| ---- | ||
| .XML | ||
| [source,xml,role="secondary"] | ||
| ---- | ||
| <mongo:mapping-converter auto-index-creation="true" /> | ||
| ---- | ||
| .Programmatic | ||
| [source,java,role="secondary"] | ||
| ---- | ||
| MongoDatabaseFactory dbFactory = new SimpleMongoClientDatabaseFactory(...); | ||
| DefaultDbRefResolver dbRefResolver = new DefaultDbRefResolver(dbFactory); | ||
| MongoMappingContext mappingContext = new MongoMappingContext(); | ||
| mappingContext.setAutoIndexCreation(true); | ||
| // ... | ||
| mappingContext.afterPropertiesSet(); | ||
| MongoTemplate template = new MongoTemplate(dbFactory, new MappingMongoConverter(dbRefResolver, mappingContext)); | ||
| ---- | ||
| ==== | ||
|
|
||
| === UUID Types | ||
|
|
||
| The MongoDB UUID representation can now be configured with different formats. | ||
| This has to be done via `MongoClientSettings` as shown in the snippet below. | ||
|
|
||
| .UUid Codec Configuration | ||
| ==== | ||
| [source,java] | ||
| ---- | ||
| @Configuration | ||
| public class Config extends AbstractMongoClientConfiguration { | ||
| @Override | ||
| public void configureClientSettings(MongoClientSettings.Builder builder) { | ||
| builder.uuidRepresentation(UuidRepresentation.STANDARD); | ||
| } | ||
| // ... | ||
| } | ||
| ---- | ||
| ==== | ||
|
|
||
| === Deferred MongoDatabase lookup in `ReactiveMongoDatabaseFactory` | ||
|
|
||
| `ReactiveMongoDatabaseFactory` now returns `Mono<MongoDatabase>` instead of `MongoDatabase` to allow access to the Reactor Subscriber context to enable context-specific routing functionality. | ||
|
|
||
| This change affects `ReactiveMongoTemplate.getMongoDatabase()` and `ReactiveMongoTemplate.getCollection()` so both methods must follow deferred retrieval. | ||
| Spring Data MongoDB 4.x requires the MongoDB Java Driver 4.8.x + | ||
| To learn more about driver versions please visit the https://www.mongodb.com/docs/drivers/java/sync/current/upgrade/[MongoDB Documentation]. |