uk.ac.starlink.hapi

Interface HapiInfo

public interface HapiInfo

Models the HAPI Info response object, as obtained from the info endpoint. Except where noted, the return values may be null.

Since:

11 Jan 2024

Author:

Mark Taylor

See Also:

HAPI 3.1.0 Sec 3.6.2

Method Summary

Modifier and Type	Method and Description
static HapiInfo	fromCommentedStream(InputStream in, int[] overread1) Reads a HapiInfo object from an input stream containing a JSON object with "#" signs at the start of lines, as per the HAPI data response when it includes a header.
static HapiInfo	fromJson(org.json.JSONObject json) Reads HapiInfo from a HAPI Info response JSON object.
String	getCadence() Returns the approximate cadence of records for this dataset.
String	getFormat() Returns the data format.
HapiVersion	getHapiVersion() Returns the HAPI version.
String	getMaxRequestDuration() Returns the maximum allowed duration for a request.
String	getMetadata(String key) Returns any other string-typed metadata item provided by the info object.
HapiParam[]	getParameters() Returns the parameters (table columns) associated with the dataset.
String	getResourceUrl() Returns the resource URL with additional information about the dataset.
String	getSampleStartDate() Returns the sample start date if available.
String	getSampleStopDate() Returns the sample stop date if available.
String	getStartDate() Returns the start date for this dataset.
String	getStopDate() Returns the end date for this dataset.
static String	readCommentedText(InputStream in, int[] overread1) Reads all the commented lines at the start of a stream, storing the first byte of the uncommented part in a supplied buffer.

Method Detail

getHapiVersion

HapiVersion getHapiVersion()

Returns the HAPI version.

Returns:

version object, not null

getParameters

HapiParam[] getParameters()

Returns the parameters (table columns) associated with the dataset.

Returns:

parameter array, not null

getStartDate

String getStartDate()

Returns the start date for this dataset.

Returns:

start date string, expected to be in Restricted ISO-8601 format

getStopDate

String getStopDate()

Returns the end date for this dataset.

Returns:

stop date string, expected to be in Restricted ISO-8601 format

getFormat

String getFormat()

Returns the data format.

Returns:

data format

getResourceUrl

String getResourceUrl()

Returns the resource URL with additional information about the dataset.

Returns:

resource URL

getCadence

String getCadence()

Returns the approximate cadence of records for this dataset.

Returns:

cadence string, expected to be as an ISO 8601 duration

getMaxRequestDuration

String getMaxRequestDuration()

Returns the maximum allowed duration for a request.

Returns:

maximum request, expected to be as an ISO 8601 duration

getSampleStartDate

String getSampleStartDate()

Returns the sample start date if available.

Returns:

sample start date, expected to be restricted ISO 8601

getSampleStopDate

String getSampleStopDate()

Returns the sample stop date if available.

Returns:

sample stop date, expected to be restricted ISO 8601

getMetadata

String getMetadata(String key)

Returns any other string-typed metadata item provided by the info object.

Parameters:

key - name of entry in Info structure JSON object

Returns:

value of entry if present and string-like

fromJson

static HapiInfo fromJson(org.json.JSONObject json)

Reads HapiInfo from a HAPI Info response JSON object.

Parameters:

json - JSON object

Returns:

info object, not null

fromCommentedStream

static HapiInfo fromCommentedStream(InputStream in,
                                    int[] overread1)
                             throws IOException

Reads a HapiInfo object from an input stream containing a JSON object with "#" signs at the start of lines, as per the HAPI data response when it includes a header. When the first non-comment line is encountered, reading stops, so that the rest of the InputStream's content can be read following exit. However, to determine that the comments have ended, the implementation has to read at least one byte from the post-comment part. This byte, if present, is stored in the first element of the supplied overread1 buffer if present. If the end of the file is encounted before any non-comment content, -1 is written to that buffer.

Parameters:

in - stream containing commented JSON

overread1 - buffer for receiving the first non-comment byte, may be null

Returns:

info object, not null

Throws:

IOException

readCommentedText

static String readCommentedText(InputStream in,
                                int[] overread1)
                         throws IOException

Reads all the commented lines at the start of a stream, storing the first byte of the uncommented part in a supplied buffer. Commented lines are those starting with a "#".

This method should be private, but Java 8, unlike Java 9+, does not permit private static methods on interfaces.

Parameters:

in - stream containing commented JSON

overread1 - buffer for receiving the first non-comment byte, may be null

Returns:

string containing comment text without the prefixed "#" characters

Throws:

IOException