apacheGH-38246: [JAVA] added new getTransferPair() function that take…

…s in a Field type for Complex Type Vectors (apache#38261)

### Rationale for this change

Additionally, a new function **getTransferPair(Field, Allocator)** is introduced so that a new Field method is not constructed each time getTransferPair is called on the Vector.
Added Field.setChildren() method and made **children** not final - for updating **field** object inside complex vector(it possible that Field will be without children on creation) - optimisation for keeping using already existing Field object.

### What changes are included in this PR?

- `getTransferPair` method for ComplexType Vectors and for BaseVariableWidthVector's

- added `Field.setChildren()` method and made **children** not final - for updating **field** object inside complex vector(it possible that Field will be without children on creation) - optimisation for keeping using already existing Field object.

### Are these changes tested?

Yes, some tests have been added to verify these changes.
### Are there any user-facing changes?

Yes.

**This PR includes breaking changes to public APIs.**

* Closes: apache#38246

Lead-authored-by: Ivan Chesnov <[email protected]>
Co-authored-by: Ivan Chesnov <[email protected]>
Signed-off-by: David Li <[email protected]>

(cherry picked from commit a376e3c)

java/vector/src/main/codegen/templates/DenseUnionVector.java

@@ -234,8 +234,8 @@ public synchronized byte registerNewTypeId(Field field) {
               typeFields.length + " relative types. Please use union of union instead");
     }
     byte typeId = nextTypeId;
-    if (fieldType != null) {
-      int[] typeIds = ((ArrowType.Union) fieldType.getType()).getTypeIds();
+    if (this.fieldType != null) {
+      int[] typeIds = ((ArrowType.Union) this.fieldType.getType()).getTypeIds();
       if (typeIds != null) {
         int thisTypeId = typeIds[nextTypeId];
         if (thisTypeId > Byte.MAX_VALUE) {
@@ -533,7 +533,7 @@ public Field getField() {
     } else {
       final UnionMode mode = UnionMode.Dense;
       fieldType = new FieldType(this.fieldType.isNullable(), new ArrowType.Union(mode, typeIds),
-              this.fieldType.getDictionary(), this.fieldType.getMetadata());
+          this.fieldType.getDictionary(), this.fieldType.getMetadata());
     }
 
     return new Field(name, fieldType, childFields);
@@ -554,6 +554,16 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator, CallB
     return new org.apache.arrow.vector.complex.DenseUnionVector.TransferImpl(ref, allocator, callBack);
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator) {
+    return getTransferPair(field, allocator, null);
+  }
+
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator, CallBack callBack) {
+    return new org.apache.arrow.vector.complex.DenseUnionVector.TransferImpl(field, allocator, callBack);
+  }
+
   @Override
   public TransferPair makeTransferPair(ValueVector target) {
     return new TransferImpl((DenseUnionVector) target);
@@ -598,6 +608,12 @@ public TransferImpl(String name, BufferAllocator allocator, CallBack callBack) {
       createTransferPairs();
     }
 
+    public TransferImpl(Field field, BufferAllocator allocator, CallBack callBack) {
+      to = new DenseUnionVector(field.getName(), allocator, null, callBack);
+      internalStruct.makeTransferPair(to.internalStruct);
+      createTransferPairs();
+    }
+
     public TransferImpl(DenseUnionVector to) {
       this.to = to;
       internalStruct.makeTransferPair(to.internalStruct);

java/vector/src/main/codegen/templates/UnionVector.java

@@ -142,8 +142,8 @@ public void initializeChildrenFromFields(List<Field> children) {
     int count = 0;
     for (Field child: children) {
       int typeId = Types.getMinorTypeForArrowType(child.getType()).ordinal();
-      if (fieldType != null) {
-        int[] typeIds = ((ArrowType.Union)fieldType.getType()).getTypeIds();
+      if (this.fieldType != null) {
+        int[] typeIds = ((ArrowType.Union)this.fieldType.getType()).getTypeIds();
         if (typeIds != null) {
           typeId = typeIds[count++];
         }
@@ -476,6 +476,16 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator, CallB
     return new org.apache.arrow.vector.complex.UnionVector.TransferImpl(ref, allocator, callBack);
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator) {
+    return getTransferPair(field, allocator, null);
+  }
+
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator, CallBack callBack) {
+    return new org.apache.arrow.vector.complex.UnionVector.TransferImpl(field, allocator, callBack);
+  }
+
   @Override
   public TransferPair makeTransferPair(ValueVector target) {
     return new TransferImpl((UnionVector) target);
@@ -528,6 +538,11 @@ public TransferImpl(String name, BufferAllocator allocator, CallBack callBack) {
       internalStructVectorTransferPair = internalStruct.makeTransferPair(to.internalStruct);
     }
 
+    public TransferImpl(Field field, BufferAllocator allocator, CallBack callBack) {
+      to = new UnionVector(field.getName(), allocator, null, callBack);
+      internalStructVectorTransferPair = internalStruct.makeTransferPair(to.internalStruct);
+    }
+
     public TransferImpl(UnionVector to) {
       this.to = to;
       internalStructVectorTransferPair = internalStruct.makeTransferPair(to.internalStruct);

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

@@ -562,6 +562,18 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator, CallB
     return getTransferPair(ref, allocator);
   }
 
+  /**
+   * Construct a transfer pair of this vector and another vector of same type.
+   * @param field The field materialized by this vector.
+   * @param allocator allocator for the target vector
+   * @param callBack not used
+   * @return TransferPair
+   */
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator, CallBack callBack) {
+    return getTransferPair(field, allocator);
+  }
+
   /**
    * Construct a transfer pair of this vector and another vector of same type.
    * @param allocator allocator for the target vector

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

@@ -655,6 +655,18 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator, CallB
     return getTransferPair(ref, allocator);
   }
 
+  /**
+   * Construct a transfer pair of this vector and another vector of same type.
+   * @param field The field materialized by this vector
+   * @param allocator allocator for the target vector
+   * @param callBack not used
+   * @return TransferPair
+   */
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator, CallBack callBack) {
+    return getTransferPair(field, allocator);
+  }
+
   /**
    * Construct a transfer pair of this vector and another vector of same type.
    * @param allocator allocator for the target vector
@@ -665,6 +677,7 @@ public TransferPair getTransferPair(BufferAllocator allocator) {
     return getTransferPair(getName(), allocator);
   }
 
+
   /**
    * Construct a transfer pair of this vector and another vector of same type.
    * @param ref name of the target vector
@@ -673,6 +686,14 @@ public TransferPair getTransferPair(BufferAllocator allocator) {
    */
   public abstract TransferPair getTransferPair(String ref, BufferAllocator allocator);
 
+  /**
+   * Construct a transfer pair of this vector and another vector of same type.
+   * @param field The field materialized by this vector
+   * @param allocator allocator for the target vector
+   * @return TransferPair
+   */
+  public abstract TransferPair getTransferPair(Field field, BufferAllocator allocator);
+
   /**
    * Transfer this vector'data to another vector. The memory associated
    * with this vector is transferred to the allocator of target vector

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

@@ -685,6 +685,18 @@ public ArrowBuf[] getBuffers(boolean clear) {
     return buffers;
   }
 
+  /**
+   * Construct a transfer pair of this vector and another vector of same type.
+   * @param field The field materialized by this vector.
+   * @param allocator allocator for the target vector
+   * @param callBack not used
+   * @return TransferPair
+   */
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator, CallBack callBack) {
+    return getTransferPair(field, allocator);
+  }
+
   /**
    * Construct a transfer pair of this vector and another vector of same type.
    * @param ref name of the target vector
@@ -715,6 +727,14 @@ public TransferPair getTransferPair(BufferAllocator allocator) {
    */
   public abstract TransferPair getTransferPair(String ref, BufferAllocator allocator);
 
+  /**
+   * Construct a transfer pair of this vector and another vector of same type.
+   * @param field The field materialized by this vector.
+   * @param allocator allocator for the target vector
+   * @return TransferPair
+   */
+  public abstract TransferPair getTransferPair(Field field, BufferAllocator allocator);
+
   /**
    * Transfer this vector'data to another vector. The memory associated
    * with this vector is transferred to the allocator of target vector

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

@@ -125,6 +125,16 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator, CallB
     return underlyingVector.getTransferPair(ref, allocator, callBack);
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator) {
+    return underlyingVector.getTransferPair(field, allocator);
+  }
+
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator, CallBack callBack) {
+    return underlyingVector.getTransferPair(field, allocator, callBack);
+  }
+
   @Override
   public TransferPair makeTransferPair(ValueVector target) {
     return underlyingVector.makeTransferPair(target);

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

@@ -253,6 +253,11 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator) {
     return new TransferImpl(ref, allocator);
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator) {
+    return new TransferImpl(field, allocator);
+  }
+
   /**
    * Construct a TransferPair with a desired target vector of the same type.
    *
@@ -271,6 +276,10 @@ public TransferImpl(String ref, BufferAllocator allocator) {
       to = new LargeVarBinaryVector(ref, field.getFieldType(), allocator);
     }
 
+    public TransferImpl(Field field, BufferAllocator allocator) {
+      to = new LargeVarBinaryVector(field, allocator);
+    }
+
     public TransferImpl(LargeVarBinaryVector to) {
       this.to = to;
     }

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

@@ -280,6 +280,11 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator) {
     return new LargeVarCharVector.TransferImpl(ref, allocator);
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator) {
+    return new LargeVarCharVector.TransferImpl(field, allocator);
+  }
+
   /**
    * Construct a TransferPair with a desired target vector of the same type.
    *
@@ -298,6 +303,10 @@ public TransferImpl(String ref, BufferAllocator allocator) {
       to = new LargeVarCharVector(ref, field.getFieldType(), allocator);
     }
 
+    public TransferImpl(Field field, BufferAllocator allocator) {
+      to = new LargeVarCharVector(field, allocator);
+    }
+
     public TransferImpl(LargeVarCharVector to) {
       this.to = to;
     }

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

@@ -106,7 +106,7 @@ public Types.MinorType getMinorType() {
 
   @Override
   public TransferPair getTransferPair(BufferAllocator allocator) {
-    return getTransferPair(null, allocator);
+    return getTransferPair((String) null, allocator);
   }
 
   @Override
@@ -162,11 +162,21 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator) {
     return new TransferImpl();
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator) {
+    return new TransferImpl();
+  }
+
   @Override
   public TransferPair getTransferPair(String ref, BufferAllocator allocator, CallBack callBack) {
     return getTransferPair(ref, allocator);
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator, CallBack callBack) {
+    return getTransferPair(field, allocator);
+  }
+
   @Override
   public TransferPair makeTransferPair(ValueVector target) {
     return new TransferImpl((NullVector) target);

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

@@ -131,10 +131,48 @@ public interface ValueVector extends Closeable, Iterable<ValueVector> {
    */
   TransferPair getTransferPair(BufferAllocator allocator);
 
+  /**
+   * To transfer quota responsibility.
+   *
+   * @param ref the name of the vector
+   * @param allocator the target allocator
+   * @return a {@link org.apache.arrow.vector.util.TransferPair transfer pair}, creating a new target vector of
+   *         the same type.
+   */
   TransferPair getTransferPair(String ref, BufferAllocator allocator);
 
+  /**
+   * To transfer quota responsibility.
+   *
+   * @param field the Field object used by the target vector
+   * @param allocator the target allocator
+   * @return a {@link org.apache.arrow.vector.util.TransferPair transfer pair}, creating a new target vector of
+   *         the same type.
+   */
+  TransferPair getTransferPair(Field field, BufferAllocator allocator);
+
+  /**
+   * To transfer quota responsibility.
+   *
+   * @param ref the name of the vector
+   * @param allocator the target allocator
+   * @param callBack A schema change callback.
+   * @return a {@link org.apache.arrow.vector.util.TransferPair transfer pair}, creating a new target vector of
+   *         the same type.
+   */
   TransferPair getTransferPair(String ref, BufferAllocator allocator, CallBack callBack);
 
+  /**
+   * To transfer quota responsibility.
+   *
+   * @param field the Field object used by the target vector
+   * @param allocator the target allocator
+   * @param callBack A schema change callback.
+   * @return a {@link org.apache.arrow.vector.util.TransferPair transfer pair}, creating a new target vector of
+   *         the same type.
+   */
+  TransferPair getTransferPair(Field field, BufferAllocator allocator, CallBack callBack);
+
   /**
    * Makes a new transfer pair used to transfer underlying buffers.
    *

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

@@ -254,6 +254,11 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator) {
     return new TransferImpl(ref, allocator);
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator) {
+    return new TransferImpl(field, allocator);
+  }
+
   /**
    * Construct a TransferPair with a desired target vector of the same type.
    *
@@ -272,6 +277,10 @@ public TransferImpl(String ref, BufferAllocator allocator) {
       to = new VarBinaryVector(ref, field.getFieldType(), allocator);
     }
 
+    public TransferImpl(Field field, BufferAllocator allocator) {
+      to = new VarBinaryVector(field, allocator);
+    }
+
     public TransferImpl(VarBinaryVector to) {
       this.to = to;
     }

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

@@ -280,6 +280,11 @@ public TransferPair getTransferPair(String ref, BufferAllocator allocator) {
     return new TransferImpl(ref, allocator);
   }
 
+  @Override
+  public TransferPair getTransferPair(Field field, BufferAllocator allocator) {
+    return new TransferImpl(field, allocator);
+  }
+
   /**
    * Construct a TransferPair with a desired target vector of the same type.
    *
@@ -298,6 +303,10 @@ public TransferImpl(String ref, BufferAllocator allocator) {
       to = new VarCharVector(ref, field.getFieldType(), allocator);
     }
 
+    public TransferImpl(Field field, BufferAllocator allocator) {
+      to = new VarCharVector(field, allocator);
+    }
+
     public TransferImpl(VarCharVector to) {
       this.to = to;
     }