uk.ac.starlink.vo.datalink

Class LinksDoc

java.lang.Object

uk.ac.starlink.vo.datalink.LinksDoc

public abstract class LinksDoc
extends Object

Represents the result of a DataLink Links service response. Such documents are usually:

• returned from a service with standardID "ivo://ivoa.net/std/DataLink#links-1.*"
• described by a MIME type "application/x-votable+xml;content=datalink"

An instance of this class gives you what you need to work with a Links service response.

This class simply aggregates three items: the table, column map, and service descriptors. However it also has some static utility methods that are useful for creating and working with datalink tables.

Since:

22 Nov 2017

Author:

Mark Taylor

Constructor Summary

Constructors

Constructor and Description
LinksDoc()

Method Summary

Modifier and Type	Method and Description
static LinksDoc	createLinksDoc(StarTable table) Returns a LinksDoc based on a supplied table.
static LinksDoc	createLinksDoc(StarTable resultTable, LinkColMap colMap, ServiceDescriptor[] servDescriptors) Creates a LinksDoc with fixed members.
static LinksDoc	createLinksDoc(VOElement el) Parses a VOElement as a LinksDoc.
abstract LinkColMap	getColumnMap() Returns an object that knows where the DataLink-defined columns are in this document's table.
abstract StarTable	getResultTable() Returns the results table.
abstract ServiceDescriptor[]	getServiceDescriptors() Returns a list of the ServiceDescriptor objects defined by RESOURCES with @type="meta" and @utype="adhoc:service".
static ServiceDescriptor[]	getServiceDescriptors(StarTable table) Utility method to extract a list of service descriptors associated with a given StarTable.
static boolean	isLinksResponse(StarTable table, int nMistake) Indicates whether the table in question looks like a Links-response table.
static LinksDoc	randomAccess(LinksDoc ldoc) Returns a LinksDoc with the same content as a given one, for which the result table is guaranteed to support random access.

Methods inherited from class java.lang.Object

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

Constructor Detail

LinksDoc

public LinksDoc()

Method Detail

getResultTable

public abstract StarTable getResultTable()

Returns the results table. This is the data table present in the RESOURCE element with @type="results". According to DALI there is only one such results resource is present, and according to DataLink it contains only one table.

Returns:

sole results table

getColumnMap

public abstract LinkColMap getColumnMap()

Returns an object that knows where the DataLink-defined columns are in this document's table.

Returns:

column map

getServiceDescriptors

public abstract ServiceDescriptor[] getServiceDescriptors()

Returns a list of the ServiceDescriptor objects defined by RESOURCES with @type="meta" and @utype="adhoc:service".

Returns:

service descriptor objects

createLinksDoc

public static LinksDoc createLinksDoc(StarTable resultTable,
                                      LinkColMap colMap,
                                      ServiceDescriptor[] servDescriptors)

Creates a LinksDoc with fixed members.

Parameters:

resultTable - results table

colMap - object that understands which columns mean what in the resultTable

servDescriptors - list of service descriptor objects associated with the table

createLinksDoc

public static LinksDoc createLinksDoc(StarTable table)

Returns a LinksDoc based on a supplied table.

There is no guarantee that the result will be represent a useful DataLink document, for instance it may have none of the required DataLink columns.

Parameters:

table - assumed DataLink results table

Returns:

LinksDoc based on table

createLinksDoc

public static LinksDoc createLinksDoc(VOElement el)
                               throws IOException

Parses a VOElement as a LinksDoc. The supplied element will normally be a top-level VOTABLE element.

There is no guarantee that the result will be represent a useful DataLink document, for instance it may have none of the required DataLink columns.

Parameters:

el - VOTable DOM element that contains RESOURCES corresponding to DataLink data and metadata

Returns:

datalink document object

Throws:

IOException - if the element structure does not contain a unique results table

randomAccess

public static LinksDoc randomAccess(LinksDoc ldoc)
                             throws IOException

Returns a LinksDoc with the same content as a given one, for which the result table is guaranteed to support random access.

Parameters:

ldoc - input links doc

Returns:

the input links doc if it's random access, or a copy with a random-access-capable result table otherwise

Throws:

IOException

getServiceDescriptors

public static ServiceDescriptor[] getServiceDescriptors(StarTable table)

Utility method to extract a list of service descriptors associated with a given StarTable. It just goes through the table parameters and chooses all those with ServiceDescriptor-typed values.

Parameters:

table - input table

Returns:

array of service descriptors associated with the table

isLinksResponse

public static boolean isLinksResponse(StarTable table,
                                      int nMistake)

Indicates whether the table in question looks like a Links-response table. A check against name, UCD and datatype is made for all the links-response columns (as listed in LinkColMap.COLDEF_MAP). If the number of missing/incorrect columns does not exceed a given tolerance, and at least one of the columns access_url, error_message and service_def is present and usable, true is returned.

Parameters:

table - table to test

nMistake - maximum number of incorrect/missing columns tolerated; 2 might be a reasonable number?

Returns:

true iff table looks like a usable links-response table within the given tolerance