uk.ac.starlink.feather

## Class AbstractItemAccumulator

- java.lang.Object
- - uk.ac.starlink.feather.AbstractItemAccumulator

- All Implemented Interfaces:
    ItemAccumulator

      public abstract class AbstractItemAccumulator
      extends java.lang.Object
      implements ItemAccumulator

  Partial ItemAccumulator implementation that handles generic aspects including writing the optional validity mask.
  Since:
    27 Feb 2020

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractItemAccumulator(StoragePolicy storage, boolean isNullable)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract void` | `addDataItem(java.lang.Object item)` Adds the given item to the list to be output.
    `void` | `addItem(java.lang.Object item)` Receive the next value in the column.
    `void` | `close()` Tidies up resources, in particular discarding any off-heap temporary storage that may have been allocated.
    `protected abstract void` | `closeData()` Releases resources.
    `protected boolean` | `isNull(java.lang.Object item)` Tests whether a given added data item is null (whether it needs to be flagged as null in the validity mask).
    `uk.ac.bristol.star.feather.ColStat` | `writeColumnBytes(java.io.OutputStream out)` Writes a feather-format column to the given output stream representing all the objects submitted by prior valls to the `addItem` method.
    `abstract long` | `writeDataBytes(java.io.OutputStream out)` Writes the bytes constituting the data stream for this column, excluding any optional validity mask.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### AbstractItemAccumulator

          protected AbstractItemAccumulator(StoragePolicy storage,
                                            boolean isNullable)

      Constructor.
      Parameters:
        `storage` - storage policy for buffering output data
        `isNullable` - if true, preparations will be made to write the validity mask; it will only be actually output if there are some null values

  - ### Method Detail

    - #### addDataItem

          protected abstract void addDataItem(java.lang.Object item)
                                       throws java.io.IOException

      Adds the given item to the list to be output. This method is invoked from this AbstractItemAccumulator's `addItem(java.lang.Object)` method, and is just the hook for the subclass-specific behaviour.
      Parameters:
        `item` - cell value
      Throws:
        `java.io.IOException`

    - #### closeData

          protected abstract void closeData()
                                     throws java.io.IOException

      Releases resources. This method is invoked from this AbstractItemAccumulator's `close()` method, and is just the hook for the subclass-specific behaviour.
      Throws:
        `java.io.IOException`

    - #### isNull

          protected boolean isNull(java.lang.Object item)

      Tests whether a given added data item is null (whether it needs to be flagged as null in the validity mask). This method is only ever called for nullable columns (if the `isNullable` flag was set true at construction time).

      The default implementation tests whether the supplied item is in fact `null`, but it may be overridden.

      Parameters:
        `item` - value to test
      Returns:
        true iff item is to be flagged null

    - #### writeDataBytes

          public abstract long writeDataBytes(java.io.OutputStream out)
                                       throws java.io.IOException

      Writes the bytes constituting the data stream for this column, excluding any optional validity mask. Note the output does not need to be aligned on an 8-byte boundary.
      Parameters:
        `out` - destination stream
      Returns:
        number of bytes written
      Throws:
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      Description copied from interface: `ItemAccumulator`
      Tidies up resources, in particular discarding any off-heap temporary storage that may have been allocated. Calling any of the other methods of this interface after closing it has undefined effects. Multiple calls to close are permitted.
      Specified by:
        `close` in interface `ItemAccumulator`
      Throws:
        `java.io.IOException`

    - #### addItem

          public void addItem(java.lang.Object item)
                       throws java.io.IOException

      Description copied from interface: `ItemAccumulator`
      Receive the next value in the column.
      Specified by:
        `addItem` in interface `ItemAccumulator`
      Parameters:
        `item` - column cell value
      Throws:
        `java.io.IOException`

    - #### writeColumnBytes

          public uk.ac.bristol.star.feather.ColStat writeColumnBytes(java.io.OutputStream out)
                                                              throws java.io.IOException

      Description copied from interface: `ItemAccumulator`
      Writes a feather-format column to the given output stream representing all the objects submitted by prior valls to the `addItem` method. The number of bytes written must be a multiple of 8.
      Specified by:
        `writeColumnBytes` in interface `ItemAccumulator`
      Parameters:
        `out` - destination stream
      Returns:
        details about what was written
      Throws:
        `java.io.IOException`