Package uk.ac.starlink.fits

## Class StandardFitsTableSerializer

- java.lang.Object
- - uk.ac.starlink.fits.StandardFitsTableSerializer

- All Implemented Interfaces:
    `FitsTableSerializer`
  Direct Known Subclasses:
    `VariableFitsTableSerializer`

      public class StandardFitsTableSerializer
      extends java.lang.Object
      implements FitsTableSerializer

  Class which knows how to do the various bits of serializing a StarTable to FITS BINTABLE format. A normal (row-oriented) organisation of the data is used. Array-valued columns are all written as fixed size arrays. This class does the hard work for FitsTableWriter.

  When writing tables that are marked up using the headers defined in `HealpixTableInfo`, this serializer will attempt to insert FITS headers corresponding to the HEALPix-FITS convention.

  Author:
    Mark Taylor (Starlink)
  See Also:
    HEALPix-FITS convention

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `StandardFitsTableSerializer​(uk.ac.starlink.table.StarTable table, boolean allowSignedByte, WideFits wide)` | Constructs a serializer to write a given StarTable, with explicit instruction about how to write byte-type columns data.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `getBadValue​(int icol)` | Returns the bad value (text of the TNULLnn card), if any, used for a given column.
    `int[]` | `getDimensions​(int icol)` | Returns the dimensions of the items which will be output for a given column.
    `char` | `getFormatChar​(int icol)` | Returns the FITS TFORM letter which describes the type of data output for a given column.
    `nom.tam.fits.Header` | `getHeader()` | Returns a header suitable for the HDU which will contain the table.
    `protected nom.tam.fits.HeaderCard[]` | `getHealpixHeaders​(uk.ac.starlink.table.HealpixTableInfo hpxInfo)` | Returns FITS headers specific for a table containing a HEALPix map.
    `long` | `getRowCount()` | Returns the number of rows which will be output.
    `void` | `writeData​(java.io.DataOutput strm)` | Writes the HDU data for the table to an output stream.

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

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

- - ### Constructor Detail

    - #### StandardFitsTableSerializer

          public StandardFitsTableSerializer​(uk.ac.starlink.table.StarTable table,
                                             boolean allowSignedByte,
                                             WideFits wide)
                                      throws java.io.IOException

      Constructs a serializer to write a given StarTable, with explicit instruction about how to write byte-type columns data. Since FITS bytes are unsigned (unlike, for instance, java bytes), they can cause trouble in some circumstances, so avoiding writing them may sometimes help.
      Parameters:
        `table` - the table to be written
        `allowSignedByte` - if true, bytes written as FITS signed bytes (TZERO=-128), if false bytes written as signed shorts
        `wide` - convention for representing over-wide tables; null to avoid this convention
      Throws:
        `java.io.IOException` - if it won't be possible to write the given table

  - ### Method Detail

    - #### getHeader

          public nom.tam.fits.Header getHeader()
                                        throws nom.tam.fits.HeaderCardException

      Description copied from interface: `FitsTableSerializer`
      Returns a header suitable for the HDU which will contain the table.
      Specified by:
        `getHeader` in interface `FitsTableSerializer`
      Returns:
        header object
      Throws:
        `nom.tam.fits.HeaderCardException`

    - #### writeData

          public void writeData​(java.io.DataOutput strm)
                         throws java.io.IOException

      Description copied from interface: `FitsTableSerializer`
      Writes the HDU data for the table to an output stream.
      Specified by:
        `writeData` in interface `FitsTableSerializer`
      Parameters:
        `strm` - destination stream
      Throws:
        `java.io.IOException`

    - #### getFormatChar

          public char getFormatChar​(int icol)

      Description copied from interface: `FitsTableSerializer`
      Returns the FITS TFORM letter which describes the type of data output for a given column. This is as described by the FITS standard - 'J' for 4-byte integer, 'A' for characters, etc. If the column is not being output, `(char)0` will be returned.
      Specified by:
        `getFormatChar` in interface `FitsTableSerializer`
      Parameters:
        `icol` - column to query
      Returns:
        format letter for data in column `icol`, or 0 for a column being skipped

    - #### getDimensions

          public int[] getDimensions​(int icol)

      Description copied from interface: `FitsTableSerializer`
      Returns the dimensions of the items which will be output for a given column. This will be `null` only if that column is not being output. Otherwise it will be a zero-element array for a scalar, 1-element array for a vector, etc.
      Specified by:
        `getDimensions` in interface `FitsTableSerializer`
      Parameters:
        `icol` - column to query
      Returns:
        dimensions array for data in column `icol` or `null` for a column being skipped

    - #### getBadValue

          public java.lang.String getBadValue​(int icol)

      Description copied from interface: `FitsTableSerializer`
      Returns the bad value (text of the TNULLnn card), if any, used for a given column.
      Specified by:
        `getBadValue` in interface `FitsTableSerializer`
      Parameters:
        `icol` - column to query
      Returns:
        blank value string, or null if there is none or the column is being skipped

    - #### getRowCount

          public long getRowCount()

      Description copied from interface: `FitsTableSerializer`
      Returns the number of rows which will be output.
      Specified by:
        `getRowCount` in interface `FitsTableSerializer`
      Returns:
        row count

    - #### getHealpixHeaders

          protected nom.tam.fits.HeaderCard[] getHealpixHeaders​(uk.ac.starlink.table.HealpixTableInfo hpxInfo)
                                                         throws uk.ac.starlink.table.TableFormatException,
                                                                nom.tam.fits.HeaderCardException

      Returns FITS headers specific for a table containing a HEALPix map. If this method is called the assumption is that the table looks like it should be a HEALPix map of some sort. If there are problems with the metadata that prevent a consistent set of headers from being generated, a TableFormatException with an informative message should be thrown.
      Parameters:
        `hpxInfo` - non-null healpix description
      Returns:
        array of FITS headers describing healpix information
      Throws:
        `uk.ac.starlink.table.TableFormatException` - if HEALPix headers could not be generated
        `nom.tam.fits.HeaderCardException`