Package uk.ac.starlink.votable
Class VOTableWriter
java.lang.Object
uk.ac.starlink.votable.VOTableWriter
- All Implemented Interfaces:
uk.ac.starlink.table.Documented
,uk.ac.starlink.table.formats.DocumentedIOHandler
,uk.ac.starlink.table.MultiStarTableWriter
,uk.ac.starlink.table.StarTableWriter
public class VOTableWriter
extends Object
implements uk.ac.starlink.table.StarTableWriter, uk.ac.starlink.table.MultiStarTableWriter, uk.ac.starlink.table.formats.DocumentedIOHandler
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 columnsTables.UBYTE_FLAG_INFO
: if set toBoolean.TRUE
and if the column has content classShort
orshort[]
, the data will be written withdatatype="unsignedByte"
instead of (signed 16-bit)"short"
.- The
COOSYS_*_INFO
andTIMESYS_*_INFO
items defined in theVOStarTable
class; suitable COOSYS/TIMESYS elements will be written and referenced as required to honour these items. - Various other of the
*_INFO
items defined in theVOStarTable
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
FieldsModifier and TypeFieldDescriptionstatic final String
Default XML declaration in written documents. -
Constructor Summary
ConstructorsConstructorDescriptionConstructs 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
Modifier and TypeMethodDescriptionboolean
Returns the format in which this writer will output the bulk table data.Returns the character encoding used for XML output.String[]
boolean
Indicates whether STREAM elements will be written inline or to an external file in the case of FITS and BINARY encoding.static uk.ac.starlink.table.StarTableWriter[]
Returns a list of votable writers with variant values of attributes.Returns the version of the VOTable standard to which the output of this writer conforms.boolean
Indicates whether the schema location attribute will be written on opening VOTABLE tags.Returns the XML declaration which is used by this writer at the head of any document written.Returns whitespace formatting policy for TABLEDATA output.boolean
looksLikeFile
(String filename) void
setCompact
(Boolean compact) Controls whitespace formatting for TABLEDATA output, ignored for other formats.void
setDataFormat
(DataFormat format) Sets the format in which the table data will be output.void
setEncoding
(Charset encoding) Sets the XML encoding used for the output VOTable.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
(String xmlDecl) Sets the XML declaration which will be used by this writer at the head of any document written.toString()
protected void
writeBetweenTableXML
(BufferedWriter writer) Outputs text between one table (TABLE and possibly other associated elements) and the next.void
writeInlineStarTable
(uk.ac.starlink.table.StarTable startab, BufferedWriter writer) Writes a table directly to a stream.void
writeInlineStarTables
(uk.ac.starlink.table.StarTable[] startabs, BufferedWriter writer) Writes multiple tables directly to a stream.protected void
writePostTableXML
(BufferedWriter writer) Outputs all the text required after any tables in the output table document.protected void
writePreTableXML
(BufferedWriter writer) Outputs all the text required before any tables are written.void
writeStarTable
(uk.ac.starlink.table.StarTable startab, OutputStream out) Writes a StarTable to a given stream; must be inline.void
writeStarTable
(uk.ac.starlink.table.StarTable startab, OutputStream out, File file) Writes a StarTable to a given stream.void
writeStarTable
(uk.ac.starlink.table.StarTable startab, String location, uk.ac.starlink.table.StarTableOutput sto) Writes a StarTable to a given location.void
writeStarTables
(uk.ac.starlink.table.TableSequence tableSeq, OutputStream out) Writes a sequence of tables to a given stream; must be inline.void
writeStarTables
(uk.ac.starlink.table.TableSequence tableSeq, OutputStream out, File file) Writes a sequence of tables to a given stream.void
writeStarTables
(uk.ac.starlink.table.TableSequence tableSeq, 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
Methods inherited from interface uk.ac.starlink.table.formats.DocumentedIOHandler
readText
-
Field Details
-
DEFAULT_XML_DECLARATION
Default XML declaration in written documents.- See Also:
-
-
Constructor Details
-
VOTableWriter
public VOTableWriter()Constructs a default VOTableWriter. Output is in TABLEDATA format. -
VOTableWriter
Constructs a VOTableWriter with specified output type and default VOTable version.- Parameters:
dataFormat
- the format in which tables will be writteninline
- whether output of streamed formats should be inline and base64-encoded or not
-
VOTableWriter
Constructs a VOTableWriter with specified output characterstics and a given version of the VOTable standard.- Parameters:
dataFormat
- the format in which tables will be writteninline
- whether output of streamed formats should be inline and base64-encoded or notversion
- version of the VOTable standard
-
-
Method Details
-
writeStarTable
public void writeStarTable(uk.ac.starlink.table.StarTable startab, String location, uk.ac.starlink.table.StarTableOutput sto) throws IOException Writes a StarTable to a given location.- Specified by:
writeStarTable
in interfaceuk.ac.starlink.table.StarTableWriter
- Parameters:
startab
- the table to writelocation
- the filename to which to write the tablesto
- object used for location resolution- Throws:
IOException
-
writeStarTables
public void writeStarTables(uk.ac.starlink.table.TableSequence tableSeq, String location, uk.ac.starlink.table.StarTableOutput sto) throws 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 interfaceuk.ac.starlink.table.MultiStarTableWriter
- Parameters:
tableSeq
- table sequencelocation
- the filename to which to write the tablesto
- object used for location resolution- Throws:
IOException
-
writeStarTable
public void writeStarTable(uk.ac.starlink.table.StarTable startab, OutputStream out) throws IOException Writes a StarTable to a given stream; must be inline. Same aswriteStarTable(startab,out,(File)null)
.- Specified by:
writeStarTable
in interfaceuk.ac.starlink.table.StarTableWriter
- Parameters:
startab
- the table to writeout
- the stream down which to write the table- Throws:
IOException
-
writeStarTables
public void writeStarTables(uk.ac.starlink.table.TableSequence tableSeq, OutputStream out) throws IOException Writes a sequence of tables to a given stream; must be inline. Same aswriteStarTables(tableSeq,out,null)
.- Specified by:
writeStarTables
in interfaceuk.ac.starlink.table.MultiStarTableWriter
- Parameters:
tableSeq
- tables to writeout
- destination stream- Throws:
IOException
-
writeStarTable
public void writeStarTable(uk.ac.starlink.table.StarTable startab, OutputStream out, File file) throws IOException Writes a StarTable to a given stream.- Parameters:
startab
- the table to writeout
- the stream down which to write the tablefile
- 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:
IOException
-
writeStarTables
public void writeStarTables(uk.ac.starlink.table.TableSequence tableSeq, OutputStream out, File file) throws IOException Writes a sequence of tables to a given stream.- Parameters:
tableSeq
- table sequence to writeout
- destination streamfile
- 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:
IOException
-
writeInlineStarTable
public void writeInlineStarTable(uk.ac.starlink.table.StarTable startab, BufferedWriter writer) throws IOException Writes a table directly to a stream.- Parameters:
startab
- table to writewriter
- destination stream- Throws:
IOException
-
writeInlineStarTables
public void writeInlineStarTables(uk.ac.starlink.table.StarTable[] startabs, BufferedWriter writer) throws IOException Writes multiple tables directly to a stream.- Parameters:
startabs
- tableswriter
- destination stream- Throws:
IOException
-
writePreTableXML
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:
IOException
- See Also:
-
writeBetweenTableXML
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:
IOException
-
writePostTableXML
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:
IOException
- See Also:
-
getExtensions
- Specified by:
getExtensions
in interfaceuk.ac.starlink.table.formats.DocumentedIOHandler
-
looksLikeFile
- Specified by:
looksLikeFile
in interfaceuk.ac.starlink.table.StarTableWriter
-
docIncludesExample
public boolean docIncludesExample()- Specified by:
docIncludesExample
in interfaceuk.ac.starlink.table.formats.DocumentedIOHandler
-
getXmlDescription
- Specified by:
getXmlDescription
in interfaceuk.ac.starlink.table.Documented
-
getFormatName
- Specified by:
getFormatName
in interfaceuk.ac.starlink.table.StarTableWriter
-
getMimeType
- Specified by:
getMimeType
in interfaceuk.ac.starlink.table.StarTableWriter
-
setDataFormat
@ConfigMethod(property="format", usage="TABLEDATA|BINARY|BINARY2|FITS", doc="<p>Gives the serialization type (DATA element content) of output VOTables.</p>", example="BINARY2", sequence=1) public void setDataFormat(DataFormat format) Sets the format in which the table data will be output.- Parameters:
format
- bulk data format
-
getDataFormat
Returns the format in which this writer will output the bulk table data.- Returns:
- bulk data format
-
setInline
@ConfigMethod(property="inline", doc="If true, STREAM elements are written base64-encoded within the body of the document, and if false they are written to a new external binary file whose name is derived from that of the output VOTable document. This is only applicable to BINARY, BINARY2 and FITS formats where output is not to a stream.", sequence=3) 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
Sets the XML declaration which will be used by this writer at the head of any document written. By default this is the value ofDEFAULT_XML_DECLARATION
.- Parameters:
xmlDecl
- new XML declaration
-
getXMLDeclaration
Returns the XML declaration which is used by this writer at the head of any document written.- Returns:
- XML declaration
-
setVotableVersion
@ConfigMethod(property="version", usage="V10|V11|V12|V13|V14|V15", example="V13", doc="<p>Gives the version of the VOTable format which will be used when writing the VOTable.\n\"<code>V10</code>\" is version 1.0 etc.</p>", sequence=2) 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
Returns the version of the VOTable standard to which the output of this writer conforms.- Returns:
- version
-
setCompact
@ConfigMethod(property="compact", example="true", doc="<p>Controls whitespace formatting for TABLEDATA output,\nignored for other formats.\nBy default a decision will be taken dependent on table width.\n</p>", sequence=4) public void setCompact(Boolean compact) Controls whitespace formatting for TABLEDATA output, ignored for other formats. If null (the default), a decision will be taken dependent on table width.- Parameters:
compact
- TRUE for compact TABLEDATA output, FALSE for more whitespace, null for auto
-
isCompact
Returns whitespace formatting policy for TABLEDATA output.- Returns:
- TRUE for compact TABLEDATA output, FALSE for more whitespace, null for auto
-
setEncoding
@ConfigMethod(property="encoding", usage="UTF-8|UTF-16|...", example="UTF-16", doc="<p>Specifies the XML encoding used in the output VOTable.\nThe default value is UTF-8.\nNote that certain optimisations are in place for UTF-8 output\nwhich means that other encodings may be significantly slower.\n</p>", sequence=5) public void setEncoding(Charset encoding) Sets the XML encoding used for the output VOTable. The default value is UTF-8. Note that certain optimisations are in place for UTF-8 output which means that other encodings may be significantly slower.- Parameters:
encoding
- encoding charset
-
getEncoding
Returns the character encoding used for XML output.- Returns:
- encoding charset
-
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
-
getStarTableWriters
public static uk.ac.starlink.table.StarTableWriter[] getStarTableWriters()Returns a list of votable writers with variant values of attributes.- Returns:
- non-standard VOTableWriters.
-