# 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
Description
`LinksDoc()`

## Method Summary

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.

### Methods inherited from class Object

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

## Constructor Details

### LinksDoc

public LinksDoc()

## Method Details

### 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 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(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 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 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 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