uk.ac.starlink.fits

## Class AbstractFitsTableWriter

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

- All Implemented Interfaces:
    MultiStarTableWriter, StarTableWriter
  Direct Known Subclasses:
    ColFitsTableWriter, FitsTableWriter, HduFitsTableWriter, HealpixFitsTableWriter, VariableFitsTableWriter, VOTableFitsTableWriter

      public abstract class AbstractFitsTableWriter
      extends StreamStarTableWriter
      implements MultiStarTableWriter

  Abstract table writer superclass designed for writing FITS tables.

  A couple of Auxiliary metadata items of the ColumnInfo metadata from written tables are respected:

  - `Tables.NULL_VALUE_INFO`: sets the value of `TNULLn` "magic" blank value for integer columns
  - `Tables.UBYTE_FLAG_INFO`: if set to `Boolean.TRUE` and if the column has content class `Short` or `short[]`, the data will be written as unsigned bytes (`TFORMn='B'`) not 16-bit signed integers (`TFORMn='I'`).
  - `BintableStarTable.LONGOFF_INFO`: if this is set to a string representation of an integer value, and the column has content class String or String[], then the data will be written as long integers (`TFORMn='K'`) with the given offset (`TZEROn=...`). This option supports round-tripping of offset long values (typically representing unsigned longs) which are converted to strings on read.
  Since:
    27 Jun 2006

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractFitsTableWriter(java.lang.String formatName)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract FitsTableSerializer` | `createSerializer(StarTable table)` Provides a suitable serializer for a given table.
    `boolean` | `getAllowSignedByte()` Returns a flag indicating how Byte-valued columns are written.
    `boolean` | `getAllowZeroLengthString()` Indicates whether zero-length string columns may be output.
    `FitsTableSerializerConfig` | `getConfig()` Returns the configuration details for writing FITS files.
    `static java.lang.String` | `getCurrentDate()` Returns an ISO-8601 data string representing the time at which this method is called.
    `java.lang.String` | `getFormatName()` Gives the name of the format which is written by this writer.
    `protected java.util.List<CardImage>` | `getMetadataCards()` Adds some standard metadata header cards to a FITS table header.
    `java.lang.String` | `getMimeType()` Returns "application/fits".
    `byte` | `getPadCharacter()` Returns the byte value with which under-length string (character array) values will be padded.
    `StringEncoder` | `getUnicodeHandler()` Returns policy for how to write character data containing non-ASCII content.
    `WideFits` | `getWide()` Indicates the convention in use for representing over-wide tables.
    `boolean` | `getWriteDate()` Indicates whether a datestamp is written to output FITS files.
    `void` | `setAllowSignedByte(boolean allowSignedByte)` Configures how Byte-valued columns are written.
    `void` | `setAllowZeroLengthString(boolean allowZeroLengthString)` Sets whether zero-length string columns may be written.
    `void` | `setFormatName(java.lang.String formatName)` Sets the declared format name.
    `void` | `setPadCharacter(byte padChar)` Sets the byte value with which under-length string (character array) values should be padded.
    `void` | `setUnicodeHandler(StringEncoder unicodeHandler)` Sets policy for how to write character columns that contain characters outside of the restricted set of ASCII-text characters permitted in FITS character data (0x20-0x7E), as defined in Appendix D of the FITS 4.0 standard.
    `void` | `setWide(WideFits wide)` Sets the convention for representing over-wide (>999 column) tables.
    `void` | `setWriteDate(boolean writeDate)` Configures whether a datestamp is written to output FITS files.
    `void` | `writePrimaryHDU(java.io.OutputStream out)` Writes the primary HDU.
    `void` | `writeStarTable(StarTable table, java.io.OutputStream out)` Writes a single table.
    `void` | `writeStarTables(TableSequence tableSeq, java.io.OutputStream out)` Writes tables.
    `void` | `writeStarTables(TableSequence tableSeq, java.lang.String location, StarTableOutput sto)` Invokes `writeStarTables(uk.ac.starlink.table.TableSequence, java.io.OutputStream)`.
    `void` | `writeTableHDU(StarTable table, FitsTableSerializer fitser, java.io.OutputStream out)` Writes a data HDU.

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

      `looksLikeFile, writeStarTable`

- - ### Constructor Detail

    - #### AbstractFitsTableWriter

          protected AbstractFitsTableWriter(java.lang.String formatName)

      Constructor.
      Parameters:
        `formatName` - format name

  - ### Method Detail

    - #### getFormatName

          public java.lang.String getFormatName()

      Description copied from interface: `StarTableWriter`
      Gives the name of the format which is written by this writer. Matching against this string may be used by callers to identify or select this writer from a list.
      Specified by:
        `getFormatName` in interface `StarTableWriter`
      Returns:
        a short string identifying the output format of this writer

    - #### setFormatName

          public void setFormatName(java.lang.String formatName)

      Sets the declared format name.
      Parameters:
        `formatName` - format name

    - #### getMimeType

          public java.lang.String getMimeType()

      Returns "application/fits".
      Specified by:
        `getMimeType` in interface `StarTableWriter`
      Returns:
        MIME type

    - #### writeStarTable

          public void writeStarTable(StarTable table,
                                     java.io.OutputStream out)
                              throws java.io.IOException

      Writes a single table. Invokes `writeStarTables(uk.ac.starlink.table.TableSequence, java.io.OutputStream)`.
      Specified by:
        `writeStarTable` in interface `StarTableWriter`
      Parameters:
        `table` - the table to write
        `out` - the output stream to which `startab` should be written
      Throws:
        `TableFormatException` - if this table cannot be written to a stream
        `java.io.IOException` - if there is some I/O error

    - #### writeStarTables

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

      Writes tables. Calls `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`
      Parameters:
        `tableSeq` - sequence of tables to write
        `out` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeStarTables

          public void writeStarTables(TableSequence tableSeq,
                                      java.lang.String location,
                                      StarTableOutput sto)
                               throws java.io.IOException

      Invokes `writeStarTables(uk.ac.starlink.table.TableSequence, java.io.OutputStream)`.
      Specified by:
        `writeStarTables` in interface `MultiStarTableWriter`
      Parameters:
        `tableSeq` - sequence of tables to write
        `location` - destination for tables
        `sto` - StarTableOutput instance
      Throws:
        `java.io.IOException`

    - #### writePrimaryHDU

          public void writePrimaryHDU(java.io.OutputStream out)
                               throws java.io.IOException

      Writes the primary HDU. This cannot contain a table since BINTABLE HDUs can only be extensions. The AbstractFitsTableWriter implementation writes a minimal, data-less HDU.
      Parameters:
        `out` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeTableHDU

          public void writeTableHDU(StarTable table,
                                    FitsTableSerializer fitser,
                                    java.io.OutputStream out)
                             throws java.io.IOException

      Writes a data HDU.
      Parameters:
        `table` - the table to be written into the HDU
        `fitser` - fits serializer initalised from `table`
        `out` - destination stream
      Throws:
        `java.io.IOException`

    - #### getConfig

          public FitsTableSerializerConfig getConfig()

      Returns the configuration details for writing FITS files. Its content can be controlled using single-config-item mutator methods (which may also be labelled as `ConfigMethod`s) on this class. This covers things that are generally orthogonal to the type of serialization, so may be set for any kind of FITS output, which is why it makes sense to manage them in the `AbstractFitsTableWriter` abstract superclass.
      Returns:
        object representing the FITS serialization options currently configured for this writer

    - #### createSerializer

          protected abstract FitsTableSerializer createSerializer(StarTable table)
                                                           throws java.io.IOException

      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.
      Parameters:
        `table` - table to serialize
      Returns:
        FITS serializer
      Throws:
        `java.io.IOException` - if the table can't be written

    - #### getMetadataCards

          protected java.util.List<CardImage> getMetadataCards()

      Adds some standard metadata header cards to a FITS table header. This includes date stamp, STIL version, etc.
      Returns:
        list of cards giving write-specific metadata

    - #### setWriteDate

          @ConfigMethod(property="date",
                        doc="<p>If true, the DATE-HDU header is filled in with the current date; otherwise it is not included.</p>")
          public void setWriteDate(boolean writeDate)

      Configures whether a datestamp is written to output FITS files.
      Parameters:
        `writeDate` - true to include DATE-HDU, false to omit it

    - #### getWriteDate

          public boolean getWriteDate()

      Indicates whether a datestamp is written to output FITS files.
      Returns:
        true to include DATE-HDU, false to omit it

    - #### setAllowSignedByte

          public void setAllowSignedByte(boolean allowSignedByte)

      Configures how Byte-valued columns are written. This is a bit fiddly, since java bytes are signed, but FITS 8-bit integers are unsigned. If true, they are written as FITS unsigned 8-bit integers with an offset, as discussed in the FITS standard (`TFORMn='B'`, `TZERO=-128`). If false, they are written as FITS signed 16-bit integers.
      Parameters:
        `allowSignedByte` - true to write offset bytes, false to write shorts

    - #### getAllowSignedByte

          public boolean getAllowSignedByte()

      Returns a flag indicating how Byte-valued columns are written.
      Returns:
        true to write offset bytes, false to write shorts

    - #### setAllowZeroLengthString

          public void setAllowZeroLengthString(boolean allowZeroLengthString)

      Sets whether zero-length string columns may be written. Such columns (`TFORMn='0A'`) are explicitly permitted by the FITS standard, but they can cause crashes because of divide-by-zero errors when encountered by some versions of CFITSIO (v3.50 and earlier), so FITS writing code may wish to avoid them. If this is set false, then A repeat values will always be >=1.
      Parameters:
        `allowZeroLengthString` - false to prevent zero-length string columns

    - #### getAllowZeroLengthString

          public boolean getAllowZeroLengthString()

      Indicates whether zero-length string columns may be output.
      Returns:
        false if zero-length string columns are avoided

    - #### setWide

          public void setWide(WideFits wide)

      Sets the convention for representing over-wide (>999 column) tables.
      Parameters:
        `wide` - wide-table representation policy, null to avoid wide tables

    - #### getWide

          public WideFits getWide()

      Indicates the convention in use for representing over-wide tables.
      Returns:
        wide-table representation policy, null for no wide tables

    - #### setPadCharacter

          public void setPadCharacter(byte padChar)

      Sets the byte value with which under-length string (character array) values should be padded. This should normally be one of 0x00 (ASCII NUL) or 0x20 (space). The function of an ASCII NUL is to terminate the string early, as described in Section 7.3.3.1 of the FITS 4.0 standard; space characters pad it to its declared length with whitespace. Other values in the range 0x21-0x7E are permitted but probably not sensible.
      Parameters:
        `padChar` - character data padding byte

    - #### getPadCharacter

          public byte getPadCharacter()

      Returns the byte value with which under-length string (character array) values will be padded. This will normally be one of 0x00 (ASCII NUL) or 0x20 (space).
      Returns:
        character data padding byte

    - #### setUnicodeHandler

          public void setUnicodeHandler(StringEncoder unicodeHandler)

      Sets policy for how to write character columns that contain characters outside of the restricted set of ASCII-text characters permitted in FITS character data (0x20-0x7E), as defined in Appendix D of the FITS 4.0 standard.
      Parameters:
        `unicodeHandler` - policy for writing non-ASCII character data

    - #### getUnicodeHandler

          public StringEncoder getUnicodeHandler()

      Returns policy for how to write character data containing non-ASCII content.
      Returns:
        policy for writing non-ASCII character data

    - #### getCurrentDate

          public static java.lang.String getCurrentDate()

      Returns an ISO-8601 data string representing the time at which this method is called.
      Returns:
        date string