From 272bd0e83ff585680756c0a4ca43d5a7443874d1 Mon Sep 17 00:00:00 2001 From: "slav.babanin" Date: Mon, 6 Jan 2025 23:11:33 -0800 Subject: [PATCH 1/4] Mark PackedBitVector as Beta as binary quantization is in public preview. JAVA-5738 --- bson/src/main/org/bson/PackedBitVector.java | 6 ++ bson/src/main/org/bson/Vector.java | 4 ++ bson/src/main/org/bson/annotations/Beta.java | 56 +++++++++++++++++++ .../src/main/org/bson/annotations/Reason.java | 34 +++++++++++ .../org/bson/annotations/package-info.java | 20 +++++++ 5 files changed, 120 insertions(+) create mode 100644 bson/src/main/org/bson/annotations/Beta.java create mode 100644 bson/src/main/org/bson/annotations/Reason.java create mode 100644 bson/src/main/org/bson/annotations/package-info.java diff --git a/bson/src/main/org/bson/PackedBitVector.java b/bson/src/main/org/bson/PackedBitVector.java index a5dd8f4dcdf..5ad406acd77 100644 --- a/bson/src/main/org/bson/PackedBitVector.java +++ b/bson/src/main/org/bson/PackedBitVector.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 PackedBitVector extends Vector { private final byte padding; @@ -53,6 +57,7 @@ public final class PackedBitVector extends Vector { * @return the underlying byte array representing this {@link PackedBitVector} vector. * @see #getPadding() */ + @Beta(Reason.SERVER) public byte[] getData() { return assertNotNull(data); } @@ -69,6 +74,7 @@ public byte[] getData() { * * @return the padding value (between 0 and 7). */ + @Beta(Reason.SERVER) public byte getPadding() { return this.padding; } diff --git a/bson/src/main/org/bson/Vector.java b/bson/src/main/org/bson/Vector.java index d267387d727..e3360ae2d60 100644 --- a/bson/src/main/org/bson/Vector.java +++ b/bson/src/main/org/bson/Vector.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; @@ -63,6 +66,7 @@ public abstract class Vector { * @return A {@link PackedBitVector} instance with the {@link DataType#PACKED_BIT} data type. * @throws IllegalArgumentException If the padding value is greater than 7. */ + @Beta(Reason.SERVER) public static PackedBitVector 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); diff --git a/bson/src/main/org/bson/annotations/Beta.java b/bson/src/main/org/bson/annotations/Beta.java new file mode 100644 index 00000000000..0db9171952c --- /dev/null +++ b/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." + * + *

It is generally safe for applications to depend on beta APIs, at + * the cost of some extra work during upgrades. However it is generally + * inadvisable for libraries (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(); +} diff --git a/bson/src/main/org/bson/annotations/Reason.java b/bson/src/main/org/bson/annotations/Reason.java new file mode 100644 index 00000000000..d0b11c79651 --- /dev/null +++ b/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 +} diff --git a/bson/src/main/org/bson/annotations/package-info.java b/bson/src/main/org/bson/annotations/package-info.java new file mode 100644 index 00000000000..80f976ca36f --- /dev/null +++ b/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 code. + */ +package org.bson.annotations; From 86380dbddb070164ec6da31607337ba98d77a01f Mon Sep 17 00:00:00 2001 From: Viacheslav Babanin Date: Wed, 8 Jan 2025 19:28:17 -0800 Subject: [PATCH 2/4] Update package-info.java --- bson/src/main/org/bson/annotations/package-info.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bson/src/main/org/bson/annotations/package-info.java b/bson/src/main/org/bson/annotations/package-info.java index 80f976ca36f..ac5cd9dabf9 100644 --- a/bson/src/main/org/bson/annotations/package-info.java +++ b/bson/src/main/org/bson/annotations/package-info.java @@ -15,6 +15,6 @@ */ /** - * Contains annotations that can apply to any part of the bson code. + * Contains annotations that can apply to any part of the BSON library code. */ package org.bson.annotations; From 4154675297306d85e3d310b29fc93d22566fe29d Mon Sep 17 00:00:00 2001 From: Viacheslav Babanin Date: Wed, 8 Jan 2025 19:39:29 -0800 Subject: [PATCH 3/4] Update bson/src/main/org/bson/PackedBitVector.java Co-authored-by: Valentin Kovalenko --- bson/src/main/org/bson/PackedBitVector.java | 1 - 1 file changed, 1 deletion(-) diff --git a/bson/src/main/org/bson/PackedBitVector.java b/bson/src/main/org/bson/PackedBitVector.java index 5ad406acd77..4be59357259 100644 --- a/bson/src/main/org/bson/PackedBitVector.java +++ b/bson/src/main/org/bson/PackedBitVector.java @@ -74,7 +74,6 @@ public byte[] getData() { * * @return the padding value (between 0 and 7). */ - @Beta(Reason.SERVER) public byte getPadding() { return this.padding; } From 0562f906c10b7a3cb156fc3c3f8499d30a518de9 Mon Sep 17 00:00:00 2001 From: Viacheslav Babanin Date: Wed, 8 Jan 2025 19:39:34 -0800 Subject: [PATCH 4/4] Update bson/src/main/org/bson/PackedBitVector.java Co-authored-by: Valentin Kovalenko --- bson/src/main/org/bson/PackedBitVector.java | 1 - 1 file changed, 1 deletion(-) diff --git a/bson/src/main/org/bson/PackedBitVector.java b/bson/src/main/org/bson/PackedBitVector.java index 4be59357259..55ac203df3a 100644 --- a/bson/src/main/org/bson/PackedBitVector.java +++ b/bson/src/main/org/bson/PackedBitVector.java @@ -57,7 +57,6 @@ public final class PackedBitVector extends Vector { * @return the underlying byte array representing this {@link PackedBitVector} vector. * @see #getPadding() */ - @Beta(Reason.SERVER) public byte[] getData() { return assertNotNull(data); }