Add Javadoc to specify that CSOT does not limit socket writes (mongodb#1791)

JAVA-5569

Author: vbabanin

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/MongoClientSettings.java

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

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-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCluster.kt

@@ -78,7 +78,11 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * Note: This timeout does not limit socket writes, therefore there is a possibility that the operation might not be
+     * timed out when expected.
+     *
      * @return the optional timeout duration
+     * @since 5.2
      */
     @Alpha(Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
@@ -131,6 +135,9 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * Note: This timeout does not limit socket writes, therefore there is a possibility that the operation might not be
+     * timed out when expected.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoCluster instance with the set time limit for operations

driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCollection.kt

@@ -102,6 +102,9 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * Note: This timeout does not limit socket writes, therefore there is a possibility that the operation might not be
+     * timed out when expected.
+     *
      * @return the optional timeout duration
      * @since 5.2
      */
@@ -176,6 +179,9 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * Note: This timeout does not limit socket writes, therefore there is a possibility that the operation might not be
+     * timed out when expected.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoCollection instance with the set time limit for operations

driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoDatabase.kt

@@ -71,6 +71,9 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * Note: This timeout does not limit socket writes, therefore there is a possibility that the operation might not be
+     * timed out when expected.
+     *
      * @return the optional timeout duration
      * @since 5.2
      */
@@ -125,6 +128,9 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * Note: This timeout does not limit socket writes, therefore there is a possibility that the operation might not be
+     * timed out when expected.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoDatabase instance with the set time limit for operations

driver-legacy/src/main/com/mongodb/MongoClientOptions.java

@@ -575,6 +575,9 @@ public ServerApi getServerApi() {
      *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
      * </ul>
      *
+     *  <p>Note that this timeout does not limit socket writes, therefore there is a possibility that the
+     *  operation might not be timed out when expected.
+     *
      * @return the timeout in milliseconds
      * @since 5.2
      */
@@ -1370,6 +1373,9 @@ public Builder srvServiceName(final String srvServiceName) {
          *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
          * </ul>
          *
+         *  <p>Note that this timeout does not limit socket writes, therefore there is a possibility that the
+         *  operation might not be timed out when expected.
+         *
          * @param timeoutMS the timeout in milliseconds
          * @return this
          * @since 5.2

driver-sync/src/main/com/mongodb/client/MongoCluster.java

@@ -110,6 +110,9 @@ public interface MongoCluster {
      *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
      * </ul>
      *
+     *  <p>Note: This timeout does not limit socket writes, therefore there is a possibility that the
+     *  operation might not be timed out when expected.
+     *
      * @param timeUnit the time unit
      * @return the timeout in the given time unit
      * @since 5.2
@@ -169,6 +172,9 @@ public interface MongoCluster {
      *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
      * </ul>
      *
+     *  <p>Note: This timeout does not limit socket writes, therefore there is a possibility that the
+     *  operation might not be timed out when expected.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit
      * @return a new MongoCluster instance with the set time limit for the full execution of an operation.

driver-sync/src/main/com/mongodb/client/MongoCollection.java

@@ -138,6 +138,9 @@ public interface MongoCollection<TDocument> {
      *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
      * </ul>
      *
+     *  <p>Note: This timeout does not limit socket writes, therefore there is a possibility that the
+     *  operation might not be timed out when expected.
+     *
      * @param timeUnit the time unit
      * @return the timeout in the given time unit
      * @since 5.2
@@ -204,6 +207,9 @@ public interface MongoCollection<TDocument> {
      *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
      * </ul>
      *
+     *  <p>Note: This timeout does not limit socket writes, therefore there is a possibility that the
+     *  operation might not be timed out when expected.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit
      * @return a new MongoCollection instance with the set time limit for the full execution of an operation