uk.ac.starlink.votable

## Class UnifiedFitsTableWriter

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

- All Implemented Interfaces:
    Documented, DocumentedIOHandler, MultiStarTableWriter, StarTableWriter
  Direct Known Subclasses:
    UnifiedFitsTableWriter.Col

      public class UnifiedFitsTableWriter
      extends FitsTableWriter
      implements DocumentedIOHandler

  FITS output handler that supports multiple different options.
  Since:
    12 Mar 2024
  See Also:
    `BeanConfig`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `UnifiedFitsTableWriter.Col` Subclass with default configuration but colfits set true.

    - ### Nested classes/interfaces inherited from class uk.ac.starlink.fits.FitsTableWriter

      `FitsTableWriter.PrimaryType, FitsTableWriter.VarArrayMode`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static FitsTableWriter.PrimaryType` | `BASIC_PRIMARY_TYPE` Primary HDU type containing a minimal primary HDU.
    `static FitsTableWriter.PrimaryType` | `NONE_PRIMARY_TYPE` Primary HDU type that does not write a primary HDU.
    `static FitsTableWriter.PrimaryType` | `VOTABLE_PRIMARY_TYPE` Primary HDU type containing full metadata for the output table in VOTable format.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UnifiedFitsTableWriter()` No-arg constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static FitsTableWriter.PrimaryType` | `createVOTablePrimaryType(VOTableVersion vers)` Returns a PrimaryType that writes a FITS-plus-style VOTable primary HDU, with a specified version of the VOTable standard.
    `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.
    `java.lang.String` | `getXmlDescription()` Returns user-directed documentation in XML format.
    `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` | `setVarArray(FitsTableWriter.VarArrayMode varArray)` Configures how variable-length array values will be stored.
    `static FitsTableWriter.PrimaryType` | `toPrimaryTypeInstance(java.lang.String txt)` Decodes a string as a PrimaryType.

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

      `createSerializer, getAllowSignedByte, getPrimaryType, getStoragePolicy, getVarArray, isColfits, setStoragePolicy, writeStarTables`

    - ### 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.formats.DocumentedIOHandler

      `matchesExtension, readText, toLink`

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

      `writeStarTable`

- - ### Field Detail

    - #### VOTABLE_PRIMARY_TYPE

          public static final FitsTableWriter.PrimaryType VOTABLE_PRIMARY_TYPE

      Primary HDU type containing full metadata for the output table in VOTable format. This corresponds to "fits-plus" format. The default version of VOTable is used.

    - #### BASIC_PRIMARY_TYPE

          public static final FitsTableWriter.PrimaryType BASIC_PRIMARY_TYPE

      Primary HDU type containing a minimal primary HDU. This corresponds to basic FITS format.

    - #### NONE_PRIMARY_TYPE

          public static final FitsTableWriter.PrimaryType NONE_PRIMARY_TYPE

      Primary HDU type that does not write a primary HDU.

  - ### Constructor Detail

    - #### UnifiedFitsTableWriter

          public UnifiedFitsTableWriter()

      No-arg 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 class: `FitsTableWriter`
      Returns true if `location` ends with something like ".fit" or ".fits" or ".fts".
      Specified by:
        `looksLikeFile` in interface `StarTableWriter`
      Overrides:
        `looksLikeFile` in class `FitsTableWriter`
      Parameters:
        `location` - filename
      Returns:
        true if it sounds like a fits file

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

    - #### setPrimaryType

          @ConfigMethod(property="primary",
                        usage="basic|votable[n.n]|none",
                        example="basic",
                        sequence=110,
                        doc="<p>Determines what is written into the Primary HDU.\nThe Primary HDU (PHDU) of a FITS file cannot contain a table;\nthe following options are available.\n<dl>\n<dt><code>basic</code></dt>\n<dd><p>A minimal PHDU is written with no interesting content\n    </p></dd><dt><code>votable[n.n]</code></dt>\n<dd><p>The PHDU contains the full table metadata as the text\n    of a VOTable document, along with headers to indicate\n    that this has been done.\n    This corresponds to the \"<strong>fits-plus</strong>\"\n    format.\n    The \"<code>[n.n]</code>\" part\n    is optional, but if included\n    (e.g. \"<code>votable1.5</code>\")\n    indicates the version of the VOTable format to use.\n    </p></dd>\n<dt><code>none</code></dt>\n<dd><p>No PHDU is written.\n    The output is therefore not a legal FITS file,\n    but it can be appended to an existing FITS file that\n    already has a PHDU and perhaps other extension HDUs.\n    </p></dd>\n</dl>\n</p>")
          public void setPrimaryType(FitsTableWriter.PrimaryType primaryType)

      Description copied from class: `FitsTableWriter`
      Sets the type of Primary HDU that will precede the extension HDU(s) corresponding to the table(s) being written.
      Overrides:
        `setPrimaryType` in class `FitsTableWriter`
      Parameters:
        `primaryType` - type of primary HDU

    - #### setColfits

          @ConfigMethod(property="col",
                        sequence=120,
                        doc="<p>If true, writes data in column-oriented format.\nIn this case, the output is a single-row table in which\neach cell is an array value holding the data\nfor an entire column.\nAll the arrays in the row have the same length,\nwhich is the row count of the table being represented.\nThis corresponds to the \"<strong>colfits</strong>\" format.\n</p>")
          public void setColfits(boolean colfits)

      Description copied from class: `FitsTableWriter`
      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.
      Overrides:
        `setColfits` in class `FitsTableWriter`
      Parameters:
        `colfits` - true for column-oriented, false for row-oriented

    - #### setVarArray

          @ConfigMethod(property="var",
                        sequence=130,
                        example="true",
                        doc="<p>Determines how variable-length array-valued columns\nwill be stored.\n<code>True</code> stores variable-length array values\nafter the main part of the table in the heap,\nwhile <code>false</code> stores all arrays as fixed-length\n(with a length equal to that of the longest array\nin the column) in the body of the table.The options <code>P</code> or <code>Q</code> can be used\nto force 32-bit or 64-bit pointers for indexing into the heap,\nbut it\'s not usually necessary since a suitable choice\nis otherwise made from the data.\n</p>")
          public void setVarArray(FitsTableWriter.VarArrayMode varArray)

      Description copied from class: `FitsTableWriter`
      Configures how variable-length array values will be stored.
      Overrides:
        `setVarArray` in class `FitsTableWriter`
      Parameters:
        `varArray` - variable-length array storage mode

    - #### createVOTablePrimaryType

          public static FitsTableWriter.PrimaryType createVOTablePrimaryType(VOTableVersion vers)

      Returns a PrimaryType that writes a FITS-plus-style VOTable primary HDU, with a specified version of the VOTable standard.
      Parameters:
        `vers` - VOTable version
      Returns:
        new PHDU type

    - #### toPrimaryTypeInstance

          public static FitsTableWriter.PrimaryType toPrimaryTypeInstance(java.lang.String txt)

      Decodes a string as a PrimaryType.

      This public static method is used by BeanConfig.

      Parameters:
        `txt` - string representation of a PrimaryType
      Returns:
        primary type instance, or null if txt doesn't look like one