Adding timeoutMS for explain helpers

[nhachicha]

Fixes JAVA-5579

[rozza]

@nhachicha - looks like some tests are failing:

com.mongodb.reactivestreams.client.ExplainTest.testExplainWithMaxTimeMS - 5 Failed

com.mongodb.client.ExplainTest.testExplainWithMaxTimeMS - 3 Failed

[nhachicha]

@rozza Fixed https://spruce.mongodb.com/version/687fc6361ce1270007a8f87d/test-analysis?page=0&sorts=STATUS%3AASC%3BBASE_STATUS%3ADESC

[Copilot]

Pull Request Overview

This PR adds timeout support to the MongoDB driver's explain operations for find and aggregate queries. The implementation adds new overloaded methods that accept a timeoutMS parameter, allowing developers to specify custom timeouts for explain operations rather than relying on global timeout settings.

Key changes include:

• Addition of four new explain method overloads accepting timeoutMS parameter for both FindIterable and AggregateIterable interfaces
• Implementation of timeout-aware execute methods that create specialized timeout executors
• Comprehensive test coverage verifying timeout behavior and command structure

Reviewed Changes

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

File	Description
AbstractExplainTest.java	Adds functional test for explain timeout behavior with fail point testing
FindIterable.java / AggregateIterable.java	Interface definitions for new timeout-aware explain methods
FindIterableImpl.java / AggregateIterableImpl.java	Core implementation of timeout-aware explain execution
Various driver adapters	Implementation of new methods across Scala, Kotlin, and reactive streams adapters

[jyemin]

All these should be 5.6.

[jyemin]

I'm not clear why all these overloads are needed. For the rest of CSOT, applications specify the timeout via MongoCluster/MongoDatabase/MongoCollection#withTimeout. Would that suffice for specifying the timeout for explain?

[vbabanin]

The changes covered by this ticket were already implemented in JAVA-5580, where we also decided not to introduce any new knobs on explain helpers (during one of the catch-ups).

According to the existing CSOT specification, timeoutMS is intended to be specified per operation. The unified spec tests also require timeoutMS to be passed explicitly for each operation.

Our API supports this model via withTimeout() methods on MongoCollection, MongoDatabase, and MongoClient, which allow users to define a timeout at the desired scope, and subsequently per operation. For example, if a user wants to apply a timeout to a specific operation, they can call:

collection.withTimeout(100, TimeUnit.SECONDS).find(...).explain();

In that case,timeoutMS is applied to the actual operation that is executed, thus explain command, not a command being explained. The maxTimeMS on the command being explained is ignored by the server, even if it was present.

This approach aligns with our existing API design, which already includes withWriteConcern() and withReadPreference() on the aforementioned API components.

We've documented this design approach, along with the reasoning and tradeoffs, here:
Design doc.

To clarify: timeoutMS and maxTimeMS are separate APIs. timeoutMS is the successor, and it deprecates maxTimeMS. As noted in the CRUD spec:

"NOTE: This option is deprecated in favor of timeoutMS."

Regarding maxTimeMS (which is going to be marked deprecated once CSOT is GA).

The prose test in the CRUD spec applies only to the deprecated maxTimeMS. In discussion comments of DRIVERS-1256, we agreed not to require drivers to implement maxTimeMS support on explain for drivers that already support CSOT, since it would introduce a soon-to-be-deprecated parameter. See also this related spec PR comment.

While CSOT is currently marked alpha, timeoutMS already works with explain() via MongoCollection and explain(), allowing users to troubleshoot operations if needed.

Given that:

• CSOT is already in place (albeit alpha).
• timeoutMS works as intended with explain() via withTimeout on MongoCollection.
• and JAVA-5580 already covered the necessary changes.

I believe, no additional changes are needed as part of this ticket JAVA-5579.