uk.ac.starlink.votable

## Class FitsPlusTableWriter

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

- All Implemented Interfaces:
    Documented, DocumentedIOHandler, MultiStarTableWriter, StarTableWriter

      public class FitsPlusTableWriter
      extends VOTableFitsTableWriter
      implements DocumentedIOHandler

  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, as if the DATA element contained a FITS element referencing the first extension HDU of the file. Tables stored in this format have all the rich metadata associated with VOTables, and benefit from the compactness of FITS tables, without the considerable disdvantage of being split into two files.

  The header cards in the primary HDU look like this:

           SIMPLE  =                    T / Standard FITS format
           BITPIX  =                    8 / Character data
           NAXIS   =                    1 / Text string
           NAXIS1  =                 nnnn / Number of characters
           VOTMETA =                    T / Table metadata in VOTABLE format
           EXTEND  =                    T / There are standard extensions

  the VOTMETA card in particular marking that this HDU contains VOTable metadata.
  Since:
    26 Aug 2004

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected FitsTableSerializer` | `createSerializer(StarTable table)` Provides a suitable serializer for a given table.
    `protected void` | `customisePrimaryHeader(nom.tam.fits.Header hdr)` Hook for adding custom entries to the FITS header which is written to the primary HDU.
    `boolean` | `docIncludesExample()` Indicates whether the serialization of some (short) example table should be added to the user documentation for this handler.
    `java.lang.String[]` | `getExtensions()` Returns the list of filename extensions recognised by this handler.
    `static StarTableWriter[]` | `getStarTableWriters()` Returns a list of FITS-plus table writers with variant values of attributes.
    `java.lang.String` | `getXmlDescription()` Returns user-directed documentation in XML format.
    `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.
    `boolean` | `looksLikeFile(java.lang.String location)` Indicates whether the destination is of a familiar form for this kind of writer.

    - ### Methods inherited from class uk.ac.starlink.votable.VOTableFitsTableWriter

      `isMagic, setAllowSignedByte, setVotableVersion, writeStarTables`

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

      `addMetadata, 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.formats.DocumentedIOHandler

      `matchesExtension, readText, toLink`

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

      `writeStarTable`

- - ### Constructor Detail

    - #### FitsPlusTableWriter

          public FitsPlusTableWriter()

      Default constructor.

    - #### FitsPlusTableWriter

          @Deprecated
          public FitsPlusTableWriter(java.lang.String name,
                                                 WideFits wide)

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

  - ### Method Detail

    - #### getExtensions

          public java.lang.String[] getExtensions()

      Description copied from interface: `DocumentedIOHandler`
      Returns the list of filename extensions recognised by this handler.
      Specified by:
        `getExtensions` in interface `DocumentedIOHandler`
      Returns:
        lower-cased filename extension strings, no "." characters

    - #### looksLikeFile

          public boolean looksLikeFile(java.lang.String location)

      Description copied from interface: `StarTableWriter`
      Indicates whether the destination is of a familiar form for this kind of writer. This may be used to guess what kind of format a table should be written in. Implementations should return `true` for values of `location` which look like the normal form for their output format, for instance one with the usual file extension.
      Specified by:
        `looksLikeFile` in interface `StarTableWriter`
      Parameters:
        `location` - the location name (probably filename)
      Returns:
        `true` iff it looks like a file this writer would normally write

    - #### docIncludesExample

          public boolean docIncludesExample()

      Description copied from interface: `DocumentedIOHandler`
      Indicates whether the serialization of some (short) example table should be added to the user documentation for this handler. Binary formats, or instances for which the `Documented.getXmlDescription()` method already includes some example output, should return false.
      Specified by:
        `docIncludesExample` in interface `DocumentedIOHandler`
      Returns:
        true if the user documentation would benefit from the addition of an example serialization

    - #### getXmlDescription

          public java.lang.String getXmlDescription()

      Description copied from interface: `Documented`
      Returns user-directed documentation in XML format.

      The output should be a sequence of one or more <P> elements, using XHTML-like XML. Since rendering may be done in a number of contexts however, use of the full range of XHTML elements is discouraged. Where possible, the content should stick to simple markup such as the elements P, A, UL, OL, LI, DL, DT, DD EM, STRONG, I, B, CODE, TT, PRE.

      Specified by:
        `getXmlDescription` in interface `Documented`
      Returns:
        XML description of this object

    - #### customisePrimaryHeader

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

      Description copied from class: `VOTableFitsTableWriter`
      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.
      Specified by:
        `customisePrimaryHeader` in class `VOTableFitsTableWriter`
      Parameters:
        `hdr` - header
      Throws:
        `nom.tam.fits.HeaderCardException`

    - #### isMagic

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

      Description copied from class: `VOTableFitsTableWriter`
      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 `VOTableFitsTableWriter.customisePrimaryHeader(nom.tam.fits.Header)`).
      Overrides:
        `isMagic` in class `VOTableFitsTableWriter`
      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

    - #### createSerializer

          protected 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

    - #### getStarTableWriters

          public static StarTableWriter[] getStarTableWriters()

      Returns a list of FITS-plus table writers with variant values of attributes. In fact this just returns two functionally identical instances but with different format names: one is "fits" and the other is "fits-plus".
      Returns:
        table writers