diff --git a/bson/src/main/org/bson/BinaryVector.java b/bson/src/main/org/bson/BinaryVector.java index 630f54ea4f5..273b4a0e5e9 100644 --- a/bson/src/main/org/bson/BinaryVector.java +++ b/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); diff --git a/bson/src/main/org/bson/PackedBitBinaryVector.java b/bson/src/main/org/bson/PackedBitBinaryVector.java index 28d00174036..33200650204 100644 --- a/bson/src/main/org/bson/PackedBitBinaryVector.java +++ b/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; 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..ac5cd9dabf9 --- /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 library code. + */ +package org.bson.annotations;