Package uk.ac.starlink.vo.datalink
Class LinksDoc
- java.lang.Object
-
- uk.ac.starlink.vo.datalink.LinksDoc
-
public abstract class LinksDoc extends java.lang.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.0
" - 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
- returned from a service with standardID
"
-
-
Constructor Summary
Constructors Constructor Description LinksDoc()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description static LinksDoc
createLinksDoc(uk.ac.starlink.table.StarTable table)
Returns a LinksDoc based on a supplied table.static LinksDoc
createLinksDoc(uk.ac.starlink.table.StarTable resultTable, LinkColMap colMap, uk.ac.starlink.votable.datalink.ServiceDescriptor[] servDescriptors)
Creates a LinksDoc with fixed members.static LinksDoc
createLinksDoc(uk.ac.starlink.votable.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 uk.ac.starlink.table.StarTable
getResultTable()
Returns the results table.abstract uk.ac.starlink.votable.datalink.ServiceDescriptor[]
getServiceDescriptors()
Returns a list of the ServiceDescriptor objects defined by RESOURCES with @type="meta" and @utype="adhoc:service".static uk.ac.starlink.votable.datalink.ServiceDescriptor[]
getServiceDescriptors(uk.ac.starlink.table.StarTable table)
Utility method to extract a list of service descriptors associated with a given StarTable.static boolean
isLinksResponse(uk.ac.starlink.table.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.
-
-
-
Method Detail
-
getResultTable
public abstract uk.ac.starlink.table.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 uk.ac.starlink.votable.datalink.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(uk.ac.starlink.table.StarTable resultTable, LinkColMap colMap, uk.ac.starlink.votable.datalink.ServiceDescriptor[] servDescriptors)
Creates a LinksDoc with fixed members.- Parameters:
resultTable
- results tablecolMap
- object that understands which columns mean what in theresultTable
servDescriptors
- list of service descriptor objects associated with the table
-
createLinksDoc
public static LinksDoc createLinksDoc(uk.ac.starlink.table.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(uk.ac.starlink.votable.VOElement el) throws java.io.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:
java.io.IOException
- if the element structure does not contain a unique results table
-
randomAccess
public static LinksDoc randomAccess(LinksDoc ldoc) throws java.io.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:
java.io.IOException
-
getServiceDescriptors
public static uk.ac.starlink.votable.datalink.ServiceDescriptor[] getServiceDescriptors(uk.ac.starlink.table.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(uk.ac.starlink.table.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 inLinkColMap.COLDEF_MAP
). If the number of missing/incorrect columns does not exceed a given tolerance, and at least one of the columnsaccess_url
,error_message
andservice_def
is present and usable, true is returned.- Parameters:
table
- table to testnMistake
- 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
-
-