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

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