uk.ac.starlink.votable

## Class VOSerializer

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

-     public abstract class VOSerializer
      extends java.lang.Object

  Class which knows how to serialize a table's fields and data to VOTable elements. For writing a full VOTable document which contains a single table the `VOTableWriter` class may be more convenient, but this class can be used in a more flexible way, by writing only the elements which are required.

  Obtain an instance of this class using the `makeSerializer` method.

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static char` | `ensureLegalXml(char c)` Returns a legal XML character corresponding to an input character.
    `static java.lang.String` | `formatAttribute(java.lang.String name, java.lang.String value)` Turns a name,value pair into an attribute assignment suitable for putting in an XML start tag.
    `static java.lang.String` | `formatText(java.lang.String text)` Performs necessary special character escaping for text which will be written as XML CDATA.
    `DataFormat` | `getFormat()` Returns the data format which this object can serialize to.
    `long` | `getRowCount()` Returns the number of rows that this serializer will write, if known.
    `RowSequence` | `getRowSequence()` Returns the row sequence that this serializer will write.
    `StarTable` | `getTable()` Returns the table object which this object can serialize.
    `VOTableVersion` | `getVersion()` Returns the version of the VOTable standard for which this serializer will write.
    `boolean` | `isCompact()` Indicates compactness of whitespace formatting for TABLEDATA format; no effect for other DataFormats.
    `static VOSerializer` | `makeFitsSerializer(StarTable table, FitsTableSerializer fitser, VOTableVersion version)` Constructs a FITS-type VOSerializer.
    `static VOSerializer` | `makeSerializer(DataFormat dataFormat, StarTable table)` Deprecated. use instead `makeSerializer(VOSerializerConfig, uk.ac.starlink.table.StarTable)`
    `static VOSerializer` | `makeSerializer(DataFormat dataFormat, VOTableVersion version, StarTable table)` Deprecated. use instead `makeSerializer(VOSerializerConfig, uk.ac.starlink.table.StarTable)`
    `static VOSerializer` | `makeSerializer(VOSerializerConfig config, StarTable table)` Returns a serializer capable of serializing a given table in accordance with a supplied configuration object.
    `void` | `setCompact(boolean isCompact)` Controls whitespace formatting for TABLEDATA format; no effect for other DataFormats.
    `void` | `writeDescription(java.io.BufferedWriter writer)` Writes any DESCRIPTION element associated with this serializer's table.
    `abstract void` | `writeFields(java.io.BufferedWriter writer)` Writes the FIELD headers corresponding to this table on a given writer.
    `abstract void` | `writeHrefDataElement(java.io.BufferedWriter xmlwriter, java.lang.String href, java.io.OutputStream streamout)` Writes this serializer's table data to a <DATA> element containing a <STREAM> element which references an external data source (optional method).
    `void` | `writeHrefTableElement(java.io.BufferedWriter xmlwriter, java.lang.String href, java.io.OutputStream streamout)`
    `abstract void` | `writeInlineDataElement(java.io.BufferedWriter writer)` Writes this serializer's table data as a self-contained <DATA> element.
    `abstract void` | `writeInlineDataElementUTF8(java.io.OutputStream out)` Writes this serializer's table data as a self-contained <DATA> element to an output stream using UTF8 encoding.
    `void` | `writeInlineTableElement(java.io.BufferedWriter writer)` Writes this serializer's table as a complete TABLE element.
    `void` | `writeInlineTableElementUTF8(java.io.OutputStream out)` Writes this serializer's table as a complete TABLE element to an output stream using UTF8 encoding.
    `void` | `writeParams(java.io.BufferedWriter writer)` Writes any PARAM and INFO elements associated with this serializer's table.
    `void` | `writePostDataXML(java.io.BufferedWriter writer)` Outputs any content of the TABLE element following the DATA element and the TABLE end tag.
    `void` | `writePreDataXML(java.io.BufferedWriter writer)` Outputs the TABLE element start tag and all of its content before the DATA element.
    `void` | `writeServiceDescriptors(java.io.BufferedWriter writer)` Writes the service descriptor parameters of this serializer's table as a sequence of zero or more RESOURCE elements.

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

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

- - ### Method Detail

    - #### getFormat

          public DataFormat getFormat()

      Returns the data format which this object can serialize to.
      Returns:
        output format

    - #### getTable

          public StarTable getTable()

      Returns the table object which this object can serialize.
      Returns:
        table to write

    - #### getVersion

          public VOTableVersion getVersion()

      Returns the version of the VOTable standard for which this serializer will write.
      Returns:
        VOTable version

    - #### setCompact

          public void setCompact(boolean isCompact)

      Controls whitespace formatting for TABLEDATA format; no effect for other DataFormats.
      Parameters:
        `isCompact` - if true, add whitespace round TR/TD elements

    - #### isCompact

          public boolean isCompact()

      Indicates compactness of whitespace formatting for TABLEDATA format; no effect for other DataFormats.
      Returns:
        if true, add whitespace round TR/TD elements

    - #### writeFields

          public abstract void writeFields(java.io.BufferedWriter writer)
                                    throws java.io.IOException

      Writes the FIELD headers corresponding to this table on a given writer.
      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeInlineDataElement

          public abstract void writeInlineDataElement(java.io.BufferedWriter writer)
                                               throws java.io.IOException

      Writes this serializer's table data as a self-contained <DATA> element. If this serializer's format is binary (non-XML) the bytes will get written base64-encoded into a STREAM element.
      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeInlineDataElementUTF8

          public abstract void writeInlineDataElementUTF8(java.io.OutputStream out)
                                                   throws java.io.IOException

      Writes this serializer's table data as a self-contained <DATA> element to an output stream using UTF8 encoding. This may be substantially faster than the otherwise equivalent `writeInlineDataElement(java.io.BufferedWriter)` method.
      Parameters:
        `out` - output stream
      Throws:
        `java.io.IOException`

    - #### writeHrefDataElement

          public abstract void writeHrefDataElement(java.io.BufferedWriter xmlwriter,
                                                    java.lang.String href,
                                                    java.io.OutputStream streamout)
                                             throws java.io.IOException

      Writes this serializer's table data to a <DATA> element containing a <STREAM> element which references an external data source (optional method). The binary data itself will be written to an output stream supplied separately (it will not be inline). If this serializer's format is not binary (i.e. if it's TABLEDATA) an `UnsupportedOperationException` will be thrown.
      Parameters:
        `xmlwriter` - destination stream for the XML output
        `href` - URL for the external stream (output as the `href` attribute of the written <STREAM> element)
        `streamout` - destination stream for the binary table data
      Throws:
        `java.io.IOException`

    - #### writeInlineTableElement

          public void writeInlineTableElement(java.io.BufferedWriter writer)
                                       throws java.io.IOException

      Writes this serializer's table as a complete TABLE element. If this serializer's format is binary (non-XML) the bytes will get written base64-encoded into a STREAM element.
      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeInlineTableElementUTF8

          public void writeInlineTableElementUTF8(java.io.OutputStream out)
                                           throws java.io.IOException

      Writes this serializer's table as a complete TABLE element to an output stream using UTF8 encoding. If this serializer's format is binary (non-XML) the bytes will get written base64-encoded into a STREAM element.

      This may be substantially faster than the otherwise equivalent `writeInlineTableElement(java.io.BufferedWriter)` method.

      Parameters:
        `out` - output stream
      Throws:
        `java.io.IOException`

    - #### writeHrefTableElement

          public void writeHrefTableElement(java.io.BufferedWriter xmlwriter,
                                            java.lang.String href,
                                            java.io.OutputStream streamout)
                                     throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### writeParams

          public void writeParams(java.io.BufferedWriter writer)
                           throws java.io.IOException

      Writes any PARAM and INFO elements associated with this serializer's table. These should generally go in the TABLE element.
      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeDescription

          public void writeDescription(java.io.BufferedWriter writer)
                                throws java.io.IOException

      Writes any DESCRIPTION element associated with this serializer's table. This should generally go just inside the TABLE element itself. If there's no suitable description text, nothing will be written.
      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writeServiceDescriptors

          public void writeServiceDescriptors(java.io.BufferedWriter writer)
                                       throws java.io.IOException

      Writes the service descriptor parameters of this serializer's table as a sequence of zero or more RESOURCE elements. Each has attributes type="meta" and utype="adhoc:service".
      Parameters:
        `writer` - destination stream
      Throws:
        `java.io.IOException`

    - #### writePreDataXML

          public void writePreDataXML(java.io.BufferedWriter writer)
                               throws java.io.IOException

      Outputs the TABLE element start tag and all of its content before the DATA element. Other items legal where a TABLE can appear may be prepended if required.
      Parameters:
        `writer` - output stream
      Throws:
        `java.io.IOException`

    - #### writePostDataXML

          public void writePostDataXML(java.io.BufferedWriter writer)
                                throws java.io.IOException

      Outputs any content of the TABLE element following the DATA element and the TABLE end tag.
      Parameters:
        `writer` - output stream
      Throws:
        `java.io.IOException`

    - #### getRowCount

          public long getRowCount()

      Returns the number of rows that this serializer will write, if known. The default implementation returns `getTable().getRowCount()`, but this may be overridden if that value is known to be unreliable.
      Returns:
        number of rows iterated over by getRowSequence, or -1 if not known

    - #### getRowSequence

          public RowSequence getRowSequence()
                                     throws java.io.IOException

      Returns the row sequence that this serializer will write.
      Returns:
        row sequence
      Throws:
        `java.io.IOException`

    - #### formatAttribute

          public static java.lang.String formatAttribute(java.lang.String name,
                                                         java.lang.String value)

      Turns a name,value pair into an attribute assignment suitable for putting in an XML start tag. The resulting string starts with, but does not end with, whitespace. Any necessary escaping of the strings is taken care of.
      Parameters:
        `name` - the attribute name
        `value` - the attribute value
      Returns:
        string of the form ' name="value"'

    - #### formatText

          public static java.lang.String formatText(java.lang.String text)

      Performs necessary special character escaping for text which will be written as XML CDATA.
      Parameters:
        `text` - the input text
      Returns:
        `text` but with XML special characters escaped

    - #### ensureLegalXml

          public static char ensureLegalXml(char c)

      Returns a legal XML character corresponding to an input character. Certain characters are simply illegal in XML (regardless of encoding). If the input character is legal in XML, it is returned; otherwise some other weird but legal character (currently the inverted question mark, "¿") is returned instead.
      Parameters:
        `c` - input character
      Returns:
        legal XML character, `c` if possible

    - #### makeSerializer

          @Deprecated
          public static VOSerializer makeSerializer(DataFormat dataFormat,
                                                                StarTable table)
                                                         throws java.io.IOException

      Deprecated. use instead `makeSerializer(VOSerializerConfig, uk.ac.starlink.table.StarTable)`
      Returns a serializer capable of serializing a given table to given data format, using the default VOTable output version.
      Parameters:
        `dataFormat` - one of the supported VOTable serialization formats
        `table` - the table to be serialized
      Returns:
        serializer
      Throws:
        `java.io.IOException`

    - #### makeSerializer

          @Deprecated
          public static VOSerializer makeSerializer(DataFormat dataFormat,
                                                                VOTableVersion version,
                                                                StarTable table)
                                                         throws java.io.IOException

      Deprecated. use instead `makeSerializer(VOSerializerConfig, uk.ac.starlink.table.StarTable)`
      Returns a serializer capable of serializing a given table to a given data format using a given VOTable version.
      Parameters:
        `dataFormat` - one of the supported VOTable serialization formats
        `version` - specifies the version of the VOTable standard to which the output will conform
        `table` - the table to be serialized
      Returns:
        serializer
      Throws:
        `java.io.IOException`

    - #### makeSerializer

          public static VOSerializer makeSerializer(VOSerializerConfig config,
                                                    StarTable table)
                                             throws java.io.IOException

      Returns a serializer capable of serializing a given table in accordance with a supplied configuration object.
      Parameters:
        `config` - configuration
        `table` - table for output
      Returns:
        serializer
      Throws:
        `java.io.IOException`

    - #### makeFitsSerializer

          public static VOSerializer makeFitsSerializer(StarTable table,
                                                        FitsTableSerializer fitser,
                                                        VOTableVersion version)
                                                 throws java.io.IOException

      Constructs a FITS-type VOSerializer. Since a FitsTableSerializer is required for this, if one is already available then supplying it directly here will be more efficient than calling `makeSerializer` which will have to construct another, possibly an expensive step.
      Parameters:
        `table` - table for serialization
        `fitser` - fits serializer
        `version` - output VOTable version
      Returns:
        serializer
      Throws:
        `java.io.IOException`