VOTableWriter (STIL)

java.lang.Object
- uk.ac.starlink.votable.VOTableWriter

All Implemented Interfaces:

Documented, DocumentedIOHandler, MultiStarTableWriter, StarTableWriter
```
public class VOTableWriter
extends java.lang.Object
implements StarTableWriter, MultiStarTableWriter, 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 columns
- Tables.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".
- The 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.
- Various other of the *_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).

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String DEFAULT_XML_DECLARATION
Default XML declaration in written documents.

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`DEFAULT_XML_DECLARATION` Default XML declaration in written documents.

Constructor Summary

Constructors
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.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected java.lang.String`	`createResourceStartTag()` Returns the start tag for the RESOURCE element that encloses the output TABLE element(s).
`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.
`ResourceType`	`getResourceType()` Returns the value of the "type" attribute that will be written on RESOURCE elements containing output TABLE elements.
`VOTableVersion`	`getVotableVersion()` Returns the version of the VOTable standard to which the output of this writer conforms.
`boolean`	`getWriteDate()` Indicates whether a datestamp is written to output VOTable files.
`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`	`setResourceType(ResourceType resourceType)` Sets the value of the "type" attribute on RESOURCE elements that contain output TABLE element(s).
`void`	`setVotableVersion(VOTableVersion version)` Sets the version of the VOTable standard to which the output of this writer will conform.
`void`	`setWriteDate(boolean writeDate)` Configures whether a datestamp is written to output VOTable files.
`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()`
`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.
`void`	`writePostTableXML(java.io.BufferedWriter writer)` Outputs all the text required after any tables in the output table document.
`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.

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
matchesExtension, readText, toLink

- Field Detail
 - DEFAULT_XML_DECLARATION
```
public static final java.lang.String DEFAULT_XML_DECLARATION
```
 Default XML declaration in written documents.
 
 See Also:
 
 Constant Field Values
- Constructor Detail
 - VOTableWriter
```
public VOTableWriter()
```
 Constructs a default VOTableWriter. Output is in TABLEDATA format.
 - VOTableWriter
```
public VOTableWriter(DataFormat dataFormat,
 boolean inline)
```
 Constructs a VOTableWriter with specified output type and default VOTable version.
 
 Parameters:
 
 dataFormat - the format in which tables will be written
 
 inline - whether output of streamed formats should be inline and base64-encoded or not
 - VOTableWriter
```
public VOTableWriter(DataFormat dataFormat,
 boolean inline,
 VOTableVersion version)
```
 Constructs a VOTableWriter with specified output characterstics and a given version of the VOTable standard.
 
 Parameters:
 
 dataFormat - the format in which tables will be written
 
 inline - whether output of streamed formats should be inline and base64-encoded or not
 
 version - version of the VOTable standard
- Method Detail
 - writeStarTable
```
public void writeStarTable(StarTable startab,
 java.lang.String location,
 StarTableOutput sto)
 throws java.io.IOException
```
 Writes a StarTable to a given location.
 
 Specified by:
 
 writeStarTable in interface StarTableWriter
 
 Parameters:
 
 startab - the table to write
 
 location - the filename to which to write the table
 
 sto - object used for location resolution
 
 Throws:
 
 TableFormatException - if startab cannot be written to location
 
 java.io.IOException - if there is some I/O error
 - writeStarTables
```
public void writeStarTables(TableSequence tableSeq,
 java.lang.String location,
 StarTableOutput sto)
 throws java.io.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 interface MultiStarTableWriter
 
 Parameters:
 
 tableSeq - table sequence
 
 location - the filename to which to write the table
 
 sto - object used for location resolution
 
 Throws:
 
 java.io.IOException
 - writeStarTable
```
public void writeStarTable(StarTable startab,
 java.io.OutputStream out)
 throws java.io.IOException
```
 Writes a StarTable to a given stream; must be inline. Same as writeStarTable(startab,out,(File)null).
 
 Specified by:
 
 writeStarTable in interface StarTableWriter
 
 Parameters:
 
 startab - the table to write
 
 out - the stream down which to write the table
 
 Throws:
 
 TableFormatException - if this table cannot be written to a stream
 
 java.io.IOException - if there is some I/O error
 - writeStarTables
```
public void writeStarTables(TableSequence tableSeq,
 java.io.OutputStream out)
 throws java.io.IOException
```
 Writes a sequence of tables to a given stream; must be inline. Same as writeStarTables(tableSeq,out,null).
 
 Specified by:
 
 writeStarTables in interface MultiStarTableWriter
 
 Parameters:
 
 tableSeq - tables to write
 
 out - destination stream
 
 Throws:
 
 java.io.IOException
 - writeStarTable
```
public void writeStarTable(StarTable startab,
 java.io.OutputStream out,
 java.io.File file)
 throws java.io.IOException
```
 Writes a StarTable to a given stream.
 
 Parameters:
 
 startab - the table to write
 
 out - the stream down which to write the table
 
 file - 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:
 
 java.io.IOException
 - writeStarTables
```
public void writeStarTables(TableSequence tableSeq,
 java.io.OutputStream out,
 java.io.File file)
 throws java.io.IOException
```
 Writes a sequence of tables to a given stream.
 
 Parameters:
 
 tableSeq - table sequence to write
 
 out - destination stream
 
 file - 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:
 
 java.io.IOException
 - writeInlineStarTable
```
public void writeInlineStarTable(StarTable startab,
 java.io.BufferedWriter writer)
 throws java.io.IOException
```
 Writes a table directly to a stream.
 
 Parameters:
 
 startab - table to write
 
 writer - destination stream
 
 Throws:
 
 java.io.IOException
 - writeInlineStarTables
```
public void writeInlineStarTables(StarTable[] startabs,
 java.io.BufferedWriter writer)
 throws java.io.IOException
```
 Writes multiple tables directly to a stream.
 
 Parameters:
 
 startabs - tables
 
 writer - destination stream
 
 Throws:
 
 java.io.IOException
 - writePreTableXML
```
public void writePreTableXML(java.io.BufferedWriter writer)
 throws java.io.IOException
```
 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:
 
 java.io.IOException
 
 See Also:
 
 writePostTableXML(java.io.BufferedWriter)
 - writeBetweenTableXML
```
public void writeBetweenTableXML(java.io.BufferedWriter writer)
 throws java.io.IOException
```
 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:
 
 java.io.IOException
 - writePostTableXML
```
public void writePostTableXML(java.io.BufferedWriter writer)
 throws java.io.IOException
```
 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:
 
 java.io.IOException
 
 See Also:
 
 writePreTableXML(java.io.BufferedWriter)
 - getExtensions
```
public java.lang.String[] getExtensions()
```
 Description copied from interface: DocumentedIOHandler
 
 Returns the list of filename extensions recognised by this handler.
 
 Specified by:
 
 getExtensions in interface DocumentedIOHandler
 
 Returns:
 
 lower-cased filename extension strings, no "." characters
 - looksLikeFile
```
public boolean looksLikeFile(java.lang.String filename)
```
 Description copied from interface: StarTableWriter
 
 Indicates whether the destination is of a familiar form for this kind of writer. This may be used to guess what kind of format a table should be written in. Implementations should return true for values of location which look like the normal form for their output format, for instance one with the usual file extension.
 
 Specified by:
 
 looksLikeFile in interface StarTableWriter
 
 Parameters:
 
 filename - the location name (probably filename)
 
 Returns:
 
 true iff it looks like a file this writer would normally write
 - docIncludesExample
```
public boolean docIncludesExample()
```
 Description copied from interface: DocumentedIOHandler
 
 Indicates whether the serialization of some (short) example table should be added to the user documentation for this handler. Binary formats, or instances for which the Documented.getXmlDescription() method already includes some example output, should return false.
 
 Specified by:
 
 docIncludesExample in interface DocumentedIOHandler
 
 Returns:
 
 true if the user documentation would benefit from the addition of an example serialization
 - getXmlDescription
```
public java.lang.String getXmlDescription()
```
 Description copied from interface: Documented
 
 Returns user-directed documentation in XML format.
 The output should be a sequence of one or more 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.
 
 Specified by:
 
 getXmlDescription in interface Documented
 
 Returns:
 
 XML description of this object
 - getFormatName
```
public java.lang.String getFormatName()
```
 Description copied from interface: StarTableWriter
 
 Gives the name of the format which is written by this writer. Matching against this string may be used by callers to identify or select this writer from a list.
 
 Specified by:
 
 getFormatName in interface StarTableWriter
 
 Returns:
 
 a short string identifying the output format of this writer
 - getMimeType
```
public java.lang.String getMimeType()
```
 Description copied from interface: StarTableWriter
 
 Returns a string suitable for use as the value of a MIME Content-Type header. If no suitable MIME type is available or known, one of "application/octet-stream" (for binary formats) or "text/plain" for ASCII ones) is recommended.
 
 Specified by:
 
 getMimeType in interface StarTableWriter
 
 Returns:
 
 MIME content type
 - setDataFormat
```
@ConfigMethod(property="format",
 usage="TABLEDATA|BINARY|BINARY2|FITS",
 doc="Gives the serialization type (DATA element content) of output VOTables.",
 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
```
public DataFormat 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
```
public void setXMLDeclaration(java.lang.String xmlDecl)
```
 Sets the XML declaration which will be used by this writer at the head of any document written. By default this is the value of DEFAULT_XML_DECLARATION.
 
 Parameters:
 
 xmlDecl - new XML declaration
 - getXMLDeclaration
```
public java.lang.String 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="Gives the version of the VOTable format which will be used when writing the VOTable.\n\"<code>V10</code>\" is version 1.0 etc.",
 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
```
public VOTableVersion 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="Controls whitespace formatting for TABLEDATA output,\nignored for other formats.\nBy default a decision will be taken dependent on table width.\n",
 sequence=4)
public void setCompact(java.lang.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
```
public java.lang.Boolean 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="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",
 sequence=5)
public void setEncoding(java.nio.charset.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
```
public java.nio.charset.Charset getEncoding()
```
 Returns the character encoding used for XML output.
 
 Returns:
 
 encoding charset
 - setWriteDate
```
@ConfigMethod(property="date",
 doc="If true, the output file will contain a comment recording the current date; otherwise it is not included.")
public void setWriteDate(boolean writeDate)
```
 Configures whether a datestamp is written to output VOTable files.
 
 Parameters:
 
 writeDate - true to include a date in the XML comments, false to omit it
 - getWriteDate
```
public boolean getWriteDate()
```
 Indicates whether a datestamp is written to output VOTable files.
 
 Returns:
 
 true if a date is included in the XML comments, false if not
 - setResourceType
```
public void setResourceType(ResourceType resourceType)
```
 Sets the value of the "type" attribute on RESOURCE elements that contain output TABLE element(s).
 
 Parameters:
 
 resourceType - resource type value
 - getResourceType
```
public ResourceType getResourceType()
```
 Returns the value of the "type" attribute that will be written on RESOURCE elements containing output TABLE elements.
 
 Returns:
 
 resource type attribute value
 - 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
```
public java.lang.String toString()
```
 Overrides:
 
 toString in class java.lang.Object
 - createResourceStartTag
```
protected java.lang.String createResourceStartTag()
```
 Returns the start tag for the RESOURCE element that encloses the output TABLE element(s).
 
 Returns:
 
 RESOURCE start tag text

Class VOTableWriter

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface uk.ac.starlink.table.formats.DocumentedIOHandler

Field Detail

DEFAULT_XML_DECLARATION

Constructor Detail

VOTableWriter

VOTableWriter

VOTableWriter

Method Detail

writeStarTable

writeStarTables

writeStarTable

writeStarTables

writeStarTable

writeStarTables

writeInlineStarTable

writeInlineStarTables

writePreTableXML

writeBetweenTableXML

writePostTableXML

getExtensions

looksLikeFile

docIncludesExample

getXmlDescription

getFormatName

getMimeType

setDataFormat

getDataFormat

setInline

getInline

setXMLDeclaration

getXMLDeclaration

setVotableVersion

getVotableVersion

setCompact

isCompact

setEncoding

getEncoding

setWriteDate

getWriteDate

setResourceType

getResourceType

setWriteSchemaLocation

getWriteSchemaLocation

toString

createResourceStartTag