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
  See Also:
    HAPI 3.1.0 Sec 3.6.2

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static HapiInfo` | `fromCommentedStream(java.io.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.
    `java.lang.String` | `getCadence()` Returns the approximate cadence of records for this dataset.
    `java.lang.String` | `getFormat()` Returns the data format.
    `HapiVersion` | `getHapiVersion()` Returns the HAPI version.
    `java.lang.String` | `getMaxRequestDuration()` Returns the maximum allowed duration for a request.
    `java.lang.String` | `getMetadata(java.lang.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.
    `java.lang.String` | `getResourceUrl()` Returns the resource URL with additional information about the dataset.
    `java.lang.String` | `getSampleStartDate()` Returns the sample start date if available.
    `java.lang.String` | `getSampleStopDate()` Returns the sample stop date if available.
    `java.lang.String` | `getStartDate()` Returns the start date for this dataset.
    `java.lang.String` | `getStopDate()` Returns the end date for this dataset.
    `static java.lang.String` | `readCommentedText(java.io.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

          java.lang.String getStartDate()

      Returns the start date for this dataset.
      Returns:
        start date string, expected to be in Restricted ISO-8601 format

    - #### getStopDate

          java.lang.String getStopDate()

      Returns the end date for this dataset.
      Returns:
        stop date string, expected to be in Restricted ISO-8601 format

    - #### getFormat

          java.lang.String getFormat()

      Returns the data format.
      Returns:
        data format

    - #### getResourceUrl

          java.lang.String getResourceUrl()

      Returns the resource URL with additional information about the dataset.
      Returns:
        resource URL

    - #### getCadence

          java.lang.String getCadence()

      Returns the approximate cadence of records for this dataset.
      Returns:
        cadence string, expected to be as an ISO 8601 duration

    - #### getMaxRequestDuration

          java.lang.String getMaxRequestDuration()

      Returns the maximum allowed duration for a request.
      Returns:
        maximum request, expected to be as an ISO 8601 duration

    - #### getSampleStartDate

          java.lang.String getSampleStartDate()

      Returns the sample start date if available.
      Returns:
        sample start date, expected to be restricted ISO 8601

    - #### getSampleStopDate

          java.lang.String getSampleStopDate()

      Returns the sample stop date if available.
      Returns:
        sample stop date, expected to be restricted ISO 8601

    - #### getMetadata

          java.lang.String getMetadata(java.lang.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(java.io.InputStream in,
                                              int[] overread1)
                                       throws java.io.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:
        `java.io.IOException`

    - #### readCommentedText

          static java.lang.String readCommentedText(java.io.InputStream in,
                                                    int[] overread1)
                                             throws java.io.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:
        `java.io.IOException`