tap.metadata

Class TableSetParser

java.lang.Object

org.xml.sax.helpers.DefaultHandler

tap.metadata.TableSetParser

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public class TableSetParser
extends org.xml.sax.helpers.DefaultHandler

Let parse an XML document representing a table set, and return the corresponding TAPMetadata instance.

Note 1: the table set must follow the syntax specified by the XML Schema http://www.ivoa.net/xml/VODataService.

Note 2: only tags specified by VODataService are checked. If there is any other tag, they are merely ignored.

Exceptions

A TAPException is thrown in the following cases:

• the root node is not "tableset"
• table name syntax ([schema.]table) is incorrect
• a single table name (just "table" without schema prefix) is ambiguous (that's to say, the same name is used for tables of different schemas)
• "name" node is missing in nodes "schema", "table" and "column"
• "targetTable" is missing in node "foreignKey"
• "fromColumn" or "targetColumn" is missing in node "fkColumn"
• "name" node is duplicated in the same node
• missing "xsi:type" as attribute in a "dataType" node
• unknown column datatype

Note: catalog prefixes are not supported in this parser.

Datatype

A column datatype may be specified either as a TAP or a VOTable datatype. Thus, the type of specification must be given with the attribute xsi:type of the node "dataType". For instance:

• <dataType xsi:type="vs:VOTableType" arraysize="1">float</dataType> for a VOTable datatype
• <dataType xsi:type="vod:TAPType">VARCHAR</dataType> for a TAP datatype

WARNING: When a vod:TAPType is set to BOOLEAN, this will be interpreted as a SMALLINT. Note that this is a convenient hack because BOOLEAN is not a valid TAPType, but it is however used a lot of time by TAP implementors.

Since:

2.0

Version:

2.3 (04/2018)

Author:

Grégory Mantelet (ARI)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	TableSetParser.ForeignKey Intermediary representation of a Foreign Key.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	VODATASERVICE_NAMESPACE XML namespace for the XML schema VODataService.
protected static java.lang.String	XSI_NAMESPACE XML namespace for the XML schema XMLSchema-instance.

Constructor Summary

Constructors

Constructor and Description
TableSetParser()

Method Summary

Modifier and Type	Method and Description
protected java.lang.String	getPosition(javax.xml.stream.XMLStreamReader reader) Get the current position of the given reader.
protected java.lang.String	getText(javax.xml.stream.XMLStreamReader reader) Get the text of the current node.
protected void	goToEndTag(javax.xml.stream.XMLStreamReader reader, java.lang.String startNode) Skip all tags from the current position to the end of the specified node.
protected int	nextTag(javax.xml.stream.XMLStreamReader reader) Skip every elements until a START ELEMENT or an END ELEMENT is reached.
TAPMetadata	parse(java.io.File file) Parse the XML TableSet stored in the specified file.
TAPMetadata	parse(java.io.InputStream input) Parse the XML TableSet stored in the given stream.
protected TAPColumn	parseColumn(javax.xml.stream.XMLStreamReader reader) Parse the XML representation of a TAP column.
protected DBType	parseDataType(javax.xml.stream.XMLStreamReader reader) Parse the XML representation of a column datatype.
protected TableSetParser.ForeignKey	parseFKey(javax.xml.stream.XMLStreamReader reader) Parse the XML representation of a TAP foreign key.
protected TAPSchema	parseSchema(javax.xml.stream.XMLStreamReader reader, java.util.List<TableSetParser.ForeignKey> allForeignKeys) Parse the XML representation of a TAP schema.
protected TAPTable	parseTable(javax.xml.stream.XMLStreamReader reader, java.util.List<TableSetParser.ForeignKey> keys) Parse the XML representation of a TAP table.
protected TAPTable	searchTable(java.lang.String tableName, TAPMetadata meta, java.lang.String position) Search for the specified table in the given TAP metadata.

Methods inherited from class org.xml.sax.helpers.DefaultHandler

characters, endDocument, endElement, endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Field Detail

XSI_NAMESPACE

protected static final java.lang.String XSI_NAMESPACE

XML namespace for the XML schema XMLSchema-instance.

See Also:

Constant Field Values

VODATASERVICE_NAMESPACE

protected static final java.lang.String VODATASERVICE_NAMESPACE

XML namespace for the XML schema VODataService.

See Also:

Constant Field Values

Constructor Detail

TableSetParser

public TableSetParser()

Method Detail

parse

public TAPMetadata parse(java.io.File file)
                  throws java.io.IOException,
                         TAPException

Parse the XML TableSet stored in the specified file.

Parameters:

file - The regular file containing the TableSet to parse.

Returns:

The corresponding TAP metadata.

Throws:

java.io.IOException - If any error occurs while reading the given file.

TAPException - If any error occurs in the XML parsing or in the TAP metadata creation.

Since:

parse(InputStream)

parse

public TAPMetadata parse(java.io.InputStream input)
                  throws java.io.IOException,
                         TAPException

Parse the XML TableSet stored in the given stream.

Parameters:

input - The stream containing the TableSet to parse.

Returns:

The corresponding TAP metadata.

Throws:

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

TAPException - If any error occurs in the XML parsing or in the TAP metadata creation.

See Also:

parseSchema(XMLStreamReader, List)

parseSchema

protected TAPSchema parseSchema(javax.xml.stream.XMLStreamReader reader,
                                java.util.List<TableSetParser.ForeignKey> allForeignKeys)
                         throws javax.xml.stream.XMLStreamException,
                                TAPException

Parse the XML representation of a TAP schema.

Important: This function MUST be called just after the start element "schema" has been read!

Attributes

No attribute is expected in the start element "schema".

Children

Only the following nodes are taken into account ; the others are ignored:

• name REQUIRED
• description {0..1}
• title {0..1}
• utype {0..1}
• table {*}

Parameters:

reader - XML reader.

allForeignKeys - List to fill with all encountered foreign keys. note: these keys are not the final TAP meta, but a collection of all information found in the XML document. The final TAP meta will be created later, once all available tables and columns are available.

Returns:

The corresponding TAP schema.

Throws:

java.lang.IllegalStateException - If this function is called while the reader has not just read the START ELEMENT tag of "table".

javax.xml.stream.XMLStreamException - If there is an error processing the underlying XML source.

TAPException - If several "name" nodes are found, or if none such node is found ; exactly one "name" node must be found.

See Also:

parseTable(XMLStreamReader, List)

parseTable

protected TAPTable parseTable(javax.xml.stream.XMLStreamReader reader,
                              java.util.List<TableSetParser.ForeignKey> keys)
                       throws javax.xml.stream.XMLStreamException,
                              TAPException

Parse the XML representation of a TAP table.

Important: This function MUST be called just after the start element "table" has been read!

Attributes

The attribute "type" may be provided in the start element "table". One of the following value is expected:

• base_table or table
• output
• view

Children

Only the following nodes are taken into account ; the others are ignored:

• name REQUIRED
• description {0..1}
• title {0..1}
• utype {0..1}
• column {*}
• foreignKey {*}

Parameters:

reader - XML reader.

keys - List to fill with all encountered foreign keys. note: these keys are not the final TAP meta, but a collection of all information found in the XML document. The final TAP meta will be created later, once all available tables and columns are available.

Returns:

The corresponding TAP table.

Throws:

javax.xml.stream.XMLStreamException - If there is an error processing the underlying XML source.

TAPException - If several "name" nodes are found, or if none such node is found ; exactly one "name" node must be found.

java.lang.IllegalStateException - If this function is called while the reader has not just read the START ELEMENT tag of "table".

See Also:

parseColumn(XMLStreamReader), parseFKey(XMLStreamReader)

parseColumn

protected TAPColumn parseColumn(javax.xml.stream.XMLStreamReader reader)
                         throws javax.xml.stream.XMLStreamException,
                                TAPException

Parse the XML representation of a TAP column.

Important: This function MUST be called just after the start element "column" has been read!

Attributes

The attribute "std" may be provided in the start element "column". One of the following value is expected:

• false (default value if the attribute is omitted)
• true

Children

Only the following nodes are taken into account ; the others are ignored:

• name REQUIRED
• description {0..1}
• ucd {0..1}
• unit {0..1}
• utype {0..1}
• dataType {0..1}
• flag {*}, but only the values 'nullable', 'indexed' and 'primary' are currently supported by the library)

Parameters:

reader - XML reader.

Returns:

The corresponding TAP column.

Throws:

javax.xml.stream.XMLStreamException - If there is an error processing the underlying XML source.

TAPException - If several "name" nodes are found, or if none such node is found ; exactly one "name" node must be found.

java.lang.IllegalStateException - If this function is called while the reader has not just read the START ELEMENT tag of "column".

See Also:

parseDataType(XMLStreamReader)

parseDataType

protected DBType parseDataType(javax.xml.stream.XMLStreamReader reader)
                        throws javax.xml.stream.XMLStreamException,
                               TAPException

Parse the XML representation of a column datatype.

Important: This function MUST be called just after the start element "dataType" has been read!

Attributes

The attribute "xsi:type" (where xsi = http://www.w3.org/2001/XMLSchema-instance) MUST be provided. Only the following values are supported and accepted (below, vs = http://www.ivoa.net/xml/VODataService):

• vs:VOTableType, and the following attributes may be also provided:
  • arraysize
  • xtype
• vs:TAPType, and the attribute "size" may be also provided

Children

No child, but a text MUST be provided. Its value depends of the attribute "xsi:type": a VOTable datatype (e.g. char, float, short) if "xsi:type=vs:VOTableType", or a TAP type (e.g. VARCHAR, REAL, SMALLINT) if "xsi:type=vs:TAPType". Any other value will be rejected.

IMPORTANT: All VOTable datatypes will be converted into TAPType automatically by the library.

Parameters:

reader - XML reader.

Returns:

The corresponding column datatype.

Throws:

javax.xml.stream.XMLStreamException - If there is an error processing the underlying XML source.

TAPException - If the attribute "xsi:type" is missing or incorrect, or if the datatype is unknown or not supported.

java.lang.IllegalStateException - If this function is called while the reader has not just read the START ELEMENT tag of "dataType".

See Also:

VOTableIterator.resolveVotType(String, String, String), DBType.DBType(DBDatatype, int)

parseFKey

protected TableSetParser.ForeignKey parseFKey(javax.xml.stream.XMLStreamReader reader)
                                       throws javax.xml.stream.XMLStreamException,
                                              TAPException

Parse the XML representation of a TAP foreign key.

Important: This function MUST be called just after the start element "foreignKey" has been read!

Attributes

No attribute is expected in the start element "foreignKey".

Children

Only the following nodes are taken into account ; the others are ignored:

• targetTable REQUIRED
• description {0..1}
• utype {0..1}
• fkColumn {1..*}
  • fromColumn REQUIRED
  • targetColumn REQUIRED

Parameters:

reader - XML reader.

Returns:

An object containing all information found in the XML node about the foreign key.

Throws:

javax.xml.stream.XMLStreamException - If there is an error processing the underlying XML source.

TAPException - If "targetTable" node is missing, or if no "fkColumn" is provided.

java.lang.IllegalStateException - If this function is called while the reader has not just read the START ELEMENT tag of "foreignKey".

See Also:

parseDataType(XMLStreamReader)

getPosition

protected final java.lang.String getPosition(javax.xml.stream.XMLStreamReader reader)

Get the current position of the given reader.

This position is returned as a string having the following syntax: "[l.x,c.y]" (where x is the line number and y the column number ; x and y start at 1 ; x and y are both -1 if the end of the XML document has been reached).

Note: The column position is generally just after the read element (node start/end tag, characters). However, with CHARACTERS items, this column position may be 2 characters after the real end.

Parameters:

reader - XML reader whose the current position must be returned.

Returns:

A string representing the current reader position.

nextTag

protected final int nextTag(javax.xml.stream.XMLStreamReader reader)
                     throws javax.xml.stream.XMLStreamException

Skip every elements until a START ELEMENT or an END ELEMENT is reached.

Parameters:

reader - XML reader.

Returns:

The event of the last read tag. Here, either XMLStreamConstants.START_ELEMENT or XMLStreamConstants.END_ELEMENT.

Throws:

javax.xml.stream.XMLStreamException - If there is an error processing the underlying XML source.

goToEndTag

protected final void goToEndTag(javax.xml.stream.XMLStreamReader reader,
                                java.lang.String startNode)
                         throws javax.xml.stream.XMLStreamException,
                                TAPException

Skip all tags from the current position to the end of the specified node.

IMPORTANT: This function MUST be called ONLY IF the reader is inside the node whose the end tag is searched. It may be in a child of this node or not, but the most important is to be inside it.

Note: No tag will be read if the given startNode is NULL or an empty string.

Parameters:

reader - XML reader.

startNode - Name of the node whose the end must be reached.

Throws:

javax.xml.stream.XMLStreamException - If there is an error processing the underlying XML source.

TAPException - If the name of the only corresponding end element does not match the given one, or if the END ELEMENT can not be found (2 possible reasons for that: 1/ malformed XML document, 2/ this function has been called before the START ELEMENT has been read).

getText

protected final java.lang.String getText(javax.xml.stream.XMLStreamReader reader)
                                  throws javax.xml.stream.XMLStreamException

Get the text of the current node.

This function iterates while the next tags are of type CHARACTERS. Consequently, the next tag (start or end element) is already read when returning this function.

All CHARACTERS elements are concatenated. All leading and trailing space characters (\r \n \t and ' ') of every lines are deleted ; only the last or the first \n or \r are kept.

Note: This function is also skipping all COMMENT elements. This is particularly useful if a COMMENT is splitting a node text content ; in such case, the comment is ignored and both divided text are concatenated.

Parameters:

reader - XML reader.

Returns:

The whole text content of the current node.

Throws:

javax.xml.stream.XMLStreamException - If there is an error processing the underlying XML source.

searchTable

protected final TAPTable searchTable(java.lang.String tableName,
                                     TAPMetadata meta,
                                     java.lang.String position)
                              throws TAPException

Search for the specified table in the given TAP metadata.

Note: This function is not case sensitive.

Parameters:

tableName - Name of the table to search. The table name MAY be prefixed by a schema name (e.g. "mySchema.myTable").

meta - All fetched TAP metadata.

position - Position of the table name in the XML document. This parameter is ONLY used in case of error.

Returns:

The corresponding TAP table.

Throws:

TAPException - If the table name syntax ([schema.]table) is incorrect, or if several tables match to the specified table name (which is not prefixed by a schema name), or if no match can be found.