[Spring Data MongoDB 5.0] Migrate removed MongoDB JMX support without breaking compilation

[Kyran121]

Parent tracking issue

• [Tracking] Add Spring Data MongoDB 5.0 migration support #1081

Prerequisite

• [Spring Data MongoDB 5.0] Add migration composite and dependency alignment #1082 provides the Spring Data MongoDB 5 migration composite.

What problem are you trying to solve?

Spring Data MongoDB 5 removes its dedicated JMX monitoring support. Applications upgrading from Spring Data MongoDB 4.x may still contain Java or XML configuration that depends on APIs which no longer exist in 5.x.

Simply diagnosing those usages and then continuing with the Spring Data MongoDB 5 dependency upgrade can leave the migrated project with unresolved types and compilation failures. The migration should not knowingly introduce that broken state.

There is no universal one-to-one replacement for the removed monitoring functionality. The appropriate replacement depends on the application and deployment environment and may involve Spring Boot Actuator, Micrometer, MongoDB driver observability, or organisation-specific monitoring infrastructure.

The migration therefore needs to distinguish source that can be removed or rewritten safely from application-specific usage that requires manual migration, while preserving compilability.

Proposed solution

Add focused Spring Data MongoDB JMX migration support that:

• Identifies Java references to Spring Data MongoDB JMX APIs that were actually removed in 5.0, using attributed types rather than broad name matching.
• Detects removed Spring Data MongoDB XML JMX configuration where it can be matched precisely and reliably.
• Removes obsolete configuration whose purpose is exclusively the removed Spring Data MongoDB JMX facility when that removal is locally safe.
• Cleans up imports and configuration made unused by a successful removal.
• Detects when removed JMX types escape into otherwise surviving application code, such as custom subclasses, fields, parameters, return types, cross-bean dependencies, or application-specific logic.
• Reports unsupported migration sites clearly rather than deleting or rewriting arbitrary application behaviour.
• Exposes a reusable module/project migration-blocker signal so the Spring Data MongoDB 5 dependency transition is not applied when unsupported removed-JMX usage remains.
• Leaves unrelated Spring Framework, JDK, third-party, and application-defined JMX usage unchanged.
• Does not automatically select or configure a replacement monitoring strategy.

Compilability invariant

UpgradeSpringDataMongoDb_5_0 must not knowingly introduce unresolved references to Spring Data MongoDB APIs removed in 5.0.

For a module whose removed JMX usage is fully and safely migratable:

1. remove the obsolete JMX configuration;
2. remove now-unused imports/configuration;
3. continue with the Spring Data MongoDB 5 migration.

For a module containing unsupported removed-JMX usage:

1. preserve the source requiring manual migration;
2. report the exact blocking usages;
3. do not apply the Spring Data MongoDB 5 dependency transition for that affected module through this composite.

This issue owns the safety contract of the MongoDB-specific composite. Higher-level dependency management, including Spring Boot 4 parent/BOM upgrades that may independently bring Spring Data MongoDB 5 into a project, must honour the same blocker through separate integration work.

Java detection boundary

Detection should be based on resolved Spring Data MongoDB types and on an explicit 4.x-present / 5.x-absent API set.

Types and configuration to detect

Spring Data MongoDB's 4.x JMX documentation exposes the monitoring MBeans backed by org.springframework.data.mongodb.monitor, and the 4.5 API marks that package for removal. Spring Data MongoDB 5 removes the package as part of discontinuing dedicated JMX support.

The removed Java type set to detect is therefore:

• org.springframework.data.mongodb.monitor.AbstractMonitor
• org.springframework.data.mongodb.monitor.AssertMetrics
• org.springframework.data.mongodb.monitor.BackgroundFlushingMetrics
• org.springframework.data.mongodb.monitor.BtreeIndexCounters
• org.springframework.data.mongodb.monitor.ConnectionMetrics
• org.springframework.data.mongodb.monitor.GlobalLockMetrics
• org.springframework.data.mongodb.monitor.MemoryMetrics
• org.springframework.data.mongodb.monitor.OperationCounters
• org.springframework.data.mongodb.monitor.ServerInfo

The XML/configuration surface should also account for:

• the Mongo namespace JMX element: <mongo:jmx/>;
• org.springframework.data.mongodb.config.MongoJmxParser, which backs that namespace configuration in 4.5 and is absent from the 5.x configuration API.

The historical JMX documentation also lists MongoAdmin, but org.springframework.data.mongodb.core.MongoAdmin and MongoAdminOperations remain present in Spring Data MongoDB 5.0 and must not be classified as removed 5.0 types merely because they are deprecated for future removal. They may warrant separate migration work when they are actually removed in a later target version.

This list should be treated as the initial authoritative detection boundary and kept aligned with the Spring Data MongoDB 4.x-to-5.x migration/API documentation rather than expanded through generic JMX naming heuristics.

Relevant semantic usage includes, where applicable:

• field and local-variable types;
• constructor calls;
• method parameters and return types;
• inheritance;
• generic type arguments;
• fully-qualified references;
• casts, class literals, and other attributed references.

Imports are secondary evidence. The migration should operate on the affected semantic usage and allow unused-import cleanup to remove obsolete imports after successful transformations.

APIs that remain present in Spring Data MongoDB 5, even if deprecated or historically associated with JMX, must not be reported as removed solely on that basis.

Safe-removal boundary

A JMX usage is mechanically removable only where the recipe can establish that the affected source exists solely to configure or expose the removed Spring Data MongoDB JMX facility and that removing it does not leave references from surviving application code.

Examples that may be safely removable include dedicated monitoring bean declarations or precise XML namespace configuration whose only purpose is the removed JMX support.

Examples that should block automatic migration unless a safe transformation can be proven include:

• application classes extending a removed monitor type;
• removed JMX types stored in surviving fields;
• removed JMX types passed into or returned from surviving application methods;
• application-specific logic built around removed monitoring objects;
• cross-bean or cross-method dependencies where removing one JMX declaration would leave surviving code uncompilable;
• any case whose ownership or behavioural impact cannot be established locally with confidence.

Each usage should be evaluated independently rather than treating an entire class as unsupported because one member is ambiguous.

XML detection boundary

Spring Data MongoDB XML JMX configuration should only be removed where the obsolete namespace element or configuration can be identified precisely.

General Spring Framework JMX configuration, application-managed MBean exporters, JDK JMX infrastructure, and unrelated XML configuration must remain unchanged.

If the available Rewrite XML infrastructure cannot distinguish a removed Spring Data MongoDB configuration reliably, that case should remain unsupported and act as a migration blocker rather than falling back to broad textual matching.

Diagnostic behaviour

For unsupported migration sites, explain that:

• Spring Data MongoDB's dedicated JMX monitoring support was removed in 5.0;
• no universally equivalent source replacement exists;
• the affected application logic must be migrated manually;
• Spring Boot Actuator or another supported observability mechanism may be appropriate depending on the application;
• the MongoDB 5 transition was withheld for the affected module by this composite to avoid leaving known uncompilable source.

Proposed implementation shape

The following is architectural guidance rather than a prescribed class/visitor design. The implementation should preserve these behaviours while remaining free to use the most appropriate OpenRewrite primitives.

Analyse removed Mongo JMX usage
        |
        +-- safely migratable
        |       `-- remove obsolete JMX-only configuration
        |
        `-- unsupported
                `-- record migration blocker + diagnostic

                     |
                     v
       Spring Data MongoDB 5 transition
                     |
              only when safe

A likely shape is to:

• perform project/module-aware analysis before the target dependency transition while Spring Data MongoDB 4.x types are still attributable;
• classify individual usages as safely removable or unsupported rather than treating all JMX usage uniformly;
• expose reusable migration-readiness/blocker state at the module/project level;
• emit diagnostics independently of the guarded migration so blocked modules still explain exactly why they were withheld;
• apply safe removals before the dependency transition;
• guard the MongoDB 5 transition when unsupported removed-JMX usage remains;
• make the resulting readiness signal reusable by higher-level callers such as the Spring Boot 4 migration rather than duplicating the JMX analysis there.

The exact recipe classes, accumulators, visitors, precondition composition, and internal data structures are intentionally left to the implementor.

Out of scope

• Automatically adding Spring Boot Actuator dependencies.
• Automatically enabling Actuator endpoints or JMX exposure.
• Selecting an application monitoring strategy.
• Deleting application-specific classes or behaviour merely to make the target dependency compile.
• Replacing organisation-specific JMX exporters or monitoring infrastructure.
• Rewriting unrelated Spring Framework, JDK, third-party, or application-owned JMX usage.
• Reporting APIs that remain available in Spring Data MongoDB 5 solely because they are deprecated.
• General Spring Data MongoDB package/import migrations unrelated to removed JMX support.
• MongoDB value-representation configuration or listener-container behaviour.
• Spring Boot Actuator MongoDB package migrations; see Migrate Spring Boot 4 MongoDB modular packages and test starters #1079.
• Preventing a separate Spring Boot parent/BOM/platform migration from independently selecting Spring Data MongoDB 5; that orchestration is tracked separately.

Acceptance criteria

• The removed Spring Data MongoDB JMX Java API set is established from the 4.x to 5.x API change rather than broad JMX naming heuristics.
• Java references to APIs removed in 5.0 are identified using attributed types.
• The initial detection set covers the removed org.springframework.data.mongodb.monitor types listed above and the <mongo:jmx/> configuration surface.
• MongoAdmin / MongoAdminOperations are not incorrectly treated as removed 5.0 APIs while they remain present in the target API.
• Safe, JMX-only Java configuration can be removed without leaving unresolved references in surviving source.
• Relevant removed XML JMX configuration is removed only where support is precise and testable.
• Imports/configuration made unused by a successful migration are cleaned up.
• Removed JMX types escaping into surviving application code are identified as blockers rather than being deleted or speculatively rewritten.
• Cross-bean/cross-method dependencies are not partially removed in a way that leaves surviving code uncompilable.
• APIs that remain available in Spring Data MongoDB 5 are not incorrectly reported as removed.
• Unrelated Spring Framework, JDK, third-party, and application-defined JMX usage remains unchanged.
• UpgradeSpringDataMongoDb_5_0 does not apply its Spring Data MongoDB 5 dependency transition to a module with unresolved JMX blockers.
• Modules whose JMX usage is fully migrated continue through the MongoDB 5 migration normally.
• Blocked modules receive clear diagnostics at the exact unsupported migration sites.
• Tests cover pure JMX configuration, mixed configuration, cross-bean dependencies, custom subclasses, fields/parameters/return types, fully-qualified references, unrelated JMX, multi-module behaviour, XML where supported, composite behaviour, and idempotency.
• The completed JMX migration support is composed into the Spring Data MongoDB 5 migration flow without knowingly leaving removed API references behind.

References

• Spring Data MongoDB 4.x to 5.x migration guide: https://docs.spring.io/spring-data/mongodb/reference/migration-guide/migration-guide-4.x-to-5.x.html
• Spring Data MongoDB JMX reference documentation.
• Spring Data MongoDB 4.x API documentation.
• Spring Data MongoDB 5.x API documentation.