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

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

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