uk.ac.starlink.votable

Class VOSerializer

java.lang.Object

uk.ac.starlink.votable.VOSerializer

public abstract class VOSerializer
extends 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

Modifier and Type	Method and Description
static 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.
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) 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, 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	writeInlineDataElementUTF8(OutputStream out) Writes this serializer's table data as a self-contained <DATA> element to an output stream using UTF8 encoding.
void	writeInlineTableElement(BufferedWriter writer) Writes this serializer's table as a complete TABLE element.
void	writeInlineTableElementUTF8(OutputStream out) 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	writeServiceDescriptors(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(BufferedWriter writer)
                          throws IOException

Writes the FIELD headers corresponding to this table on a given writer.

Parameters:

writer - destination stream

Throws:

IOException

writeInlineDataElement

public abstract void writeInlineDataElement(BufferedWriter writer)
                                     throws 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:

IOException

writeInlineDataElementUTF8

public abstract void writeInlineDataElementUTF8(OutputStream out)
                                         throws 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:

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 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:

IOException

writeInlineTableElement

public void writeInlineTableElement(BufferedWriter writer)
                             throws 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:

IOException

writeInlineTableElementUTF8

public void writeInlineTableElementUTF8(OutputStream out)
                                 throws 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:

IOException

writeHrefTableElement

public void writeHrefTableElement(BufferedWriter xmlwriter,
                                  String href,
                                  OutputStream streamout)
                           throws IOException

Throws:

IOException

writeParams

public void writeParams(BufferedWriter writer)
                 throws 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:

IOException

writeDescription

public void writeDescription(BufferedWriter writer)
                      throws 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:

IOException

writeServiceDescriptors

public void writeServiceDescriptors(BufferedWriter writer)
                             throws 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:

IOException

writePreDataXML

public void writePreDataXML(BufferedWriter writer)
                     throws 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:

IOException

writePostDataXML

public void writePostDataXML(BufferedWriter writer)
                      throws IOException

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 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 IOException

Returns the row sequence that this serializer will write.

Returns:

row sequence

Throws:

IOException

formatAttribute

public static String formatAttribute(String name,
                                     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 String formatText(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,
                                          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 formats

table - the table to be serialized

Returns:

serializer

Throws:

IOException

makeSerializer

public static VOSerializer makeSerializer(DataFormat dataFormat,
                                          VOTableVersion version,
                                          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 formats

version - specifies the version of the VOTable standard to which the output will conform

table - the table to be serialized

Returns:

serializer

Throws:

IOException

makeFitsSerializer

public static VOSerializer makeFitsSerializer(StarTable table,
                                              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 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:

IOException