From 7d889a784a339ba3e2e8833b2987ec5276898f12 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Thu, 23 Oct 2025 09:26:56 +0200 Subject: [PATCH 01/11] Prepare issue branch. --- pom.xml | 2 +- spring-data-mongodb-distribution/pom.xml | 2 +- spring-data-mongodb/pom.xml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pom.xml b/pom.xml index b23a16229f..1c2a7ffee9 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ org.springframework.data spring-data-mongodb-parent - 5.0.0-SNAPSHOT + 5.0.x-GH-5078-SNAPSHOT pom Spring Data MongoDB diff --git a/spring-data-mongodb-distribution/pom.xml b/spring-data-mongodb-distribution/pom.xml index fc88571622..0a30bf9ff8 100644 --- a/spring-data-mongodb-distribution/pom.xml +++ b/spring-data-mongodb-distribution/pom.xml @@ -15,7 +15,7 @@ org.springframework.data spring-data-mongodb-parent - 5.0.0-SNAPSHOT + 5.0.x-GH-5078-SNAPSHOT ../pom.xml diff --git a/spring-data-mongodb/pom.xml b/spring-data-mongodb/pom.xml index 37730f7d40..469b10ab92 100644 --- a/spring-data-mongodb/pom.xml +++ b/spring-data-mongodb/pom.xml @@ -13,7 +13,7 @@ org.springframework.data spring-data-mongodb-parent - 5.0.0-SNAPSHOT + 5.0.x-GH-5078-SNAPSHOT ../pom.xml From b33c2c2e74235fc404f5fb1b640f72324bfcdcbd Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Thu, 23 Oct 2025 09:51:51 +0200 Subject: [PATCH 02/11] Update observability configuration section. Recommend using driver native API for observability. See: #5009 --- .../observability/ContextProviderFactory.java | 3 +++ .../observability/MongoHandlerContext.java | 3 +++ .../MongoHandlerObservationConvention.java | 5 +++- .../MongoObservationCommandListener.java | 3 +++ .../mongodb/observability/package-info.java | 3 +++ .../pages/observability/observability.adoc | 24 +++++++++++++++---- 6 files changed, 36 insertions(+), 5 deletions(-) diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/ContextProviderFactory.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/ContextProviderFactory.java index f605b96711..d28cba2739 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/ContextProviderFactory.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/ContextProviderFactory.java @@ -37,6 +37,9 @@ /** * Factory to create a {@link ContextProvider} to propagate the request context across tasks. Requires either * {@link SynchronousContextProvider} or {@link ReactiveContextProvider} to be present. + *

+ * NOTE: MongoDB Java Driver 5.7+ comes with observability directly built in which can be configured + * via {@code MongoClientSettings.Builder#observabilitySettings(ObservabilitySettings)}. * * @author Mark Paluch * @since 3.0 diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoHandlerContext.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoHandlerContext.java index cab9cd5cb8..e91f1f068b 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoHandlerContext.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoHandlerContext.java @@ -35,6 +35,9 @@ /** * A {@link Observation.Context} that contains MongoDB events. + *

+ * NOTE: MongoDB Java Driver 5.7+ comes with observability directly built in which can be configured + * via {@code MongoClientSettings.Builder#observabilitySettings(ObservabilitySettings)}. * * @author Marcin Grzejszczak * @author Greg Turnquist diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoHandlerObservationConvention.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoHandlerObservationConvention.java index 7d1100c582..6081bf9f65 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoHandlerObservationConvention.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoHandlerObservationConvention.java @@ -20,7 +20,10 @@ /** * {@link ObservationConvention} for {@link MongoHandlerContext}. - * + *

+ * NOTE: MongoDB Java Driver 5.7+ comes with observability directly built in which can be configured + * via {@code MongoClientSettings.Builder#observabilitySettings(ObservabilitySettings)}. + * * @author Greg Turnquist * @since 4 */ diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoObservationCommandListener.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoObservationCommandListener.java index 314da09eaa..140c54d3de 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoObservationCommandListener.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/MongoObservationCommandListener.java @@ -36,6 +36,9 @@ /** * Implement MongoDB's {@link CommandListener} using Micrometer's {@link Observation} API. + *

+ * NOTE: MongoDB Java Driver 5.7+ comes with observability directly built in which can be configured + * via {@code MongoClientSettings.Builder#observabilitySettings(ObservabilitySettings)}. * * @author OpenZipkin Brave Authors * @author Marcin Grzejszczak diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/package-info.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/package-info.java index d6319e5f4f..b9cb874dc9 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/package-info.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/observability/package-info.java @@ -1,5 +1,8 @@ /** * Infrastructure to provide driver observability using Micrometer. + *

+ * NOTE: MongoDB Java Driver 5.7+ comes with observability directly built in which can be configured + * via {@code MongoClientSettings.Builder#observabilitySettings(ObservabilitySettings)}. */ @org.jspecify.annotations.NullMarked package org.springframework.data.mongodb.observability; diff --git a/src/main/antora/modules/ROOT/pages/observability/observability.adoc b/src/main/antora/modules/ROOT/pages/observability/observability.adoc index 8a9b0a1eeb..3e18d5f13f 100644 --- a/src/main/antora/modules/ROOT/pages/observability/observability.adoc +++ b/src/main/antora/modules/ROOT/pages/observability/observability.adoc @@ -3,11 +3,27 @@ [[mongodb.observability]] = Observability -Spring Data MongoDB currently has the most up-to-date code to support Observability in your MongoDB application. -These changes, however, haven't been picked up by Spring Boot (yet). -Until those changes are applied, if you wish to use Spring Data MongoDB's flavor of Observability, you must carry out the following steps. +[NOTE] +==== +MongoDB Java Driver 5.7+ comes with observability directly built in. +We recommend switching to the driver native `ObservabilitySettings`, which can be configured as outlined below: +[source,java] +---- +@Bean +MongoClientSettingsBuilderCustomizer mongoDbObservabilitySettings(ObservationRegistry registry) { + return (clientSettingsBuilder) -> { + clientSettingsBuilder.observabilitySettings(ObservabilitySettings.micrometerBuilder() + .observationRegistry(observationRegistry) + .build()); + }; +} +---- +In the light of driver native observability support, the types within the Spring Data provided _org.springframework.data.mongodb.observability_ package will not see further development and are subject to deprecation/removal in subsequent releases. +==== + +To use Spring Data MongoDB's flavor of Observability you must: -. First of all, you must opt into Spring Data MongoDB's configuration settings by customizing `MongoClientSettings` through either your `@SpringBootApplication` class or one of your configuration classes. +. opt into Spring Data MongoDB's configuration settings by customizing `MongoClientSettings` through either your `@SpringBootApplication` class or one of your configuration classes. + .Registering MongoDB Micrometer customizer setup ==== From 5de39286fd465b2d1f009eebfa043b5b813b2732 Mon Sep 17 00:00:00 2001 From: Jens Schauder Date: Fri, 24 Oct 2025 11:38:02 +0200 Subject: [PATCH 03/11] Correct Maven Repository information. --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 1d321285b3..62d9862d04 100644 --- a/README.adoc +++ b/README.adoc @@ -137,7 +137,7 @@ The https://spring.io/[spring.io] site contains several guides that show how to [[building-from-source]] == Building from Source -You do not need to build from source to use Spring Data. Binaries are available in https://repo.spring.io[repo.spring.io] +You do not need to build from source to use Spring Data. Binaries are available in https://central.sonatype.com[Maven Central] or in case of snapshots from https://repo.spring.io[repo.spring.io] and accessible from Maven using the Maven configuration noted <>. NOTE: Configuration for Gradle is similar to Maven. From 79700aec1466ef9035191481bf989cf8786c377e Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Tue, 28 Oct 2025 11:04:52 +0100 Subject: [PATCH 04/11] Update security readme. --- SECURITY.adoc | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/SECURITY.adoc b/SECURITY.adoc index 9c518d999a..de5e8d975b 100644 --- a/SECURITY.adoc +++ b/SECURITY.adoc @@ -1,9 +1,16 @@ -# Security Policy += Security Policy -## Supported Versions +== Reporting a Vulnerability -Please see the https://spring.io/projects/spring-data-mongodb[Spring Data MongoDB] project page for supported versions. +Please, https://github.com/spring-projects/security-advisories/security/advisories/new[open a draft security advisory] if you need to disclose and discuss a security issue in private with the Spring Data team. +Note that we only accept reports against https://spring.io/projects/spring-data#support[supported versions]. -## Reporting a Vulnerability +For more details, check out our https://spring.io/security-policy[security policy]. + +== JAR signing + +Spring Data JARs released on Maven Central are signed. +You'll find more information about the key here: https://spring.io/GPG-KEY-spring.txt + +Versions released prior to 2023 may be signed with a different key. -Please don't raise security vulnerabilities here. Head over to https://pivotal.io/security to learn how to disclose them responsibly. From e180d0c2a820617497a6ada6dc63f027a61c7328 Mon Sep 17 00:00:00 2001 From: Jens Schauder Date: Wed, 5 Nov 2025 09:47:56 +0100 Subject: [PATCH 05/11] Reduce duplicate AOT documentation. Removed generic AOT documentation with a reference to the section in Spring Data Commons. See: spring-projects/spring-data-commons#3384 --- .../modules/ROOT/pages/mongodb/aot.adoc | 67 ++----------------- 1 file changed, 4 insertions(+), 63 deletions(-) diff --git a/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc b/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc index 7a2e5f28d2..e239c8c337 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc @@ -1,69 +1,10 @@ = Ahead of Time Optimizations -This chapter covers Spring Data's Ahead of Time (AOT) optimizations that build upon {spring-framework-docs}/core/aot.html[Spring's Ahead of Time Optimizations]. +For a general explanation of what Ahead of Time (AoT) Optimizations Spring Data offers and how to enable them see +xref:{commons}@data-commons::page$aot.adoc[] -[[aot.hints]] -== Runtime Hints - -Running an application as a native image requires additional information compared to a regular JVM runtime. -Spring Data contributes {spring-framework-docs}/core/aot.html#aot.hints[Runtime Hints] during AOT processing for native image usage. -These are in particular hints for: - -* Auditing -* `ManagedTypes` to capture the outcome of class-path scans -* Repositories -** Reflection hints for entities, return types, and Spring Data annotations -** Repository fragments -** Querydsl `Q` classes -** Kotlin Coroutine support -* Web support (Jackson Hints for `PagedModel`) - -[[aot.repositories]] -== Ahead of Time Repositories - -AOT Repositories are an extension to AOT processing by pre-generating eligible query method implementations. -Query methods are opaque to developers regarding their underlying queries being executed in a query method call. -AOT repositories contribute query method implementations based on derived or annotated queries, updates or aggregations that are known at build-time. -This optimization moves query method processing from runtime to build-time, which can lead to a significant bootstrap performance improvement as query methods do not need to be analyzed reflectively upon each application start. - -The resulting AOT repository fragment follows the naming scheme of `Impl__Aot` and is placed in the same package as the repository interface. -You can find all queries in their MQL form for generated repository query methods. - -[TIP] -==== -`spring.aot.repositories.enabled` property needs to be set to `true` for repository fragment code generation. -==== - -[NOTE] -==== -Consider AOT repository classes an internal optimization. -Do not use them directly in your code as generation and implementation details may change in future releases. -==== - -=== Running with AOT Repositories - -AOT is a mandatory step to transform a Spring application to a native executable, so it is automatically enabled when running in this mode. -When AOT is enabled (either for native compilation or by setting `spring.aot.enabled=true`), AOT repositories are automatically enabled by default. - -You can disable AOT repository generation entirely or only disable MongoDB AOT repositories: - -* Set the `spring.aot.repositories.enabled=false` property to disable generated repositories for all Spring Data modules. -* Set the `spring.aot.mongodb.repositories.enabled=false` property to disable only MongoDB AOT repositories. - -AOT repositories contribute configuration changes to the actual repository bean registration to register the generated repository fragment. - -[NOTE] -==== -When AOT optimizations are included, some decisions that have been taken at build-time are hard-coded in the application setup. -For instance, profiles that have been enabled at build-time are automatically enabled at runtime as well. -Also, the Spring Data module implementing a repository is fixed. -Changing the implementation requires AOT re-processing. -==== - -=== Eligible Methods in Data MongoDB - -AOT repositories filter methods that are eligible for AOT processing. -These are typically all query methods that are not backed by an xref:repositories/custom-implementations.adoc[implementation fragment]. +Each module offers optimizations for a slightly different set of repository method. +With Spring Data MongoDb we generally support query methods that are not backed by an xref:repositories/custom-implementations.adoc[implementation fragment], and don't require, with a few limitations detailed below. **Supported Features** From 2ac439d2d48b5ce0e5f6f8178c5b8bd42536c363 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Wed, 12 Nov 2025 08:41:11 +0100 Subject: [PATCH 06/11] Import AOT documentation from commons. --- src/main/antora/modules/ROOT/pages/mongodb/aot.adoc | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc b/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc index e239c8c337..2c88669bce 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc @@ -1,9 +1,10 @@ -= Ahead of Time Optimizations +include::{commons}@data-commons::page$aot.adoc[] -For a general explanation of what Ahead of Time (AoT) Optimizations Spring Data offers and how to enable them see -xref:{commons}@data-commons::page$aot.adoc[] +== MongoDB Specific Ahead Of Time Features + +[[aot.repositories.mongodb]] +=== MongoDB Ahead of Time Repositories -Each module offers optimizations for a slightly different set of repository method. With Spring Data MongoDb we generally support query methods that are not backed by an xref:repositories/custom-implementations.adoc[implementation fragment], and don't require, with a few limitations detailed below. **Supported Features** @@ -19,7 +20,8 @@ With Spring Data MongoDb we generally support query methods that are not backed * `@Meta.flags` is not evaluated. * Limited `Collation` detection. -* No support for in-clauses with pattern matching / case insensitivity +* No support for in-clauses with pattern matching / case insensitivity. +* Custom Collection return types (e.g. `io.vavr.collection`, `"org.eclipse.collections`) are not yet supported. **Excluded methods** From 4ed5d008239d0ed08aea565aa3e9a1b4e4d08afa Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Wed, 12 Nov 2025 09:10:37 +0100 Subject: [PATCH 07/11] Mention java.util.Date _id to ObjectId conversion. See: #5092 --- .../modules/ROOT/pages/mongodb/template-crud-operations.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/src/main/antora/modules/ROOT/pages/mongodb/template-crud-operations.adoc b/src/main/antora/modules/ROOT/pages/mongodb/template-crud-operations.adoc index 491bb4ab7d..7ec06a69bb 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/template-crud-operations.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/template-crud-operations.adoc @@ -191,6 +191,7 @@ When you use the `MappingMongoConverter`, certain rules govern how properties fr The following outlines what type conversion, if any, is done on the property mapped to the `_id` document field when using the `MappingMongoConverter` (the default for `MongoTemplate`). . If possible, an `id` property or field declared as a `String` in the Java class is converted to and stored as an `ObjectId` by using a Spring `Converter`. Valid conversion rules are delegated to the MongoDB Java driver. If it cannot be converted to an `ObjectId`, then the value is stored as a string in the database. +. An `id` property or field declared as `Date` is converted to and stored as `ObjectId`. . An `id` property or field declared as `BigInteger` in the Java class is converted to and stored as an `ObjectId` by using a Spring `Converter`. If no field or property specified in the previous sets of rules is present in the Java class, an implicit `_id` file is generated by the driver but not mapped to a property or field of the Java class. From 4b08bf56346b260610a46102c22cf3d96ab23937 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Wed, 12 Nov 2025 09:51:10 +0100 Subject: [PATCH 08/11] Document discontinued JMX support. --- .../modules/ROOT/assets/images/jconsole.png | Bin 49294 -> 0 bytes .../migration-guide-4.x-to-5.x.adoc | 5 ++ .../modules/ROOT/pages/mongodb/jmx.adoc | 64 +----------------- 3 files changed, 6 insertions(+), 63 deletions(-) delete mode 100644 src/main/antora/modules/ROOT/assets/images/jconsole.png diff --git a/src/main/antora/modules/ROOT/assets/images/jconsole.png b/src/main/antora/modules/ROOT/assets/images/jconsole.png deleted file mode 100644 index 267aee8a4b41323e3d3e0658af3267545897866c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 49294 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 C1l}_M diff --git a/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc index 4351cc70e7..cc27f46954 100644 --- a/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc +++ b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc @@ -57,3 +57,8 @@ static class Config extends AbstractMongoClientConfiguration { ---- Users upgrading from prior versions may choose `BigDecimalRepresentation.STRING` as default to retain previous behaviour. + +== JMX Support Discontinued. + +We recommend switching to Spring Boot https://docs.spring.io/spring-boot/reference/actuator/endpoints.html[Actuator Endpoints]. + diff --git a/src/main/antora/modules/ROOT/pages/mongodb/jmx.adoc b/src/main/antora/modules/ROOT/pages/mongodb/jmx.adoc index 8b98bcebd2..d32756dfb8 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/jmx.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/jmx.adoc @@ -3,68 +3,6 @@ [NOTE] ==== -JMX support has been deprecated in 4.5 and will be removed in 5.0. + +JMX support has been removed in 5.0. + We recommend switching to Spring Boot https://docs.spring.io/spring-boot/reference/actuator/endpoints.html[Actuator Endpoints] and expose those over JMX if needed. ==== - -The JMX support for MongoDB exposes the results of running the 'serverStatus' command on the admin database for a single MongoDB server instance. It also exposes an administrative MBean, `MongoAdmin`, that lets you perform administrative operations, such as dropping or creating a database. The JMX features build upon the JMX feature set available in the Spring Framework. See link:{springDocsUrl}/integration.html#jmx[here] for more details. - -[[mongodb:jmx-configuration]] -== MongoDB JMX Configuration - -Spring's Mongo namespace lets you enable JMX functionality, as the following example shows: - -.XML schema to configure MongoDB -==== -[source,xml] ----- - - - - - - - - - - - - - - - - - - - - ----- -==== - -The preceding code exposes several MBeans: - -* `AssertMetrics` -* `BackgroundFlushingMetrics` -* `BtreeIndexCounters` -* `ConnectionMetrics` -* `GlobalLockMetrics` -* `MemoryMetrics` -* `OperationCounters` -* `ServerInfo` -* `MongoAdmin` - -The following screenshot from JConsole shows the resulting configuration: - -image::jconsole.png[] From 8c14216a4ab6d9e6f9171af9c0c43e6d613e4a15 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Wed, 12 Nov 2025 09:52:14 +0100 Subject: [PATCH 09/11] Update Driver minimum Version --- .../pages/migration-guide/migration-guide-4.x-to-5.x.adoc | 6 +++++- src/main/antora/modules/ROOT/pages/preface.adoc | 4 ++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc index cc27f46954..d2fb2ef32c 100644 --- a/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc +++ b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc @@ -1,9 +1,13 @@ [[mongodb.migration.4.x-5.x]] = Migration Guide from 4.x to 5.x -Spring Data MongoDB 4.x requires the MongoDB Java Driver 5.5.x + +Spring Data MongoDB 5.x requires the MongoDB Java Driver 5.6+ + To learn more about driver versions please visit the https://www.mongodb.com/docs/drivers/java/sync/current/upgrade/[MongoDB Documentation]. +== MongoDB Java Driver 4.x Driver Compatibility Removed + +Spring Data MongoDB does no longer support the 4.x MongoDB Java Driver generation. + == UUID Representation Changes Spring Data no longer defaults UUID settings via its configuration support classes, factory beans, nor XML namespace. + diff --git a/src/main/antora/modules/ROOT/pages/preface.adoc b/src/main/antora/modules/ROOT/pages/preface.adoc index d52509c81e..f1aa26025c 100644 --- a/src/main/antora/modules/ROOT/pages/preface.adoc +++ b/src/main/antora/modules/ROOT/pages/preface.adoc @@ -3,7 +3,7 @@ The Spring Data MongoDB 4.x binaries require JDK level 17 and above and https://spring.io/docs[Spring Framework] {springVersion} and above. -In terms of database and driver, you need at least version 4.x of https://www.mongodb.org/[MongoDB] and a compatible MongoDB Java Driver (5.2.x). +In terms of database and driver, you need at least version 4.x of https://www.mongodb.org/[MongoDB] and a compatible MongoDB Java Driver (5.6+). [[compatibility.matrix]] == Compatibility Matrix @@ -24,7 +24,7 @@ See also the https://www.mongodb.com/docs/drivers/java/sync/current/compatibilit |2025.0 |4.5.x -|5.3.x +|5.6.x |6.x to 8.x |2024.1 From 72842fc93ac09eb0bafbfe517fe2dea5a4af3858 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Wed, 12 Nov 2025 09:52:46 +0100 Subject: [PATCH 10/11] Document Lifecycle change of DefaultMessageListenerContainer. --- .../pages/migration-guide/migration-guide-4.x-to-5.x.adoc | 4 ++++ .../antora/modules/ROOT/pages/mongodb/change-streams.adoc | 2 ++ 2 files changed, 6 insertions(+) diff --git a/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc index d2fb2ef32c..fad40786aa 100644 --- a/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc +++ b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-4.x-to-5.x.adoc @@ -62,6 +62,10 @@ static class Config extends AbstractMongoClientConfiguration { Users upgrading from prior versions may choose `BigDecimalRepresentation.STRING` as default to retain previous behaviour. +== DefaultMessageListenerContainer auto startup + +The `DefaultMessageListenerContainer` that can be used to listen to e.g. _Change Streams_ now defaults its `SmartLifecycle` auto startup to `true`. + == JMX Support Discontinued. We recommend switching to Spring Boot https://docs.spring.io/spring-boot/reference/actuator/endpoints.html[Actuator Endpoints]. diff --git a/src/main/antora/modules/ROOT/pages/mongodb/change-streams.adoc b/src/main/antora/modules/ROOT/pages/mongodb/change-streams.adoc index 1f999500bf..bf215e328e 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/change-streams.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/change-streams.adoc @@ -44,6 +44,8 @@ container.stop(); <5> Do not forget to stop the container once you are sure you no longer need it. Doing so stops all running `Task` instances within the container. ==== +`DefaultMessageListenerContainer` implements `SmartLifecycle` and will by default be automatically started when registered as a Bean in the Application Context. + [NOTE] ==== Errors while processing are passed on to an `org.springframework.util.ErrorHandler`. If not stated otherwise a log appending `ErrorHandler` gets applied by default. + From c8c0745e86f119379c55d144023a6a72b8469fd6 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Wed, 12 Nov 2025 09:53:19 +0100 Subject: [PATCH 11/11] Update Overview Section with latest features (Vector & AOT) --- src/main/antora/modules/ROOT/pages/mongodb.adoc | 2 ++ src/main/antora/modules/ROOT/pages/mongodb/aot.adoc | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/src/main/antora/modules/ROOT/pages/mongodb.adoc b/src/main/antora/modules/ROOT/pages/mongodb.adoc index 907cbf06be..aaa32be612 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb.adoc @@ -16,6 +16,8 @@ Includes integrated object mapping between documents and POJOs. * xref:repositories/core-extensions.adoc#mongodb.repositories.queries.type-safe[QueryDSL integration] to support type-safe queries. * xref:mongodb/client-session-transactions.adoc[Multi-Document Transactions]. * xref:mongodb/template-query-operations.adoc#mongo.geo-json[GeoSpatial integration]. +* xref:mongodb/mongo-search-indexes.adoc#mongo.search.vector[Vector Index] and declarative xref:mongodb/repositories/vector-search.adoc[Vector Search] support. +* xref:mongodb/aot.adoc[Ahead Of Time (AOT)] optimizations. For most tasks, you should use `MongoTemplate` or the Repository support, which both leverage the rich mapping functionality. `MongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations. diff --git a/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc b/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc index 2c88669bce..42583fbddb 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc @@ -7,6 +7,11 @@ include::{commons}@data-commons::page$aot.adoc[] With Spring Data MongoDb we generally support query methods that are not backed by an xref:repositories/custom-implementations.adoc[implementation fragment], and don't require, with a few limitations detailed below. +[NOTE] +==== +Reactive Repository interfaces using Project Reactor, Kotlin Coroutines et. al. are not supported. +==== + **Supported Features** * Derived `find`, `count`, `exists` and `delete` methods