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. 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. 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 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/assets/images/jconsole.png b/src/main/antora/modules/ROOT/assets/images/jconsole.png deleted file mode 100644 index 267aee8a4b..0000000000 Binary files a/src/main/antora/modules/ROOT/assets/images/jconsole.png and /dev/null differ 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..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 @@ -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. + @@ -57,3 +61,12 @@ 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.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 7a2e5f28d2..42583fbddb 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/aot.adoc @@ -1,70 +1,17 @@ -= Ahead of Time Optimizations +include::{commons}@data-commons::page$aot.adoc[] -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]. +== MongoDB Specific Ahead Of Time Features -[[aot.hints]] -== Runtime Hints +[[aot.repositories.mongodb]] +=== MongoDB Ahead of Time Repositories -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. -==== +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] ==== -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. +Reactive Repository interfaces using Project Reactor, Kotlin Coroutines et. al. are not supported. ==== -=== 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]. - **Supported Features** * Derived `find`, `count`, `exists` and `delete` methods @@ -78,7 +25,8 @@ These are typically all query methods that are not backed by an xref:repositorie * `@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** 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. + 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[] 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. 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 ==== 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