uk.ac.starlink.votable

## Class VOTableWriter

- java.lang.Object
- - uk.ac.starlink.votable.VOTableWriter

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

      public class VOTableWriter
      extends java.lang.Object
      implements StarTableWriter, MultiStarTableWriter, DocumentedIOHandler

  Implementation of the `StarTableWriter` interface for VOTables. The `dataFormat` and `inline` attributes can be modified to affect how the bulk cell data are output - this may be in TABLEDATA, FITS, BINARY or BINARY2 format, and in the latter three cases may be either inline as base64 encoded CDATA or to a separate stream.

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

  - `Tables.NULL_VALUE_INFO`: sets the value of "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 with `datatype="unsignedByte"` instead of (signed 16-bit) `"short"`.
  - The `COOSYS_*_INFO` and `TIMESYS_*_INFO` items defined in the `VOStarTable` class; suitable COOSYS/TIMESYS elements will be written and referenced as required to honour these items.
  - Various other of the `*_INFO` items defined in the `VOStarTable` class; this has the effect that VOTable column attributes read in from a VOTable will be passed through if the same table is written out to a VOTable (or VOTable-based format like FITS-plus).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT_XML_DECLARATION` Default XML declaration in written documents.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VOTableWriter()` Constructs a default VOTableWriter.
    `VOTableWriter(DataFormat dataFormat, boolean inline)` Constructs a VOTableWriter with specified output type and default VOTable version.
    `VOTableWriter(DataFormat dataFormat, boolean inline, VOTableVersion version)` Constructs a VOTableWriter with specified output characterstics and a given version of the VOTable standard.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `docIncludesExample()` Indicates whether the serialization of some (short) example table should be added to the user documentation for this handler.
    `DataFormat` | `getDataFormat()` Returns the format in which this writer will output the bulk table data.
    `java.lang.String[]` | `getExtensions()` Returns the list of filename extensions recognised by this handler.
    `java.lang.String` | `getFormatName()` Gives the name of the format which is written by this writer.
    `boolean` | `getInline()` Indicates whether STREAM elements will be written inline or to an external file in the case of FITS and BINARY encoding.
    `java.lang.String` | `getMimeType()` Returns a string suitable for use as the value of a MIME Content-Type header.
    `static StarTableWriter[]` | `getStarTableWriters()` Returns a list of votable writers with variant values of attributes.
    `VOTableVersion` | `getVotableVersion()` Returns the version of the VOTable standard to which the output of this writer conforms.
    `boolean` | `getWriteSchemaLocation()` Indicates whether the schema location attribute will be written on opening VOTABLE tags.
    `java.lang.String` | `getXMLDeclaration()` Returns the XML declaration which is used by this writer at the head of any document written.
    `java.lang.String` | `getXmlDescription()` Returns user-directed documentation in XML format.
    `boolean` | `looksLikeFile(java.lang.String filename)` Indicates whether the destination is of a familiar form for this kind of writer.
    `void` | `setDataFormat(DataFormat format)` Sets the format in which the table data will be output.
    `void` | `setInline(boolean inline)` Sets whether STREAM elements should be written inline or to an external file in the case of FITS and BINARY encoding.
    `void` | `setVotableVersion(VOTableVersion version)` Sets the version of the VOTable standard to which the output of this writer will conform.
    `void` | `setWriteSchemaLocation(boolean writeSchemaLocation)` Determines whether the schema location attribute will be written on opening VOTABLE tags.
    `void` | `setXMLDeclaration(java.lang.String xmlDecl)` Sets the XML declaration which will be used by this writer at the head of any document written.
    `java.lang.String` | `toString()`
    `protected void` | `writeBetweenTableXML(java.io.BufferedWriter writer)` Outputs text between one table (TABLE and possibly other associated elements) and the next.
    `void` | `writeInlineStarTable(StarTable startab, java.io.BufferedWriter writer)` Writes a table directly to a stream.
    `void` | `writeInlineStarTables(StarTable[] startabs, java.io.BufferedWriter writer)` Writes multiple tables directly to a stream.
    `protected void` | `writePostTableXML(java.io.BufferedWriter writer)` Outputs all the text required after any tables in the output table document.
    `protected void` | `writePreTableXML(java.io.BufferedWriter writer)` Outputs all the text required before any tables are written.
    `void` | `writeStarTable(StarTable startab, java.io.OutputStream out)` Writes a StarTable to a given stream; must be inline.
    `void` | `writeStarTable(StarTable startab, java.io.OutputStream out, java.io.File file)` Writes a StarTable to a given stream.
    `void` | `writeStarTable(StarTable startab, java.lang.String location, StarTableOutput sto)` Writes a StarTable to a given location.
    `void` | `writeStarTables(TableSequence tableSeq, java.io.OutputStream out)` Writes a sequence of tables to a given stream; must be inline.
    `void` | `writeStarTables(TableSequence tableSeq, java.io.OutputStream out, java.io.File file)` Writes a sequence of tables to a given stream.
    `void` | `writeStarTables(TableSequence tableSeq, java.lang.String location, StarTableOutput sto)` Writes a sequence of tables to a given location.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface uk.ac.starlink.table.formats.DocumentedIOHandler

      `matchesExtension, readText, toLink`

- - ### Field Detail

    - #### DEFAULT_XML_DECLARATION

          public static final java.lang.String DEFAULT_XML_DECLARATION

      Default XML declaration in written documents.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### VOTableWriter

          public VOTableWriter()

      Constructs a default VOTableWriter. Output is in TABLEDATA format.

    - #### VOTableWriter

          public VOTableWriter(DataFormat dataFormat,
                               boolean inline)

      Constructs a VOTableWriter with specified output type and default VOTable version.
      Parameters:
        `dataFormat` - the format in which tables will be written
        `inline` - whether output of streamed formats should be inline and base64-encoded or not

    - #### VOTableWriter

          public VOTableWriter(DataFormat dataFormat,
                               boolean inline,
                               VOTableVersion version)

      Constructs a VOTableWriter with specified output characterstics and a given version of the VOTable standard.
      Parameters:
        `dataFormat` - the format in which tables will be written
        `inline` - whether output of streamed formats should be inline and base64-encoded or not
        `version` - version of the VOTable standard

  - ### Method Detail

    - #### writeStarTable

          public void writeStarTable(StarTable startab,
                                     java.lang.String location,
                                     StarTableOutput sto)
                              throws java.io.IOException

      Writes a StarTable to a given location.
      Specified by:
        `writeStarTable` in interface `StarTableWriter`
      Parameters:
        `startab` - the table to write
        `location` - the filename to which to write the table
        `sto` - object used for location resolution
      Throws:
        `TableFormatException` - if `startab` cannot be written to `location`
        `java.io.IOException` - if there is some I/O error

    - #### writeStarTables

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

      Writes a sequence of tables to a given location. They are written as separate TABLE elements in the same VOTable document.
      Specified by:
        `writeStarTables` in interface `MultiStarTableWriter`
      Parameters:
        `tableSeq` - table sequence
        `location` - the filename to which to write the table
        `sto` - object used for location resolution
      Throws:
        `java.io.IOException`

    - #### writeStarTable

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

      Writes a StarTable to a given stream; must be inline. Same as `writeStarTable(startab,out,(File)null)`.
      Specified by:
        `writeStarTable` in interface `StarTableWriter`
      Parameters:
        `startab` - the table to write
        `out` - the stream down which to write the table
      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 a sequence of tables to a given stream; must be inline. Same as `writeStarTables(tableSeq,out,null)`.
      Specified by:
        `writeStarTables` in interface `MultiStarTableWriter`
      Parameters:
        `tableSeq` - tables to write
        `out` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeStarTable

          public void writeStarTable(StarTable startab,
                                     java.io.OutputStream out,
                                     java.io.File file)
                              throws java.io.IOException

      Writes a StarTable to a given stream.
      Parameters:
        `startab` - the table to write
        `out` - the stream down which to write the table
        `file` - the filename to which `out` refers; this is used if necessary to come up with a suitable filename for related files which need to be written. May be `null`.
      Throws:
        `java.io.IOException`

    - #### writeStarTables

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

      Writes a sequence of tables to a given stream.
      Parameters:
        `tableSeq` - table sequence to write
        `out` - destination stream
        `file` - the filename to which `out` refers; this is used if necessary to come up with a suitable filename for related files which need to be written. May be `null`.
      Throws:
        `java.io.IOException`

    - #### writeInlineStarTable

          public void writeInlineStarTable(StarTable startab,
                                           java.io.BufferedWriter writer)
                                    throws java.io.IOException

      Writes a table directly to a stream.
      Parameters:
        `startab` - table to write
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeInlineStarTables

          public void writeInlineStarTables(StarTable[] startabs,
                                            java.io.BufferedWriter writer)
                                     throws java.io.IOException

      Writes multiple tables directly to a stream.
      Parameters:
        `startabs` - tables
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writePreTableXML

          protected void writePreTableXML(java.io.BufferedWriter writer)
                                   throws java.io.IOException

      Outputs all the text required before any tables are written. This method can be overridden to alter the behaviour of the writer if required.
      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`
      See Also:
        `writePostTableXML(java.io.BufferedWriter)`

    - #### writeBetweenTableXML

          protected void writeBetweenTableXML(java.io.BufferedWriter writer)
                                       throws java.io.IOException

      Outputs text between one table (TABLE and possibly other associated elements) and the next. It's only called as a separator between adjacent tables, not at the start or end of a sequence of them; hence it's not called if only a single table is being output. This method can be overridden to alter the behaviour of the writer if required.

      This method closes one RESOURCE element and opens another one.

      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writePostTableXML

          protected void writePostTableXML(java.io.BufferedWriter writer)
                                    throws java.io.IOException

      Outputs all the text required after any tables in the output table document. This method can be overridden to alter the behaviour of this writer if required.
      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`
      See Also:
        `writePreTableXML(java.io.BufferedWriter)`

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

      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:
        `filename` - 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

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

    - #### getMimeType

          public java.lang.String getMimeType()

      Description copied from interface: `StarTableWriter`
      Returns a string suitable for use as the value of a MIME Content-Type header. If no suitable MIME type is available or known, one of "`application/octet-stream`" (for binary formats) or "`text/plain`" for ASCII ones) is recommended.
      Specified by:
        `getMimeType` in interface `StarTableWriter`
      Returns:
        MIME content type

    - #### setDataFormat

          @ConfigMethod(property="format",
                        usage="TABLEDATA|BINARY|BINARY2|FITS",
                        doc="<p>Gives the serialization type (DATA element content) of output VOTables.</p>")
          public void setDataFormat(DataFormat format)

      Sets the format in which the table data will be output.
      Parameters:
        `format` - bulk data format

    - #### getDataFormat

          public DataFormat getDataFormat()

      Returns the format in which this writer will output the bulk table data.
      Returns:
        bulk data format

    - #### setInline

          @ConfigMethod(property="inline",
                        doc="If true, STREAM elements are written base64-encoded within the body of the document, and if false they are written to a new external binary file whose name is derived from that of the output VOTable document. This is only applicable to BINARY, BINARY2 and FITS formats where output is not to a stream.")
          public void setInline(boolean inline)

      Sets whether STREAM elements should be written inline or to an external file in the case of FITS and BINARY encoding.
      Parameters:
        `inline` - `true` iff streamed data will be encoded inline in the STREAM element

    - #### getInline

          public boolean getInline()

      Indicates whether STREAM elements will be written inline or to an external file in the case of FITS and BINARY encoding.
      Returns:
        `true` iff streamed data will be encoded inline in the STREAM element

    - #### setXMLDeclaration

          public void setXMLDeclaration(java.lang.String xmlDecl)

      Sets the XML declaration which will be used by this writer at the head of any document written. By default this is the value of `DEFAULT_XML_DECLARATION`.
      Parameters:
        `xmlDecl` - new XML declaration

    - #### getXMLDeclaration

          public java.lang.String getXMLDeclaration()

      Returns the XML declaration which is used by this writer at the head of any document written.
      Returns:
        XML declaration

    - #### setVotableVersion

          @ConfigMethod(property="version",
                        usage="V10|V11|V12|V13|V14",
                        example="V14",
                        doc="<p>Gives the version of the VOTable format which will be used when writing the VOTable.\n\"<code>V10</code>\" is version 1.0 etc.</p>")
          public void setVotableVersion(VOTableVersion version)

      Sets the version of the VOTable standard to which the output of this writer will conform.
      Parameters:
        `version` - new version

    - #### getVotableVersion

          public VOTableVersion getVotableVersion()

      Returns the version of the VOTable standard to which the output of this writer conforms.
      Returns:
        version

    - #### setWriteSchemaLocation

          public void setWriteSchemaLocation(boolean writeSchemaLocation)

      Determines whether the schema location attribute will be written on opening VOTABLE tags.
      Parameters:
        `writeSchemaLocation` - whether to write xsi:schemaLocation atts

    - #### getWriteSchemaLocation

          public boolean getWriteSchemaLocation()

      Indicates whether the schema location attribute will be written on opening VOTABLE tags.
      Returns:
        whether xsi:schemaLocation attributes will be written

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getStarTableWriters

          public static StarTableWriter[] getStarTableWriters()

      Returns a list of votable writers with variant values of attributes.
      Returns:
        non-standard VOTableWriters.