Client Backpressure

config/spotbugs/exclude.xml

@@ -15,9 +15,13 @@
   -->
 
 <!--
+    Every time you add an entry to this file, you must specify its MongoDB status and SpotBugs rank.
+
     To determine the rank of a newly-detected bug that you would like to exclude,
-    run spotbugsMain task with xml.enabled, then examine the XML report in
-    <module>/build/reports/spotbugs/main.xml, where the rankings are
+    run the `spotbugsMain` Gradle task with `xmlReports.enabled`
+    (example: `./gradlew spotbugsMain -PxmlReports.enabled=true`),
+    then examine the XML report in
+    `<module>/build/reports/spotbugs/main.xml`, where the rankings are
     included as part of the report, e.g.
 
     <BugInstance type="PA_PUBLIC_PRIMITIVE_ATTRIBUTE" priority="2" rank="16" ...
@@ -295,5 +299,22 @@
         <Class name="com.mongodb.internal.crypt.capi.CAPI$cstring"/>
         <Bug pattern="NM_CLASS_NAMING_CONVENTION"/>
     </Match>
-
+    <Match>
+        <!-- MongoDB status: "False Positive", SpotBugs rank: 18 -->
+        <!-- The second parameter of the Java SE API method we override is not annotated,
+             but we know the argument may be `null`, so we annotate the corresponding parameter
+             in the overriding method with `@Nullable`. -->
+        <Class name="com.mongodb.internal.thread.MongoScheduledThreadPoolExecutor"/>
+        <Method name="afterExecute"/>
+        <Bug pattern="NP_METHOD_PARAMETER_TIGHTENS_ANNOTATION"/>
+    </Match>
+    <Match>
+        <!-- MongoDB status: "False Positive", SpotBugs rank: 18 -->
+        <!-- The second parameter of the Java SE API method we override is not annotated,
+             but we know the argument may be `null`, so we annotate the corresponding parameter
+             in the overriding method with `@Nullable`. -->
+        <Class name="com.mongodb.internal.thread.MongoThreadPoolExecutor"/>
+        <Method name="afterExecute"/>
+        <Bug pattern="NP_METHOD_PARAMETER_TIGHTENS_ANNOTATION"/>
+    </Match>
 </FindBugsFilter>

driver-benchmarks/src/main/com/mongodb/benchmark/benchmarks/RawBsonArrayEncodingBenchmark.java

@@ -17,7 +17,8 @@
 
 package com.mongodb.benchmark.benchmarks;
 
-import org.bson.BsonArray;import org.bson.BsonDocument;
+import org.bson.BsonArray;
+import org.bson.BsonDocument;
 import org.bson.RawBsonDocument;
 import org.bson.codecs.BsonDocumentCodec;
 
@@ -52,4 +53,4 @@ public void setUp() throws IOException {
     public int getBytesPerRun() {
         return documentBytes.length * NUM_INTERNAL_ITERATIONS;
     }
-}
+}

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

@@ -17,6 +17,7 @@
 package com.mongodb;
 
 import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Beta;
 import com.mongodb.annotations.Reason;
 import com.mongodb.connection.ClusterSettings;
 import com.mongodb.connection.ConnectionPoolSettings;
@@ -264,14 +265,20 @@
  * <p>SRV configuration:</p>
  * <ul>
  * <li>{@code srvServiceName=string}: The SRV service name. See {@link ClusterSettings#getSrvServiceName()} for details.</li>
- * <li>{@code srvMaxHosts=number}: The maximum number of hosts from the SRV record to connect to.</li>
+ * <li>{@code srvMaxHosts=n}: The maximum number of hosts from the SRV record to connect to.</li>
  * </ul>
  * <p>General configuration:</p>
  * <ul>
- * <li>{@code retryWrites=true|false}. If true the driver will retry supported write operations if they fail due to a network error.
- *  Defaults to true.</li>
- * <li>{@code retryReads=true|false}. If true the driver will retry supported read operations if they fail due to a network error.
- *  Defaults to true.</li>
+ * <li>{@code retryWrites=true|false}: Whether attempts to execute write commands should be retried if they fail due to a retryable error.
+ *  Defaults to true. See also {@code maxAdaptiveRetries}.</li>
+ * <li>{@code retryReads=true|false}: Whether attempts to execute read commands should be retried if they fail due to a retryable error.
+ *  Defaults to true. See also {@code maxAdaptiveRetries}.</li>
+ * <li>{@code maxAdaptiveRetries=n}: This is {@linkplain Beta Beta API}.
+ * The maximum number of retry attempts when encountering a retryable overload error.
+ * See {@link MongoClientSettings.Builder#maxAdaptiveRetries(Integer)} for more information.</li>
+ * <li>{@code enableOverloadRetargeting=true|false}: This is {@linkplain Beta Beta API}.
+ *   Whether to enable overload retargeting. Defaults to false.
+ *  See {@link MongoClientSettings.Builder#enableOverloadRetargeting(boolean)} for more information.</li>
  * <li>{@code uuidRepresentation=unspecified|standard|javaLegacy|csharpLegacy|pythonLegacy}.  See
  * {@link MongoClientSettings#getUuidRepresentation()} for documentation of semantics of this parameter.  Defaults to "javaLegacy", but
  * will change to "unspecified" in the next major release.</li>
@@ -308,6 +315,8 @@ public class ConnectionString {
     private WriteConcern writeConcern;
     private Boolean retryWrites;
     private Boolean retryReads;
+    private Integer maxAdaptiveRetries;
+    private Boolean enableOverloadRetargeting;
     private ReadConcern readConcern;
 
     private Integer minConnectionPoolSize;
@@ -558,6 +567,8 @@ public ConnectionString(final String connectionString, @Nullable final DnsClient
         GENERAL_OPTIONS_KEYS.add("servermonitoringmode");
         GENERAL_OPTIONS_KEYS.add("retrywrites");
         GENERAL_OPTIONS_KEYS.add("retryreads");
+        GENERAL_OPTIONS_KEYS.add("maxadaptiveretries");
+        GENERAL_OPTIONS_KEYS.add("enableoverloadretargeting");
 
         GENERAL_OPTIONS_KEYS.add("appname");
 
@@ -706,6 +717,15 @@ private void translateOptions(final Map<String, List<String>> optionsMap) {
                 case "retryreads":
                     retryReads = parseBoolean(value, "retryreads");
                     break;
+                case "maxadaptiveretries":
+                    maxAdaptiveRetries = parseInteger(value, "maxadaptiveretries");
+                    if (maxAdaptiveRetries < 0) {
+                        throw new IllegalArgumentException("maxAdaptiveRetries must be >= 0");
+                    }
+                    break;
+                case "enableoverloadretargeting":
+                    enableOverloadRetargeting = parseBoolean(value, "enableoverloadretargeting");
+                    break;
                 case "uuidrepresentation":
                     uuidRepresentation = createUuidRepresentation(value);
                     break;
@@ -1455,13 +1475,15 @@ public WriteConcern getWriteConcern() {
     }
 
     /**
-     * <p>Gets whether writes should be retried if they fail due to a network error</p>
-     *
+     * Gets whether attempts to execute write commands should be retried if they fail due to a retryable error.
+     * See {@link MongoClientSettings.Builder#retryWrites(boolean)} for more information.
+     * <p>
      * The name of this method differs from others in this class so as not to conflict with the now removed
      * getRetryWrites() method, which returned a primitive {@code boolean} value, and didn't allow callers to differentiate
      * between a false value and an unset value.
      *
-     * @return the retryWrites value, or null if unset
+     * @return the {@code retryWrites} value, or {@code null} if unset
+     * @see #getMaxAdaptiveRetries()
      * @since 3.9
      * @mongodb.server.release 3.6
      */
@@ -1471,9 +1493,11 @@ public Boolean getRetryWritesValue() {
     }
 
     /**
-     * <p>Gets whether reads should be retried if they fail due to a network error</p>
+     * Gets whether attempts to execute read commands should be retried if they fail due to a retryable error.
+     * See {@link MongoClientSettings.Builder#retryReads(boolean)} for more information.
      *
-     * @return the retryWrites value
+     * @return the {@code retryReads} value, or {@code null} if unset
+     * @see #getMaxAdaptiveRetries()
      * @since 3.11
      * @mongodb.server.release 3.6
      */
@@ -1482,6 +1506,33 @@ public Boolean getRetryReads() {
         return retryReads;
     }
 
+    /**
+     * Gets the maximum number of retry attempts when encountering a retryable overload error.
+     * See {@link MongoClientSettings.Builder#maxAdaptiveRetries(Integer)} for more information.
+     *
+     * @return The {@code maxAdaptiveRetries} value, or {@code null} if unset.
+     * @since 5.7
+     */
+    @Beta(Reason.CLIENT)
+    @Nullable
+    public Integer getMaxAdaptiveRetries() {
+        return maxAdaptiveRetries;
+    }
+
+    /**
+     * Gets whether overload retargeting is enabled.
+     * See {@link MongoClientSettings.Builder#enableOverloadRetargeting(boolean)} for more information.
+     *
+     * @return the enableOverloadRetargeting value, or null if not set
+     * @see MongoClientSettings.Builder#enableOverloadRetargeting(boolean)
+     * @since 5.7
+     */
+    @Beta(Reason.CLIENT)
+    @Nullable
+    public Boolean getEnableOverloadRetargeting() {
+        return enableOverloadRetargeting;
+    }
+
     /**
      * Gets the minimum connection pool size specified in the connection string.
      * @return the minimum connection pool size
@@ -1795,6 +1846,8 @@ public boolean equals(final Object o) {
                 && Objects.equals(writeConcern, that.writeConcern)
                 && Objects.equals(retryWrites, that.retryWrites)
                 && Objects.equals(retryReads, that.retryReads)
+                && Objects.equals(maxAdaptiveRetries, that.maxAdaptiveRetries)
+                && Objects.equals(enableOverloadRetargeting, that.enableOverloadRetargeting)
                 && Objects.equals(readConcern, that.readConcern)
                 && Objects.equals(minConnectionPoolSize, that.minConnectionPoolSize)
                 && Objects.equals(maxConnectionPoolSize, that.maxConnectionPoolSize)
@@ -1826,7 +1879,7 @@ public boolean equals(final Object o) {
     @Override
     public int hashCode() {
         return Objects.hash(credential, isSrvProtocol, hosts, database, collection, directConnection, readPreference,
-                writeConcern, retryWrites, retryReads, readConcern, minConnectionPoolSize, maxConnectionPoolSize, maxWaitTime,
+                writeConcern, retryWrites, retryReads, maxAdaptiveRetries, enableOverloadRetargeting, readConcern, minConnectionPoolSize, maxConnectionPoolSize, maxWaitTime,
                 maxConnectionIdleTime, maxConnectionLifeTime, maxConnecting, connectTimeout, timeout, socketTimeout, sslEnabled,
                 sslInvalidHostnameAllowed, requiredReplicaSetName, serverSelectionTimeout, localThreshold, heartbeatFrequency,
                 serverMonitoringMode, applicationName, compressorList, uuidRepresentation, srvServiceName, srvMaxHosts, proxyHost,