Class 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