Address comments

Author: jhrotko

vector/src/main/java/org/apache/arrow/vector/FixedSizeExtensionType.java

@@ -16,6 +16,19 @@
  */
 package org.apache.arrow.vector;
 
+/**
+ * Interface for extension types with fixed-width storage.
+ *
+ * <p>Extension types that implement this interface have a known, constant byte width per value.
+ * This allows for optimizations in memory allocation and data access patterns.
+ *
+ * @see org.apache.arrow.vector.extension.UuidType
+ */
 public interface FixedSizeExtensionType {
-  public int getTypeWidth();
+  /**
+   * Returns the fixed byte width of each value in this extension type.
+   *
+   * @return the number of bytes per value
+   */
+  int getTypeWidth();
 }

vector/src/main/java/org/apache/arrow/vector/UuidVector.java

@@ -48,21 +48,38 @@
  * UUID value = vector.getObject(0);
  * }</pre>
  *
- * @see {@link UuidType}
- * @see {@link UuidHolder}
- * @see {@link NullableUuidHolder}
+ * @see UuidType
+ * @see UuidHolder
+ * @see NullableUuidHolder
  */
 public class UuidVector extends ExtensionTypeVector<FixedSizeBinaryVector>
     implements ValueIterableVector<UUID>, FixedWidthVector, FixedSizeExtensionType {
   private final Field field;
+
+  /** The fixed byte width of UUID values (16 bytes). */
   public static final int TYPE_WIDTH = UUID_BYTE_WIDTH;
 
+  /**
+   * Constructs a UUID vector with the given name, allocator, and underlying vector.
+   *
+   * @param name the name of the vector
+   * @param allocator the buffer allocator
+   * @param underlyingVector the underlying FixedSizeBinaryVector for storage
+   */
   public UuidVector(
       String name, BufferAllocator allocator, FixedSizeBinaryVector underlyingVector) {
     super(name, allocator, underlyingVector);
     this.field = new Field(name, FieldType.nullable(new UuidType()), null);
   }
 
+  /**
+   * Constructs a UUID vector with the given name, field type, allocator, and underlying vector.
+   *
+   * @param name the name of the vector
+   * @param fieldType the field type (should contain UuidType)
+   * @param allocator the buffer allocator
+   * @param underlyingVector the underlying FixedSizeBinaryVector for storage
+   */
   public UuidVector(
       String name,
       FieldType fieldType,
@@ -72,11 +89,25 @@ public UuidVector(
     this.field = new Field(name, fieldType, null);
   }
 
+  /**
+   * Constructs a UUID vector with the given name and allocator.
+   *
+   * <p>Creates a new underlying FixedSizeBinaryVector with 16-byte width.
+   *
+   * @param name the name of the vector
+   * @param allocator the buffer allocator
+   */
   public UuidVector(String name, BufferAllocator allocator) {
     super(name, allocator, new FixedSizeBinaryVector(name, allocator, UUID_BYTE_WIDTH));
     this.field = new Field(name, FieldType.nullable(new UuidType()), null);
   }
 
+  /**
+   * Constructs a UUID vector from a field and allocator.
+   *
+   * @param field the field definition (should contain UuidType)
+   * @param allocator the buffer allocator
+   */
   public UuidVector(Field field, BufferAllocator allocator) {
     super(
         field.getName(),
@@ -104,10 +135,23 @@ public int hashCode(int index, ArrowBufHasher hasher) {
     return getUnderlyingVector().hashCode(index, hasher);
   }
 
+  /**
+   * Checks if the value at the given index is set (non-null).
+   *
+   * @param index the index to check
+   * @return 1 if the value is set, 0 if null
+   */
   public int isSet(int index) {
     return getUnderlyingVector().isSet(index);
   }
 
+  /**
+   * Gets the UUID value at the given index as an ArrowBuf.
+   *
+   * @param index the index to retrieve
+   * @return a buffer slice containing the 16-byte UUID
+   * @throws IllegalStateException if the value at the index is null and null checking is enabled
+   */
   public ArrowBuf get(int index) throws IllegalStateException {
     if (NullCheckingForGet.NULL_CHECKING_ENABLED && this.isSet(index) == 0) {
       throw new IllegalStateException("Value at index is null");
@@ -116,6 +160,12 @@ public ArrowBuf get(int index) throws IllegalStateException {
     }
   }
 
+  /**
+   * Reads the UUID value at the given index into a NullableUuidHolder.
+   *
+   * @param index the index to read from
+   * @param holder the holder to populate with the UUID data
+   */
   public void get(int index, NullableUuidHolder holder) {
     if (NullCheckingForGet.NULL_CHECKING_ENABLED && this.isSet(index) == 0) {
       holder.isSet = 0;
@@ -125,15 +175,23 @@ public void get(int index, NullableUuidHolder holder) {
     }
   }
 
+  /**
+   * Reads the UUID value at the given index into a UuidHolder.
+   *
+   * @param index the index to read from
+   * @param holder the holder to populate with the UUID data
+   */
   public void get(int index, UuidHolder holder) {
-    if (NullCheckingForGet.NULL_CHECKING_ENABLED && this.isSet(index) == 0) {
-      holder.isSet = 0;
-    } else {
-      holder.isSet = 1;
-      holder.buffer = getBufferSlicePostNullCheck(index);
-    }
+    holder.isSet = 1;
+    holder.buffer = getBufferSlicePostNullCheck(index);
   }
 
+  /**
+   * Sets the UUID value at the given index.
+   *
+   * @param index the index to set
+   * @param value the UUID value to set, or null to set a null value
+   */
   public void set(int index, UUID value) {
     if (value != null) {
       set(index, UuidUtility.getBytesFromUUID(value));
@@ -142,33 +200,77 @@ public void set(int index, UUID value) {
     }
   }
 
+  /**
+   * Sets the UUID value at the given index from a UuidHolder.
+   *
+   * @param index the index to set
+   * @param holder the holder containing the UUID data
+   */
   public void set(int index, UuidHolder holder) {
     this.set(index, holder.isSet, holder.buffer);
   }
 
+  /**
+   * Sets the UUID value at the given index from a NullableUuidHolder.
+   *
+   * @param index the index to set
+   * @param holder the holder containing the UUID data
+   */
   public void set(int index, NullableUuidHolder holder) {
     this.set(index, holder.isSet, holder.buffer);
   }
 
+  /**
+   * Sets the UUID value at the given index with explicit null flag.
+   *
+   * @param index the index to set
+   * @param isSet 1 if the value is set, 0 if null
+   * @param buffer the buffer containing the 16-byte UUID data
+   */
   public void set(int index, int isSet, ArrowBuf buffer) {
     getUnderlyingVector().set(index, isSet, buffer);
   }
 
+  /**
+   * Sets the UUID value at the given index from an ArrowBuf.
+   *
+   * @param index the index to set
+   * @param value the buffer containing the 16-byte UUID data
+   */
   public void set(int index, ArrowBuf value) {
     getUnderlyingVector().set(index, value);
   }
 
+  /**
+   * Sets the UUID value at the given index by copying from a source buffer.
+   *
+   * @param index the index to set
+   * @param source the source buffer to copy from
+   * @param sourceOffset the offset in the source buffer where the UUID data starts
+   */
   public void set(int index, ArrowBuf source, int sourceOffset) {
     // Copy bytes from source buffer to target vector data buffer
     ArrowBuf dataBuffer = getUnderlyingVector().getDataBuffer();
     dataBuffer.setBytes((long) index * UUID_BYTE_WIDTH, source, sourceOffset, UUID_BYTE_WIDTH);
     getUnderlyingVector().setIndexDefined(index);
   }
 
+  /**
+   * Sets the UUID value at the given index from a byte array.
+   *
+   * @param index the index to set
+   * @param value the 16-byte array containing the UUID data
+   */
   public void set(int index, byte[] value) {
     getUnderlyingVector().set(index, value);
   }
 
+  /**
+   * Sets the UUID value at the given index, expanding capacity if needed.
+   *
+   * @param index the index to set
+   * @param value the UUID value to set, or null to set a null value
+   */
   public void setSafe(int index, UUID value) {
     if (value != null) {
       setSafe(index, UuidUtility.getBytesFromUUID(value));
@@ -177,6 +279,12 @@ public void setSafe(int index, UUID value) {
     }
   }
 
+  /**
+   * Sets the UUID value at the given index from a NullableUuidHolder, expanding capacity if needed.
+   *
+   * @param index the index to set
+   * @param holder the holder containing the UUID data, or null to set a null value
+   */
   public void setSafe(int index, NullableUuidHolder holder) {
     if (holder != null) {
       getUnderlyingVector().setSafe(index, holder.isSet, holder.buffer);
@@ -185,6 +293,12 @@ public void setSafe(int index, NullableUuidHolder holder) {
     }
   }
 
+  /**
+   * Sets the UUID value at the given index from a UuidHolder, expanding capacity if needed.
+   *
+   * @param index the index to set
+   * @param holder the holder containing the UUID data, or null to set a null value
+   */
   public void setSafe(int index, UuidHolder holder) {
     if (holder != null) {
       getUnderlyingVector().setSafe(index, holder.isSet, holder.buffer);
@@ -193,20 +307,27 @@ public void setSafe(int index, UuidHolder holder) {
     }
   }
 
+  /**
+   * Sets the UUID value at the given index from a byte array, expanding capacity if needed.
+   *
+   * @param index the index to set
+   * @param value the 16-byte array containing the UUID data
+   */
   public void setSafe(int index, byte[] value) {
     getUnderlyingVector().setIndexDefined(index);
     getUnderlyingVector().setSafe(index, value);
   }
 
+  /**
+   * Sets the UUID value at the given index from an ArrowBuf, expanding capacity if needed.
+   *
+   * @param index the index to set
+   * @param value the buffer containing the 16-byte UUID data
+   */
   public void setSafe(int index, ArrowBuf value) {
     getUnderlyingVector().setSafe(index, value);
   }
 
-  @Override
-  public int getTypeWidth() {
-    return UUID_BYTE_WIDTH;
-  }
-
   @Override
   public void copyFrom(int fromIndex, int thisIndex, ValueVector from) {
     getUnderlyingVector()
@@ -285,34 +406,74 @@ private ArrowBuf getBufferSlicePostNullCheck(int index) {
         .slice((long) index * UUID_BYTE_WIDTH, UUID_BYTE_WIDTH);
   }
 
+  @Override
+  public int getTypeWidth() {
+    return getUnderlyingVector().getTypeWidth();
+  }
+
   /** {@link TransferPair} for {@link UuidVector}. */
   public class TransferImpl implements TransferPair {
     UuidVector to;
 
+    /**
+     * Constructs a transfer pair with the given target vector.
+     *
+     * @param to the target UUID vector
+     */
     public TransferImpl(UuidVector to) {
       this.to = to;
     }
 
+    /**
+     * Constructs a transfer pair, creating a new target vector from the field and allocator.
+     *
+     * @param field the field definition for the target vector
+     * @param allocator the buffer allocator for the target vector
+     */
     public TransferImpl(Field field, BufferAllocator allocator) {
       this.to = new UuidVector(field, allocator);
     }
 
+    /**
+     * Constructs a transfer pair, creating a new target vector with the given name and allocator.
+     *
+     * @param ref the name for the target vector
+     * @param allocator the buffer allocator for the target vector
+     */
     public TransferImpl(String ref, BufferAllocator allocator) {
       this.to = new UuidVector(ref, allocator);
     }
 
+    /**
+     * Gets the target vector of this transfer pair.
+     *
+     * @return the target UUID vector
+     */
     public UuidVector getTo() {
       return this.to;
     }
 
+    /** Transfers ownership of data from the source vector to the target vector. */
     public void transfer() {
       getUnderlyingVector().transferTo(to.getUnderlyingVector());
     }
 
+    /**
+     * Splits and transfers a range of values from the source vector to the target vector.
+     *
+     * @param startIndex the starting index in the source vector
+     * @param length the number of values to transfer
+     */
     public void splitAndTransfer(int startIndex, int length) {
       getUnderlyingVector().splitAndTransferTo(startIndex, length, to.getUnderlyingVector());
     }
 
+    /**
+     * Copies a value from the source vector to the target vector, expanding capacity if needed.
+     *
+     * @param fromIndex the index in the source vector
+     * @param toIndex the index in the target vector
+     */
     public void copyValueSafe(int fromIndex, int toIndex) {
       to.copyFromSafe(fromIndex, toIndex, (ValueVector) UuidVector.this);
     }