diff --git a/README.adoc b/README.adoc index 39d5ff0cf6..c7f510c082 100644 --- a/README.adoc +++ b/README.adoc @@ -93,142 +93,11 @@ and declare the appropriate dependency version. ---- -== Upgrading from 2.x +[[upgrading]] +== Upgrading -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. - -=== XML Namespace - -.Changed XML Namespace Elements and Attributes: -|=== -| Element / Attribute | 2.x | 3.x - -| `` -| Used to create a `com.mongodb.MongoClient` -| Now exposes a `com.mongodb.client.MongoClient` - -| `` -| Was a comma delimited list of replica set members (host/port) -| Now defines the replica set name. + -Use `` instead - -| `` -| NONE, NORMAL, SAFE, FSYNC_SAFE, REPLICAS_SAFE, MAJORITY -| W1, W2, W3, UNACKNOWLEDGED, ACKNOWLEDGED, JOURNALED, MAJORITY -|=== - -.Removed XML Namespace Elements and Attributes: -|=== -| Element / Attribute | Replacement in 3.x | Comment - -| `` -| `` -| Referencing a `com.mongodb.client.MongoClient`. - -| `` -| `` -| Single authentication data instead of list. - -| `` -| `` -| See `com.mongodb.MongoClientSettings` for details. -|=== - -.New XML Namespace Elements and Attributes: -|=== -| Element | Comment - -| `` -| Replacement for `` - -| `` -| Replacement for `uri` and `client-uri`. - -| `` -| Replacement for `uri` and `client-uri`. - -| `` -| Namespace element for `com.mongodb.MongoClientSettings`. - -|=== - -=== 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` -|=== - -.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 -| -| -|=== - -=== Other Changes - -==== 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] ----- -static class Config extends AbstractMongoClientConfiguration { - - @Override - public void configureClientSettings(MongoClientSettings.Builder builder) { - builder.uuidRepresentation(UuidRepresentation.STANDARD); - } - - // ... -} ----- -==== +Instructions for how to upgrade from earlier versions of Spring Data are provided on the project https://github.com/spring-projects/spring-data-commons/wiki[wiki]. +Follow the links in the https://github.com/spring-projects/spring-data-commons/wiki#release-notes[release notes section] to find the version that you want to upgrade to. [[getting-help]] == Getting Help @@ -313,7 +182,7 @@ To initialize the replica set, start a mongo client: [source,bash] ---- $ $MONGODB_HOME/bin/mongo -MongoDB server version: 5.0.0 +MongoDB server version: 6.0.0 ... ---- diff --git a/src/main/asciidoc/upgrading.adoc b/src/main/asciidoc/upgrading.adoc index 42eb7ad5b8..b710c5bfb0 100644 --- a/src/main/asciidoc/upgrading.adoc +++ b/src/main/asciidoc/upgrading.adoc @@ -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 - -| `` -| Used to create a `com.mongodb.MongoClient` -| Now exposes a `com.mongodb.client.MongoClient` - -| `` -| Was a comma delimited list of replica set members (host/port) -| Now defines the replica set name. + -Use `` instead - -| `` -| 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 - -| `` -| `` -| Referencing a `com.mongodb.client.MongoClient`. - -| `` -| `` -| Single authentication data instead of list. - -| `` -| `` -| See `com.mongodb.MongoClientSettings` for details. -|=== - -.New XML Namespace Elements and Attributes: -|=== -Element | Comment - -| `` -| Replacement for `` - -| `` -| Replacement for `uri` and `client-uri`. - -| `` -| Replacement for `uri` and `client-uri`. - -| `` -| 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 <> 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"] ----- - ----- - -.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` 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].