CSOT

build.gradle

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

config/spotbugs/exclude.xml

@@ -277,4 +277,28 @@
         <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"/>
+        <Method name="awaitOn"/>
+        <Bug pattern="RV_RETURN_VALUE_IGNORED_BAD_PRACTICE"/>
+    </Match>
+    <Match>
+        <Class name="com.mongodb.internal.time.Timeout"/>
+        <Method name="awaitOn"/>
+        <Bug pattern="RV_RETURN_VALUE_IGNORED"/>
+    </Match>
+    <Match>
+        <Class name="com.mongodb.internal.time.Timeout"/>
+        <Method name="awaitOn"/>
+        <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/src/main/com/mongodb/ConnectionString.java

@@ -127,9 +127,11 @@
  * <li>{@code sslInvalidHostNameAllowed=true|false}: Whether to allow invalid host names for TLS connections.</li>
  * <li>{@code tlsAllowInvalidHostnames=true|false}: Whether to allow invalid host names for TLS connections. Supersedes the
  * sslInvalidHostNameAllowed option</li>
+ * <li>{@code timeoutMS=ms}: Time limit for the full execution of an operation.</li>
  * <li>{@code connectTimeoutMS=ms}: How long a connection can take to be opened before timing out.</li>
  * <li>{@code socketTimeoutMS=ms}: How long a receive on a socket can take before timing out.
- * This option is the same as {@link SocketSettings#getReadTimeout(TimeUnit)}.</li>
+ * This option is the same as {@link SocketSettings#getReadTimeout(TimeUnit)}.
+ * Deprecated, use {@code timeoutMS} instead.</li>
  * <li>{@code maxIdleTimeMS=ms}: Maximum idle time of a pooled connection. A connection that exceeds this limit will be closed</li>
  * <li>{@code maxLifeTimeMS=ms}: Maximum life time of a pooled connection. A connection that exceeds this limit will be closed</li>
  * </ul>
@@ -149,7 +151,7 @@
  * <li>{@code waitQueueTimeoutMS=ms}: The maximum duration to wait until either:
  * an {@linkplain ConnectionCheckedOutEvent in-use connection} becomes {@linkplain ConnectionCheckedInEvent available},
  * or a {@linkplain ConnectionCreatedEvent connection is created} and begins to be {@linkplain ConnectionReadyEvent established}.
- * See {@link #getMaxWaitTime()} for more details.</li>
+ * See {@link #getMaxWaitTime()} for more details. . Deprecated, use {@code timeoutMS} instead.</li>
  * <li>{@code maxConnecting=n}: The maximum number of connections a pool may be establishing concurrently.</li>
  * </ul>
  * <p>Write concern configuration:</p>
@@ -177,7 +179,7 @@
  * <li>{@code wtimeoutMS=ms}
  * <ul>
  * <li>The driver adds { wtimeout : ms } to all write commands. Implies {@code safe=true}.</li>
- * <li>Used in combination with {@code w}</li>
+ * <li>Used in combination with {@code w}. Deprecated, use {@code timeoutMS} instead</li>
  * </ul>
  * </li>
  * </ul>
@@ -296,6 +298,7 @@ public class ConnectionString {
     private Integer maxConnectionLifeTime;
     private Integer maxConnecting;
     private Integer connectTimeout;
+    private Long timeout;
     private Integer socketTimeout;
     private Boolean sslEnabled;
     private Boolean sslInvalidHostnameAllowed;
@@ -485,6 +488,7 @@ public ConnectionString(final String connectionString, @Nullable final DnsClient
 
         credential = createCredentials(combinedOptionsMaps, userName, password);
         warnOnUnsupportedOptions(combinedOptionsMaps);
+        warnDeprecatedTimeouts(combinedOptionsMaps);
     }
 
     private static final Set<String> GENERAL_OPTIONS_KEYS = new LinkedHashSet<>();
@@ -493,16 +497,18 @@ public ConnectionString(final String connectionString, @Nullable final DnsClient
     private static final Set<String> WRITE_CONCERN_KEYS = new HashSet<>();
     private static final Set<String> COMPRESSOR_KEYS = new HashSet<>();
     private static final Set<String> ALL_KEYS = new HashSet<>();
+    private static final Set<String> DEPRECATED_TIMEOUT_KEYS = new HashSet<>();
 
     static {
         GENERAL_OPTIONS_KEYS.add("minpoolsize");
         GENERAL_OPTIONS_KEYS.add("maxpoolsize");
+        GENERAL_OPTIONS_KEYS.add("timeoutms");
+        GENERAL_OPTIONS_KEYS.add("sockettimeoutms");
         GENERAL_OPTIONS_KEYS.add("waitqueuetimeoutms");
         GENERAL_OPTIONS_KEYS.add("connecttimeoutms");
         GENERAL_OPTIONS_KEYS.add("maxidletimems");
         GENERAL_OPTIONS_KEYS.add("maxlifetimems");
         GENERAL_OPTIONS_KEYS.add("maxconnecting");
-        GENERAL_OPTIONS_KEYS.add("sockettimeoutms");
 
         // Order matters here: Having tls after ssl means than the tls option will supersede the ssl option when both are set
         GENERAL_OPTIONS_KEYS.add("ssl");
@@ -564,6 +570,10 @@ public ConnectionString(final String connectionString, @Nullable final DnsClient
         ALL_KEYS.addAll(READ_PREFERENCE_KEYS);
         ALL_KEYS.addAll(WRITE_CONCERN_KEYS);
         ALL_KEYS.addAll(COMPRESSOR_KEYS);
+
+        DEPRECATED_TIMEOUT_KEYS.add("sockettimeoutms");
+        DEPRECATED_TIMEOUT_KEYS.add("waitqueuetimeoutms");
+        DEPRECATED_TIMEOUT_KEYS.add("wtimeoutms");
     }
 
     // Any options contained in the connection string completely replace the corresponding options specified in TXT records,
@@ -577,15 +587,23 @@ private Map<String, List<String>> combineOptionsMaps(final Map<String, List<Stri
 
 
     private void warnOnUnsupportedOptions(final Map<String, List<String>> optionsMap) {
-        for (final String key : optionsMap.keySet()) {
-            if (!ALL_KEYS.contains(key)) {
-                if (LOGGER.isWarnEnabled()) {
-                    LOGGER.warn(format("Connection string contains unsupported option '%s'.", key));
-                }
-            }
+        if (LOGGER.isWarnEnabled()) {
+            optionsMap.keySet()
+                    .stream()
+                    .filter(k -> !ALL_KEYS.contains(k))
+                    .forEach(k -> LOGGER.warn(format("Connection string contains unsupported option '%s'.", k)));
+        }
+    }
+    private void warnDeprecatedTimeouts(final Map<String, List<String>> optionsMap) {
+        if (LOGGER.isWarnEnabled()) {
+            optionsMap.keySet()
+                    .stream()
+                    .filter(DEPRECATED_TIMEOUT_KEYS::contains)
+                    .forEach(k -> LOGGER.warn(format("Use of deprecated timeout option: '%s'. Prefer 'timeoutMS' instead.", k)));
         }
     }
 
+
     private void translateOptions(final Map<String, List<String>> optionsMap) {
         boolean tlsInsecureSet = false;
         boolean tlsAllowInvalidHostnamesSet = false;
@@ -620,6 +638,9 @@ private void translateOptions(final Map<String, List<String>> optionsMap) {
                 case "sockettimeoutms":
                     socketTimeout = parseInteger(value, "sockettimeoutms");
                     break;
+                case "timeoutms":
+                    timeout = parseLong(value, "timeoutms");
+                    break;
                 case "proxyhost":
                     proxyHost = value;
                     break;
@@ -1140,6 +1161,15 @@ private int parseInteger(final String input, final String key) {
         }
     }
 
+    private long parseLong(final String input, final String key) {
+        try {
+            return Long.parseLong(input);
+        } catch (NumberFormatException e) {
+            throw new IllegalArgumentException(format("The connection string contains an invalid value for '%s'. "
+                    + "'%s' is not a valid long", key, input));
+        }
+    }
+
     private List<String> parseHosts(final List<String> rawHosts) {
         if (rawHosts.size() == 0){
             throw new IllegalArgumentException("The connection string must contain at least one host");
@@ -1514,6 +1544,37 @@ public Integer getMaxConnecting() {
         return maxConnecting;
     }
 
+    /**
+     * The time limit for the full execution of an operation in milliseconds.
+     *
+     * <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>
+     *
+     * @return the time limit for the full execution of an operation in milliseconds or null.
+     * @since 4.x
+     */
+    @Nullable
+    public Long getTimeout() {
+        return timeout;
+    }
+
     /**
      * Gets the socket connect timeout specified in the connection string.
      * @return the socket connect timeout
@@ -1704,6 +1765,7 @@ public boolean equals(final Object o) {
                 && Objects.equals(maxConnectionLifeTime, that.maxConnectionLifeTime)
                 && Objects.equals(maxConnecting, that.maxConnecting)
                 && Objects.equals(connectTimeout, that.connectTimeout)
+                && Objects.equals(timeout, that.timeout)
                 && Objects.equals(socketTimeout, that.socketTimeout)
                 && Objects.equals(proxyHost, that.proxyHost)
                 && Objects.equals(proxyPort, that.proxyPort)
@@ -1726,7 +1788,7 @@ public boolean equals(final Object o) {
     public int hashCode() {
         return Objects.hash(credential, isSrvProtocol, hosts, database, collection, directConnection, readPreference,
                 writeConcern, retryWrites, retryReads, readConcern, minConnectionPoolSize, maxConnectionPoolSize, maxWaitTime,
-                maxConnectionIdleTime, maxConnectionLifeTime, maxConnecting, connectTimeout, socketTimeout, sslEnabled,
+                maxConnectionIdleTime, maxConnectionLifeTime, maxConnecting, connectTimeout, timeout, socketTimeout, sslEnabled,
                 sslInvalidHostnameAllowed, requiredReplicaSetName, serverSelectionTimeout, localThreshold, heartbeatFrequency,
                 applicationName, compressorList, uuidRepresentation, srvServiceName, srvMaxHosts, proxyHost, proxyPort,
                 proxyUsername, proxyPassword);

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

@@ -50,7 +50,9 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
+import java.util.concurrent.TimeUnit;
 
+import static com.mongodb.assertions.Assertions.isTrue;
 import static com.mongodb.assertions.Assertions.isTrueArgument;
 import static com.mongodb.assertions.Assertions.notNull;
 import static java.util.Arrays.asList;
@@ -114,6 +116,8 @@ public final class MongoClientSettings {
     private final ContextProvider contextProvider;
     private final DnsClient dnsClient;
     private final InetAddressResolver inetAddressResolver;
+    @Nullable
+    private final Long timeoutMS;
 
     /**
      * Gets the default codec registry.  It includes the following providers:
@@ -232,6 +236,7 @@ public static final class Builder {
 
         private int heartbeatConnectTimeoutMS;
         private int heartbeatSocketTimeoutMS;
+        private Long timeoutMS;
 
         private ContextProvider contextProvider;
         private DnsClient dnsClient;
@@ -255,6 +260,7 @@ private Builder(final MongoClientSettings settings) {
             uuidRepresentation = settings.getUuidRepresentation();
             serverApi = settings.getServerApi();
             dnsClient = settings.getDnsClient();
+            timeoutMS = settings.getTimeout(MILLISECONDS);
             inetAddressResolver = settings.getInetAddressResolver();
             transportSettings = settings.getTransportSettings();
             streamFactoryFactory = settings.getStreamFactoryFactory();
@@ -318,6 +324,9 @@ public Builder applyConnectionString(final ConnectionString connectionString) {
             if (connectionString.getWriteConcern() != null) {
                 writeConcern = connectionString.getWriteConcern();
             }
+            if (connectionString.getTimeout() != null) {
+                timeoutMS = connectionString.getTimeout();
+            }
             return this;
         }
 
@@ -690,6 +699,40 @@ public Builder inetAddressResolver(@Nullable final InetAddressResolver inetAddre
             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>
+         *
+         * @param timeout the timeout
+         * @param timeUnit the time unit
+         * @return this
+         * @since 4.x
+         * @see #getTimeout
+         */
+        public Builder timeout(final long timeout, final TimeUnit timeUnit) {
+            isTrueArgument("timeoutMS must be >= 0", timeout >= 0);
+            this.timeoutMS = MILLISECONDS.convert(timeout, timeUnit);
+            return this;
+        }
+
+
         // Package-private to provide interop with MongoClientOptions
         Builder heartbeatConnectTimeoutMS(final int heartbeatConnectTimeoutMS) {
             this.heartbeatConnectTimeoutMS = heartbeatConnectTimeoutMS;
@@ -883,6 +926,38 @@ public ServerApi getServerApi() {
         return serverApi;
     }
 
+    /**
+     * 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 4.x
+     */
+    @Nullable
+    public Long getTimeout(final TimeUnit timeUnit) {
+        return timeoutMS == null ? null : timeUnit.convert(timeoutMS, MILLISECONDS);
+    }
+
     /**
      * Gets the auto-encryption settings.
      * <p>
@@ -1034,7 +1109,8 @@ public boolean equals(final Object o) {
                 && Objects.equals(autoEncryptionSettings, that.autoEncryptionSettings)
                 && Objects.equals(dnsClient, that.dnsClient)
                 && Objects.equals(inetAddressResolver, that.inetAddressResolver)
-                && Objects.equals(contextProvider, that.contextProvider);
+                && Objects.equals(contextProvider, that.contextProvider)
+                && Objects.equals(timeoutMS, that.timeoutMS);
     }
 
     @Override
@@ -1043,7 +1119,8 @@ public int hashCode() {
                 streamFactoryFactory, commandListeners, codecRegistry, loggerSettings, clusterSettings, socketSettings,
                 heartbeatSocketSettings, connectionPoolSettings, serverSettings, sslSettings, applicationName, compressorList,
                 uuidRepresentation, serverApi, autoEncryptionSettings, heartbeatSocketTimeoutSetExplicitly,
-                heartbeatConnectTimeoutSetExplicitly, dnsClient, inetAddressResolver, contextProvider);
+                heartbeatConnectTimeoutSetExplicitly, dnsClient, inetAddressResolver, contextProvider, timeoutMS);
+
     }
 
     @Override
@@ -1074,10 +1151,12 @@ public String toString() {
                 + ", dnsClient=" + dnsClient
                 + ", inetAddressResolver=" + inetAddressResolver
                 + ", contextProvider=" + contextProvider
+                + ", timeoutMS=" + timeoutMS
                 + '}';
     }
 
     private MongoClientSettings(final Builder builder) {
+        isTrue("timeoutMS > 0 ", builder.timeoutMS == null || builder.timeoutMS >= 0);
         readPreference = builder.readPreference;
         writeConcern = builder.writeConcern;
         retryWrites = builder.retryWrites;
@@ -1113,5 +1192,6 @@ private MongoClientSettings(final Builder builder) {
         heartbeatSocketTimeoutSetExplicitly = builder.heartbeatSocketTimeoutMS != 0;
         heartbeatConnectTimeoutSetExplicitly = builder.heartbeatConnectTimeoutMS != 0;
         contextProvider = builder.contextProvider;
+        timeoutMS = builder.timeoutMS;
     }
 }