Package uk.ac.starlink.votable

Class VOTableWriter

  • All Implemented Interfaces:
    uk.ac.starlink.table.MultiStarTableWriter, uk.ac.starlink.table.StarTableWriter
    public class VOTableWriter
extends java.lang.Object
implements uk.ac.starlink.table.StarTableWriter, uk.ac.starlink.table.MultiStarTableWriter
    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 Summary

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

    • Constructor Summary

      Constructors 
      Constructor 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 Description
      DataFormat getDataFormat()
      Returns the format in which this writer will output the bulk table data.
      java.lang.String getFormatName()  
      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()  
      static uk.ac.starlink.table.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.
      boolean looksLikeFile​(java.lang.String filename)
      Returns true for filenames with the extension ".xml", ".vot" or ".votable";
      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​(uk.ac.starlink.table.StarTable startab, java.io.BufferedWriter writer)
      Writes a table directly to a stream.
      void writeInlineStarTables​(uk.ac.starlink.table.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​(uk.ac.starlink.table.StarTable startab, java.io.OutputStream out)
      Writes a StarTable to a given stream; must be inline.
      void writeStarTable​(uk.ac.starlink.table.StarTable startab, java.io.OutputStream out, java.io.File file)
      Writes a StarTable to a given stream.
      void writeStarTable​(uk.ac.starlink.table.StarTable startab, java.lang.String location, uk.ac.starlink.table.StarTableOutput sto)
      Writes a StarTable to a given location.
      void writeStarTables​(uk.ac.starlink.table.TableSequence tableSeq, java.io.OutputStream out)
      Writes a sequence of tables to a given stream; must be inline.
      void writeStarTables​(uk.ac.starlink.table.TableSequence tableSeq, java.io.OutputStream out, java.io.File file)
      Writes a sequence of tables to a given stream.
      void writeStarTables​(uk.ac.starlink.table.TableSequence tableSeq, java.lang.String location, uk.ac.starlink.table.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

    • 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​(uk.ac.starlink.table.StarTable startab,
                           java.lang.String location,
                           uk.ac.starlink.table.StarTableOutput sto)
                    throws java.io.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:
        java.io.IOException

      • writeStarTables

        public void writeStarTables​(uk.ac.starlink.table.TableSequence tableSeq,
                            java.lang.String location,
                            uk.ac.starlink.table.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 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:
        java.io.IOException

      • writeStarTable

        public void writeStarTable​(uk.ac.starlink.table.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 uk.ac.starlink.table.StarTableWriter
        Parameters:
        startab - the table to write
        out - the stream down which to write the table
        Throws:
        java.io.IOException

      • writeStarTables

        public void writeStarTables​(uk.ac.starlink.table.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 uk.ac.starlink.table.MultiStarTableWriter
        Parameters:
        tableSeq - tables to write
        out - destination stream
        Throws:
        java.io.IOException

      • writeStarTable

        public void writeStarTable​(uk.ac.starlink.table.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​(uk.ac.starlink.table.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​(uk.ac.starlink.table.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​(uk.ac.starlink.table.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)

      • looksLikeFile

        public boolean looksLikeFile​(java.lang.String filename)
        Returns true for filenames with the extension ".xml", ".vot" or ".votable";
        Specified by:
        looksLikeFile in interface uk.ac.starlink.table.StarTableWriter
        Parameters:
        filename - name of the file
        Returns:
        true if filename looks like the home of a VOTable

      • getFormatName

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

      • getMimeType

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

      • setDataFormat

        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

        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

        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 uk.ac.starlink.table.StarTableWriter[] getStarTableWriters()
        Returns a list of votable writers with variant values of attributes.
        Returns:
        non-standard VOTableWriters.