Add BSON Binary Subtype 9 support for vector storage and retrieval.

bson/src/main/org/bson/BsonBinary.java

@@ -93,7 +93,7 @@ public BsonBinary(final UUID uuid) {
     }
 
     /**
-     * Construct a {@linkplain BsonBinarySubType#VECTOR subtype 9} {@link BsonBinary} from the given {@link @Vector}.
+     * Constructs a {@linkplain BsonBinarySubType#VECTOR subtype 9} {@link BsonBinary} from the given {@link Vector}.
      *
      * @param vector the {@link Vector}
      * @since 5.3
@@ -152,7 +152,7 @@ public UUID asUuid() {
      * @since 5.3
      */
     public Vector asVector() {
-        if (!BsonBinarySubType.isVector(type)) {
+        if (type != BsonBinarySubType.VECTOR.getValue()) {
             throw new BsonInvalidOperationException("type must be a Vector subtype.");
         }
 

bson/src/main/org/bson/BsonBinarySubType.java

@@ -100,17 +100,6 @@ public static boolean isUuid(final byte value) {
         return value == UUID_LEGACY.getValue() || value == UUID_STANDARD.getValue();
     }
 
-    /**
-     * Returns true if the given value is a {@link #VECTOR} subtype.
-     *
-     * @param value the subtype value as a byte.
-     * @return true if value is a {@link #VECTOR} subtype.
-     * @since 5.3
-     */
-    public static boolean isVector(final byte value) {
-        return value == VECTOR.getValue();
-    }
-
     BsonBinarySubType(final byte value) {
         this.value = value;
     }

bson/src/main/org/bson/Float32Vector.java

@@ -16,8 +16,6 @@
 
 package org.bson;
 
-import org.bson.types.Binary;
-
 import java.util.Arrays;
 
 import static org.bson.assertions.Assertions.assertNotNull;
@@ -31,17 +29,15 @@
  * @see Vector#floatVector(float[])
  * @see BsonBinary#BsonBinary(Vector)
  * @see BsonBinary#asVector()
- * @see Binary#Binary(Vector)
- * @see Binary#asVector()
  * @since 5.3
  */
 public final class Float32Vector extends Vector {
 
-    private final float[] vectorData;
+    private final float[] data;
 
     Float32Vector(final float[] vectorData) {
         super(DataType.FLOAT32);
-        this.vectorData = assertNotNull(vectorData);
+        this.data = assertNotNull(vectorData);
     }
 
     /**
@@ -52,33 +48,32 @@ public final class Float32Vector extends Vector {
      *
      * @return the underlying float array representing this {@link Float32Vector} vector.
      */
-    public float[] getVectorArray() {
-        return assertNotNull(vectorData);
+    public float[] getData() {
+        return assertNotNull(data);
     }
 
     @Override
     public boolean equals(final Object o) {
         if (this == o) {
             return true;
         }
-        if (!(o instanceof Float32Vector)) {
+        if (o == null || getClass() != o.getClass()) {
             return false;
         }
-
         Float32Vector that = (Float32Vector) o;
-        return Arrays.equals(vectorData, that.vectorData);
+        return Arrays.equals(data, that.data);
     }
 
     @Override
     public int hashCode() {
-        return Arrays.hashCode(vectorData);
+        return Arrays.hashCode(data);
     }
 
     @Override
     public String toString() {
         return "Float32Vector{"
-                + "vectorData=" + Arrays.toString(vectorData)
-                + ", vectorType=" + getDataType()
+                + "data=" + Arrays.toString(data)
+                + ", dataType=" + getDataType()
                 + '}';
     }
 }

bson/src/main/org/bson/Int8Vector.java

@@ -16,9 +16,8 @@
 
 package org.bson;
 
-import org.bson.types.Binary;
-
 import java.util.Arrays;
+import java.util.Objects;
 
 import static org.bson.assertions.Assertions.assertNotNull;
 
@@ -31,17 +30,15 @@
  * @see Vector#int8Vector(byte[])
  * @see BsonBinary#BsonBinary(Vector)
  * @see BsonBinary#asVector()
- * @see Binary#Binary(Vector)
- * @see Binary#asVector()
  * @since 5.3
  */
 public final class Int8Vector extends Vector {
 
-    private byte[] vectorData;
+    private byte[] data;
 
-    Int8Vector(final byte[] vectorData) {
+    Int8Vector(final byte[] data) {
         super(DataType.INT8);
-        this.vectorData = assertNotNull(vectorData);
+        this.data = assertNotNull(data);
     }
 
     /**
@@ -52,33 +49,32 @@ public final class Int8Vector extends Vector {
      *
      * @return the underlying byte array representing this {@link Int8Vector} vector.
      */
-    public byte[] getVectorArray() {
-        return assertNotNull(vectorData);
+    public byte[] getData() {
+        return assertNotNull(data);
     }
 
     @Override
     public boolean equals(final Object o) {
         if (this == o) {
             return true;
         }
-        if (!(o instanceof Int8Vector)) {
+        if (o == null || getClass() != o.getClass()) {
             return false;
         }
-
         Int8Vector that = (Int8Vector) o;
-        return Arrays.equals(vectorData, that.vectorData);
+        return Objects.deepEquals(data, that.data);
     }
 
     @Override
     public int hashCode() {
-        return Arrays.hashCode(vectorData);
+        return Arrays.hashCode(data);
     }
 
     @Override
     public String toString() {
         return "Int8Vector{"
-                + "vectorData=" + Arrays.toString(vectorData)
-                + ", vectorType=" + getDataType()
+                + "data=" + Arrays.toString(data)
+                + ", dataType=" + getDataType()
                 + '}';
     }
 }

bson/src/main/org/bson/PackedBitVector.java

@@ -16,9 +16,8 @@
 
 package org.bson;
 
-import org.bson.types.Binary;
-
 import java.util.Arrays;
+import java.util.Objects;
 
 import static org.bson.assertions.Assertions.assertNotNull;
 
@@ -31,18 +30,16 @@
  * @see Vector#packedBitVector(byte[], byte)
  * @see BsonBinary#BsonBinary(Vector)
  * @see BsonBinary#asVector()
- * @see Binary#Binary(Vector)
- * @see Binary#asVector()
  * @since 5.3
  */
 public final class PackedBitVector extends Vector {
 
     private final byte padding;
-    private final byte[] vectorData;
+    private final byte[] data;
 
-    PackedBitVector(final byte[] vectorData, final byte padding) {
+    PackedBitVector(final byte[] data, final byte padding) {
         super(DataType.PACKED_BIT);
-        this.vectorData = assertNotNull(vectorData);
+        this.data = assertNotNull(data);
         this.padding = padding;
     }
 
@@ -56,15 +53,15 @@ public final class PackedBitVector extends Vector {
      * @return the underlying byte array representing this {@link PackedBitVector} vector.
      * @see #getPadding()
      */
-    public byte[] getVectorArray() {
-        return assertNotNull(vectorData);
+    public byte[] getData() {
+        return assertNotNull(data);
     }
 
     /**
      * Returns the padding value for this vector.
      *
      * <p>Padding refers to the number of least-significant bits in the final byte that are ignored when retrieving
-     * {@linkplain #getVectorArray() the vector array). For instance, if the padding value is 3, this means that the last byte contains
+     * {@linkplain #getData() the vector array}. For instance, if the padding value is 3, this means that the last byte contains
      * 3 least-significant unused bits, which should be disregarded during operations.</p>
      * <p>
      *
@@ -81,25 +78,24 @@ public boolean equals(final Object o) {
         if (this == o) {
             return true;
         }
-        if (!(o instanceof PackedBitVector)) {
+        if (o == null || getClass() != o.getClass()) {
             return false;
         }
-
         PackedBitVector that = (PackedBitVector) o;
-        return padding == that.padding && Arrays.equals(vectorData, that.vectorData);
+        return padding == that.padding && Arrays.equals(data, that.data);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(padding, Arrays.hashCode(vectorData));
+        return Objects.hash(padding, Arrays.hashCode(data));
     }
 
     @Override
     public String toString() {
         return "PackedBitVector{"
                 + "padding=" + padding
-                + ", vectorData=" + Arrays.toString(vectorData)
-                + ", vectorType=" + getDataType()
+                + ", data=" + Arrays.toString(data)
+                + ", dataType=" + getDataType()
                 + '}';
     }
 }

bson/src/main/org/bson/Vector.java

@@ -16,8 +16,6 @@
 
 package org.bson;
 
-
-import static org.bson.assertions.Assertions.isTrue;
 import static org.bson.assertions.Assertions.isTrueArgument;
 import static org.bson.assertions.Assertions.notNull;
 
@@ -28,16 +26,19 @@
  * <p>
  * Vectors are densely packed arrays of numbers, all the same type, which are stored efficiently
  * in BSON using a binary format.
+ * <p>
+ * <b>NOTE:</b> This class is intended to be treated as <b>sealed</b>. Any subclasses added outside the library are not guaranteed to
+ * function correctly in the current and future releases.
  *
  * @mongodb.server.release 6.0
  * @see BsonBinary
  * @since 5.3
  */
 public abstract class Vector {
-    private final DataType vectorType;
+    private final DataType dataType;
 
-    Vector(final DataType vectorType) {
-        this.vectorType = vectorType;
+    Vector(final DataType dataType) {
+        this.dataType = dataType;
     }
 
     /**
@@ -55,19 +56,19 @@ public abstract class Vector {
      * Resulting vector: 12 bits: 111011101110
      * </pre>
      * <p>
-     * NOTE: The byte array `vectorData` is not copied; changes to the provided array will be reflected
+     * NOTE: The byte array `data` is not copied; changes to the provided array will be reflected
      * in the created {@link PackedBitVector} instance.
      *
-     * @param vectorData The byte array representing the packed bit vector data. Each byte can store 8 bits.
+     * @param data The byte array representing the packed bit vector data. Each byte can store 8 bits.
      * @param padding    The number of least-significant bits (0 to 7) to ignore in the final byte of the vector data.
      * @return A {@link PackedBitVector} instance with the {@link DataType#PACKED_BIT} data type.
      * @throws IllegalArgumentException If the padding value is greater than 7.
      */
-    public static PackedBitVector packedBitVector(final byte[] vectorData, final byte padding) {
-        notNull("vectorData", vectorData);
-        isTrueArgument("Padding must be between 0 and 7 bits.", padding >= 0 && padding <= 7);
-        isTrueArgument("Padding must be 0 if vector is empty", padding == 0 || vectorData.length > 0);
-        return new PackedBitVector(vectorData, padding);
+    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);
+        isTrueArgument("Padding must be 0 if vector is empty. Provided padding: " + padding, padding == 0 || data.length > 0);
+        return new PackedBitVector(data, padding);
     }
 
     /**
@@ -76,31 +77,31 @@ public static PackedBitVector packedBitVector(final byte[] vectorData, final byt
      * <p>A {@link DataType#INT8} vector is a vector of 8-bit signed integers where each byte in the vector represents an element of a vector,
      * with values in the range [-128, 127].</p>
      * <p>
-     * NOTE: The byte array `vectorData` is not copied; changes to the provided array will be reflected
+     * NOTE: The byte array `data` is not copied; changes to the provided array will be reflected
      * in the created {@link Int8Vector} instance.
      *
-     * @param vectorData The byte array representing the {@link DataType#INT8} vector data.
+     * @param data The byte array representing the {@link DataType#INT8} vector data.
      * @return A {@link Int8Vector} instance with the {@link DataType#INT8} data type.
      */
-    public static Int8Vector int8Vector(final byte[] vectorData) {
-        notNull("vectorData", vectorData);
-        return new Int8Vector(vectorData);
+    public static Int8Vector int8Vector(final byte[] data) {
+        notNull("data", data);
+        return new Int8Vector(data);
     }
 
     /**
      * Creates a vector with the {@link DataType#FLOAT32} data type.
      * <p>
      * A {@link DataType#FLOAT32} vector is a vector of floating-point numbers, where each element in the vector is a float.</p>
      * <p>
-     * NOTE: The float array `vectorData` is not copied; changes to the provided array will be reflected
+     * NOTE: The float array `data` is not copied; changes to the provided array will be reflected
      * in the created {@link Float32Vector} instance.
      *
-     * @param vectorData The float array representing the {@link DataType#FLOAT32} vector data.
+     * @param data The float array representing the {@link DataType#FLOAT32} vector data.
      * @return A {@link Float32Vector} instance with the {@link DataType#FLOAT32} data type.
      */
-    public static Float32Vector floatVector(final float[] vectorData) {
-        notNull("vectorData", vectorData);
-        return new Float32Vector(vectorData);
+    public static Float32Vector floatVector(final float[] data) {
+        notNull("data", data);
+        return new Float32Vector(data);
     }
 
     /**
@@ -145,13 +146,13 @@ public Float32Vector asFloat32Vector() {
      * @return the data type of the vector.
      */
     public DataType getDataType() {
-        return this.vectorType;
+        return this.dataType;
     }
 
 
     private void ensureType(final DataType expected) {
-        if (this.vectorType != expected) {
-            throw new IllegalStateException("Expected vector type " + expected + " but found " + this.vectorType);
+        if (this.dataType != expected) {
+            throw new IllegalStateException("Expected vector data type " + expected + ", but found " + this.dataType);
         }
     }