docs(bigquery): add Javadoc comments to all methods in ArrowDeserializer and ArrowPojoUtils

Author: jinseopkim0

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/ArrowDeserializer.java

@@ -45,10 +45,20 @@
  */
 final class ArrowDeserializer {
 
+  /** Lazy initialization holder for the root {@link BufferAllocator}. */
   private static class AllocatorHolder {
     private static final BufferAllocator ALLOCATOR = new RootAllocator(Long.MAX_VALUE);
   }
 
+  /**
+   * Instantiates a new {@link VectorSchemaRoot} for the given Arrow schema using vectors allocated
+   * from the provided child allocator, ensuring LIFO cleanup if an error occurs during
+   * construction.
+   *
+   * @param arrowSchema the Apache Arrow schema definition
+   * @param allocator the buffer allocator to bind the vectors to
+   * @return a new VectorSchemaRoot containing allocated field vectors
+   */
   private static VectorSchemaRoot createVectorSchemaRoot(
       org.apache.arrow.vector.types.pojo.Schema arrowSchema, BufferAllocator allocator) {
     List<FieldVector> vectors = ArrowPojoUtils.createVectors(arrowSchema, allocator);
@@ -93,6 +103,13 @@ static String arrowSchemaToJson(Object arrowSchema) {
     return ((org.apache.arrow.vector.types.pojo.Schema) arrowSchema).toJson();
   }
 
+  /**
+   * Deserializes an Apache Arrow Schema object from its JSON string representation.
+   *
+   * @param json the JSON string representation of the Arrow schema
+   * @return the deserialized Apache Arrow Schema object, or null if json is null
+   * @throws IllegalArgumentException if the JSON string cannot be parsed as an Arrow schema
+   */
   static Object jsonToArrowSchema(String json) {
     if (json == null) {
       return null;
@@ -195,8 +212,8 @@ static Schema arrowSchemaToBigQuerySchema(Object arrowSchema) {
    * Deserializes a raw binary Arrow record batch payload into a list of BigQuery {@link
    * FieldValueList} row objects.
    *
-   * <p>Allocates off-heap memory within a local {@link RootAllocator} scope and closes all Arrow
-   * vector resources before returning, guaranteeing that native memory is released.
+   * <p>Allocates off-heap memory within a local child allocator scope and closes all Arrow vector
+   * resources before returning, guaranteeing that native memory is released.
    *
    * @param recordBatchBytes the raw binary Arrow record batch payload
    * @param schema the target BigQuery Schema

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/ArrowPojoUtils.java

@@ -24,11 +24,22 @@
 import org.apache.arrow.vector.types.pojo.Field;
 import org.apache.arrow.vector.types.pojo.Schema;
 
-/** Internal helper for Apache Arrow Schema/Field conversions. */
+/**
+ * Internal helper utility for converting Apache Arrow POJO Schema and Field definitions into
+ * BigQuery Veneer {@link com.google.cloud.bigquery.Schema} and {@link
+ * com.google.cloud.bigquery.Field} models.
+ */
 final class ArrowPojoUtils {
 
   private ArrowPojoUtils() {}
 
+  /**
+   * Converts an Apache Arrow {@link Schema} into a BigQuery Veneer {@link
+   * com.google.cloud.bigquery.Schema}.
+   *
+   * @param arrowSchema the Apache Arrow schema definition
+   * @return the corresponding BigQuery Veneer Schema
+   */
   static com.google.cloud.bigquery.Schema arrowSchemaToBigQuerySchema(Schema arrowSchema) {
     List<com.google.cloud.bigquery.Field> fields = new ArrayList<>();
     for (Field arrowField : arrowSchema.getFields()) {
@@ -37,6 +48,16 @@ static com.google.cloud.bigquery.Schema arrowSchemaToBigQuerySchema(Schema arrow
     return com.google.cloud.bigquery.Schema.of(fields);
   }
 
+  /**
+   * Recursively converts an Apache Arrow {@link Field} into a BigQuery Veneer {@link
+   * com.google.cloud.bigquery.Field}.
+   *
+   * <p>Handles primitive types, repeated/list types, and nested struct/record types.
+   *
+   * @param arrowField the Apache Arrow field definition
+   * @return the corresponding BigQuery Veneer Field
+   * @throws IllegalArgumentException if an Arrow List field contains no child elements
+   */
   static com.google.cloud.bigquery.Field arrowFieldToBigQueryField(Field arrowField) {
     String name = arrowField.getName();
     ArrowType type = arrowField.getType();
@@ -83,6 +104,17 @@ static com.google.cloud.bigquery.Field arrowFieldToBigQueryField(Field arrowFiel
     return builder.build();
   }
 
+  /**
+   * Instantiates a list of {@link FieldVector} instances corresponding to the fields in the
+   * provided Arrow schema using the specified allocator.
+   *
+   * <p>Guarantees exception-safe LIFO cleanup of already-allocated vectors if an allocation fails
+   * halfway through.
+   *
+   * @param arrowSchema the Apache Arrow schema definition
+   * @param allocator the buffer allocator to allocate vector memory from
+   * @return the list of allocated FieldVector instances
+   */
   static List<FieldVector> createVectors(Schema arrowSchema, BufferAllocator allocator) {
     List<FieldVector> vectors = new ArrayList<>();
     try {
@@ -102,6 +134,13 @@ static List<FieldVector> createVectors(Schema arrowSchema, BufferAllocator alloc
     }
   }
 
+  /**
+   * Maps an Apache {@link ArrowType} to its corresponding BigQuery {@link LegacySQLTypeName}.
+   *
+   * @param type the Apache Arrow type
+   * @return the matching BigQuery LegacySQLTypeName
+   * @throws IllegalArgumentException if the Arrow type is unsupported
+   */
   private static LegacySQLTypeName arrowTypeToLegacySQLTypeName(ArrowType type) {
     switch (type.getTypeID()) {
       case Int: