Class ServiceInvoker


  • public class ServiceInvoker
    extends java.lang.Object
    Provides functionality related to invoking a service defined by a DataLink document. It is based on a ServiceDescriptor.

    This class divides the input ServiceParams defined by the ServiceDescriptor into three different categories according to how their values are acquired at service invocation time:

    • row parameters: the value is acquired from a cell of the result table; a table row object must be supplied to obtain the value
    • fixed parameters: the value is provided by the parameter definition and fixed for all invocations
    • user parameters: the value must be supplied for each invocation by the user

    The DataLink-1.0 standard is not very explicit about this distinction, but the above division appears(?) to be the consensus of the standard authors. This does not however prevent service invocations filling these parameter values differently than according to the above outline. For instance, users may be given the option to change the values of fixed or row parameters for a given invocation.

    Since:
    22 Nov 2017
    Author:
    Mark Taylor
    See Also:
    DataLink-1.0, sec 4
    • Constructor Summary

      Constructors 
      Constructor Description
      ServiceInvoker​(uk.ac.starlink.votable.datalink.ServiceDescriptor descriptor, uk.ac.starlink.table.StarTable resultTable)
      Attempts to construct an invoker based on a service descriptor and an associated results table.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.net.URL completeUrl​(java.util.Map<uk.ac.starlink.votable.datalink.ServiceParam,​java.lang.String> paramMap)
      Assembles an invocation URL from the base URL of this service and any name-value pairs supplied in a given map.
      java.util.Map<uk.ac.starlink.votable.datalink.ServiceParam,​java.lang.String> getFixedParamMap()
      Returns a parameter-value map for the fixed parameters.
      uk.ac.starlink.votable.datalink.ServiceParam[] getFixedParams()
      Returns the 'fixed' parameters of this service.
      java.util.Map<uk.ac.starlink.votable.datalink.ServiceParam,​java.lang.String> getRowParamMap​(java.lang.Object[] row)
      Constructs a parameter-value map for the row parameters at a given table row.
      uk.ac.starlink.votable.datalink.ServiceParam[] getRowParams()
      Returns the 'row' parameters of this service.
      uk.ac.starlink.votable.datalink.ServiceDescriptor getServiceDescriptor()
      Returns this invoker's service descriptor.
      java.net.URL getUrl​(java.lang.Object[] row, java.util.Map<uk.ac.starlink.votable.datalink.ServiceParam,​java.lang.String> userParamMap)
      Assembles an invocation URL from the base URL of this service, the values of any row parameters corresponding to a supplied table row, and any additional parameters supplied explicitly.
      uk.ac.starlink.votable.datalink.ServiceParam[] getUserParams()
      Returns the 'user' parameters of this service.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • ServiceInvoker

        public ServiceInvoker​(uk.ac.starlink.votable.datalink.ServiceDescriptor descriptor,
                              uk.ac.starlink.table.StarTable resultTable)
                       throws java.net.MalformedURLException,
                              java.io.IOException
        Attempts to construct an invoker based on a service descriptor and an associated results table.
        Parameters:
        descriptor - service descriptor
        resultTable - result table corresponding to the descriptor
        Throws:
        java.net.MalformedURLException - if the descriptor's accessUrl is no good
        java.io.IOException - if the descriptor references a column that is not present in the result table
    • Method Detail

      • getServiceDescriptor

        public uk.ac.starlink.votable.datalink.ServiceDescriptor getServiceDescriptor()
        Returns this invoker's service descriptor.
        Returns:
        service descriptor
      • getRowParams

        public uk.ac.starlink.votable.datalink.ServiceParam[] getRowParams()
        Returns the 'row' parameters of this service. These take their values from one of the columns in the results table.
        Returns:
        list of 'row' parameters
      • getFixedParams

        public uk.ac.starlink.votable.datalink.ServiceParam[] getFixedParams()
        Returns the 'fixed' parameters of this service. These have fixed values supplied in the parameter definitions.
        Returns:
        list of 'fixed' parameters
      • getUserParams

        public uk.ac.starlink.votable.datalink.ServiceParam[] getUserParams()
        Returns the 'user' parameters of this service. The values for these must to be supplied externally in some unspecified way (for instance by user action). They may have some hints in the form of options or min/max values.
        Returns:
        list of 'user' parameters
      • getFixedParamMap

        public java.util.Map<uk.ac.starlink.votable.datalink.ServiceParam,​java.lang.String> getFixedParamMap()
        Returns a parameter-value map for the fixed parameters.
        Returns:
        map containing fixed parameter-value pairs
      • getRowParamMap

        public java.util.Map<uk.ac.starlink.votable.datalink.ServiceParam,​java.lang.String> getRowParamMap​(java.lang.Object[] row)
        Constructs a parameter-value map for the row parameters at a given table row.
        Parameters:
        row - a row of cell values from this invoker's table
        Returns:
        map containing row parameter-value pairs
      • completeUrl

        public java.net.URL completeUrl​(java.util.Map<uk.ac.starlink.votable.datalink.ServiceParam,​java.lang.String> paramMap)
        Assembles an invocation URL from the base URL of this service and any name-value pairs supplied in a given map. Values are appended in the form ?n1=v1&n2=v2.
        Parameters:
        paramMap - map representing parameter values to be appended to this service's base URL
        Returns:
        base URL with supplied parameter name-value pairs appended
      • getUrl

        public java.net.URL getUrl​(java.lang.Object[] row,
                                   java.util.Map<uk.ac.starlink.votable.datalink.ServiceParam,​java.lang.String> userParamMap)
        Assembles an invocation URL from the base URL of this service, the values of any row parameters corresponding to a supplied table row, and any additional parameters supplied explicitly.

        This utility method calls the methods getRowParamMap, getFixedParamMap and completeUrl.

        Parameters:
        row - table row
        userParamMap - additional non-'row' parameter-value pairs, usually corresponding to the 'user' parameters
        Returns:
        base URL with row and user name-value pairs appended