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
     
  • 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
    Returns an object that knows where the DataLink-defined columns are in this document's table.
    abstract uk.ac.starlink.table.StarTable
    Returns the results table.
    abstract uk.ac.starlink.votable.datalink.ServiceDescriptor[]
    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
    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 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