uk.ac.starlink.hapi

## Class HapiService

- java.lang.Object
- - uk.ac.starlink.hapi.HapiService

-     public class HapiService
      extends java.lang.Object

  Encapsulates an HTTP(S) URL that serves the HAPI protocol.
  Since:
    11 Jan 2024

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `HapiService(java.lang.String url)` Constructor with default content coding.
    `HapiService(java.lang.String url, java.util.function.Supplier<ContentCoding> codingSupplier)` Constructor with configurable content coding.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.net.URL` | `createQuery(HapiEndpoint endpoint, java.util.Map<java.lang.String,java.lang.String> requestParams)` Returns a URL representing a query to a given endpoint of this service with specified parameters.
    `boolean` | `equals(java.lang.Object o)`
    `static java.util.Map<java.lang.String,java.lang.String>` | `getRequestParameters(java.net.URL hapiUrl)` Parses a HAPI request URL to return a name-value map giving the request parameters.
    `int` | `hashCode()`
    `java.io.InputStream` | `openChunkedStream(java.net.URL url, int chunkLimit, IOConsumer<java.lang.String> limitCallback)` Opens an input stream from for a HAPI data request that may be broken into several chunks if it encounters a HAPI 1408 "Bad request - too much time or data requested" response.
    `java.io.InputStream` | `openStream(java.net.URL url)` Reads an input stream for a URL pointing at this service.
    `org.json.JSONObject` | `readJson(HapiEndpoint endpoint)` Reads a JSON object from an endpoint of this service with no additional request parameters.
    `org.json.JSONObject` | `readJson(HapiEndpoint endpoint, java.util.Map<java.lang.String,java.lang.String> requestParams)` Reads a JSON object from an endpoint of this service with supplied additional request parameters.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### HapiService

          public HapiService(java.lang.String url)
                      throws java.net.MalformedURLException

      Constructor with default content coding.
      Parameters:
        `url` - service base URL, with or without trailing slash
      Throws:
        `java.net.MalformedURLException` - if it's not an HTTP or HTTPS URL

    - #### HapiService

          public HapiService(java.lang.String url,
                             java.util.function.Supplier<ContentCoding> codingSupplier)
                      throws java.net.MalformedURLException

      Constructor with configurable content coding.
      Parameters:
        `url` - service base URL, with or without trailing slash
        `codingSupplier` - supplier for content coding, or null for default
      Throws:
        `java.net.MalformedURLException` - if it's not an HTTP or HTTPS URL

  - ### Method Detail

    - #### createQuery

          public java.net.URL createQuery(HapiEndpoint endpoint,
                                          java.util.Map<java.lang.String,java.lang.String> requestParams)

      Returns a URL representing a query to a given endpoint of this service with specified parameters.
      Parameters:
        `endpoint` - endpoint
        `requestParams` - map of key-value pairs giving additional request parameters
      Returns:
        URL for query

    - #### openStream

          public java.io.InputStream openStream(java.net.URL url)
                                         throws java.io.IOException

      Reads an input stream for a URL pointing at this service. This is a drop-in replacement for `URL.openStream()`, but handles a few extras like service-sensitive logging, HTTP-level compression and 3xx indirection.
      Parameters:
        `url` - URL
      Returns:
        stream from URL
      Throws:
        `java.io.IOException`

    - #### openChunkedStream

          public java.io.InputStream openChunkedStream(java.net.URL url,
                                                       int chunkLimit,
                                                       IOConsumer<java.lang.String> limitCallback)
                                                throws java.io.IOException

      Opens an input stream from for a HAPI data request that may be broken into several chunks if it encounters a HAPI 1408 "Bad request - too much time or data requested" response.

      A limit must be supplied for the maximum number of chunks that will be retrieved for a given request. If this limit is exceeded, behaviour depends on the supplied `failOnLimit` flag. If true, then such a request fails with an IOException. If false, the input stream includes all the data from the maximum number of chunks, and a WARNING is issued through the logging system to indicate that not the whole stream was included.

      Parameters:
        `url` - HAPI request URL
        `chunkLimit` - the maximum number of chunks permitted
        `limitCallback` - called with message if chunk limit is exceeded; may be null
      Throws:
        `java.io.IOException`

    - #### readJson

          public org.json.JSONObject readJson(HapiEndpoint endpoint)
                                       throws java.io.IOException

      Reads a JSON object from an endpoint of this service with no additional request parameters.
      Parameters:
        `endpoint` - endpoint
      Returns:
        JSONobject read from endpoint
      Throws:
        `java.io.IOException`

    - #### readJson

          public org.json.JSONObject readJson(HapiEndpoint endpoint,
                                              java.util.Map<java.lang.String,java.lang.String> requestParams)
                                       throws java.io.IOException

      Reads a JSON object from an endpoint of this service with supplied additional request parameters.
      Parameters:
        `endpoint` - endpoint
        `requestParams` - map of key-value pairs giving additional request parameters
      Returns:
        JSONobject read from endpoint
      Throws:
        `java.io.IOException`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### getRequestParameters

          public static java.util.Map<java.lang.String,java.lang.String> getRequestParameters(java.net.URL hapiUrl)

      Parses a HAPI request URL to return a name-value map giving the request parameters.
      Parameters:
        `hapiUrl` - URL
      Returns:
        name-value map for query parameter assignments in URL query part