CSOT

README.md

@@ -54,6 +54,17 @@ almost always be binary compatible with prior minor releases from the same major
 Patch 5.x.y increments (such as 5.0.0 -> 5.0.1, 5.1.1 -> 5.1.2, etc) will occur for bug fixes only and will always be binary compatible
 with prior patch releases of the same minor release branch.
 
+#### @Alpha
+
+APIs marked with the `@Alpha` annotation are in the early stages of development, subject to incompatible changes, 
+or even removal, in a future release and may lack some intended features. An APIs bearing `@Alpha` annotation may 
+contain known issues affecting functionality, performance, and stability. They are also exempt from any compatibility 
+guarantees made by its containing library.
+
+It is inadvisable for <i>applications</i> to use Alpha APIs in production environments or for <i>libraries</i>
+(which get included on users' CLASSPATHs, outside the library developers' control) to depend on these APIs. Alpha APIs
+are intended for <b>experimental purposes</b> only.
+
 #### @Beta
 
 APIs marked with the `@Beta` annotation at the class or method level are subject to change. They can be modified in any way, or even

THIRD-PARTY-NOTICES

@@ -37,7 +37,10 @@ https://github.com/mongodb/mongo-java-driver.
     See the License for the specific language governing permissions and
     limitations under the License.
 
-3) The following files: Beta.java
+3) The following files:
+
+    Alpha.java (formerly Beta.java)
+    Beta.java
 
     Copyright 2010 The Guava Authors
     Copyright 2011 The Guava Authors

build.gradle

@@ -158,6 +158,7 @@ configure(scalaProjects) {
                     "-unchecked",
                     "-language:reflectiveCalls",
                     "-Wconf:cat=deprecation:ws,any:e",
+                    "-Wconf:msg=While parsing annotations in:silent",
                     "-Xlint:strict-unsealed-patmat"
             ]
         }

config/checkstyle/suppressions.xml

@@ -29,6 +29,7 @@
     <suppress checks="MethodLength" files="QuickTour"/>
     <suppress checks="Regexp" files="Tour"/>
 
+    <suppress checks="FileLength" files="UnifiedCrudHelper"/>
     <suppress checks="MethodLength" files="PojoRoundTripTest"/>
     <suppress checks="MethodLength" files="AbstractUnifiedTest"/>
     <suppress checks="MethodLength" files="AbstractClientSideEncryptionTest"/>
@@ -87,6 +88,7 @@
     <suppress checks="ParameterNumber" files="Operations"/>
     <suppress checks="ParameterNumber" files="ChangeStreamDocument"/>
     <suppress checks="ParameterNumber" files="StructuredLogger"/>
+    <suppress checks="ParameterNumber" files="MongoClusterImpl"/>
 
     <!--Legacy code that has not yet been cleaned-->
     <suppress checks="FinalClass" files="AggregationOptions"/>

config/spotbugs/exclude.xml

@@ -223,7 +223,7 @@
     -->
     <Match>
         <!-- MongoDB status: "False Positive", SpotBugs rank: 13 -->
-        <Class name="com.mongodb.kotlin.client.coroutine.MongoClient"/>
+        <Class name="com.mongodb.kotlin.client.coroutine.MongoCluster"/>
         <Method name="startSession"/>
         <Bug pattern="NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE"/>
     </Match>
@@ -233,4 +233,25 @@
         <Bug pattern="NP_NONNULL_PARAM_VIOLATION"/>
     </Match>
 
+    <!-- Ignoring await return; intended to be used in a loop -->
+    <Match>
+        <Class name="com.mongodb.internal.time.Timeout"/>
+        <Bug pattern="RV_RETURN_VALUE_IGNORED_BAD_PRACTICE"/>
+    </Match>
+    <Match>
+        <Class name="com.mongodb.internal.time.Timeout"/>
+        <Bug pattern="RV_RETURN_VALUE_IGNORED"/>
+    </Match>
+    <Match>
+        <Class name="com.mongodb.internal.time.Timeout"/>
+        <Bug pattern="WA_AWAIT_NOT_IN_LOOP"/>
+    </Match>
+
+    <!-- Void method returning null but @NotNull API -->
+    <Match>
+        <Class name="com.mongodb.internal.operation.DropIndexOperation"/>
+        <Method name="execute"/>
+        <Bug pattern="NP_NONNULL_RETURN_VIOLATION"/>
+    </Match>
+
 </FindBugsFilter>

driver-core/build.gradle

@@ -58,6 +58,7 @@ dependencies {
     implementation "org.mongodb:mongodb-crypt:$mongoCryptVersion", optional
 
     testImplementation project(':bson').sourceSets.test.output
+    testImplementation('org.junit.jupiter:junit-jupiter-api')
     testRuntimeOnly "io.netty:netty-tcnative-boringssl-static"
 
     classifiers.forEach {

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

@@ -17,6 +17,7 @@
 package com.mongodb;
 
 import com.mongodb.annotations.Beta;
+import com.mongodb.annotations.Reason;
 import com.mongodb.lang.Nullable;
 
 import static com.mongodb.assertions.Assertions.notNull;
@@ -28,7 +29,7 @@
  * @see MongoCredential#AWS_CREDENTIAL_PROVIDER_KEY
  * @since 4.4
  */
-@Beta(Beta.Reason.CLIENT)
+@Beta(Reason.CLIENT)
 public final class AwsCredential {
     private final String accessKeyId;
     private final String secretAccessKey;

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

@@ -16,15 +16,21 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.NotThreadSafe;
+import com.mongodb.annotations.Reason;
+import com.mongodb.lang.Nullable;
 
 import javax.net.ssl.SSLContext;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
 
 import static com.mongodb.assertions.Assertions.notNull;
+import static com.mongodb.internal.TimeoutSettings.convertAndValidateTimeout;
 import static java.util.Collections.unmodifiableMap;
+import static java.util.concurrent.TimeUnit.MILLISECONDS;
 
 /**
  * The client-side settings for data key creation and explicit encryption.
@@ -42,6 +48,8 @@ public final class ClientEncryptionSettings {
     private final Map<String, Map<String, Object>> kmsProviders;
     private final Map<String, Supplier<Map<String, Object>>> kmsProviderPropertySuppliers;
     private final Map<String, SSLContext> kmsProviderSslContextMap;
+    @Nullable
+    private final Long timeoutMS;
     /**
      * A builder for {@code ClientEncryptionSettings} so that {@code ClientEncryptionSettings} can be immutable, and to support easier
      * construction through chaining.
@@ -53,6 +61,8 @@ public static final class Builder {
         private Map<String, Map<String, Object>> kmsProviders;
         private Map<String, Supplier<Map<String, Object>>> kmsProviderPropertySuppliers = new HashMap<>();
         private Map<String, SSLContext> kmsProviderSslContextMap = new HashMap<>();
+        @Nullable
+        private Long timeoutMS;
 
         /**
          * Sets the {@link MongoClientSettings} that will be used to access the key vault.
@@ -120,6 +130,43 @@ public Builder kmsProviderSslContextMap(final Map<String, SSLContext> kmsProvide
             return this;
         }
 
+        /**
+         * Sets the time limit for the full execution of an operation.
+         *
+         * <ul>
+         *   <li>{@code null} means that the timeout mechanism for operations will defer to using:
+         *    <ul>
+         *        <li>{@code waitQueueTimeoutMS}: The maximum wait time in milliseconds that a thread may wait for a connection to become
+         *        available</li>
+         *        <li>{@code socketTimeoutMS}: How long a send or receive on a socket can take before timing out.</li>
+         *        <li>{@code wTimeoutMS}: How long the server will wait for the write concern to be fulfilled before timing out.</li>
+         *        <li>{@code maxTimeMS}: The cumulative time limit for processing operations on a cursor.
+         *        See: <a href="https://docs.mongodb.com/manual/reference/method/cursor.maxTimeMS">cursor.maxTimeMS</a>.</li>
+         *        <li>{@code maxCommitTimeMS}: The maximum amount of time to allow a single {@code commitTransaction} command to execute.
+         *        See: {@link TransactionOptions#getMaxCommitTime}.</li>
+         *   </ul>
+         *   </li>
+         *   <li>{@code 0} means infinite timeout.</li>
+         *    <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>
+         *
+         * @param timeout the timeout
+         * @param timeUnit the time unit
+         * @return this
+         * @since CSOT
+         * @see #getTimeout
+         */
+        @Alpha(Reason.CLIENT)
+        public ClientEncryptionSettings.Builder timeout(final long timeout, final TimeUnit timeUnit) {
+            this.timeoutMS = convertAndValidateTimeout(timeout, timeUnit);
+            return this;
+        }
+
         /**
          * Build an instance of {@code ClientEncryptionSettings}.
          *
@@ -253,12 +300,46 @@ public Map<String, SSLContext> getKmsProviderSslContextMap() {
         return unmodifiableMap(kmsProviderSslContextMap);
     }
 
+    /**
+     * The time limit for the full execution of an operation.
+     *
+     * <p>If set the following deprecated options will be ignored:
+     * {@code waitQueueTimeoutMS}, {@code socketTimeoutMS}, {@code wTimeoutMS}, {@code maxTimeMS} and {@code maxCommitTimeMS}</p>
+     *
+     * <ul>
+     *   <li>{@code null} means that the timeout mechanism for operations will defer to using:
+     *    <ul>
+     *        <li>{@code waitQueueTimeoutMS}: The maximum wait time in milliseconds that a thread may wait for a connection to become
+     *        available</li>
+     *        <li>{@code socketTimeoutMS}: How long a send or receive on a socket can take before timing out.</li>
+     *        <li>{@code wTimeoutMS}: How long the server will wait for the write concern to be fulfilled before timing out.</li>
+     *        <li>{@code maxTimeMS}: The cumulative time limit for processing operations on a cursor.
+     *        See: <a href="https://docs.mongodb.com/manual/reference/method/cursor.maxTimeMS">cursor.maxTimeMS</a>.</li>
+     *        <li>{@code maxCommitTimeMS}: The maximum amount of time to allow a single {@code commitTransaction} command to execute.
+     *        See: {@link TransactionOptions#getMaxCommitTime}.</li>
+     *   </ul>
+     *   </li>
+     *   <li>{@code 0} means infinite timeout.</li>
+     *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
+     * </ul>
+     *
+     * @param timeUnit the time unit
+     * @return the timeout in the given time unit
+     * @since CSOT
+     */
+    @Alpha(Reason.CLIENT)
+    @Nullable
+    public Long getTimeout(final TimeUnit timeUnit) {
+        return timeoutMS == null ? null : timeUnit.convert(timeoutMS, MILLISECONDS);
+    }
+
     private ClientEncryptionSettings(final Builder builder) {
         this.keyVaultMongoClientSettings = notNull("keyVaultMongoClientSettings", builder.keyVaultMongoClientSettings);
         this.keyVaultNamespace = notNull("keyVaultNamespace", builder.keyVaultNamespace);
         this.kmsProviders = notNull("kmsProviders", builder.kmsProviders);
         this.kmsProviderPropertySuppliers = notNull("kmsProviderPropertySuppliers", builder.kmsProviderPropertySuppliers);
         this.kmsProviderSslContextMap = notNull("kmsProviderSslContextMap", builder.kmsProviderSslContextMap);
+        this.timeoutMS = builder.timeoutMS;
     }
 
 }

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

@@ -16,14 +16,19 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
+import com.mongodb.annotations.Reason;
 import com.mongodb.lang.Nullable;
 import com.mongodb.session.ClientSession;
 
 import java.util.Objects;
+import java.util.concurrent.TimeUnit;
 
 import static com.mongodb.assertions.Assertions.notNull;
+import static com.mongodb.internal.TimeoutSettings.convertAndValidateTimeout;
+import static java.util.concurrent.TimeUnit.MILLISECONDS;
 
 /**
  * The options to apply to a {@code ClientSession}.
@@ -38,6 +43,7 @@ public final class ClientSessionOptions {
 
     private final Boolean causallyConsistent;
     private final Boolean snapshot;
+    private final Long defaultTimeoutMS;
     private final TransactionOptions defaultTransactionOptions;
 
     /**
@@ -77,6 +83,25 @@ public TransactionOptions getDefaultTransactionOptions() {
         return defaultTransactionOptions;
     }
 
+    /**
+     * Gets the default time limit for the following operations executed on the session:
+     *
+     * <ul>
+     *   <li>{@code commitTransaction}</li>
+     *   <li>{@code abortTransaction}</li>
+     *   <li>{@code withTransaction}</li>
+     *   <li>{@code close}</li>
+     * </ul>
+     * @param timeUnit the time unit
+     * @return the default timeout
+     * @since CSOT
+     */
+    @Alpha(Reason.CLIENT)
+    @Nullable
+    public Long getDefaultTimeout(final TimeUnit timeUnit) {
+        return defaultTimeoutMS == null ? null : timeUnit.convert(defaultTimeoutMS, MILLISECONDS);
+    }
+
     @Override
     public boolean equals(final Object o) {
         if (this == o) {
@@ -85,36 +110,24 @@ public boolean equals(final Object o) {
         if (o == null || getClass() != o.getClass()) {
             return false;
         }
-
-        ClientSessionOptions that = (ClientSessionOptions) o;
-
-        if (!Objects.equals(causallyConsistent, that.causallyConsistent)) {
-            return false;
-        }
-
-        if (!Objects.equals(snapshot, that.snapshot)) {
-            return false;
-        }
-        if (!Objects.equals(defaultTransactionOptions, that.defaultTransactionOptions)) {
-            return false;
-        }
-
-        return true;
+        final ClientSessionOptions that = (ClientSessionOptions) o;
+        return Objects.equals(causallyConsistent, that.causallyConsistent)
+                && Objects.equals(snapshot, that.snapshot)
+                && Objects.equals(defaultTimeoutMS, that.defaultTimeoutMS)
+                && Objects.equals(defaultTransactionOptions, that.defaultTransactionOptions);
     }
 
     @Override
     public int hashCode() {
-        int result = causallyConsistent != null ? causallyConsistent.hashCode() : 0;
-        result = 31 * result + (snapshot != null ? snapshot.hashCode() : 0);
-        result = 31 * result + (defaultTransactionOptions != null ? defaultTransactionOptions.hashCode() : 0);
-        return result;
+        return Objects.hash(causallyConsistent, snapshot, defaultTimeoutMS, defaultTransactionOptions);
     }
 
     @Override
     public String toString() {
         return "ClientSessionOptions{"
                 + "causallyConsistent=" + causallyConsistent
-                + "snapshot=" + snapshot
+                + ", snapshot=" + snapshot
+                + ", defaultTimeoutMS=" + defaultTimeoutMS
                 + ", defaultTransactionOptions=" + defaultTransactionOptions
                 + '}';
     }
@@ -141,6 +154,7 @@ public static Builder builder(final ClientSessionOptions options) {
         builder.causallyConsistent = options.isCausallyConsistent();
         builder.snapshot = options.isSnapshot();
         builder.defaultTransactionOptions = options.getDefaultTransactionOptions();
+        builder.defaultTimeoutMS = options.defaultTimeoutMS;
         return builder;
     }
 
@@ -151,6 +165,7 @@ public static Builder builder(final ClientSessionOptions options) {
     public static final class Builder {
         private Boolean causallyConsistent;
         private Boolean snapshot;
+        private Long defaultTimeoutMS;
         private TransactionOptions defaultTransactionOptions = TransactionOptions.builder().build();
 
         /**
@@ -196,6 +211,27 @@ public Builder defaultTransactionOptions(final TransactionOptions defaultTransac
             return this;
         }
 
+        /**
+         * Sets the default time limit for the following operations executed on the session:
+         *
+         * <ul>
+         *   <li>{@code commitTransaction}</li>
+         *   <li>{@code abortTransaction}</li>
+         *   <li>{@code withTransaction}</li>
+         *   <li>{@code close}</li>
+         * </ul>
+         * @param defaultTimeout the timeout
+         * @param timeUnit the time unit
+         * @return this
+         * @since CSOT
+         * @see #getDefaultTimeout
+         */
+        @Alpha(Reason.CLIENT)
+        public Builder defaultTimeout(final long defaultTimeout, final TimeUnit timeUnit) {
+            this.defaultTimeoutMS = convertAndValidateTimeout(defaultTimeout, timeUnit, "defaultTimeout");
+            return this;
+        }
+
         /**
          * Build the session options instance.
          *
@@ -218,5 +254,6 @@ private ClientSessionOptions(final Builder builder) {
                 : Boolean.valueOf(!builder.snapshot);
         this.snapshot = builder.snapshot;
         this.defaultTransactionOptions = builder.defaultTransactionOptions;
+        this.defaultTimeoutMS = builder.defaultTimeoutMS;
     }
 }