Mark CSOT feature as Alpha

README.md

@@ -52,6 +52,17 @@ almost always be binary compatible with prior minor releases from the same major
 Patch 4.x.y increments (such as 4.0.0 -> 4.0.1, 4.1.1 -> 4.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 at the class, method or field level are in the early stages of development, 
+subject to incompatible changes, or even removal, in a future release and may lack some intended features. These APIs 
+may be unstable, have potential performance implications as development progresses, and are 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,12 @@ 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, UnsignedLongs.java, UnsignedLongsTest.java
+3) The following files:
+
+    Alpha.java (formerly Beta.java)
+    Beta.java
+    UnsignedLongs.java
+    UnsignedLongsTest.java
 
     Copyright 2010 The Guava Authors
     Copyright 2011 The Guava Authors

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

@@ -16,6 +16,7 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
 import com.mongodb.lang.Nullable;
@@ -94,6 +95,7 @@ public TransactionOptions getDefaultTransactionOptions() {
      * @return the default timeout
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     @Nullable
     public Long getDefaultTimeout(final TimeUnit timeUnit) {
         return defaultTimeoutMS == null ? null : timeUnit.convert(defaultTimeoutMS, MILLISECONDS);
@@ -223,6 +225,7 @@ public Builder defaultTransactionOptions(final TransactionOptions defaultTransac
          * @since CSOT
          * @see #getDefaultTimeout
          */
+        @Alpha(Alpha.Reason.CLIENT)
         public Builder defaultTimeout(final long defaultTimeout, final TimeUnit timeUnit) {
             this.defaultTimeoutMS = convertAndValidateTimeout(defaultTimeout, timeUnit, "defaultTimeout");
             return this;

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

@@ -16,6 +16,7 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.connection.ClusterSettings;
 import com.mongodb.connection.ConnectionPoolSettings;
 import com.mongodb.connection.ServerMonitoringMode;
@@ -137,7 +138,8 @@
  * <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 timeoutMS=ms}: Time limit for the full execution of an operation. Note: This parameter is part of an Alpha API and may be
+ * subject to changes or even removal in future releases.</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)}.
@@ -1575,6 +1577,7 @@ public Integer getMaxConnecting() {
      * @return the time limit for the full execution of an operation in milliseconds or null.
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     @Nullable
     public Long getTimeout() {
         return timeout;

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

@@ -16,6 +16,7 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
 import com.mongodb.client.gridfs.codecs.GridFSFileCodecProvider;
@@ -704,6 +705,7 @@ public Builder inetAddressResolver(@Nullable final InetAddressResolver inetAddre
          * @since CSOT
          * @see #getTimeout
          */
+        @Alpha(Alpha.Reason.CLIENT)
         public Builder timeout(final long timeout, final TimeUnit timeUnit) {
             this.timeoutMS = convertAndValidateTimeout(timeout, timeUnit);
             return this;
@@ -916,6 +918,7 @@ public ServerApi getServerApi() {
      * @return the timeout in the given time unit
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     @Nullable
     public Long getTimeout(final TimeUnit timeUnit) {
         return timeoutMS == null ? null : timeUnit.convert(timeoutMS, MILLISECONDS);

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

@@ -15,6 +15,8 @@
  */
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
+
 import java.util.concurrent.TimeUnit;
 
 /**
@@ -35,6 +37,7 @@
  * @see MongoClientSettings#getTimeout(TimeUnit)
  * @since CSOT
  */
+@Alpha(Alpha.Reason.CLIENT)
 public final class MongoOperationTimeoutException extends MongoTimeoutException {
     private static final long serialVersionUID = 1L;
 

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

@@ -16,6 +16,7 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.lang.Nullable;
 
@@ -112,6 +113,7 @@ public Long getMaxCommitTime(final TimeUnit timeUnit) {
      * @since CSOT
      */
     @Nullable
+    @Alpha(Alpha.Reason.CLIENT)
     public Long getTimeout(final TimeUnit timeUnit) {
         notNull("timeUnit", timeUnit);
         if (timeoutMS == null) {
@@ -308,6 +310,7 @@ public Builder maxCommitTime(@Nullable final Long maxCommitTime, final TimeUnit
          * @return this
          * @since CSOT
          */
+        @Alpha(Alpha.Reason.CLIENT)
         public Builder timeout(@Nullable final Long timeout, final TimeUnit timeUnit) {
             this.timeoutMS = convertAndValidateTimeoutNullable(timeout, timeUnit);
             return this;

driver-core/src/main/com/mongodb/annotations/Alpha.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ * Copyright 2010 The Guava Authors
+ * Copyright 2011 The Guava Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.mongodb.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Signifies that a public API (public class, method or field) is in the early stages
+ * of development, subject to incompatible changes, or even removal, in a future release
+ * and may lack some intended features. An API bearing this annotation may be unstable,
+ * have potential performance implications as development progresses, and is exempt from
+ * any compatibility guarantees made by its containing library.
+ *
+ * <p>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.</p>
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target({
+        ElementType.ANNOTATION_TYPE,
+        ElementType.CONSTRUCTOR,
+        ElementType.FIELD,
+        ElementType.METHOD,
+        ElementType.PACKAGE,
+        ElementType.TYPE })
+@Documented
+@Alpha(Alpha.Reason.CLIENT)
+public @interface Alpha {
+    /**
+     * @return The reason an API element is marked with {@link Alpha}.
+     */
+    Alpha.Reason[] value();
+
+    /**
+     * @see Alpha#value()
+     */
+    enum Reason {
+        /**
+         * Indicates that the driver API is either experimental or in development.
+         * Use in production environments is inadvisable due to potential API changes and possible instability.
+         */
+        CLIENT,
+    }
+}

driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoCluster.kt

@@ -19,6 +19,7 @@ import com.mongodb.ClientSessionOptions
 import com.mongodb.ReadConcern
 import com.mongodb.ReadPreference
 import com.mongodb.WriteConcern
+import com.mongodb.annotations.Alpha
 import com.mongodb.reactivestreams.client.MongoCluster as JMongoCluster
 import java.util.concurrent.TimeUnit
 import kotlinx.coroutines.flow.Flow
@@ -73,6 +74,7 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      *
      * @return the optional timeout duration
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
 
     /**
@@ -129,6 +131,7 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      * @see [MongoDatabase.timeout]
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun withTimeout(timeout: Long, timeUnit: TimeUnit = TimeUnit.MILLISECONDS): MongoCluster =
         MongoCluster(wrapped.withTimeout(timeout, timeUnit))
 

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

@@ -19,6 +19,7 @@ import com.mongodb.MongoNamespace
 import com.mongodb.ReadConcern
 import com.mongodb.ReadPreference
 import com.mongodb.WriteConcern
+import com.mongodb.annotations.Alpha
 import com.mongodb.bulk.BulkWriteResult
 import com.mongodb.client.model.BulkWriteOptions
 import com.mongodb.client.model.CountOptions
@@ -106,6 +107,7 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * @return the optional timeout duration
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
 
     /**
@@ -182,6 +184,7 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * @see [MongoCollection.timeout]
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun withTimeout(timeout: Long, timeUnit: TimeUnit = TimeUnit.MILLISECONDS): MongoCollection<T> =
         MongoCollection(wrapped.withTimeout(timeout, timeUnit))
 

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

@@ -18,6 +18,7 @@ package com.mongodb.kotlin.client.coroutine
 import com.mongodb.ReadConcern
 import com.mongodb.ReadPreference
 import com.mongodb.WriteConcern
+import com.mongodb.annotations.Alpha
 import com.mongodb.client.model.CreateCollectionOptions
 import com.mongodb.client.model.CreateViewOptions
 import com.mongodb.reactivestreams.client.MongoDatabase as JMongoDatabase
@@ -74,6 +75,7 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * @return the optional timeout duration
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
 
     /**
@@ -130,6 +132,7 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * @see [MongoDatabase.timeout]
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun withTimeout(timeout: Long, timeUnit: TimeUnit = TimeUnit.MILLISECONDS): MongoDatabase =
         MongoDatabase(wrapped.withTimeout(timeout, timeUnit))
 

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

@@ -19,6 +19,7 @@ import com.mongodb.ClientSessionOptions
 import com.mongodb.ReadConcern
 import com.mongodb.ReadPreference
 import com.mongodb.WriteConcern
+import com.mongodb.annotations.Alpha
 import com.mongodb.client.MongoCluster as JMongoCluster
 import java.util.concurrent.TimeUnit
 import org.bson.Document
@@ -70,6 +71,7 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      *
      * @return the optional timeout duration
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
 
     /**
@@ -126,6 +128,7 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      * @see [MongoDatabase.timeout]
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun withTimeout(timeout: Long, timeUnit: TimeUnit = TimeUnit.MILLISECONDS): MongoCluster =
         MongoCluster(wrapped.withTimeout(timeout, timeUnit))
 

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

@@ -19,6 +19,7 @@ import com.mongodb.MongoNamespace
 import com.mongodb.ReadConcern
 import com.mongodb.ReadPreference
 import com.mongodb.WriteConcern
+import com.mongodb.annotations.Alpha
 import com.mongodb.bulk.BulkWriteResult
 import com.mongodb.client.MongoCollection as JMongoCollection
 import com.mongodb.client.model.BulkWriteOptions
@@ -103,6 +104,7 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * @return the optional timeout duration
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
 
     /**
@@ -179,6 +181,7 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * @see [MongoCollection.timeout]
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun withTimeout(timeout: Long, timeUnit: TimeUnit = TimeUnit.MILLISECONDS): MongoCollection<T> =
         MongoCollection(wrapped.withTimeout(timeout, timeUnit))
 

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

@@ -18,6 +18,7 @@ package com.mongodb.kotlin.client
 import com.mongodb.ReadConcern
 import com.mongodb.ReadPreference
 import com.mongodb.WriteConcern
+import com.mongodb.annotations.Alpha
 import com.mongodb.client.MongoDatabase as JMongoDatabase
 import com.mongodb.client.model.CreateCollectionOptions
 import com.mongodb.client.model.CreateViewOptions
@@ -72,6 +73,7 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * @return the optional timeout duration
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
 
     /**
@@ -128,6 +130,7 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * @see [MongoDatabase.timeout]
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     public fun withTimeout(timeout: Long, timeUnit: TimeUnit = TimeUnit.MILLISECONDS): MongoDatabase =
         MongoDatabase(wrapped.withTimeout(timeout, timeUnit))
 

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

@@ -16,6 +16,7 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
 import com.mongodb.connection.ClusterConnectionMode;
@@ -579,6 +580,7 @@ public ServerApi getServerApi() {
      * @return the timeout in milliseconds
      * @since CSOT
      */
+    @Alpha(Alpha.Reason.CLIENT)
     @Nullable
     public Long getTimeout() {
         return wrapped.getTimeout(MILLISECONDS);
@@ -1377,6 +1379,7 @@ public Builder srvServiceName(final String srvServiceName) {
          * @since CSOT
          * @see #getTimeout
          */
+        @Alpha(Alpha.Reason.CLIENT)
         public Builder timeout(final long timeoutMS) {
             wrapped.timeout(timeoutMS, MILLISECONDS);
             return this;