org.hapiserver

Class HapiClient

java.lang.Object

org.hapiserver.HapiClient

public class HapiClient
extends java.lang.Object

Utility classes for interacting with a HAPI server. JSON responses are presented using JSON, and data responses are record-by-record.

Method Summary

Modifier and Type	Method and Description
protected static long	cacheAgeLimitMillis() allow cached files to be used for no more than 1 hour.
static int	dayOfYear(int year, int month, int day) return the doy of year of the month and day for the year.
static org.json.JSONObject	getCatalog(java.net.URL server) return the catalog as a JSONObject.
static java.lang.String[]	getCatalogIdsArray(java.net.URL server) return the catalog as a String array.
static java.util.Iterator<HapiRecord>	getData(java.net.URL server, java.lang.String id, java.lang.String startTime, java.lang.String endTime) return the data record-by-record
static java.util.Iterator<HapiRecord>	getData(java.net.URL server, java.lang.String id, java.lang.String parameters, java.lang.String startTime, java.lang.String endTime) return the data record-by-record
static java.util.Iterator<HapiRecord>	getDataCSV(java.net.URL server, java.lang.String id, java.lang.String startTime, java.lang.String endTime) return the data record-by-record, using the CSV response.
static java.util.Iterator<HapiRecord>	getDataCSV(java.net.URL server, java.lang.String id, java.lang.String parameters, java.lang.String startTime, java.lang.String endTime) return the data record-by-record, using the CSV response.
static org.json.JSONObject	getInfo(java.net.URL server, java.lang.String id) get the info for the id
static JSONObject	getInfo(java.net.URL server, java.lang.String id, java.lang.String parameters) get the info for the id, for a subset of the parameters.
static java.lang.String[]	getInfoParametersArray(java.net.URL server, java.lang.String id) return a list of the parameters for the id, as a String array.
static int[]	isoTimeToArray(java.lang.String time) return array [ year, months, days, hours, minutes, seconds, nanoseconds ]
static java.lang.String	readFromCachedURL(java.net.URL url, java.lang.String type) return the resource, if cached, or null if the data is not cached.
static java.lang.String	readFromFile(java.io.File f) read the file into a string.
static java.lang.String	readFromURL(java.net.URL url, java.lang.String type) read data from the URL.
static long	toMillisecondsSince1970(java.lang.String time) return the time as milliseconds since 1970-01-01T00:00Z.
protected static boolean	useCache() use cache of HAPI responses, to allow for use in offline mode.
static void	writeToCachedURL(java.net.URL url, java.lang.String type, java.lang.String data) write the data (for example, an info response) to a cache file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

useCache

protected static boolean useCache()

use cache of HAPI responses, to allow for use in offline mode.

Returns:

cacheAgeLimitMillis

protected static long cacheAgeLimitMillis()

allow cached files to be used for no more than 1 hour.

Returns:

readFromFile

public static java.lang.String readFromFile(java.io.File f)
                                     throws java.io.IOException

read the file into a string.

Parameters:

f - non-empty file

Returns:

String containing file contents.

Throws:

java.io.IOException

readFromCachedURL

public static java.lang.String readFromCachedURL(java.net.URL url,
                                                 java.lang.String type)
                                          throws java.io.IOException

return the resource, if cached, or null if the data is not cached.

Parameters:

url -

type - "json" (the extension) or "" for no additional extension.

Returns:

the data or null.

Throws:

java.io.IOException

writeToCachedURL

public static void writeToCachedURL(java.net.URL url,
                                    java.lang.String type,
                                    java.lang.String data)
                             throws java.io.IOException

write the data (for example, an info response) to a cache file. This is called from readFromURL to cache the data.

Parameters:

url - the resource location, query param id is handled specially, but others are ignored.

type - "json" (the extension), or "" if no extension should be added.

data - the data.

Throws:

java.io.IOException

readFromURL

public static java.lang.String readFromURL(java.net.URL url,
                                           java.lang.String type)
                                    throws java.io.IOException

read data from the URL.

Parameters:

url - the URL to read from

type - the extension to use for the cache file (JSON, bin, txt).

Returns:

non-empty string

Throws:

java.io.IOException

getCatalog

public static org.json.JSONObject getCatalog(java.net.URL server)
                                      throws java.io.IOException,
                                             JSONException

return the catalog as a JSONObject. For example:

 jo= getCatalog( URL( "https://jfaden.net/HapiServerDemo/hapi/catalog" ) )
 print jo.get('HAPI') # "2.0"
 catalog= jo.getJSONArray( 'catalog' )
 for i in range(catalog.length()):
    print catalog.getJSONObject(i).get('id')
 

Parameters:

server -

Returns:

Throws:

java.io.IOException

org.json.JSONException

JSONException

See Also:

getCatalogIdsArray(java.net.URL)

getCatalogIdsArray

public static java.lang.String[] getCatalogIdsArray(java.net.URL server)
                                             throws java.io.IOException,
                                                    JSONException

return the catalog as a String array.

 catalog= getCatalogIdsArray( URL( "https://jfaden.net/HapiServerDemo/hapi/catalog" ) )
 for s in catalog:
    print s
 

Parameters:

server -

Returns:

Throws:

java.io.IOException

JSONException

getInfo

public static org.json.JSONObject getInfo(java.net.URL server,
                                          java.lang.String id)
                                   throws java.io.IOException,
                                          JSONException

get the info for the id

Parameters:

server -

id - HAPI dataset identifier, matching [a-zA-Z_]+[a-zA-Z0-9_/]*

Returns:

the JSON for info

Throws:

java.io.IOException

org.json.JSONException

JSONException

getInfo

public static JSONObject getInfo(java.net.URL server,
                                 java.lang.String id,
                                 java.lang.String parameters)
                          throws java.io.IOException,
                                 JSONException

get the info for the id, for a subset of the parameters.

Parameters:

server -

id - HAPI dataset identifier, matching [a-zA-Z_]+[a-zA-Z0-9_/]*

parameters - comma-separated list of parameter names.

Returns:

the JSON for info

Throws:

java.io.IOException

org.json.JSONException

JSONException

getInfoParametersArray

public static java.lang.String[] getInfoParametersArray(java.net.URL server,
                                                        java.lang.String id)
                                                 throws java.io.IOException,
                                                        JSONException

return a list of the parameters for the id, as a String array.

Parameters:

server -

id -

Returns:

Throws:

java.io.IOException

JSONException

See Also:

getInfo(java.net.URL, java.lang.String)

getDataCSV

public static java.util.Iterator<HapiRecord> getDataCSV(java.net.URL server,
                                                        java.lang.String id,
                                                        java.lang.String startTime,
                                                        java.lang.String endTime)
                                                 throws java.io.IOException,
                                                        JSONException

return the data record-by-record, using the CSV response.

Parameters:

server -

id -

startTime -

endTime -

Returns:

Iterator, which will return records until the stream is empty.

Throws:

java.io.IOException

org.json.JSONException - should the server return an invalid response.

JSONException

getDataCSV

public static java.util.Iterator<HapiRecord> getDataCSV(java.net.URL server,
                                                        java.lang.String id,
                                                        java.lang.String parameters,
                                                        java.lang.String startTime,
                                                        java.lang.String endTime)
                                                 throws java.io.IOException,
                                                        JSONException

return the data record-by-record, using the CSV response.

Parameters:

server -

id -

parameters -

startTime -

endTime -

Returns:

Iterator, which will return records until the stream is empty.

Throws:

java.io.IOException

org.json.JSONException - should the server return an invalid response.

JSONException

getData

public static java.util.Iterator<HapiRecord> getData(java.net.URL server,
                                                     java.lang.String id,
                                                     java.lang.String startTime,
                                                     java.lang.String endTime)
                                              throws java.io.IOException,
                                                     JSONException

return the data record-by-record

Parameters:

server - the HAPI server

id - the dataset id

startTime - the start time

endTime - the end time

Returns:

the records in an iterator

Throws:

java.io.IOException

org.json.JSONException - should the server return an invalid response

JSONException

getData

public static java.util.Iterator<HapiRecord> getData(java.net.URL server,
                                                     java.lang.String id,
                                                     java.lang.String parameters,
                                                     java.lang.String startTime,
                                                     java.lang.String endTime)
                                              throws java.io.IOException,
                                                     JSONException

return the data record-by-record

Parameters:

server - the HAPI server

id - the dataset id

parameters - a comma-separated list of parameter names

startTime - the start time

endTime - the end time

Returns:

the records in an iterator

Throws:

java.io.IOException

org.json.JSONException - should the server return an invalid response

JSONException

toMillisecondsSince1970

public static long toMillisecondsSince1970(java.lang.String time)

return the time as milliseconds since 1970-01-01T00:00Z. This does not include leap seconds. For example, in Jython:

 
 from org.hapiserver.HapiClient import *
 x= toMillisecondsSince1970('2000-01-02T00:00:00.0Z')
 print x / 86400000   # 10958.0 days
 print x % 86400000   # and no milliseconds
 
 

Parameters:

time -

Returns:

number of non-leap-second milliseconds since 1970-01-01T00:00Z.

dayOfYear

public static int dayOfYear(int year,
                            int month,
                            int day)

return the doy of year of the month and day for the year. For example,

 
 from org.hapiserver.HapiClient import *
 print dayOfYear( 2000, 5, 29 ) # 150
 
 

Parameters:

year - the year

month - the month, from 1 to 12.

day - the day in the month.

Returns:

the day of year.

isoTimeToArray

public static int[] isoTimeToArray(java.lang.String time)

return array [ year, months, days, hours, minutes, seconds, nanoseconds ]

Parameters:

time -

Returns:

the decomposed time