Package uk.ac.starlink.votable
Class VOSerializer
java.lang.Object
uk.ac.starlink.votable.VOSerializer
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
Modifier and TypeMethodDescriptionstatic char
ensureLegalXml
(char c) Returns a legal XML character corresponding to an input character.static String
formatAttribute
(String name, String value) Turns a name,value pair into an attribute assignment suitable for putting in an XML start tag.static String
formatText
(String text) Performs necessary special character escaping for text which will be written as XML CDATA.Returns the data format which this object can serialize to.long
Returns the number of rows that this serializer will write, if known.uk.ac.starlink.table.RowSequence
Returns the row sequence that this serializer will write.uk.ac.starlink.table.StarTable
getTable()
Returns the table object which this object can serialize.Returns the version of the VOTable standard for which this serializer will write.boolean
Indicates compactness of whitespace formatting for TABLEDATA format; no effect for other DataFormats.static VOSerializer
makeFitsSerializer
(uk.ac.starlink.table.StarTable table, uk.ac.starlink.fits.FitsTableSerializer fitser, VOTableVersion version) 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
setCompact
(boolean isCompact) Controls whitespace formatting for TABLEDATA format; no effect for other DataFormats.void
writeDescription
(BufferedWriter writer) Writes any DESCRIPTION element associated with this serializer's table.abstract void
writeFields
(BufferedWriter writer) Writes the FIELD headers corresponding to this table on a given writer.abstract void
writeHrefDataElement
(BufferedWriter xmlwriter, String href, 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
(BufferedWriter xmlwriter, String href, OutputStream streamout) abstract void
writeInlineDataElement
(BufferedWriter writer) Writes this serializer's table data as a self-contained <DATA> element.abstract void
Writes this serializer's table data as a self-contained <DATA> element to an output stream using UTF8 encoding.void
Writes this serializer's table as a complete TABLE element.void
Writes this serializer's table as a complete TABLE element to an output stream using UTF8 encoding.void
writeParams
(BufferedWriter writer) Writes any PARAM and INFO elements associated with this serializer's table.void
writePostDataXML
(BufferedWriter writer) Outputs any content of the TABLE element following the DATA element and the TABLE end tag.void
writePreDataXML
(BufferedWriter writer) Outputs the TABLE element start tag and all of its content before the DATA element.void
Writes the service descriptor parameters of this serializer's table as a sequence of zero or more RESOURCE elements.
-
Method Details
-
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
-
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
Writes the FIELD headers corresponding to this table on a given writer.- Parameters:
writer
- destination stream- Throws:
IOException
-
writeInlineDataElement
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:
IOException
-
writeInlineDataElementUTF8
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 equivalentwriteInlineDataElement(java.io.BufferedWriter)
method.- Parameters:
out
- output stream- Throws:
IOException
-
writeHrefDataElement
public abstract void writeHrefDataElement(BufferedWriter xmlwriter, String href, OutputStream streamout) throws 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 outputhref
- URL for the external stream (output as the href attribute of the written <STREAM> element)streamout
- destination stream for the binary table data- Throws:
IOException
-
writeInlineTableElement
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:
IOException
-
writeInlineTableElementUTF8
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:
IOException
-
writeHrefTableElement
public void writeHrefTableElement(BufferedWriter xmlwriter, String href, OutputStream streamout) throws IOException - Throws:
IOException
-
writeParams
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:
IOException
-
writeDescription
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:
IOException
-
writeServiceDescriptors
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:
IOException
-
writePreDataXML
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:
IOException
-
writePostDataXML
Outputs any content of the TABLE element following the DATA element and the TABLE end tag.- Parameters:
writer
- output stream- Throws:
IOException
-
getRowCount
public long getRowCount()Returns the number of rows that this serializer will write, if known. The default implementation returnsgetTable().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
Returns the row sequence that this serializer will write.- Returns:
- row sequence
- Throws:
IOException
-
formatAttribute
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 namevalue
- the attribute value- Returns:
- string of the form ' name="value"'
-
formatText
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 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 formatstable
- the table to be serialized- Returns:
- serializer
- Throws:
IOException
-
makeSerializer
public static VOSerializer makeSerializer(DataFormat dataFormat, VOTableVersion version, uk.ac.starlink.table.StarTable table) throws 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 formatsversion
- specifies the version of the VOTable standard to which the output will conformtable
- the table to be serialized- Returns:
- serializer
- Throws:
IOException
-
makeFitsSerializer
public static VOSerializer makeFitsSerializer(uk.ac.starlink.table.StarTable table, uk.ac.starlink.fits.FitsTableSerializer fitser, VOTableVersion version) throws 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 callingmakeSerializer
which will have to construct another, possibly an expensive step.- Parameters:
table
- table for serializationfitser
- fits serializerversion
- output VOTable version- Returns:
- serializer
- Throws:
IOException
-