Class 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(uk.ac.starlink.votable.DataFormat, uk.ac.starlink.table.StarTable) method.

    Author:
    Mark Taylor (Starlink)
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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.
      uk.ac.starlink.table.StarTable getTable()
      Returns the table object which this object can serialize.
      static VOSerializer makeFitsSerializer​(uk.ac.starlink.table.StarTable table, uk.ac.starlink.fits.FitsTableSerializer fitser)
      Constructs a FITS-type VOSerializer.
      static VOSerializer makeSerializer​(DataFormat dataFormat, uk.ac.starlink.table.StarTable table)
      Returns a serializer capable of serializing a given table to given data format, using the default VOTable output version.
      static VOSerializer makeSerializer​(DataFormat dataFormat, VOTableVersion version, uk.ac.starlink.table.StarTable table)
      Returns a serializer capable of serializing a given table to a given data format using a given VOTable version.
      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.DataOutput 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.DataOutput streamout)  
      abstract void writeInlineDataElement​(java.io.BufferedWriter writer)
      Writes this serializer's table data as a self-contained <DATA> element.
      void writeInlineTableElement​(java.io.BufferedWriter writer)
      Writes this serializer's table as a complete TABLE element.
      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 uk.ac.starlink.table.StarTable getTable()
        Returns the table object which this object can serialize.
        Returns:
        table to write
      • 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
      • writeHrefDataElement

        public abstract void writeHrefDataElement​(java.io.BufferedWriter xmlwriter,
                                                  java.lang.String href,
                                                  java.io.DataOutput 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
      • writeHrefTableElement

        public void writeHrefTableElement​(java.io.BufferedWriter xmlwriter,
                                          java.lang.String href,
                                          java.io.DataOutput 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
      • 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

        public static VOSerializer makeSerializer​(DataFormat dataFormat,
                                                  uk.ac.starlink.table.StarTable table)
                                           throws java.io.IOException
        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

        public static VOSerializer makeSerializer​(DataFormat dataFormat,
                                                  VOTableVersion version,
                                                  uk.ac.starlink.table.StarTable table)
                                           throws java.io.IOException
        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
      • makeFitsSerializer

        public static VOSerializer makeFitsSerializer​(uk.ac.starlink.table.StarTable table,
                                                      uk.ac.starlink.fits.FitsTableSerializer fitser)
                                               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
        Throws:
        java.io.IOException