Class VOTableWriter

java.lang.Object
uk.ac.starlink.votable.VOTableWriter
All Implemented Interfaces:
uk.ac.starlink.table.Documented, uk.ac.starlink.table.formats.DocumentedIOHandler, uk.ac.starlink.table.MultiStarTableWriter, uk.ac.starlink.table.StarTableWriter

public class VOTableWriter extends Object implements uk.ac.starlink.table.StarTableWriter, uk.ac.starlink.table.MultiStarTableWriter, uk.ac.starlink.table.formats.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).
Author:
Mark Taylor (Starlink)
  • Field Details

    • DEFAULT_XML_DECLARATION

      public static final String DEFAULT_XML_DECLARATION
      Default XML declaration in written documents.
      See Also:
  • Constructor Details

    • 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 Details

    • writeStarTable

      public void writeStarTable(uk.ac.starlink.table.StarTable startab, String location, uk.ac.starlink.table.StarTableOutput sto) throws IOException
      Writes a StarTable to a given location.
      Specified by:
      writeStarTable in interface uk.ac.starlink.table.StarTableWriter
      Parameters:
      startab - the table to write
      location - the filename to which to write the table
      sto - object used for location resolution
      Throws:
      IOException
    • writeStarTables

      public void writeStarTables(uk.ac.starlink.table.TableSequence tableSeq, String location, uk.ac.starlink.table.StarTableOutput sto) throws 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 uk.ac.starlink.table.MultiStarTableWriter
      Parameters:
      tableSeq - table sequence
      location - the filename to which to write the table
      sto - object used for location resolution
      Throws:
      IOException
    • writeStarTable

      public void writeStarTable(uk.ac.starlink.table.StarTable startab, OutputStream out) throws IOException
      Writes a StarTable to a given stream; must be inline. Same as writeStarTable(startab,out,(File)null).
      Specified by:
      writeStarTable in interface uk.ac.starlink.table.StarTableWriter
      Parameters:
      startab - the table to write
      out - the stream down which to write the table
      Throws:
      IOException
    • writeStarTables

      public void writeStarTables(uk.ac.starlink.table.TableSequence tableSeq, OutputStream out) throws IOException
      Writes a sequence of tables to a given stream; must be inline. Same as writeStarTables(tableSeq,out,null).
      Specified by:
      writeStarTables in interface uk.ac.starlink.table.MultiStarTableWriter
      Parameters:
      tableSeq - tables to write
      out - destination stream
      Throws:
      IOException
    • writeStarTable

      public void writeStarTable(uk.ac.starlink.table.StarTable startab, OutputStream out, File file) throws 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:
      IOException
    • writeStarTables

      public void writeStarTables(uk.ac.starlink.table.TableSequence tableSeq, OutputStream out, File file) throws 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:
      IOException
    • writeInlineStarTable

      public void writeInlineStarTable(uk.ac.starlink.table.StarTable startab, BufferedWriter writer) throws IOException
      Writes a table directly to a stream.
      Parameters:
      startab - table to write
      writer - destination stream
      Throws:
      IOException
    • writeInlineStarTables

      public void writeInlineStarTables(uk.ac.starlink.table.StarTable[] startabs, BufferedWriter writer) throws IOException
      Writes multiple tables directly to a stream.
      Parameters:
      startabs - tables
      writer - destination stream
      Throws:
      IOException
    • writePreTableXML

      protected void writePreTableXML(BufferedWriter writer) throws 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:
      IOException
      See Also:
    • writeBetweenTableXML

      protected void writeBetweenTableXML(BufferedWriter writer) throws 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:
      IOException
    • writePostTableXML

      protected void writePostTableXML(BufferedWriter writer) throws 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:
      IOException
      See Also:
    • getExtensions

      public String[] getExtensions()
      Specified by:
      getExtensions in interface uk.ac.starlink.table.formats.DocumentedIOHandler
    • looksLikeFile

      public boolean looksLikeFile(String filename)
      Specified by:
      looksLikeFile in interface uk.ac.starlink.table.StarTableWriter
    • docIncludesExample

      public boolean docIncludesExample()
      Specified by:
      docIncludesExample in interface uk.ac.starlink.table.formats.DocumentedIOHandler
    • getXmlDescription

      public String getXmlDescription()
      Specified by:
      getXmlDescription in interface uk.ac.starlink.table.Documented
    • getFormatName

      public String getFormatName()
      Specified by:
      getFormatName in interface uk.ac.starlink.table.StarTableWriter
    • getMimeType

      public String getMimeType()
      Specified by:
      getMimeType in interface uk.ac.starlink.table.StarTableWriter
    • setDataFormat

      @ConfigMethod(property="format", usage="TABLEDATA|BINARY|BINARY2|FITS", doc="<p>Gives the serialization type (DATA element content) of output VOTables.</p>", example="BINARY2", sequence=1) 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.", sequence=3) 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(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 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|V15", example="V13", 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>", sequence=2) 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
    • setCompact

      @ConfigMethod(property="compact", example="true", doc="<p>Controls whitespace formatting for TABLEDATA output,\nignored for other formats.\nBy default a decision will be taken dependent on table width.\n</p>", sequence=4) public void setCompact(Boolean compact)
      Controls whitespace formatting for TABLEDATA output, ignored for other formats. If null (the default), a decision will be taken dependent on table width.
      Parameters:
      compact - TRUE for compact TABLEDATA output, FALSE for more whitespace, null for auto
    • isCompact

      public Boolean isCompact()
      Returns whitespace formatting policy for TABLEDATA output.
      Returns:
      TRUE for compact TABLEDATA output, FALSE for more whitespace, null for auto
    • setEncoding

      @ConfigMethod(property="encoding", usage="UTF-8|UTF-16|...", example="UTF-16", doc="<p>Specifies the XML encoding used in the output VOTable.\nThe default value is UTF-8.\nNote that certain optimisations are in place for UTF-8 output\nwhich means that other encodings may be significantly slower.\n</p>", sequence=5) public void setEncoding(Charset encoding)
      Sets the XML encoding used for the output VOTable. The default value is UTF-8. Note that certain optimisations are in place for UTF-8 output which means that other encodings may be significantly slower.
      Parameters:
      encoding - encoding charset
    • getEncoding

      public Charset getEncoding()
      Returns the character encoding used for XML output.
      Returns:
      encoding charset
    • setWriteDate

      @ConfigMethod(property="date", doc="<p>If true, the output file will contain a comment recording the current date; otherwise it is not included.</p>") public void setWriteDate(boolean writeDate)
      Configures whether a datestamp is written to output VOTable files.
      Parameters:
      writeDate - true to include a date in the XML comments, false to omit it
    • getWriteDate

      public boolean getWriteDate()
      Indicates whether a datestamp is written to output VOTable files.
      Returns:
      true if a date is included in the XML comments, false if not
    • 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 String toString()
      Overrides:
      toString in class Object