uk.ac.starlink.fits

## Class BintableStarTable

- java.lang.Object
- - uk.ac.starlink.table.AbstractStarTable
  - - uk.ac.starlink.fits.BintableStarTable

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, StarTable

      public abstract class BintableStarTable
      extends AbstractStarTable

  An implementation of the StarTable interface which uses a FITS BINTABLE extension.

  The implementation varies according to whether random or sequential-only access is provided by the underlying data access. A factory method is provided to create an appropriate instance.

  Some instances of this class hang on to file descriptors. If you are in danger of running out of that resource before instances are garbage collected, you can call the `AbstractStarTable.close()` method to release them. Attempting to read data following such a call may result in an exception.

  Limited support is provided for the HEALPix-FITS convention; the relevant `HealpixTableInfo` table parameters are added, but any BAD_DATA keyword value is ignored, and the 1024-element array-valued column variant of the format is not understood.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ValueInfo` | `LONGOFF_INFO` Column aux metadata key for stringified longs offset.
    `static ValueInfo` | `TBCOL_INFO` Column aux metadata key for TBCOLn cards.
    `static ValueInfo` | `TDISP_INFO` Column aux metadata key for TDISPn cards.
    `static ValueInfo` | `TFORM_INFO` Column aux metadata key for TFORMn cards.
    `static ValueInfo` | `TNULL_INFO` Column aux metadata key for TNULLn cards.
    `static ValueInfo` | `TSCAL_INFO` Column aux metadata key for TSCALn cards.
    `static ValueInfo` | `TZERO_INFO` Column aux metadata key for TZEROn cards.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `BintableStarTable(FitsHeader hdr, boolean isRandom, WideFits wide)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static BintableStarTable` | `createTable(FitsHeader hdr, InputFactory inputFact, WideFits wide)` Returns an instance of this class given a data access instance.
    `java.util.List<ValueInfo>` | `getColumnAuxDataInfos()` Goes through the table columns (`ColumnInfo` objects) and picks out all the AuxData items which exist, generalising where necessary and returning a union of them in alphabetical order by name.
    `int` | `getColumnCount()` Returns the number of columns in this table.
    `ColumnInfo` | `getColumnInfo(int icol)` Returns the object describing the data in a given column.
    `protected long[]` | `getColumnOffsets()` Returns the array of byte offsets from the start of the row at which each column starts.
    `long` | `getRowCount()` Returns the number of rows in this table, if known.
    `protected long` | `getRowLength()` Returns the number of bytes occupied in the data stream by a single row of the table.
    `protected java.lang.Object` | `readCell(BasicInput stream, int icol)` Reads a cell from a given column from the current position in a stream.
    `protected java.lang.Object[]` | `readRow(BasicInput stream)` Reads a whole row of the table from the current position in a stream, returning a new Object[] array.
    `static void` | `streamStarTable(FitsHeader hdr, BasicInput input, WideFits wide, TableSink sink)` Reads a BINTABLE extension from a stream and writes the result to a table sink.

    - ### Methods inherited from class uk.ac.starlink.table.AbstractStarTable

      `checkedLongToInt, close, getCell, getName, getParameters, getRow, getRowAccess, getRowSequence, getRowSplittable, getURL, isRandom, setName, setParameters, setURL`

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

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

    - ### Methods inherited from interface uk.ac.starlink.table.StarTable

      `getParameterByName, setParameter`

- - ### Field Detail

    - #### TNULL_INFO

          public static final ValueInfo TNULL_INFO

      Column aux metadata key for TNULLn cards.

    - #### TSCAL_INFO

          public static final ValueInfo TSCAL_INFO

      Column aux metadata key for TSCALn cards.

    - #### TZERO_INFO

          public static final ValueInfo TZERO_INFO

      Column aux metadata key for TZEROn cards.

    - #### TDISP_INFO

          public static final ValueInfo TDISP_INFO

      Column aux metadata key for TDISPn cards.

    - #### TBCOL_INFO

          public static final ValueInfo TBCOL_INFO

      Column aux metadata key for TBCOLn cards.

    - #### TFORM_INFO

          public static final ValueInfo TFORM_INFO

      Column aux metadata key for TFORMn cards.

    - #### LONGOFF_INFO

          public static final ValueInfo LONGOFF_INFO

      Column aux metadata key for stringified longs offset.

  - ### Constructor Detail

    - #### BintableStarTable

          protected BintableStarTable(FitsHeader hdr,
                                      boolean isRandom,
                                      WideFits wide)
                               throws java.io.IOException

      Constructor.
      Parameters:
        `hdr` - FITS header cards
        `isRandom` - true if the data access will be random-access, false for sequential-only
        `wide` - convention for representing extended columns; use null to avoid use of extended columns
      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### getRowCount

          public long getRowCount()

      Description copied from interface: `StarTable`
      Returns the number of rows in this table, if known. If the number of rows cannot be (easily) determined, a value of -1 will be returned.
      Specified by:
        `getRowCount` in interface `StarTable`
      Specified by:
        `getRowCount` in class `AbstractStarTable`
      Returns:
        the number of rows, or -1

    - #### getColumnCount

          public int getColumnCount()

      Description copied from interface: `StarTable`
      Returns the number of columns in this table.
      Specified by:
        `getColumnCount` in interface `StarTable`
      Specified by:
        `getColumnCount` in class `AbstractStarTable`
      Returns:
        the number of columns

    - #### getColumnInfo

          public ColumnInfo getColumnInfo(int icol)

      Description copied from interface: `StarTable`
      Returns the object describing the data in a given column.
      Specified by:
        `getColumnInfo` in interface `StarTable`
      Specified by:
        `getColumnInfo` in class `AbstractStarTable`
      Parameters:
        `icol` - the column for which header information is required
      Returns:
        a ValueInfo object for column `icol`

    - #### getColumnAuxDataInfos

          public java.util.List<ValueInfo> getColumnAuxDataInfos()

      Description copied from class: `AbstractStarTable`
      Goes through the table columns (`ColumnInfo` objects) and picks out all the AuxData items which exist, generalising where necessary and returning a union of them in alphabetical order by name. Subclasses should override this if they can do better, for instance providing an order for the keys.
      Specified by:
        `getColumnAuxDataInfos` in interface `StarTable`
      Overrides:
        `getColumnAuxDataInfos` in class `AbstractStarTable`
      Returns:
        a list of all the auxiliary metadata `ValueInfo` items which in fact crop up in column metadata
      See Also:
        `DefaultValueInfo.getAuxData()`

    - #### readCell

          protected java.lang.Object readCell(BasicInput stream,
                                              int icol)
                                       throws java.io.IOException

      Reads a cell from a given column from the current position in a stream.
      Parameters:
        `icol` - the column index corresponding to the cell to be read
        `stream` - a stream containing the byte data, positioned to the right place
      Throws:
        `java.io.IOException`

    - #### readRow

          protected java.lang.Object[] readRow(BasicInput stream)
                                        throws java.io.IOException

      Reads a whole row of the table from the current position in a stream, returning a new Object[] array.
      Parameters:
        `stream` - a stream containing the byte data, positioned to the right place
      Returns:
        `ncol`-element array of cells for this row
      Throws:
        `java.io.IOException`

    - #### getRowLength

          protected long getRowLength()

      Returns the number of bytes occupied in the data stream by a single row of the table. This is equal to the sum of the column offsets array.
      Returns:
        row length in bytes

    - #### getColumnOffsets

          protected long[] getColumnOffsets()

      Returns the array of byte offsets from the start of the row at which each column starts.
      Returns:
        `ncol`-element array of byte offsets

    - #### createTable

          public static BintableStarTable createTable(FitsHeader hdr,
                                                      InputFactory inputFact,
                                                      WideFits wide)
                                               throws java.io.IOException

      Returns an instance of this class given a data access instance.
      Parameters:
        `hdr` - FITS header cards
        `inputFact` - factory for access to the data part of the HDU representing a FITS BINTABLE extension
        `wide` - convention for representing extended columns; use null to avoid use of extended columns
      Returns:
        StarTable instance; it will be random-access according to whether the input factory is
      Throws:
        `java.io.IOException`

    - #### streamStarTable

          public static void streamStarTable(FitsHeader hdr,
                                             BasicInput input,
                                             WideFits wide,
                                             TableSink sink)
                                      throws java.io.IOException

      Reads a BINTABLE extension from a stream and writes the result to a table sink.
      Parameters:
        `hdr` - FITS header object describing the BINTABLE extension
        `input` - input stream positioned at the start of the data part of the BINTABLE extension
        `wide` - convention for representing extended columns; use null to avoid use of extended columns
        `sink` - destination for the table
      Throws:
        `java.io.IOException`