Package uk.ac.starlink.vo.datalink

## Class ServiceInvoker

- java.lang.Object
- - uk.ac.starlink.vo.datalink.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 `ServiceParam`s 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