ClientMetaData refactoring #1807

rozza · 2025-09-22T13:14:47Z

Avoid appending duplicate metadata

Avoid appending duplicate metadata JAVA-5955

Copilot

Pull Request Overview

This PR refactors the ClientMetadata implementation to avoid appending duplicate metadata to the MongoDB driver information. The changes introduce a new internal DriverInformation class and modify the metadata handling to check for duplicates before appending, addressing issue JAVA-5955.

Key changes:

Introduces new internal classes DriverInformation and DriverInformationHelper for managing driver information
Updates ClientMetadata to use a list-based approach with duplicate checking
Refactors tests to use the new infrastructure and adds comprehensive test coverage for duplicate metadata scenarios

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
AbstractClientMetadataProseTest.java	Extensively refactored test methods to use new DriverInformation class and added multiple new test cases for duplicate metadata scenarios
MongoDriverInformationSpec.scala	Updated exclusions list to include new synthetic method
MongoDriverInformationSpecification.groovy	Updated test comments to reflect "append" vs "prepend" behavior
ClientMetadataTest.java	Modified test expectations to align with new metadata building approach
ClientMetadata.java	Core refactoring to use DriverInformation list with duplicate checking
package-info.java	Added package documentation for internal client classes
DriverInformationHelper.java	New utility class for extracting driver information fields
DriverInformation.java	New data class representing driver information with proper equals/hashCode
Internal.java	New annotation for marking internal APIs
MongoDriverInformation.java	Refactored to use DriverInformation internally while maintaining public API

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

driver-core/src/main/com/mongodb/internal/client/package-info.java

…java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

rozza · 2025-09-22T14:18:14Z

driver-core/src/main/com/mongodb/annotations/Internal.java

+        ElementType.TYPE })
+@Documented
+@Alpha(Reason.CLIENT)
+public @interface Internal {


Had to add an internal method MongoDriverInformation#getDriverInformationList to get the list of DriverInformation and added this annotation as a way to highlight things for internal use only.

If this ok, then I'll add a ticket to annotation each of the internal packages in their package-info.java

We already have VisibleForTesting should we try to unify all these in a similar fashion to ApiStatus
(already supported in IntelliJ ~)

I didnt want to misuse that as it's not for testing. It's needed for the ClientMetaData API as well. This all stems from MongoDriverInformation being lossy, I need the combined information of name, version and platform.

We have other places where methods are exposed in the public API but intended for internal use. For example:

mongo-java-driver/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java

Lines 37 to 55 in 5e4e96a

/**

* Notify the client session that a message has been sent.

* 

* For internal use only

* 

*

* @return true if this is the first message sent, false otherwise

* @since 4.0

*/

boolean notifyMessageSent();

/**

* Notify the client session that command execution is being initiated. This should be called before server selection occurs.

* 

* For internal use only

* 

* @param operation the operation

*/

void notifyOperationInitiated(Object operation);

Since we’ve introduced a new annotation here, should we make it consistent with those cases by adding the annotation there as well? We could do this in a separate ticket.

Added JAVA-5975

rozza · 2025-09-22T14:19:08Z

driver-core/src/main/com/mongodb/internal/client/DriverInformation.java

+
+import java.util.Objects;
+
+public final class DriverInformation {


The changes required by the spec ensure that driver information as a whole can be checked for equality - so that duplicates aren't appended.

rozza · 2025-09-22T14:20:16Z

driver-core/src/main/com/mongodb/internal/connection/ClientMetadata.java

+                   driverInformationList.add(driverInformation);
+               }
+            }
+            if (hasAddedNewData) {


Only recalculate the clientMetadataBsonDocument if there has been a real change.

rozza · 2025-09-22T14:21:41Z

driver-core/src/main/com/mongodb/internal/connection/ClientMetadata.java

-        tryWithLimit(client, d -> {
-            putAtPath(d, "driver.name", driverInformation.getInitialDriverName());
-            putAtPath(d, "driver.version", driverInformation.getInitialDriverVersion());
+        tryWithLimit(clientMetadata, d -> {


We add the initial driver information - if there is room. Then later we add the full driver information (eg the extended libraries that use the driver) if there is room.

This behavior is defined by the spec.

rozza · 2025-09-22T14:24:10Z

driver-core/src/main/com/mongodb/MongoDriverInformation.java

 * @mongodb.server.release 3.4
 */
 public final class MongoDriverInformation {
-    private final List<String> driverNames;


Using lists of Strings, no longer works for the new test cases - as it meant we couldn't check for duplicates effectively.

rozza · 2025-09-22T14:27:07Z

driver-core/src/test/unit/com/mongodb/MongoDriverInformationSpecification.groovy

    }

-    def 'should not prepend data if none has been added'() {
+    def 'should not append data if none has been added'() {


We never prepended the data - so these tests needed some tweaking to make sense.

rozza · 2025-09-22T14:27:54Z

driver-core/src/test/unit/com/mongodb/MongoDriverInformationSpecification.groovy

        options.getDriverPlatforms() == ['Java oracle64-1.8.0.31']
    }

-    def 'should error if trying to set a version without setting a name'() {


There is a specific new test from the spec that actually tests we can do this. So removed the check and this test.

rozza · 2025-09-22T14:28:41Z

driver-sync/src/test/functional/com/mongodb/client/AbstractClientMetadataProseTest.java

-    }
-
-    @ParameterizedTest
+    @DisplayName("Test 1: Test that the driver updates metadata")


The new prose tests. I renamed the existing ones to make it easier for future changes / adding new tests.

driver-core/src/main/com/mongodb/internal/client/package-info.java

driver-core/src/main/com/mongodb/MongoDriverInformation.java

driver-core/src/main/com/mongodb/internal/connection/ClientMetadata.java

driver-sync/src/test/functional/com/mongodb/client/AbstractClientMetadataProseTest.java

nhachicha · 2025-09-23T11:18:06Z

driver-core/src/main/com/mongodb/annotations/Internal.java

+        ElementType.TYPE })
+@Documented
+@Alpha(Reason.CLIENT)
+public @interface Internal {


We already have VisibleForTesting should we try to unify all these in a similar fashion to ApiStatus
(already supported in IntelliJ ~)

rozza · 2025-09-23T12:25:43Z

I used APIStatus in the kafka connector - but it hasn't been adopted by the Java driver. We seem to have our own inhouse annotations that do the same thing. Eg. VisibileForTesting seems to be inspired by their annotations library.

I think there is a ticket to move away from our own null annotations, to a more standardized one. Perhaps we should also look to adopt APIStatus as part of that work. JAVA-5938 thats not scheduled until 6.0.0

driver-core/src/main/com/mongodb/internal/client/DriverInformationHelper.java

…tionHelper.java Co-authored-by: Viacheslav Babanin <frest0512@gmail.com>

nhachicha

Since it's outside the scope of this PR, we can create a ticket to consider folding the @Internal annotation underAPIStatus 👍

driver-core/src/main/com/mongodb/annotations/Internal.java

vbabanin · 2025-10-01T17:08:41Z

driver-core/src/main/com/mongodb/annotations/Internal.java

+        ElementType.TYPE })
+@Documented
+@Alpha(Reason.CLIENT)
+public @interface Internal {


We have other places where methods are exposed in the public API but intended for internal use. For example:

mongo-java-driver/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/ClientSession.java

Lines 37 to 55 in 5e4e96a

/**

* Notify the client session that a message has been sent.

* 

* For internal use only

* 

*

* @return true if this is the first message sent, false otherwise

* @since 4.0

*/

boolean notifyMessageSent();

/**

* Notify the client session that command execution is being initiated. This should be called before server selection occurs.

* 

* For internal use only

* 

* @param operation the operation

*/

void notifyOperationInitiated(Object operation);

Since we’ve introduced a new annotation here, should we make it consistent with those cases by adding the annotation there as well? We could do this in a separate ticket.

Avoid appending duplicate metadata Added new @internal annotation for non public / public apis JAVA-5955 --------- Co-authored-by: Viacheslav Babanin <frest0512@gmail.com>

ClientMetaData refactoring

6b7dab5

Avoid appending duplicate metadata JAVA-5955

rozza requested a review from Copilot September 22, 2025 13:14

Copilot AI reviewed Sep 22, 2025

View reviewed changes

driver-core/src/main/com/mongodb/internal/client/package-info.java Outdated Show resolved Hide resolved

Update driver-core/src/main/com/mongodb/internal/client/package-info.…

cda23e3

…java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

rozza marked this pull request as ready for review September 22, 2025 14:13

rozza requested a review from a team as a code owner September 22, 2025 14:14

rozza requested review from nhachicha and removed request for a team September 22, 2025 14:14

rozza commented Sep 22, 2025

View reviewed changes

nhachicha reviewed Sep 23, 2025

View reviewed changes

rozza requested a review from nhachicha September 23, 2025 12:25

vbabanin reviewed Sep 23, 2025

View reviewed changes

driver-core/src/main/com/mongodb/internal/client/DriverInformationHelper.java Outdated Show resolved Hide resolved

Update driver-core/src/main/com/mongodb/internal/client/DriverInforma…

70c8179

…tionHelper.java Co-authored-by: Viacheslav Babanin <frest0512@gmail.com>

nhachicha approved these changes Sep 24, 2025

View reviewed changes

rozza and others added 3 commits September 24, 2025 10:47

Merge branch 'main' into JAVA-5955

c85a77c

PR add imports post improvement

3803341

Merge branch 'main' into JAVA-5955

3910d5c

vbabanin requested changes Oct 1, 2025

View reviewed changes

rozza and others added 2 commits October 2, 2025 09:24

Fix license copy pasta

0bb50c5

Merge branch 'main' into JAVA-5955

bd04aa7

rozza merged commit 94aca5e into mongodb:main Oct 2, 2025
53 of 56 checks passed

rozza deleted the JAVA-5955 branch October 2, 2025 10:15

	/**
	* Notify the client session that a message has been sent.
	* <p>
	* For internal use only
	* </p>
	*
	* @return true if this is the first message sent, false otherwise
	* @since 4.0
	*/
	boolean notifyMessageSent();

	/**
	* Notify the client session that command execution is being initiated. This should be called before server selection occurs.
	* <p>
	* For internal use only
	* </p>
	* @param operation the operation
	*/
	void notifyOperationInitiated(Object operation);


		import java.util.Objects;

		public final class DriverInformation {

ClientMetaData refactoring #1807

ClientMetaData refactoring #1807

Uh oh!

Conversation

rozza commented Sep 22, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vbabanin Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rozza Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rozza commented Sep 23, 2025

Uh oh!

Uh oh!

nhachicha left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vbabanin Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vbabanin Oct 1, 2025 •

edited

Loading

rozza Oct 2, 2025 •

edited

Loading

vbabanin Oct 1, 2025 •

edited

Loading