tap.formatter

Class VOTableFormat

java.lang.Object

tap.formatter.VOTableFormat

All Implemented Interfaces:

OutputFormat

public class VOTableFormat
extends java.lang.Object
implements OutputFormat

Format any given query (table) result into VOTable.

Format and version of the resulting VOTable can be provided in parameters at the construction time. This formatter is using STIL. So all formats and versions managed by STIL are also here. Basically, you have the following formats: TABLEDATA, BINARY, BINARY2 (only when using VOTable v1.3) and FITS. The versions are: 1.0, 1.1, 1.2 and 1.3.

Note: The MIME type is automatically set in function of the given VOTable serialization:

• none or unknown: equivalent to BINARY
• BINARY: "application/x-votable+xml" = "votable"
• BINARY2: "application/x-votable+xml;serialization=BINARY2" = "votable/b2"
• TABLEDATA: "application/x-votable+xml;serialization=TABLEDATA" = "votable/td"
• FITS: "application/x-votable+xml;serialization=FITS" = "votable/fits"

It is however possible to change these default values thanks to setMimeType(String, String).

In addition of the INFO elements for QUERY_STATUS="OK" and QUERY_STATUS="OVERFLOW", two additional INFO elements are written:

• PROVIDER = ServiceConnection.getProviderName() and ServiceConnection.getProviderDescription()
• QUERY = the ADQL query at the origin of this result.

Furthermore, this formatter provides a function to format an error in VOTable: writeError(String, Map, PrintWriter). This is useful for TAP which requires to return in VOTable any error that occurs while any operation. See DefaultTAPErrorWriter for more details.

Version:

2.3 (03/2019)

Author:

Grégory Mantelet (CDS;ARI)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	VOTableFormat.LimitedStarTable Special StarTable able to read a fixed maximum number of rows TableIterator.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	mimeType MIME type associated with this format.
protected ServiceConnection	service The ServiceConnection to use (for the log and to have some information about the service (particularly: name, description).
protected java.lang.String	shortMimeType Short form of the MIME type associated with this format.
protected uk.ac.starlink.votable.DataFormat	votFormat Format of the VOTable data part in which data must be formatted.
protected uk.ac.starlink.votable.VOTableVersion	votVersion VOTable version in which table data must be formatted.

Constructor Summary

Constructors

Constructor and Description
VOTableFormat(ServiceConnection service) Creates a VOTable formatter.
VOTableFormat(ServiceConnection service, uk.ac.starlink.votable.DataFormat votFormat) Creates a VOTable formatter.
VOTableFormat(ServiceConnection service, uk.ac.starlink.votable.DataFormat votFormat, uk.ac.starlink.votable.VOTableVersion votVersion) Creates a VOTable formatter.

Method Summary

Modifier and Type	Method and Description
protected static uk.ac.starlink.table.ColumnInfo	getColumnInfo(TAPColumn tapCol) Convert the given TAPColumn object into a ColumnInfo object.
protected static java.lang.Class<?>	getDatatypeClass(VotType.VotDatatype datatype, java.lang.String arraysize) Convert the VOTable datatype string into a corresponding Class object.
java.lang.String	getDescription() Gets a description of this format.
java.lang.String	getFileExtension() Gets a file extension for this format.
java.lang.String	getMimeType() Gets the MIME type corresponding to this format.
protected static int[]	getShape(java.lang.String arraysize) Convert the given VOTable arraysize into a ColumnInfo shape.
java.lang.String	getShortMimeType() Gets a short expression of its MIME type.
protected static TAPColumn	getValidColMeta(DBColumn typeFromQuery, TAPColumn typeFromResult) Try to get or otherwise to build appropriate metadata using those extracted from the ADQL query and those extracted from the result.
uk.ac.starlink.votable.DataFormat	getVotSerialization() Get the set VOTable data serialization/format (e.g.
uk.ac.starlink.votable.VOTableVersion	getVotVersion() Get the set VOTable version.
void	setMimeType(java.lang.String mimeType, java.lang.String shortForm) Set the MIME type associated with this format.
static uk.ac.starlink.table.ColumnInfo[]	toColumnInfos(TableIterator result, TAPExecutionReport execReport, java.lang.Thread thread) Writes fields' metadata of the given query result.
void	writeError(java.lang.String message, java.util.Map<java.lang.String,java.lang.String> otherInfo, java.io.PrintWriter writer) Write the given error message as VOTable document.
protected void	writeHeader(uk.ac.starlink.votable.VOTableVersion votVersion, TAPExecutionReport execReport, java.io.BufferedWriter out) Writes the first VOTable nodes/elements preceding the data: VOTABLE, RESOURCE and 3 INFOS (QUERY_STATUS, PROVIDER, QUERY).
void	writeResult(TableIterator queryResult, java.io.OutputStream output, TAPExecutionReport execReport, java.lang.Thread thread) Formats the given query result and writes it in the given output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

service

protected final ServiceConnection service

The ServiceConnection to use (for the log and to have some information about the service (particularly: name, description).

votFormat

protected final uk.ac.starlink.votable.DataFormat votFormat

Format of the VOTable data part in which data must be formatted. Possible values are: TABLEDATA, BINARY, BINARY2 or FITS. By default, it is set to BINARY.

votVersion

protected final uk.ac.starlink.votable.VOTableVersion votVersion

VOTable version in which table data must be formatted. By default, it is set to v13.

mimeType

protected java.lang.String mimeType

MIME type associated with this format.

shortMimeType

protected java.lang.String shortMimeType

Short form of the MIME type associated with this format.

Constructor Detail

VOTableFormat

public VOTableFormat(ServiceConnection service)
              throws java.lang.NullPointerException

Creates a VOTable formatter.

Note: The MIME type is automatically set to "application/x-votable+xml" = "votable". It is however possible to change this default value thanks to setMimeType(String, String).

Parameters:

service - The service to use (for the log and to have some information about the service (particularly: name, description).

Throws:

java.lang.NullPointerException - If the given service connection is null.

VOTableFormat

public VOTableFormat(ServiceConnection service,
                     uk.ac.starlink.votable.DataFormat votFormat)
              throws java.lang.NullPointerException

Creates a VOTable formatter.

Note: The MIME type is automatically set in function of the given VOTable serialization:

• none or unknown: equivalent to BINARY
• BINARY: "application/x-votable+xml" = "votable"
• BINARY2: "application/x-votable+xml;serialization=BINARY2" = "votable/b2"
• TABLEDATA: "application/x-votable+xml;serialization=TABLEDATA" = "votable/td"
• FITS: "application/x-votable+xml;serialization=FITS" = "votable/fits"

It is however possible to change these default values thanks to setMimeType(String, String).

Parameters:

service - The service to use (for the log and to have some information about the service (particularly: name, description).

votFormat - Serialization of the VOTable data part. (TABLEDATA, BINARY, BINARY2 or FITS).

Throws:

java.lang.NullPointerException - If the given service connection is null.

VOTableFormat

public VOTableFormat(ServiceConnection service,
                     uk.ac.starlink.votable.DataFormat votFormat,
                     uk.ac.starlink.votable.VOTableVersion votVersion)
              throws java.lang.NullPointerException

Creates a VOTable formatter.

Note: The MIME type is automatically set in function of the given VOTable serialization:

• none or unknown: equivalent to BINARY
• BINARY: "application/x-votable+xml" = "votable"
• BINARY2: "application/x-votable+xml;serialization=BINARY2" = "votable/b2"
• TABLEDATA: "application/x-votable+xml;serialization=TABLEDATA" = "votable/td"
• FITS: "application/x-votable+xml;serialization=FITS" = "votable/fits"

It is however possible to change these default values thanks to setMimeType(String, String).

Parameters:

service - The service to use (for the log and to have some information about the service (particularly: name, description).

votFormat - Serialization of the VOTable data part. (TABLEDATA, BINARY, BINARY2 or FITS).

votVersion - Version of the resulting VOTable.

Throws:

java.lang.NullPointerException - If the given service connection is null.

Method Detail

getMimeType

public final java.lang.String getMimeType()

Description copied from interface: OutputFormat

Gets the MIME type corresponding to this format.

Specified by:

getMimeType in interface OutputFormat

Returns:

Its MIME type (MUST BE DIFFERENT FROM NULL).

getShortMimeType

public final java.lang.String getShortMimeType()

Description copied from interface: OutputFormat

Gets a short expression of its MIME type.

Specified by:

getShortMimeType in interface OutputFormat

Returns:

Its short MIME type.

setMimeType

public final void setMimeType(java.lang.String mimeType,
                              java.lang.String shortForm)

Set the MIME type associated with this format.

Note: NULL means no modification of the current value:

Parameters:

mimeType - Full MIME type of this VOTable format. note: if NULL, the MIME type is not modified.

shortForm - Short form of this MIME type. note: if NULL, the short MIME type is not modified.

getVotSerialization

public final uk.ac.starlink.votable.DataFormat getVotSerialization()

Get the set VOTable data serialization/format (e.g. BINARY, TABLEDATA).

Returns:

The data format.

getVotVersion

public final uk.ac.starlink.votable.VOTableVersion getVotVersion()

Get the set VOTable version.

Returns:

The VOTable version.

getDescription

public java.lang.String getDescription()

Description copied from interface: OutputFormat

Gets a description of this format.

Specified by:

getDescription in interface OutputFormat

Returns:

Its description.

getFileExtension

public java.lang.String getFileExtension()

Description copied from interface: OutputFormat

Gets a file extension for this format.

Specified by:

getFileExtension in interface OutputFormat

Returns:

Its file extension.

writeError

public void writeError(java.lang.String message,
                       java.util.Map<java.lang.String,java.lang.String> otherInfo,
                       java.io.PrintWriter writer)
                throws java.io.IOException

Write the given error message as VOTable document.

Note: In the TAP protocol, all errors must be returned as VOTable. The class DefaultTAPErrorWriter is in charge of the management and reporting of all errors. It is calling this function while the error message to display to the user is ready and must be written in the HTTP response.

Here is the XML format of this VOTable error:

        <VOTABLE version="..." xmlns="..." >
                <RESOURCE type="results">
                        <INFO name="QUERY_STATUS" value="ERROR>
                                ...
                        </INFO>
                        <INFO name="PROVIDER" value="...">...</INFO>
                        <!-- other optional INFOs (e.g. request parameters) -->
                </RESOURCE>
        </VOTABLE>
 

Parameters:

message - Error message to display to the user.

otherInfo - List of other additional information to display. optional

writer - Stream in which the VOTable error must be written.

Throws:

java.io.IOException - If any error occurs while writing in the given output.

Since:

2.0

writeResult

public final void writeResult(TableIterator queryResult,
                              java.io.OutputStream output,
                              TAPExecutionReport execReport,
                              java.lang.Thread thread)
                       throws TAPException,
                              java.io.IOException,
                              java.lang.InterruptedException

Description copied from interface: OutputFormat

Formats the given query result and writes it in the given output stream.

Note: the given output stream should not be closed at the end of this function. It is up to the called to do it.

Specified by:

writeResult in interface OutputFormat

Parameters:

queryResult - The raw (table) result to format.

output - The output stream (a ServletOutputStream or a stream on a file) in which the formatted result must be written.

execReport - The report of the execution of the TAP query whose the result must be now written.

thread - The thread which has asked the result writing.

Throws:

TAPException - If there is an error while formatting the query result.

java.io.IOException - If any error occurs while writing into the given stream.

java.lang.InterruptedException - If the query has been interrupted/aborted.

writeHeader

protected void writeHeader(uk.ac.starlink.votable.VOTableVersion votVersion,
                           TAPExecutionReport execReport,
                           java.io.BufferedWriter out)
                    throws java.io.IOException,
                           TAPException

Writes the first VOTable nodes/elements preceding the data: VOTABLE, RESOURCE and 3 INFOS (QUERY_STATUS, PROVIDER, QUERY).

Parameters:

votVersion - Target VOTable version.

execReport - The report of the query execution.

out - Writer in which the root node must be written.

Throws:

java.io.IOException - If there is an error while writing the root node in the given Writer.

TAPException - If there is any other error (by default: never happen).

toColumnInfos

public static final uk.ac.starlink.table.ColumnInfo[] toColumnInfos(TableIterator result,
                                                                    TAPExecutionReport execReport,
                                                                    java.lang.Thread thread)
                                                             throws java.io.IOException,
                                                                    TAPException,
                                                                    java.lang.InterruptedException

Writes fields' metadata of the given query result.

Parameters:

result - The query result from whose fields' metadata must be written.

execReport - The report of the query execution.

thread - The thread which asked for the result writing.

Returns:

Extracted field's metadata, or NULL if no metadata have been found (theoretically, it never happens).

Throws:

java.io.IOException - If there is an error while writing the metadata.

TAPException - If there is any other error.

java.lang.InterruptedException - If the given thread has been interrupted.

getValidColMeta

protected static final TAPColumn getValidColMeta(DBColumn typeFromQuery,
                                                 TAPColumn typeFromResult)

Try to get or otherwise to build appropriate metadata using those extracted from the ADQL query and those extracted from the result.

Parameters:

typeFromQuery - Metadata extracted/guessed from the ADQL query.

typeFromResult - Metadata extracted/guessed from the result.

Returns:

The most appropriate metadata.

getColumnInfo

protected static final uk.ac.starlink.table.ColumnInfo getColumnInfo(TAPColumn tapCol)

Convert the given TAPColumn object into a ColumnInfo object.

Parameters:

tapCol - TAPColumn to convert into ColumnInfo.

Returns:

The corresponding ColumnInfo.

getDatatypeClass

protected static final java.lang.Class<?> getDatatypeClass(VotType.VotDatatype datatype,
                                                           java.lang.String arraysize)

Convert the VOTable datatype string into a corresponding Class object.

Parameters:

datatype - Value of the VOTable attribute "datatype".

arraysize - Value of the VOTable attribute "arraysize".

Returns:

The corresponding Class object.

getShape

protected static final int[] getShape(java.lang.String arraysize)

Convert the given VOTable arraysize into a ColumnInfo shape.

Parameters:

arraysize - Value of the VOTable attribute "arraysize".

Returns:

The corresponding ColumnInfo shape.