Merge branch 'main' into JAVA-6122

# Conflicts:
#	driver-core/src/main/com/mongodb/MongoClientSettings.java
#	driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCluster.kt
#	driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCollection.kt
#	driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoDatabase.kt
#	driver-sync/src/main/com/mongodb/client/MongoCluster.java
#	driver-sync/src/main/com/mongodb/client/MongoCollection.java
#	driver-sync/src/main/com/mongodb/client/MongoDatabase.java

Author: vbabanin

.evergreen/.evg.yml

@@ -2507,23 +2507,14 @@ buildvariants:
     tasks:
       - name: ".ocsp"
 
-  - matrix_name: "scala-tests-2"
+  - matrix_name: "scala-tests"
     matrix_spec: { auth: "noauth", ssl: "nossl", jdk: [ "jdk8", "jdk17", "jdk21" ], version: [ "7.0" ], topology: "replicaset",
-                   scala: ["2.11", "2.12", "2.13"] , os: "ubuntu" }
+                   scala: "*" , os: "ubuntu" }
     display_name: "${scala} ${jdk} ${version} ${topology} ${os}"
     tags: [ "test-scala-variant" ]
     tasks:
       - name: "scala-test-task"
 
-  - matrix_name: "scala-tests-3"
-    matrix_spec: { auth: "noauth", ssl: "nossl", jdk: [ "jdk17", "jdk21" ], version: [ "8.0" ], topology: "replicaset",
-                   scala: "3", os: "ubuntu" }
-    display_name: "${scala} ${jdk} ${version} ${topology} ${os}"
-    tags: [ "test-scala-variant" ]
-    tasks:
-      - name: "scala-test-task"
-
-
   - matrix_name: "kotlin-tests"
     matrix_spec: { auth: "noauth", ssl: "nossl", jdk: [ "jdk8", "jdk17", "jdk21" ], version: [ "7.0" ], topology: "replicaset", os: "ubuntu" }
     display_name: "Kotlin: ${jdk} ${version} ${topology} ${os}"

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

@@ -172,10 +172,15 @@ public Builder keyExpiration(@Nullable final Long keyExpiration, final TimeUnit
          *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
          * </ul>
          *
-         * <p><strong>Note:</strong> The timeout set through this method overrides the timeout defined in the key vault client settings
-         * specified in {@link #keyVaultMongoClientSettings(MongoClientSettings)}.
-         * Essentially, for operations that require accessing the key vault, the remaining timeout from the initial operation
-         * determines the duration allowed for key vault access.</p>
+         * <p>Note:
+         * <ul>
+         *   <li>The timeout set through this method overrides the timeout defined in the key vault client settings
+         *       specified in {@link #keyVaultMongoClientSettings(MongoClientSettings)}.
+         *       Essentially, for operations that require accessing the key vault, the remaining timeout from the initial operation
+         *       determines the duration allowed for key vault access.</li>
+         *   <li>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.</li>
+         * </ul>
          *
          * @param timeout the timeout
          * @param timeUnit the time unit
@@ -368,6 +373,16 @@ public Long getKeyExpiration(final TimeUnit timeUnit) {
      *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
      * </ul>
      *
+     * <p>Note:
+     * <ul>
+     *   <li>The timeout set through this method overrides the timeout defined in the key vault client settings
+     *       specified in {@link Builder#keyVaultMongoClientSettings(MongoClientSettings)}.
+     *       Essentially, for operations that require accessing the key vault, the remaining timeout from the initial operation
+     *       determines the duration allowed for key vault access.</li>
+     *   <li>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.</li>
+     * </ul>
+     *
      * @param timeUnit the time unit
      * @return the timeout in the given time unit
      * @since 5.2

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

@@ -92,6 +92,11 @@ public TransactionOptions getDefaultTransactionOptions() {
      *   <li>{@code withTransaction}</li>
      *   <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.
+     *
      * @param timeUnit the time unit
      * @return the default timeout
      * @since 5.2
@@ -220,6 +225,11 @@ public Builder defaultTransactionOptions(final TransactionOptions defaultTransac
          *   <li>{@code withTransaction}</li>
          *   <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.
+         *
          * @param defaultTimeout the timeout
          * @param timeUnit the time unit
          * @return this

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

@@ -40,6 +40,7 @@ public enum ErrorCategory {
     /**
      * An execution timeout error
      *
+     * @see MongoExecutionTimeoutException
      * @mongodb.driver.manual reference/operator/meta/maxTimeMS/ maxTimeMS
      */
     EXECUTION_TIMEOUT;

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

@@ -738,6 +738,9 @@ public Builder inetAddressResolver(@Nullable final InetAddressResolver inetAddre
          * <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
@@ -974,6 +977,9 @@ public ServerApi getServerApi() {
      * <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

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

@@ -16,30 +16,18 @@
 
 package com.mongodb;
 
-import com.mongodb.annotations.Alpha;
-import com.mongodb.annotations.Reason;
 import org.bson.BsonDocument;
 
 /**
- * Exception indicating that the execution of the current operation timed out as a result of the maximum operation time being exceeded.
+ * Exception indicating that the execution of the current command timed out by the server
+ * as a result of the {@linkplain ErrorCategory#EXECUTION_TIMEOUT maximum operation time being exceeded}.
  *
+ * @see MongoTimeoutException
  * @since 2.12
  */
 public class MongoExecutionTimeoutException extends MongoException {
     private static final long serialVersionUID = 5955669123800274594L;
 
-    /**
-     * Construct a new instance.
-     *
-     * @param message the error message
-     * @since 5.2
-     */
-    @Alpha(Reason.CLIENT)
-    public MongoExecutionTimeoutException(final String message) {
-        super(message);
-
-    }
-
     /**
      * Construct a new instance.
      *

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

@@ -25,15 +25,15 @@
  * Exception thrown to indicate that a MongoDB operation has exceeded the specified timeout for
  * the full execution of operation.
  *
- * <p>The {@code MongoOperationTimeoutException} might provide information about the underlying
+ * <p>The {@link MongoOperationTimeoutException} might provide information about the underlying
  * cause of the timeout, if available. For example, if retries are attempted due to transient failures,
  * and a timeout occurs in any of the attempts, the exception from one of the retries may be appended
- * as the cause to this {@code MongoOperationTimeoutException}.
+ * as the cause to this {@link MongoOperationTimeoutException}.
  *
- * <p>The key difference between {@code MongoOperationTimeoutException} and {@code MongoExecutionTimeoutException}
- * lies in the nature of these exceptions. {@code MongoExecutionTimeoutException} indicates a server-side timeout
- * capped by a user-specified number. These server errors are transformed into the new {@code MongoOperationTimeoutException}.
- * On the other hand, {@code MongoOperationExecutionException} denotes a timeout during the execution of the entire operation.
+ * <p>The key difference between {@link MongoOperationTimeoutException} and {@link MongoExecutionTimeoutException}
+ * lies in the nature of these exceptions. {@link MongoExecutionTimeoutException} indicates a server-side timeout
+ * capped by a user-specified number. These server errors are transformed into the new {@link MongoOperationTimeoutException}.
+ * On the other hand, {@link MongoOperationTimeoutException} denotes a timeout during the execution of the entire operation.
  *
  * @see MongoClientSettings.Builder#timeout(long, TimeUnit)
  * @see MongoClientSettings#getTimeout(TimeUnit)

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

@@ -21,7 +21,9 @@
 import com.mongodb.lang.Nullable;
 
 /**
- * An exception indicating that the driver has timed out waiting for either a server or a connection to become available.
+ * An exception indicating that the driver has timed out doing something.
+ *
+ * @see MongoExecutionTimeoutException
  */
 public class MongoTimeoutException extends MongoClientException {
 

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

@@ -109,6 +109,9 @@ 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.
+     *
      * @param timeUnit the time unit
      * @return the timeout in the given time unit
      * @since 5.2
@@ -292,6 +295,9 @@ 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.
+         *
          * @param timeout the timeout
          * @param timeUnit the time unit
          * @return this

driver-core/src/main/com/mongodb/internal/TimeoutContext.java

@@ -28,6 +28,7 @@
 
 import static com.mongodb.assertions.Assertions.assertNotNull;
 import static com.mongodb.assertions.Assertions.assertNull;
+import static com.mongodb.assertions.Assertions.assertTrue;
 import static com.mongodb.assertions.Assertions.isTrue;
 import static com.mongodb.internal.VisibleForTesting.AccessModifier.PRIVATE;
 import static com.mongodb.internal.time.Timeout.ZeroSemantics.ZERO_DURATION_MEANS_INFINITE;
@@ -41,6 +42,9 @@
 public class TimeoutContext {
     private static final int NO_ROUND_TRIP_TIME_MS = 0;
     private final TimeoutSettings timeoutSettings;
+    /**
+     * Is {@code null} iff {@link #timeoutSettings}{@code .}{@link TimeoutSettings#getTimeoutMS() getTimeoutMS()} is {@code null}.
+     */
     @Nullable
     private final Timeout timeout;
     @Nullable
@@ -139,6 +143,7 @@ private TimeoutContext(final boolean isMaintenanceContext,
                            final TimeoutSettings timeoutSettings,
                            @Nullable final MaxTimeSupplier maxTimeSupplier,
                            @Nullable final Timeout timeout) {
+        assertTrue((timeoutSettings.getTimeoutMS() == null) == (timeout == null));
         this.isMaintenanceContext = isMaintenanceContext;
         this.timeoutSettings = timeoutSettings;
         this.minRoundTripTimeMS = minRoundTripTimeMS;
@@ -149,7 +154,8 @@ private TimeoutContext(final boolean isMaintenanceContext,
     /**
      * Allows for the differentiation between users explicitly setting a global operation timeout via {@code timeoutMS}.
      *
-     * @return true if a timeout has been set.
+     * @return true iff {@link #getTimeoutSettings()}{@code .}{@link TimeoutSettings#getTimeoutMS() getTimeoutMS()} is not {@code null}.
+     * @see #getTimeout()
      */
     public boolean hasTimeoutMS() {
         return timeoutSettings.getTimeoutMS() != null;
@@ -170,7 +176,6 @@ public Timeout timeoutIncludingRoundTrip() {
 
     /**
      * Returns the remaining {@code timeoutMS} if set or the {@code alternativeTimeoutMS}.
-     *
      * zero means infinite timeout.
      *
      * @param alternativeTimeoutMS the alternative timeout.
@@ -191,6 +196,10 @@ public TimeoutSettings getTimeoutSettings() {
         return timeoutSettings;
     }
 
+    /**
+     * @return {@code null} iff {@link #hasTimeoutMS()} is {@code false}.
+     * @see #hasTimeoutMS()
+     */
     @Nullable
     public Timeout getTimeout() {
         return timeout;