Mark PackedBitVector as Beta, aligning with binary quantization preview (#1594)

JAVA-5738
---------

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

Author: vbabanin

bson/src/main/org/bson/BinaryVector.java

@@ -16,6 +16,9 @@
 
 package org.bson;
 
+import org.bson.annotations.Beta;
+import org.bson.annotations.Reason;
+
 import static org.bson.assertions.Assertions.isTrueArgument;
 import static org.bson.assertions.Assertions.notNull;
 
@@ -59,6 +62,7 @@ public abstract class BinaryVector {
      * @return A {@link PackedBitBinaryVector} instance with the {@link DataType#PACKED_BIT} data type.
      * @throws IllegalArgumentException If the padding value is greater than 7.
      */
+    @Beta(Reason.SERVER)
     public static PackedBitBinaryVector packedBitVector(final byte[] data, final byte padding) {
         notNull("data", data);
         isTrueArgument("Padding must be between 0 and 7 bits. Provided padding: " + padding, padding >= 0 && padding <= 7);

bson/src/main/org/bson/PackedBitBinaryVector.java

@@ -16,6 +16,9 @@
 
 package org.bson;
 
+import org.bson.annotations.Beta;
+import org.bson.annotations.Reason;
+
 import java.util.Arrays;
 import java.util.Objects;
 
@@ -32,6 +35,7 @@
  * @see BsonBinary#asVector()
  * @since 5.3
  */
+@Beta(Reason.SERVER)
 public final class PackedBitBinaryVector extends BinaryVector {
 
     private final byte padding;

bson/src/main/org/bson/annotations/Beta.java

@@ -0,0 +1,56 @@
+/*
+ * 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 org.bson.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 subject to
+ * incompatible changes, or even removal, in a future release. An API bearing
+ * this annotation is exempt from any compatibility guarantees made by its
+ * containing library. Note that the presence of this annotation implies nothing
+ * about the quality or performance of the API in question, only the fact that
+ * it is not "API-frozen."
+ *
+ * <p>It is generally safe for <i>applications</i> to depend on beta APIs, at
+ * the cost of some extra work during upgrades. However it is generally
+ * inadvisable for <i>libraries</i> (which get included on users' CLASSPATHs,
+ * outside the library developers' control) to do so.
+ *
+ **/
+@Retention(RetentionPolicy.CLASS)
+@Target({
+        ElementType.ANNOTATION_TYPE,
+        ElementType.CONSTRUCTOR,
+        ElementType.FIELD,
+        ElementType.METHOD,
+        ElementType.PACKAGE,
+        ElementType.TYPE })
+@Documented
+@Beta(Reason.CLIENT)
+public @interface Beta {
+    /**
+     * @return The reason an API element is marked with {@link Beta}.
+     */
+    Reason[] value();
+}

bson/src/main/org/bson/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 org.bson.annotations;
+
+/**
+ * Enumerates the reasons an API element might be marked with annotations like {@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
+}

bson/src/main/org/bson/annotations/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+
+/**
+ * Contains annotations that can apply to any part of the BSON library code.
+ */
+package org.bson.annotations;