Skip to content

Improve CSOT API discoverability and document its effect on retrying #1939

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vbabanin wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Improve CSOT API discoverability and document its effect on retrying #1939

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4cadad6
Improve CSOT API discoverability and document its effect on retrying
vbabanin Apr 12, 2026
e168f53
Merge branch 'main' into JAVA-6122
vbabanin Apr 12, 2026
6b0c88b
Add documentation to GridFSBucket.
vbabanin Apr 12, 2026
23ef136
Replace fully-qualified KDoc references with imports in Kotlin timeou…
vbabanin Apr 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions driver-core/src/main/com/mongodb/ClientSessionOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,9 @@ public TransactionOptions getDefaultTransactionOptions() {
* <li>{@code close}</li>
* </ul>
*
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore
* there is a possibility that the operation might not be timed out when expected. This limitation does not
* apply to the reactive streams API.
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore
* there is a possibility that the operation might not be timed out when expected. This limitation does not
* apply to the reactive streams API.
*
* @param timeUnit the time unit
* @return the default timeout
Expand Down Expand Up @@ -226,9 +226,9 @@ public Builder defaultTransactionOptions(final TransactionOptions defaultTransac
* <li>{@code close}</li>
* </ul>
*
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore
* there is a possibility that the operation might not be timed out when expected. This limitation does not
* apply to the reactive streams API.
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore
* there is a possibility that the operation might not be timed out when expected. This limitation does not
* apply to the reactive streams API.
*
* @param defaultTimeout the timeout
* @param timeUnit the time unit
Expand Down
54 changes: 49 additions & 5 deletions driver-core/src/main/com/mongodb/MongoClientSettings.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -432,9 +432,13 @@ public Builder writeConcern(final WriteConcern writeConcern) {
*
* <p>Starting with the 3.11.0 release, the default value is true</p>
*
* <p>If a {@linkplain #timeout(long, TimeUnit) timeout} is set, the driver may retry
* multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
*
* @param retryWrites sets if writes should be retried if they fail due to a network error.
* @return this
* @see #getRetryWrites()
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This @see #getRetryWrites() tag is inside MongoClientSettings.Builder, but Builder doesn’t define getRetryWrites(). This will produce a broken/unresolved Javadoc reference. Consider updating it to reference the actual getter on MongoClientSettings (e.g., MongoClientSettings#getRetryWrites()).

Suggested change
* @see #getRetryWrites()
* @see MongoClientSettings#getRetryWrites()

Copilot uses AI. Check for mistakes.
* @see #timeout(long, TimeUnit)
* @mongodb.server.release 3.6
*/
public Builder retryWrites(final boolean retryWrites) {
Expand All @@ -445,9 +449,13 @@ public Builder retryWrites(final boolean retryWrites) {
/**
* Sets whether reads should be retried if they fail due to a network error.
*
* <p>If a {@linkplain #timeout(long, TimeUnit) timeout} is set, the driver may retry
* multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
*
* @param retryReads sets if reads should be retried if they fail due to a network error.
* @return this
* @see #getRetryReads()
* @see #timeout(long, TimeUnit)
Comment on lines +452 to +458
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This @see #getRetryReads() tag is inside MongoClientSettings.Builder, but Builder doesn’t define getRetryReads(). This will produce a broken/unresolved Javadoc reference. Consider updating it to reference the actual getter on MongoClientSettings (e.g., MongoClientSettings#getRetryReads()).

Copilot uses AI. Check for mistakes.
* @since 3.11
* @mongodb.server.release 3.6
*/
Expand Down Expand Up @@ -716,14 +724,28 @@ public Builder inetAddressResolver(@Nullable final InetAddressResolver inetAddre
* <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
* </ul>
*
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the
* operation might not be timed out when expected. This limitation does not apply to the reactive streams API.
* <p>The timeout can be set at the following levels (ordered by lowest precedence):
* <ul>
* <li>{@link #timeout(long, TimeUnit) MongoClientSettings} (current)</li>
* <li>{@code MongoCluster.withTimeout}</li>
* <li>{@code MongoDatabase.withTimeout}</li>
* <li>{@code MongoCollection.withTimeout}</li>
* <li>{@link ClientSessionOptions.Builder#defaultTimeout(long, TimeUnit) ClientSessionOptions}</li>
* <li>{@link TransactionOptions.Builder#timeout(Long, TimeUnit) TransactionOptions}</li>
* </ul>
* If not set at a given level, the timeout is inherited from the level above.
*
* <p>If {@linkplain #retryWrites(boolean) write} or {@linkplain #retryReads(boolean) read} retries are enabled,
* the driver may retry multiple times until the timeout expires.
*
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the
* operation might not be timed out when expected. This limitation does not apply to the reactive streams API.
*
* @param timeout the timeout
* @param timeUnit the time unit
* @return this
* @since 5.2
* @see #getTimeout
* @see #getTimeout(TimeUnit)
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@see #getTimeout(TimeUnit) here is in MongoClientSettings.Builder, but Builder doesn’t have a getTimeout method. This will result in an unresolved Javadoc reference; consider changing it to point at MongoClientSettings#getTimeout(TimeUnit) instead.

Suggested change
* @see #getTimeout(TimeUnit)
* @see MongoClientSettings#getTimeout(TimeUnit)

Copilot uses AI. Check for mistakes.
*/
@Alpha(Reason.CLIENT)
public Builder timeout(final long timeout, final TimeUnit timeUnit) {
Expand Down Expand Up @@ -792,7 +814,11 @@ public WriteConcern getWriteConcern() {
*
* <p>Starting with the 3.11.0 release, the default value is true</p>
*
* <p>If a {@linkplain #getTimeout(TimeUnit) timeout} is set, the driver may retry
* multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
*
* @return the retryWrites value
* @see #getTimeout(TimeUnit)
* @mongodb.server.release 3.6
*/
public boolean getRetryWrites() {
Expand All @@ -802,7 +828,11 @@ public boolean getRetryWrites() {
/**
* Returns true if reads should be retried if they fail due to a network error or other retryable error. The default value is true.
*
* <p>If a {@linkplain #getTimeout(TimeUnit) timeout} is set, the driver may retry
* multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
*
* @return the retryReads value
* @see #getTimeout(TimeUnit)
* @since 3.11
* @mongodb.server.release 3.6
*/
Expand Down Expand Up @@ -934,12 +964,26 @@ public ServerApi getServerApi() {
* <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
* </ul>
*
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the
* operation might not be timed out when expected. This limitation does not apply to the reactive streams API.
* <p>The timeout can also be set at the following levels (ordered by lowest precedence):
* <ul>
* <li>{@code MongoCluster.getTimeout}</li>
* <li>{@code MongoDatabase.getTimeout}</li>
* <li>{@code MongoCollection.getTimeout}</li>
* <li>{@link ClientSessionOptions.Builder#defaultTimeout(long, TimeUnit) ClientSessionOptions}</li>
* <li>{@link TransactionOptions.Builder#timeout(Long, TimeUnit) TransactionOptions}</li>
* </ul>
* If not set at a given level, the timeout is inherited from the level above.
*
* <p>If {@linkplain #getRetryWrites() write} or {@linkplain #getRetryReads() read} retries are enabled,
* the driver may retry multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
*
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the
* operation might not be timed out when expected. This limitation does not apply to the reactive streams API.
*
* @param timeUnit the time unit
* @return the timeout in the given time unit
* @since 5.2
* @see Builder#timeout(long, TimeUnit)
*/
@Alpha(Reason.CLIENT)
@Nullable
Expand Down
8 changes: 4 additions & 4 deletions driver-core/src/main/com/mongodb/TransactionOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,8 +109,8 @@ public Long getMaxCommitTime(final TimeUnit timeUnit) {
* <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
* </ul>
*
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the
* operation might not be timed out when expected. This limitation does not apply to the reactive streams API.
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the
* operation might not be timed out when expected. This limitation does not apply to the reactive streams API.
*
* @param timeUnit the time unit
* @return the timeout in the given time unit
Expand Down Expand Up @@ -295,8 +295,8 @@ public Builder maxCommitTime(@Nullable final Long maxCommitTime, final TimeUnit
* <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
* </ul>
*
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the
* operation might not be timed out when expected. This limitation does not apply to the reactive streams API.
* <p>Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the
* operation might not be timed out when expected. This limitation does not apply to the reactive streams API.
*
* @param timeout the timeout
* @param timeUnit the time unit
Expand Down
30 changes: 29 additions & 1 deletion driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoCluster.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ import com.mongodb.MongoClientSettings
import com.mongodb.MongoException
import com.mongodb.ReadConcern
import com.mongodb.ReadPreference
import com.mongodb.TransactionOptions
import com.mongodb.WriteConcern
import com.mongodb.annotations.Alpha
import com.mongodb.annotations.Reason
Expand Down Expand Up @@ -81,7 +82,21 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
* - `0` means infinite timeout.
* - `> 0` The time limit to use for the full execution of an operation.
*
* The timeout can be set at the following levels (ordered by lowest precedence):
* - [MongoClientSettings.Builder.timeout]
* - [MongoCluster.withTimeout] (current)
* - [MongoDatabase.withTimeout]
* - [MongoCollection.withTimeout]
* - [ClientSessionOptions.Builder.defaultTimeout]
* - [TransactionOptions.Builder.timeout]
*
* If not set at a given level, the timeout is inherited from the level above.
*
* If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
* enabled, the driver may retry multiple times until the timeout expires.
*
* @return the optional timeout duration
* @see [withTimeout]
*/
@Alpha(Reason.CLIENT)
public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
Expand Down Expand Up @@ -134,10 +149,23 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
* - `0` means an infinite timeout
* - `> 0` The time limit to use for the full execution of an operation.
*
* The timeout can be set at the following levels (ordered by lowest precedence):
* - [MongoClientSettings.Builder.timeout]
* - [MongoCluster.withTimeout] (current)
* - [MongoDatabase.withTimeout]
* - [MongoCollection.withTimeout]
* - [ClientSessionOptions.Builder.defaultTimeout]
* - [TransactionOptions.Builder.timeout]
*
* If not set at a given level, the timeout is inherited from the level above.
*
* If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
* enabled, the driver may retry multiple times until the timeout expires.
*
* @param timeout the timeout, which must be greater than or equal to 0
* @param timeUnit the time unit, defaults to Milliseconds
* @return a new MongoCluster instance with the set time limit for operations
* @see [MongoDatabase.timeout]
* @see [timeout]
* @since 5.2
*/
@Alpha(Reason.CLIENT)
Expand Down
36 changes: 33 additions & 3 deletions ...r-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoCollection.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,12 @@
*/
package com.mongodb.kotlin.client.coroutine

import com.mongodb.ClientSessionOptions
import com.mongodb.MongoClientSettings
import com.mongodb.MongoNamespace
import com.mongodb.ReadConcern
import com.mongodb.ReadPreference
import com.mongodb.TransactionOptions
import com.mongodb.WriteConcern
import com.mongodb.annotations.Alpha
import com.mongodb.annotations.Reason
Expand Down Expand Up @@ -105,7 +108,21 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
* - `0` means infinite timeout.
* - `> 0` The time limit to use for the full execution of an operation.
*
* The timeout can be set at the following levels (ordered by lowest precedence):
* - [MongoClientSettings.Builder.timeout]
* - [MongoCluster.withTimeout]
* - [MongoDatabase.withTimeout]
* - [MongoCollection.withTimeout] (current)
* - [ClientSessionOptions.Builder.defaultTimeout]
* - [TransactionOptions.Builder.timeout]
*
* If not set at a given level, the timeout is inherited from the level above.
*
* If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
* enabled, the driver may retry multiple times until the timeout expires.
*
* @return the optional timeout duration
* @see [withTimeout]
* @since 5.2
*/
@Alpha(Reason.CLIENT)
Expand Down Expand Up @@ -149,7 +166,7 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
/**
* Create a new collection instance with a different read preference.
*
* @param newReadPreference the new [com.mongodb.ReadPreference] for the collection
* @param newReadPreference the new [ReadPreference] for the collection
* @return a new MongoCollection instance with the different readPreference
*/
public fun withReadPreference(newReadPreference: ReadPreference): MongoCollection<T> =
Expand All @@ -168,7 +185,7 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
/**
* Create a new collection instance with a different write concern.
*
* @param newWriteConcern the new [com.mongodb.WriteConcern] for the collection
* @param newWriteConcern the new [WriteConcern] for the collection
* @return a new MongoCollection instance with the different writeConcern
*/
public fun withWriteConcern(newWriteConcern: WriteConcern): MongoCollection<T> =
Expand All @@ -179,10 +196,23 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
* - `0` means an infinite timeout
* - `> 0` The time limit to use for the full execution of an operation.
*
* The timeout can be set at the following levels (ordered by lowest precedence):
* - [MongoClientSettings.Builder.timeout]
* - [MongoCluster.withTimeout]
* - [MongoDatabase.withTimeout]
* - [MongoCollection.withTimeout] (current)
* - [ClientSessionOptions.Builder.defaultTimeout]
* - [TransactionOptions.Builder.timeout]
*
* If not set at a given level, the timeout is inherited from the level above.
*
* If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
* enabled, the driver may retry multiple times until the timeout expires.
*
* @param timeout the timeout, which must be greater than or equal to 0
* @param timeUnit the time unit, defaults to Milliseconds
* @return a new MongoCollection instance with the set time limit for operations
* @see [MongoCollection.timeout]
* @see [timeout]
* @since 5.2
*/
@Alpha(Reason.CLIENT)
Expand Down
32 changes: 31 additions & 1 deletion driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoDatabase.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,11 @@
*/
package com.mongodb.kotlin.client.coroutine

import com.mongodb.ClientSessionOptions
import com.mongodb.MongoClientSettings
import com.mongodb.ReadConcern
import com.mongodb.ReadPreference
import com.mongodb.TransactionOptions
import com.mongodb.WriteConcern
import com.mongodb.annotations.Alpha
import com.mongodb.annotations.Reason
Expand Down Expand Up @@ -73,7 +76,21 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
* - `0` means infinite timeout.
* - `> 0` The time limit to use for the full execution of an operation.
*
* The timeout can be set at the following levels (ordered by lowest precedence):
* - [MongoClientSettings.Builder.timeout]
* - [MongoCluster.withTimeout]
* - [MongoDatabase.withTimeout] (current)
* - [MongoCollection.withTimeout]
* - [ClientSessionOptions.Builder.defaultTimeout]
* - [TransactionOptions.Builder.timeout]
*
* If not set at a given level, the timeout is inherited from the level above.
*
* If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
* enabled, the driver may retry multiple times until the timeout expires.
*
* @return the optional timeout duration
* @see [withTimeout]
* @since 5.2
*/
@Alpha(Reason.CLIENT)
Expand Down Expand Up @@ -127,10 +144,23 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
* - `0` means an infinite timeout
* - `> 0` The time limit to use for the full execution of an operation.
*
* The timeout can be set at the following levels (ordered by lowest precedence):
* - [MongoClientSettings.Builder.timeout]
* - [MongoCluster.withTimeout]
* - [MongoDatabase.withTimeout] (current)
* - [MongoCollection.withTimeout]
* - [ClientSessionOptions.Builder.defaultTimeout]
* - [TransactionOptions.Builder.timeout]
*
* If not set at a given level, the timeout is inherited from the level above.
*
* If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
* enabled, the driver may retry multiple times until the timeout expires.
*
* @param timeout the timeout, which must be greater than or equal to 0
* @param timeUnit the time unit, defaults to Milliseconds
* @return a new MongoDatabase instance with the set time limit for operations
* @see [MongoDatabase.timeout]
* @see [timeout]
* @since 5.2
*/
@Alpha(Reason.CLIENT)
Expand Down
Loading