|
1 | | -[[upgrading.2-3]] |
2 | | -= Upgrading from 2.x to 3.x |
| 1 | +[[upgrading.data-mongo]] |
| 2 | += Upgrading |
3 | 3 |
|
4 | | -Spring Data MongoDB 3.x requires the MongoDB Java Driver 4.x. + |
5 | | -The 4.0 MongoDB Java Driver does no longer support certain features that have already been deprecated in one of the last minor versions. |
6 | | -Some of the changes affect the initial setup configuration as well as compile/runtime features. |
7 | | -We summarized the most typical changes one might encounter. |
| 4 | +include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1] |
8 | 5 |
|
9 | | -Things to keep in mind when using the 4.0 driver: |
| 6 | +[[upgrading.3-4]] |
| 7 | +== Upgrading MongoDB Drivers |
10 | 8 |
|
11 | | -* `IndexOperations.resetIndexCache()` is no longer supported. |
12 | | -* Any `MapReduceOptions.extraOption` is silently ignored. |
13 | | -* `WriteResult` no longer holds error information but, instead, throws an `Exception`. |
14 | | -* `MongoOperations.executeInSession(…)` no longer calls `requestStart` and `requestDone`. |
15 | | -* Index name generation has become a driver-internal operation. |
16 | | -Spring Data MongoDB still uses the 2.x schema to generate names. |
17 | | -* Some `Exception` messages differ between the generation 2 and 3 servers as well as between the MMap.v1 and WiredTiger storage engines. |
18 | | - |
19 | | -== Dependency Changes |
20 | | - |
21 | | -Instead of the single artifact uber-jar `mongo-java-driver`, imports are now split to include separate artifacts: |
22 | | - |
23 | | -* `org.mongodb:mongodb-driver-core` (required) |
24 | | -* `org.mongodb:mongodb-driver-sync` (optional) |
25 | | -* `org.mongodb:mongodb-driver-reactivestreams` (optional) |
26 | | - |
27 | | -Depending on the application one of the `mongodb-driver-sync`, `mongodb-driver-reactivestreams` artifacts is is required next to the mandatory `mongodb-driver-core`. |
28 | | -It is possible to combine the sync and reactive drivers in one application if needed. |
29 | | - |
30 | | -== Java Configuration |
31 | | - |
32 | | -.Java API changes |
33 | | -|=== |
34 | | -Type | Comment |
35 | | - |
36 | | -| `MongoClientFactoryBean` |
37 | | -| Creates `com.mongodb.client.MongoClient` instead of `com.mongodb.MongoClient` + |
38 | | -Uses `MongoClientSettings` instead of `MongoClientOptions`. |
39 | | - |
40 | | -| `MongoDataIntegrityViolationException` |
41 | | -| Uses `WriteConcernResult` instead of `WriteResult`. |
42 | | - |
43 | | -| `BulkOperationException` |
44 | | -| Uses `MongoBulkWriteException` and `com.mongodb.bulk.BulkWriteError` instead of `BulkWriteException` and `com.mongodb.BulkWriteError` |
45 | | - |
46 | | -| `ReactiveMongoClientFactoryBean` |
47 | | -| Uses `com.mongodb.MongoClientSettings` instead of `com.mongodb.async.client.MongoClientSettings` |
48 | | - |
49 | | -| `ReactiveMongoClientSettingsFactoryBean` |
50 | | -| Now produces `com.mongodb.MongoClientSettings` instead of `com.mongodb.async.client.MongoClientSettings` |
51 | | - |
52 | | -| `AbstractMongoClientConfiguration`, `AbstractReactiveMongoConfiguration` |
53 | | -| Configuration methods use parameter injection instead of calling local methods to avoid the need for cglib proxies |
54 | | -|=== |
55 | | - |
56 | | -.Removed Java API: |
57 | | -|=== |
58 | | -2.x | Replacement in 3.x | Comment |
59 | | - |
60 | | -| `MongoClientOptionsFactoryBean` |
61 | | -| `MongoClientSettingsFactoryBean` |
62 | | -| Creating a `com.mongodb.MongoClientSettings`. |
63 | | - |
64 | | -| `AbstractMongoConfiguration` |
65 | | -| `AbstractMongoClientConfiguration` + |
66 | | -(Available since 2.1) |
67 | | -| Using `com.mongodb.client.MongoClient`. |
68 | | - |
69 | | -| `MongoDbFactory#getLegacyDb()` |
70 | | -| - |
71 | | -| - |
72 | | - |
73 | | -| `SimpleMongoDbFactory` |
74 | | -| `SimpleMongoClientDbFactory` + |
75 | | -(Available since 2.1) |
76 | | -| |
77 | | - |
78 | | -| `MapReduceOptions#getOutputType()` |
79 | | -| `MapReduceOptions#getMapReduceAction()` |
80 | | -| Returns `MapReduceAction` instead of `MapReduceCommand.OutputType`. |
81 | | - |
82 | | -| `Meta\|Query` maxScan & snapshot |
83 | | -| |
84 | | -| |
85 | | -|=== |
86 | | - |
87 | | -== XML Namespace |
88 | | - |
89 | | -.Changed XML Namespace Elements and Attributes: |
90 | | -|=== |
91 | | -Element / Attribute | 2.x | 3.x |
92 | | - |
93 | | -| `<mongo:mongo-client />` |
94 | | -| Used to create a `com.mongodb.MongoClient` |
95 | | -| Now exposes a `com.mongodb.client.MongoClient` |
96 | | - |
97 | | -| `<mongo:mongo-client replica-set="..." />` |
98 | | -| Was a comma delimited list of replica set members (host/port) |
99 | | -| Now defines the replica set name. + |
100 | | -Use `<mongo:client-settings cluster-hosts="..." />` instead |
101 | | - |
102 | | -| `<mongo:db-factory writeConcern="..." />` |
103 | | -| NONE, NORMAL, SAFE, FSYNC_SAFE, REPLICAS_SAFE, MAJORITY |
104 | | -| W1, W2, W3, UNAKNOWLEDGED, AKNOWLEDGED, JOURNALED, MAJORITY |
105 | | -|=== |
106 | | - |
107 | | -.Removed XML Namespace Elements and Attributes: |
108 | | -|=== |
109 | | -Element / Attribute | Replacement in 3.x | Comment |
110 | | - |
111 | | -| `<mongo:db-factory mongo-ref="..." />` |
112 | | -| `<mongo:db-factory mongo-client-ref="..." />` |
113 | | -| Referencing a `com.mongodb.client.MongoClient`. |
114 | | - |
115 | | -| `<mongo:mongo-client credentials="..." />` |
116 | | -| `<mongo:mongo-client credential="..." />` |
117 | | -| Single authentication data instead of list. |
118 | | - |
119 | | -| `<mongo:client-options />` |
120 | | -| `<mongo:client-settings />` |
121 | | -| See `com.mongodb.MongoClientSettings` for details. |
122 | | -|=== |
123 | | - |
124 | | -.New XML Namespace Elements and Attributes: |
125 | | -|=== |
126 | | -Element | Comment |
127 | | - |
128 | | -| `<mongo:db-factory mongo-client-ref="..." />` |
129 | | -| Replacement for `<mongo:db-factory mongo-ref="..." />` |
130 | | - |
131 | | -| `<mongo:db-factory connection-string="..." />` |
132 | | -| Replacement for `uri` and `client-uri`. |
133 | | - |
134 | | -| `<mongo:mongo-client connection-string="..." />` |
135 | | -| Replacement for `uri` and `client-uri`. |
136 | | - |
137 | | -| `<mongo:client-settings />` |
138 | | -| Namespace element for `com.mongodb.MongoClientSettings`. |
139 | | - |
140 | | -|=== |
141 | | - |
142 | | -.Deprecations: |
143 | | -|=== |
144 | | -2.x | Replacement in 3.x | Comment |
145 | | - |
146 | | -| `MongoDbFactorySupport` |
147 | | -| `MongoDatabaseFactorySupport` |
148 | | -| |
149 | | - |
150 | | -| `SimpleMongoClientDbFactory` |
151 | | -| `SimpleMongoClientDatabaseFactory` |
152 | | -| |
153 | | - |
154 | | -| `MongoDbFactory` |
155 | | -| `MongoDatabaseFactory` |
156 | | -| |
157 | | - |
158 | | -|=== |
159 | | - |
160 | | -== Other Changes |
161 | | - |
162 | | -=== Auto Index Creation |
163 | | - |
164 | | -Annotation based index creation is now turned **OFF** by default and needs to be enabled eg. when relying on `@GeoSpatialIndexed`. |
165 | | -Please refer to <<mapping.index-creation>> on how to create indexes programmatically. |
166 | | - |
167 | | -.Enable Auto Index Creation |
168 | | -==== |
169 | | -.Java |
170 | | -[source,java,role="primary"] |
171 | | ----- |
172 | | -@Configuration |
173 | | -public class Config extends AbstractMongoClientConfiguration { |
174 | | -
|
175 | | - @Override |
176 | | - protected boolean autoIndexCreation() { |
177 | | - return true; |
178 | | - } |
179 | | -
|
180 | | - // ... |
181 | | -} |
182 | | ----- |
183 | | -
|
184 | | -.XML |
185 | | -[source,xml,role="secondary"] |
186 | | ----- |
187 | | -<mongo:mapping-converter auto-index-creation="true" /> |
188 | | ----- |
189 | | -
|
190 | | -.Programmatic |
191 | | -[source,java,role="secondary"] |
192 | | ----- |
193 | | -MongoDatabaseFactory dbFactory = new SimpleMongoClientDatabaseFactory(...); |
194 | | -DefaultDbRefResolver dbRefResolver = new DefaultDbRefResolver(dbFactory); |
195 | | -
|
196 | | -MongoMappingContext mappingContext = new MongoMappingContext(); |
197 | | -mappingContext.setAutoIndexCreation(true); |
198 | | -// ... |
199 | | -mappingContext.afterPropertiesSet(); |
200 | | -
|
201 | | -MongoTemplate template = new MongoTemplate(dbFactory, new MappingMongoConverter(dbRefResolver, mappingContext)); |
202 | | ----- |
203 | | -==== |
204 | | - |
205 | | -=== UUID Types |
206 | | - |
207 | | -The MongoDB UUID representation can now be configured with different formats. |
208 | | -This has to be done via `MongoClientSettings` as shown in the snippet below. |
209 | | - |
210 | | -.UUid Codec Configuration |
211 | | -==== |
212 | | -[source,java] |
213 | | ----- |
214 | | -@Configuration |
215 | | -public class Config extends AbstractMongoClientConfiguration { |
216 | | -
|
217 | | - @Override |
218 | | - public void configureClientSettings(MongoClientSettings.Builder builder) { |
219 | | - builder.uuidRepresentation(UuidRepresentation.STANDARD); |
220 | | - } |
221 | | -
|
222 | | - // ... |
223 | | -} |
224 | | ----- |
225 | | -==== |
226 | | - |
227 | | -=== Deferred MongoDatabase lookup in `ReactiveMongoDatabaseFactory` |
228 | | - |
229 | | -`ReactiveMongoDatabaseFactory` now returns `Mono<MongoDatabase>` instead of `MongoDatabase` to allow access to the Reactor Subscriber context to enable context-specific routing functionality. |
230 | | - |
231 | | -This change affects `ReactiveMongoTemplate.getMongoDatabase()` and `ReactiveMongoTemplate.getCollection()` so both methods must follow deferred retrieval. |
| 9 | +Spring Data MongoDB 4.x requires the MongoDB Java Driver 4.8.x + |
| 10 | +To learn more about driver versions please visit the https://www.mongodb.com/docs/drivers/java/sync/current/upgrade/[MongoDB Documentation]. |
0 commit comments