uk.ac.starlink.fits

## Class FitsTableWriter

- java.lang.Object
- - uk.ac.starlink.table.StreamStarTableWriter
  - - uk.ac.starlink.fits.AbstractFitsTableWriter
    - - uk.ac.starlink.fits.FitsTableWriter

- All Implemented Interfaces:
    MultiStarTableWriter, StarTableWriter
  Direct Known Subclasses:
    UnifiedFitsTableWriter

      public class FitsTableWriter
      extends AbstractFitsTableWriter

  Handles writing of a StarTable in FITS binary format. Not all columns can be written to a FITS table, only those ones whose `contentClass` is in the following list:
  - Boolean
  - Character
  - Byte
  - Short
  - Integer
  - Long
  - Float
  - Double
  - Character
  - String
  - boolean[]
  - char[]
  - byte[]
  - short[]
  - int[]
  - long[]
  - float[]
  - double[]
  - String[]
  In all other cases a warning message will be logged and the column will be ignored for writing purposes.

  Output is currently to fixed-width columns only. For StarTable columns of variable size, a first pass is made through the table data to determine the largest size they assume, and the size in the output table is set to the largest of these. Excess space is padded with some sort of blank value (NaN for floating point values, spaces for strings, zero-like values otherwise).

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `FitsTableWriter.PrimaryType` Characterises the type of Primary HDU that will precede table extensions written by this writer.
    `static class` | `FitsTableWriter.VarArrayMode` Enumeration for variable-length array value storage options.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FitsTableWriter()` Default constructor.
    `FitsTableWriter(java.lang.String name, boolean allowSignedByte, WideFits wide)` Deprecated. allows some configuration options but not others; use no-arg constructor and configuration methods instead

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `FitsTableSerializer` | `createSerializer(StarTable table)` Provides a suitable serializer for a given table.
    `boolean` | `getAllowSignedByte()` Returns a flag indicating how Byte-valued columns are written.
    `FitsTableWriter.PrimaryType` | `getPrimaryType()` Returns the type of Primary HDU that will precede the extension HDU(s) corresponding to the table(s) being written.
    `StoragePolicy` | `getStoragePolicy()` Returns the storage policy that will be used if required.
    `FitsTableWriter.VarArrayMode` | `getVarArray()` Indicates how variable-length array valued columns will be stored.
    `boolean` | `isColfits()` Returns whether table data will be written in column-oriented form.
    `boolean` | `looksLikeFile(java.lang.String location)` Returns true if `location` ends with something like ".fit" or ".fits" or ".fts".
    `void` | `setColfits(boolean colfits)` Sets whether table data should be written in column-oriented form.
    `void` | `setPrimaryType(FitsTableWriter.PrimaryType primaryType)` Sets the type of Primary HDU that will precede the extension HDU(s) corresponding to the table(s) being written.
    `void` | `setStoragePolicy(StoragePolicy storage)` Sets the storage policy to use where required.
    `void` | `setVarArray(FitsTableWriter.VarArrayMode varArray)` Configures how variable-length array values will be stored.
    `void` | `writeStarTables(TableSequence tableSeq, java.io.OutputStream out)` Writes tables.

    - ### Methods inherited from class uk.ac.starlink.fits.AbstractFitsTableWriter

      `getAllowZeroLengthString, getConfig, getCurrentDate, getFormatName, getMetadataCards, getMimeType, getPadCharacter, getUnicodeHandler, getWide, getWriteDate, setAllowSignedByte, setAllowZeroLengthString, setFormatName, setPadCharacter, setUnicodeHandler, setWide, setWriteDate, writePrimaryHDU, writeStarTable, writeStarTables, writeTableHDU`

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

      `writeStarTable, writeStarTable`

    - ### 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.StarTableWriter

      `writeStarTable`

- - ### Constructor Detail

    - #### FitsTableWriter

          public FitsTableWriter()

      Default constructor.

    - #### FitsTableWriter

          @Deprecated
          public FitsTableWriter(java.lang.String name,
                                             boolean allowSignedByte,
                                             WideFits wide)

      Deprecated. allows some configuration options but not others; use no-arg constructor and configuration methods instead
      Deprecated custom constructor.

  - ### Method Detail

    - #### looksLikeFile

          public boolean looksLikeFile(java.lang.String location)

      Returns true if `location` ends with something like ".fit" or ".fits" or ".fts".
      Parameters:
        `location` - filename
      Returns:
        true if it sounds like a fits file

    - #### setPrimaryType

          public void setPrimaryType(FitsTableWriter.PrimaryType primaryType)

      Sets the type of Primary HDU that will precede the extension HDU(s) corresponding to the table(s) being written.
      Parameters:
        `primaryType` - type of primary HDU

    - #### getPrimaryType

          public FitsTableWriter.PrimaryType getPrimaryType()

      Returns the type of Primary HDU that will precede the extension HDU(s) corresponding to the table(s) being written.
      Returns:
        type of primary HDU

    - #### setColfits

          public void setColfits(boolean colfits)

      Sets whether table data should be written in column-oriented form. If true, the output will be a single-row table of array-valued columns, in which each cell is an array with `nrow` elements.
      Parameters:
        `colfits` - true for column-oriented, false for row-oriented

    - #### isColfits

          public boolean isColfits()

      Returns whether table data will be written in column-oriented form.
      Returns:
        true for column-oriented, false for row-oriented

    - #### setVarArray

          public void setVarArray(FitsTableWriter.VarArrayMode varArray)

      Configures how variable-length array values will be stored.
      Parameters:
        `varArray` - variable-length array storage mode

    - #### getVarArray

          public FitsTableWriter.VarArrayMode getVarArray()

      Indicates how variable-length array valued columns will be stored.
      Returns:
        variable-length array storage mode

    - #### setStoragePolicy

          public void setStoragePolicy(StoragePolicy storage)

      Sets the storage policy to use where required. This is only relevant for column-oriented output, for which data has to be cached before rewriting it.
      Parameters:
        `storage` - storage policy to use when writing colfits

    - #### getStoragePolicy

          public StoragePolicy getStoragePolicy()

      Returns the storage policy that will be used if required.
      Returns:
        storage policy used when writing colfits

    - #### getAllowSignedByte

          public boolean getAllowSignedByte()

      Description copied from class: `AbstractFitsTableWriter`
      Returns a flag indicating how Byte-valued columns are written.
      Overrides:
        `getAllowSignedByte` in class `AbstractFitsTableWriter`
      Returns:
        true to write offset bytes, false to write shorts

    - #### createSerializer

          public FitsTableSerializer createSerializer(StarTable table)
                                               throws java.io.IOException

      Description copied from class: `AbstractFitsTableWriter`
      Provides a suitable serializer for a given table. Note this should throw an IOException if it can be determined that the submitted table cannot be written by this writer, for instance if it has too many columns.
      Specified by:
        `createSerializer` in class `AbstractFitsTableWriter`
      Parameters:
        `table` - table to serialize
      Returns:
        FITS serializer
      Throws:
        `java.io.IOException` - if the table can't be written

    - #### writeStarTables

          public void writeStarTables(TableSequence tableSeq,
                                      java.io.OutputStream out)
                               throws java.io.IOException

      Description copied from class: `AbstractFitsTableWriter`
      Writes tables. Calls `AbstractFitsTableWriter.writePrimaryHDU(java.io.OutputStream)` to write the primary HDU. Subclasses which want to put something related to the input tables into the primary HDU will need to override this method (writeStarTables).
      Specified by:
        `writeStarTables` in interface `MultiStarTableWriter`
      Overrides:
        `writeStarTables` in class `AbstractFitsTableWriter`
      Parameters:
        `tableSeq` - sequence of tables to write
        `out` - destination stream
      Throws:
        `java.io.IOException`