public class VOTableWriter extends java.lang.Object implements StarTableWriter, MultiStarTableWriter, DocumentedIOHandler
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 to Boolean.TRUE
and if the column has content class
Short
or short[]
, the data will be written
with datatype="unsignedByte"
instead of
(signed 16-bit) "short"
.COOSYS_*_INFO
and TIMESYS_*_INFO
items defined in the VOStarTable
class;
suitable COOSYS/TIMESYS elements will be written and referenced
as required to honour these items.*_INFO
items defined in the
VOStarTable
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).Modifier and Type | Field and Description |
---|---|
static java.lang.String |
DEFAULT_XML_DECLARATION
Default XML declaration in written documents.
|
Constructor and Description |
---|
VOTableWriter()
Constructs 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.
|
Modifier and Type | Method and Description |
---|---|
boolean |
docIncludesExample()
Indicates whether the serialization of some (short) example table
should be added to the user documentation for this handler.
|
DataFormat |
getDataFormat()
Returns the format in which this writer will output the bulk table data.
|
java.nio.charset.Charset |
getEncoding()
Returns the character encoding used for XML output.
|
java.lang.String[] |
getExtensions()
Returns the list of filename extensions recognised by this handler.
|
java.lang.String |
getFormatName()
Gives the name of the format which is written by this writer.
|
boolean |
getInline()
Indicates whether STREAM elements will be written inline or to
an external file in the case of FITS and BINARY encoding.
|
java.lang.String |
getMimeType()
Returns a string suitable for use as the value of a MIME
Content-Type header.
|
static StarTableWriter[] |
getStarTableWriters()
Returns a list of votable writers with variant values of attributes.
|
VOTableVersion |
getVotableVersion()
Returns the version of the VOTable standard to which the output
of this writer conforms.
|
boolean |
getWriteSchemaLocation()
Indicates whether the schema location attribute will be written
on opening VOTABLE tags.
|
java.lang.String |
getXMLDeclaration()
Returns the XML declaration which is used by this writer
at the head of any document written.
|
java.lang.String |
getXmlDescription()
Returns user-directed documentation in XML format.
|
java.lang.Boolean |
isCompact()
Returns whitespace formatting policy for TABLEDATA output.
|
boolean |
looksLikeFile(java.lang.String filename)
Indicates whether the destination is of a familiar form for this
kind of writer.
|
void |
setCompact(java.lang.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(java.nio.charset.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(java.lang.String xmlDecl)
Sets the XML declaration which will be used by this writer
at the head of any document written.
|
java.lang.String |
toString() |
protected void |
writeBetweenTableXML(java.io.BufferedWriter writer)
Outputs text between one table (TABLE and possibly other associated
elements) and the next.
|
void |
writeInlineStarTable(StarTable startab,
java.io.BufferedWriter writer)
Writes a table directly to a stream.
|
void |
writeInlineStarTables(StarTable[] startabs,
java.io.BufferedWriter writer)
Writes multiple tables directly to a stream.
|
protected void |
writePostTableXML(java.io.BufferedWriter writer)
Outputs all the text required after any tables in the
output table document.
|
protected void |
writePreTableXML(java.io.BufferedWriter writer)
Outputs all the text required before any tables are written.
|
void |
writeStarTable(StarTable startab,
java.io.OutputStream out)
Writes a StarTable to a given stream; must be inline.
|
void |
writeStarTable(StarTable startab,
java.io.OutputStream out,
java.io.File file)
Writes a StarTable to a given stream.
|
void |
writeStarTable(StarTable startab,
java.lang.String location,
StarTableOutput sto)
Writes a StarTable to a given location.
|
void |
writeStarTables(TableSequence tableSeq,
java.io.OutputStream out)
Writes a sequence of tables to a given stream; must be inline.
|
void |
writeStarTables(TableSequence tableSeq,
java.io.OutputStream out,
java.io.File file)
Writes a sequence of tables to a given stream.
|
void |
writeStarTables(TableSequence tableSeq,
java.lang.String location,
StarTableOutput sto)
Writes a sequence of tables to a given location.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
matchesExtension, readText, toLink
public static final java.lang.String DEFAULT_XML_DECLARATION
public VOTableWriter()
public VOTableWriter(DataFormat dataFormat, boolean inline)
dataFormat
- the format in which tables will be writteninline
- whether output of streamed formats should be
inline and base64-encoded or notpublic VOTableWriter(DataFormat dataFormat, boolean inline, VOTableVersion version)
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 standardpublic void writeStarTable(StarTable startab, java.lang.String location, StarTableOutput sto) throws java.io.IOException
writeStarTable
in interface StarTableWriter
startab
- the table to writelocation
- the filename to which to write the tablesto
- object used for location resolutionTableFormatException
- if startab cannot be written
to locationjava.io.IOException
- if there is some I/O errorpublic void writeStarTables(TableSequence tableSeq, java.lang.String location, StarTableOutput sto) throws java.io.IOException
writeStarTables
in interface MultiStarTableWriter
tableSeq
- table sequencelocation
- the filename to which to write the tablesto
- object used for location resolutionjava.io.IOException
public void writeStarTable(StarTable startab, java.io.OutputStream out) throws java.io.IOException
writeStarTable(startab,out,(File)null)
.writeStarTable
in interface StarTableWriter
startab
- the table to writeout
- the stream down which to write the tableTableFormatException
- if this table cannot be written to a
streamjava.io.IOException
- if there is some I/O errorpublic void writeStarTables(TableSequence tableSeq, java.io.OutputStream out) throws java.io.IOException
writeStarTables(tableSeq,out,null)
.writeStarTables
in interface MultiStarTableWriter
tableSeq
- tables to writeout
- destination streamjava.io.IOException
public void writeStarTable(StarTable startab, java.io.OutputStream out, java.io.File file) throws java.io.IOException
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.java.io.IOException
public void writeStarTables(TableSequence tableSeq, java.io.OutputStream out, java.io.File file) throws java.io.IOException
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.java.io.IOException
public void writeInlineStarTable(StarTable startab, java.io.BufferedWriter writer) throws java.io.IOException
startab
- table to writewriter
- destination streamjava.io.IOException
public void writeInlineStarTables(StarTable[] startabs, java.io.BufferedWriter writer) throws java.io.IOException
startabs
- tableswriter
- destination streamjava.io.IOException
protected void writePreTableXML(java.io.BufferedWriter writer) throws java.io.IOException
writer
- destination streamjava.io.IOException
writePostTableXML(java.io.BufferedWriter)
protected void writeBetweenTableXML(java.io.BufferedWriter writer) throws java.io.IOException
This method closes one RESOURCE element and opens another one.
writer
- destination streamjava.io.IOException
protected void writePostTableXML(java.io.BufferedWriter writer) throws java.io.IOException
writer
- destination streamjava.io.IOException
writePreTableXML(java.io.BufferedWriter)
public java.lang.String[] getExtensions()
DocumentedIOHandler
getExtensions
in interface DocumentedIOHandler
public boolean looksLikeFile(java.lang.String filename)
StarTableWriter
looksLikeFile
in interface StarTableWriter
filename
- the location name (probably filename)public boolean docIncludesExample()
DocumentedIOHandler
Documented.getXmlDescription()
method already includes some example output, should return false.docIncludesExample
in interface DocumentedIOHandler
public java.lang.String getXmlDescription()
Documented
The output should be a sequence of one or more <P> elements, using XHTML-like XML. Since rendering may be done in a number of contexts however, use of the full range of XHTML elements is discouraged. Where possible, the content should stick to simple markup such as the elements P, A, UL, OL, LI, DL, DT, DD EM, STRONG, I, B, CODE, TT, PRE.
getXmlDescription
in interface Documented
public java.lang.String getFormatName()
StarTableWriter
getFormatName
in interface StarTableWriter
public java.lang.String getMimeType()
StarTableWriter
application/octet-stream
"
(for binary formats) or "text/plain
" for ASCII ones)
is recommended.getMimeType
in interface StarTableWriter
@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)
format
- bulk data formatpublic DataFormat getDataFormat()
@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)
inline
- true iff streamed data will be encoded
inline in the STREAM elementpublic boolean getInline()
public void setXMLDeclaration(java.lang.String xmlDecl)
DEFAULT_XML_DECLARATION
.xmlDecl
- new XML declarationpublic java.lang.String getXMLDeclaration()
@ConfigMethod(property="version", usage="V10|V11|V12|V13|V14", 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)
version
- new versionpublic VOTableVersion getVotableVersion()
@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(java.lang.Boolean compact)
compact
- TRUE for compact TABLEDATA output,
FALSE for more whitespace,
null for autopublic java.lang.Boolean isCompact()
@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(java.nio.charset.Charset encoding)
encoding
- encoding charsetpublic java.nio.charset.Charset getEncoding()
public void setWriteSchemaLocation(boolean writeSchemaLocation)
writeSchemaLocation
- whether to write xsi:schemaLocation attspublic boolean getWriteSchemaLocation()
public java.lang.String toString()
toString
in class java.lang.Object
public static StarTableWriter[] getStarTableWriters()