uk.ac.starlink.votable

## Class VOTableFitsTableWriter

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

- All Implemented Interfaces:
    MultiStarTableWriter, StarTableWriter
  Direct Known Subclasses:
    ColFitsPlusTableWriter, FitsPlusTableWriter

      public abstract class VOTableFitsTableWriter
      extends AbstractFitsTableWriter

  TableWriter which writes table data into the first extension of a FITS file, Unlike `FitsTableWriter` however, the primary extension is not left contentless, instead it gets the text of a DATA-less VOTable written into it. This VOTable describes the metadata of the table. Tables stored using this (non-standard) mechanism have all the rich metadata associated with VOTables, and benefit from the compactness of FITS tables, withouth the considerable disadvantage of being split into two files.
  Since:
    26 Aug 2004

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract void` | `customisePrimaryHeader(nom.tam.fits.Header hdr)` Hook for adding custom entries to the FITS header which is written to the primary HDU.
    `boolean` | `isMagic(byte[] buffer)` Determines whether a given byte buffer looks like it contains the start of a primary header written by this writer.
    `protected boolean` | `isMagic(int icard, java.lang.String key, java.lang.String value)` Tests a header card to see if it looks like part of the magic number for the format written by this handler.
    `void` | `setAllowSignedByte(boolean allowSignedByte)` Configures how Byte-valued columns are written.
    `void` | `setVotableVersion(VOTableVersion votVersion)` Sets the version of the VOTable standard to use for encoding metadata in the primary HDU.
    `void` | `writeStarTables(TableSequence tableSeq, java.io.OutputStream out)` Writes tables.

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

      `addMetadata, createSerializer, getAllowSignedByte, getAllowZeroLengthString, getConfig, getCurrentDate, getFormatName, getMimeType, getPadCharacter, getWide, getWriteDate, setAllowZeroLengthString, setFormatName, setPadCharacter, 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

      `looksLikeFile, writeStarTable`

- - ### Constructor Detail

    - #### VOTableFitsTableWriter

          protected VOTableFitsTableWriter(java.lang.String formatName)

      Constructor.
      Parameters:
        `formatName` - handler format name

  - ### Method Detail

    - #### setAllowSignedByte

          public void setAllowSignedByte(boolean allowSignedByte)

      Description copied from class: `AbstractFitsTableWriter`
      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.
      Overrides:
        `setAllowSignedByte` in class `AbstractFitsTableWriter`
      Parameters:
        `allowSignedByte` - true to write offset bytes, false to write shorts

    - #### 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.DataOutput)` 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`

    - #### setVotableVersion

          public void setVotableVersion(VOTableVersion votVersion)

      Sets the version of the VOTable standard to use for encoding metadata in the primary HDU.
      Parameters:
        `votVersion` - VOTable version to use

    - #### customisePrimaryHeader

          protected abstract void customisePrimaryHeader(nom.tam.fits.Header hdr)
                                                  throws nom.tam.fits.HeaderCardException

      Hook for adding custom entries to the FITS header which is written to the primary HDU. This is called just after the required cards (SIMPLE, BITPIX, NAXIS, NAXIS1 ) are added and just before the EXTEND card.
      Parameters:
        `hdr` - header
      Throws:
        `nom.tam.fits.HeaderCardException`

    - #### isMagic

          public boolean isMagic(byte[] buffer)

      Determines whether a given byte buffer looks like it contains the start of a primary header written by this writer. Calls the protected `isMagic(int,java.lang.String,java.lang.String)` method.
      Parameters:
        `buffer` - start of a file
      Returns:
        true iff `buffer` looks like it contains a file written by this handler

    - #### isMagic

          protected boolean isMagic(int icard,
                                    java.lang.String key,
                                    java.lang.String value)

      Tests a header card to see if it looks like part of the magic number for the format written by this handler. The `VOTableFitsTableWriter` implementation tests that the first four cards read:

              SIMPLE = T
              BITPIX = 8
              NAXIS  = 1
              NAXIS1 = ???

      Subclasses may override this to add tests for later cards (as written in `customisePrimaryHeader(nom.tam.fits.Header)`).
      Parameters:
        `icard` - 0-based card index
        `key` - card name
        `value` - card value
      Returns:
        true iff the presented card is one that could have been written by this writer