Do various small timeout-related improvements (#1908)

Author: stIncMale

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/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/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;