Mark CSOT feature as Alpha (#1372)

JAVA-5402

Co-authored-by: Valentin Kovalenko <[email protected]>

Author: vbabanin

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 are in the early stages of development, subject to incompatible changes, 
+or even removal, in a future release and may lack some intended features. An APIs bearing `@Alpha` annotation may 
+contain known issues affecting functionality, performance, and stability. They are also 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/AwsCredential.java

@@ -17,6 +17,7 @@
 package com.mongodb;
 
 import com.mongodb.annotations.Beta;
+import com.mongodb.annotations.Reason;
 import com.mongodb.lang.Nullable;
 
 import static com.mongodb.assertions.Assertions.notNull;
@@ -28,7 +29,7 @@
  * @see MongoCredential#AWS_CREDENTIAL_PROVIDER_KEY
  * @since 4.4
  */
-@Beta(Beta.Reason.CLIENT)
+@Beta(Reason.CLIENT)
 public final class AwsCredential {
     private final String accessKeyId;
     private final String secretAccessKey;

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

@@ -16,7 +16,9 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.NotThreadSafe;
+import com.mongodb.annotations.Reason;
 import com.mongodb.lang.Nullable;
 
 import javax.net.ssl.SSLContext;
@@ -159,6 +161,7 @@ public Builder kmsProviderSslContextMap(final Map<String, SSLContext> kmsProvide
          * @since CSOT
          * @see #getTimeout
          */
+        @Alpha(Reason.CLIENT)
         public ClientEncryptionSettings.Builder timeout(final long timeout, final TimeUnit timeUnit) {
             this.timeoutMS = convertAndValidateTimeout(timeout, timeUnit);
             return this;
@@ -324,6 +327,7 @@ public Map<String, SSLContext> getKmsProviderSslContextMap() {
      * @return the timeout in the given time unit
      * @since CSOT
      */
+    @Alpha(Reason.CLIENT)
     @Nullable
     public Long getTimeout(final TimeUnit timeUnit) {
         return timeoutMS == null ? null : timeUnit.convert(timeoutMS, MILLISECONDS);

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

@@ -16,8 +16,10 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
+import com.mongodb.annotations.Reason;
 import com.mongodb.lang.Nullable;
 import com.mongodb.session.ClientSession;
 
@@ -94,6 +96,7 @@ public TransactionOptions getDefaultTransactionOptions() {
      * @return the default timeout
      * @since CSOT
      */
+    @Alpha(Reason.CLIENT)
     @Nullable
     public Long getDefaultTimeout(final TimeUnit timeUnit) {
         return defaultTimeoutMS == null ? null : timeUnit.convert(defaultTimeoutMS, MILLISECONDS);
@@ -223,6 +226,7 @@ public Builder defaultTransactionOptions(final TransactionOptions defaultTransac
          * @since CSOT
          * @see #getDefaultTimeout
          */
+        @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,8 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Reason;
 import com.mongodb.connection.ClusterSettings;
 import com.mongodb.connection.ConnectionPoolSettings;
 import com.mongodb.connection.ServerMonitoringMode;
@@ -137,7 +139,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 {@linkplain Alpha 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)}.
@@ -1574,6 +1577,7 @@ public Integer getMaxConnecting() {
      * @return the time limit for the full execution of an operation in milliseconds or null.
      * @since CSOT
      */
+    @Alpha(Reason.CLIENT)
     @Nullable
     public Long getTimeout() {
         return timeout;

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

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

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

@@ -18,6 +18,7 @@
 
 import com.mongodb.annotations.Beta;
 import com.mongodb.annotations.Immutable;
+import com.mongodb.annotations.Reason;
 import com.mongodb.lang.Nullable;
 
 import java.util.Arrays;
@@ -176,7 +177,7 @@ public final class MongoCredential {
      * @see AwsCredential
      * @since 4.4
      */
-    @Beta(Beta.Reason.CLIENT)
+    @Beta(Reason.CLIENT)
     public static final String AWS_CREDENTIAL_PROVIDER_KEY = "AWS_CREDENTIAL_PROVIDER";
 
     /**

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

@@ -16,6 +16,8 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Reason;
 import org.bson.BsonDocument;
 
 /**
@@ -32,6 +34,7 @@ public class MongoExecutionTimeoutException extends MongoException {
      * @param message the error message
      * @since CSOT
      */
+    @Alpha(Reason.CLIENT)
     public MongoExecutionTimeoutException(final String message) {
         super(message);
 

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

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

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

@@ -16,11 +16,15 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Reason;
+
 /**
  * This exception is thrown when there is a timeout writing a response from the socket.
  *
  * @since CSOT
  */
+@Alpha(Reason.CLIENT)
 public class MongoSocketWriteTimeoutException extends MongoSocketException {
 
     private static final long serialVersionUID = 1L;

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

@@ -16,6 +16,9 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
+import com.mongodb.annotations.Reason;
+
 /**
  * An exception indicating that the driver has timed out waiting for either a server or a connection to become available.
  */
@@ -38,6 +41,7 @@ public MongoTimeoutException(final String message) {
      * @param cause the cause
      * @since CSOT
      */
+    @Alpha(Reason.CLIENT)
     public MongoTimeoutException(final String message, final Throwable cause) {
         super(message, cause);
     }

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

@@ -16,6 +16,7 @@
 package com.mongodb;
 
 import com.mongodb.annotations.Beta;
+import com.mongodb.annotations.Reason;
 import org.bson.BsonDocument;
 
 import static com.mongodb.assertions.Assertions.assertNotNull;
@@ -26,7 +27,7 @@
  *
  * @since 4.9
  */
-@Beta(Beta.Reason.SERVER)
+@Beta(Reason.SERVER)
 public final class MongoUpdatedEncryptedFieldsException extends MongoClientException {
     private static final long serialVersionUID = 1;
 

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

@@ -16,7 +16,9 @@
 
 package com.mongodb;
 
+import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Immutable;
+import com.mongodb.annotations.Reason;
 import com.mongodb.lang.Nullable;
 
 import java.util.Objects;
@@ -112,6 +114,7 @@ public Long getMaxCommitTime(final TimeUnit timeUnit) {
      * @since CSOT
      */
     @Nullable
+    @Alpha(Reason.CLIENT)
     public Long getTimeout(final TimeUnit timeUnit) {
         notNull("timeUnit", timeUnit);
         if (timeoutMS == null) {
@@ -294,6 +297,7 @@ public Builder maxCommitTime(@Nullable final Long maxCommitTime, final TimeUnit
          * @return this
          * @since CSOT
          */
+        @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,51 @@
+/*
+ * 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 element 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 contain known issues affecting functionality, performance,
+ * and stability. It is also 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
+@Beta(Reason.CLIENT)
+public @interface Alpha {
+    /**
+     * @return The reason an API element is marked with {@link Alpha}.
+     */
+    Reason[] value();
+}

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

@@ -47,25 +47,10 @@
         ElementType.PACKAGE,
         ElementType.TYPE })
 @Documented
-@Beta(Beta.Reason.CLIENT)
+@Beta(Reason.CLIENT)
 public @interface Beta {
     /**
      * @return The reason an API element is marked with {@link Beta}.
      */
     Reason[] value();
-
-    /**
-     * @see Beta#value()
-     */
-    enum Reason {
-        /**
-         * The driver API is in preview.
-         */
-        CLIENT,
-        /**
-         * The driver API relies on the server API, which is in preview.
-         * We still may decide to change the driver API even if the server API stays unchanged.
-         */
-        SERVER
-    }
 }

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

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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;
+
+/**
+ * Enumerates the reasons an API element might be marked with annotations like {@link Alpha} or {@link Beta}.
+ */
+@Beta(Reason.CLIENT)
+public enum Reason {
+    /**
+     * Indicates that the status of the driver API is the reason for the annotation.
+     */
+    CLIENT,
+
+    /**
+     * The driver API relies on the server API.
+     * This dependency is the reason for the annotation and suggests that changes in the server API could impact the driver API.
+     */
+    SERVER
+}