content: /*
   * Licensed to the Apache Software Foundation (ASF) under one or more
   * contributor license agreements.  See the NOTICE file distributed with
   * this work for additional information regarding copyright ownership.
   * The ASF licenses this file to You 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.apache.arrow.vector;
  
  import java.util.List;
  import org.apache.arrow.memory.ArrowBuf;
  import org.apache.arrow.vector.ipc.message.ArrowFieldNode;
  import org.apache.arrow.vector.types.pojo.Field;
  
  /**
   * A vector corresponding to a Field in the schema. It has inner vectors backed by buffers
   * (validity, offsets, data, ...)
   */
  public interface FieldVector extends ValueVector {
  
    /**
     * Initializes the child vectors to be later loaded with loadBuffers.
     *
     * @param children the schema
     */
    void initializeChildrenFromFields(List<Field> children);
  
    /**
     * The returned list is the same size as the list passed to initializeChildrenFromFields.
     *
     * @return the children according to schema (empty for primitive types)
     */
    List<FieldVector> getChildrenFromFields();
  
    /**
     * Loads data in the vectors. (ownBuffers must be the same size as getFieldVectors())
     *
     * @param fieldNode the fieldNode
     * @param ownBuffers the buffers for this Field (own buffers only, children not included)
     */
    void loadFieldBuffers(ArrowFieldNode fieldNode, List<ArrowBuf> ownBuffers);
  
    /**
     * Get the buffers of the fields, (same size as getFieldVectors() since it is their content).
     *
     * @return the buffers containing the data for this vector (ready for reading)
     */
    List<ArrowBuf> getFieldBuffers();
  
    /**
     * Retrieves the export buffer count for the C Data Interface.
     *
     * @return the number of variadic buffers
     */
    default int getExportedCDataBufferCount() {
      return getFieldBuffers().size();
    }
  
    /**
     * Export a given buffer and its memory address into a list of buffers and a pointer to the list
     * of buffers.
     *
     * @param buffer the buffer to export
     * @param buffers the list of buffers
     * @param buffersPtr the pointer to the list of buffers
     * @param nullValue the null value to use for null buffer
     * @param retain whether to retain the buffer when exporting
     */
    default void exportBuffer(
        ArrowBuf buffer,
        List<ArrowBuf> buffers,
        ArrowBuf buffersPtr,
        long nullValue,
        boolean retain) {
      if (buffer != null) {
        if (retain) {
          buffer.getReferenceManager().retain();
        }
        buffersPtr.writeLong(buffer.memoryAddress());
      } else {
        buffersPtr.writeLong(nullValue);
      }
      buffers.add(buffer);
    }
  
    /**
     * Export the buffers of the fields for C Data Interface. This method traverse the buffers and
     * export buffer and buffer's memory address into a list of buffers and a pointer to the list of
     * buffers.
     *
     * <p>By default, when exporting a buffer, it will increase ref count for exported buffer that
     * counts the usage at imported side.
     */
    default void exportCDataBuffers(List<ArrowBuf> buffers, ArrowBuf buffersPtr, long nullValue) {
      List<ArrowBuf> fieldBuffers = getFieldBuffers();
  
      for (ArrowBuf arrowBuf : fieldBuffers) {
        exportBuffer(arrowBuf, buffers, buffersPtr, nullValue, true);
      }
    }
  
    /**
     * Get the inner vectors.
     *
     * @return the inner vectors for this field as defined by the TypeLayout
     * @deprecated This API will be removed as the current implementations no longer support inner
     *     vectors.
     */
    @Deprecated
    List<BufferBacked> getFieldInnerVectors();
  
    /**
     * Gets the starting address of the underlying buffer associated with validity vector.
     *
     * @return buffer address
     */
    long getValidityBufferAddress();
  
    /**
     * Gets the starting address of the underlying buffer associated with data vector.
     *
     * @return buffer address
     */
    long getDataBufferAddress();
  
    /**
     * Gets the starting address of the underlying buffer associated with offset vector.
     *
     * @return buffer address
     */
    long getOffsetBufferAddress();
  
    /**
     * Set the element at the given index to null.
     *
     * @param index the value to change
     */
    void setNull(int index);
  }
  