uk.ac.starlink.parquet

## Interface Encoder<T>

-     public interface Encoder<T>

  Defines transmission of a java value type to a RecordConsumer for writing to parquet tables.
  Since:
    25 Feb 2021

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addValue(T value, RecordConsumer consumer)` Passes a supplied non-null value representing a cell of this encoder's column to a record consumer.
    `void` | `checkNull()` Called if a null value will be written.
    `java.lang.String` | `getColumnName()` Returns the name of the column that will be written to the parquet file.
    `Type` | `getColumnType()` Returns the type of the top-level field that will be written.
    `T` | `typedValue(java.lang.Object obj)` Converts an object presented for record consumption to an object of this encoder's parameterised class.

- - ### Method Detail

    - #### getColumnName

          java.lang.String getColumnName()

      Returns the name of the column that will be written to the parquet file. This is the top-level field, which may correspond to a group type containing lower-level elements, which will be assigned subordinate names automatically.

      Note this name must obey the (undocumented?) parquet field syntax constraints; it seems that roughly it has to look like a java token.

      Returns:
        field name

    - #### getColumnType

          Type getColumnType()

      Returns the type of the top-level field that will be written. This may be a primitive type or a group type.
      Returns:
        column type

    - #### typedValue

          T typedValue(java.lang.Object obj)

      Converts an object presented for record consumption to an object of this encoder's parameterised class. The presented object ought to be of the right class anyway, so this may just be a cast. However, if the object is of an unexpected type, or if its value corresponds to a blank value, null should be returned.
      Parameters:
        `obj` - object for encoding, expected to be of this encoder's type
      Returns:
        typed object for record consumption, or null if it does not correspond to a definite typed value

    - #### addValue

          void addValue(T value,
                        RecordConsumer consumer)

      Passes a supplied non-null value representing a cell of this encoder's column to a record consumer. This is invoked between RecordConsumer `startField` and `endField` calls, but if additional structuring calls are required they must be done by this method.
      Parameters:
        `value` - non-null typed value to write
        `consumer` - value consumer

    - #### checkNull

          void checkNull()

      Called if a null value will be written. This is a hook that allows an encoder to complain if it is unable to write nulls. Implementations that can write null should implement as a no-op.

      Really this should throw an IOException, but the parquet-mr classes that end up calling it don't, so it would only cause pain. You'll have to throw a RuntimeException if there's trouble.