com.orange.api.session

Class OrangeConnection

java.lang.Object

com.orange.api.session.OrangeConnection

public class OrangeConnection
extends java.lang.Object

Author:

Gulliver Johnson

Constructor Summary

Constructors

Constructor and Description
OrangeConnection() Initialise an unauthenticated connection to retrieve public data

Method Summary

Methods

Modifier and Type	Method and Description
void	close() To be used to securely kill the connection upon process termination.
java.lang.String	getApplication(int global_id) Returns the arbitrary application label for the given sensor ID.
java.lang.String[]	getApplicationList(int[] ids) Returns an array comprised of the application label for each identified sensor.
SensorData[]	getDataBetween(int global_id, java.util.Date start, java.util.Date end) Returns an array of SensorData types, each describing one single reading update sent by the named sensor by both reading and timestamp.
SensorData[]	getDataSince(int global_id, java.util.Date time) Returns an array of SensorData types, each describing one single reading update sent by the named sensor by both reading and timestamp.
java.util.Date	getDateAdded(int global_id) Returns the timestamp for the very first reading received from the identified sensor.
java.util.Date[]	getDateAddedList(int[] ids) Returns a Date array containing the timestamp for each identified sensor's very first received reading.
int[]	getIDsWhere(java.lang.String[] cols, java.lang.String[] args) Returns an array of global_ids filtered by multiple given columns and values.
int[]	getIDsWhere(java.lang.String col, java.lang.String arg) Returns an array of global_ids filtered by a given column matching a value.
int[]	getIDsWhereSince(java.lang.String[] cols, java.lang.String[] args, java.util.Date timestamp) Returns an array of global_ids filtered by a list of columns and values, and a timestamp.
int[]	getIDsWhereSince(java.lang.String col, java.lang.String arg, java.util.Date timestamp) Returns an array of global_ids filtered by both a column with a value and a timestamp.
float	getLastReading(int global_id) Returns the most recently received reading from a given sensor.
float[]	getLastReadingList(int[] ids) Returns an array composed of the most recently received reading from each sensor identified in ids.
java.util.Date	getLastTimestamp(int global_id) Returns the timestamp for the most recently received reading from a given sensor.
java.util.Date[]	getLastTimestampList(int[] ids) Returns an array composed of the timestamp for each identified sensor's latest reading.
double	getLat(int global_id) Returns the latitude of the identified sensor as a double to six decimal places.
SensorData[]	getLatestList(int[] ids) Returns a list of SensorData objects containing the latest reading and timestamp for each named sensor ID.
double[]	getLatList(int[] ids) Returns the latitude of each identified sensor as an element in an array of doubles.
double	getLng(int global_id) Returns the longitude of the identified sensor as a double to six decimal places.
double[]	getLngList(int[] ids) Returns the longitude of each identified sensor as an element in an array of doubles.
java.lang.String	getMeasures(int global_id) Returns the 'measures' attribute for a given sensor ID.
java.lang.String[]	getMeasuresList(int[] ids) Returns an array comprised of the measures attribute for each identified sensor.
Position	getPosition(int global_id) Returns the Position of the identified sensor, containing the global_id with its latitude and longitude.
Position[]	getPositionList(int[] ids) Returns the Positions of the identified sensors as an array.
java.lang.String	getUnit(int global_id) Returns the unit of measurement for the identified sensor.
java.lang.String[]	getUnitList(int[] ids) Returns an array comprised of the unit of measurement for each identified sensor.

Methods inherited from class java.lang.Object

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

Constructor Detail

OrangeConnection

public OrangeConnection()

Initialise an unauthenticated connection to retrieve public data

Method Detail

close

public void close()

To be used to securely kill the connection upon process termination.

getIDsWhere

public int[] getIDsWhere(java.lang.String col,
                java.lang.String arg)

Returns an array of global_ids filtered by a given column matching a value.

Valid columns to query are limited to:

• application - the application label as defined by the sensor's owner
• measures - the physical attribute measured by the sensor. Examples include DISTANCE, TEMPERATURE, LIGHT, and ACCELERATION.
• unit - the unit of the stored readings. Examples include "cm", "kelvin", and "m/s^2"

Other methods must be used if filtering by a non-text column.

Parameters:

col - one of application, measures, or unit

arg - an argument to filter by

Returns:

an array of global IDs as filtered by col with value = arg

getIDsWhere

public int[] getIDsWhere(java.lang.String[] cols,
                java.lang.String[] args)

Returns an array of global_ids filtered by multiple given columns and values.

Parameters:

cols - a String array containing column names - one of application, measures, or unit

args - an array of string arguments to filter by

Returns:

an array of global IDs as filtered by cols with value = respective arg

getIDsWhereSince

public int[] getIDsWhereSince(java.lang.String col,
                     java.lang.String arg,
                     java.util.Date timestamp)

Returns an array of global_ids filtered by both a column with a value and a timestamp. Any IDs of matching sensors which have sent a reading since the specified timestamp will be returned.

Parameters:

col - one of application, measures, or unit

arg - a value to filter by

timestamp - returned values will have timestamps greater than this

Returns:

an array of global IDs from rows updated since the given timestamp, matching the given properties

getIDsWhereSince

public int[] getIDsWhereSince(java.lang.String[] cols,
                     java.lang.String[] args,
                     java.util.Date timestamp)

Returns an array of global_ids filtered by a list of columns and values, and a timestamp. Any IDs of matching sensors which have sent a reading since the specified timestamp will be returned.

Parameters:

col - a list containing 'application', 'measures', and/or 'unit'

arg - a list containing respective values to filter by

timestamp - returned values will have timestamps greater than this

Returns:

an array of global IDs from rows updated since the given timestamp, matching the given properties

getApplication

public java.lang.String getApplication(int global_id)

Returns the arbitrary application label for the given sensor ID. An application label is given as a descriptor by the sensor's operator upon registration, and is neither unique nor constrained. May be null.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the sensor's application label, or null if none.

getApplicationList

public java.lang.String[] getApplicationList(int[] ids)

Returns an array comprised of the application label for each identified sensor. Never null for at least one valid global_id.

Parameters:

ids - an array of unique sensor global_ids

Returns:

an array with the application label for each identified sensor

getMeasures

public java.lang.String getMeasures(int global_id)

Returns the 'measures' attribute for a given sensor ID. Never null for a valid global_id. The measures attribute describes a physical property, such as distance, temperature, light intensity, or wind speed.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the property measured by the sensor

getMeasuresList

public java.lang.String[] getMeasuresList(int[] ids)

Returns an array comprised of the measures attribute for each identified sensor. Never null for at least one valid global_id.

Parameters:

ids - an array of unique sensor global_ids

Returns:

an array with the measures attribute for each identified sensor

See Also:

getMeasures(int)

getUnit

public java.lang.String getUnit(int global_id)

Returns the unit of measurement for the identified sensor. Never null for a vlid global_id.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the unit of measurement for the identified sensor

getUnitList

public java.lang.String[] getUnitList(int[] ids)

Returns an array comprised of the unit of measurement for each identified sensor. Never null for at least one valid global_id.

Parameters:

ids - an array of unique sensor IDS (global_ids)

Returns:

an array with the unit of measurement for each identified sensor

getLat

public double getLat(int global_id)

Returns the latitude of the identified sensor as a double to six decimal places. Never null for a valid sensor_id.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the sensor's latitude as a double to six decimal places

getLatList

public double[] getLatList(int[] ids)

Returns the latitude of each identified sensor as an element in an array of doubles. Never null for a valid sensor_id.

Parameters:

ids - an array of unique sensor IDs (global_ids)

Returns:

the latitude of each identified sensor as an array of doubles

See Also:

getLat(int)

getLng

public double getLng(int global_id)

Returns the longitude of the identified sensor as a double to six decimal places. Never null for a valid sensor_id.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the sensor's longitude as a double to six decimal places

getLngList

public double[] getLngList(int[] ids)

Returns the longitude of each identified sensor as an element in an array of doubles. Never null for a valid sensor_id.

Parameters:

ids - an array of unique sensor IDs (global_ids)

Returns:

the longitude for each identified sensor

See Also:

getLng(int)

getPosition

public Position getPosition(int global_id)

Returns the Position of the identified sensor, containing the global_id with its latitude and longitude. Include com.orange.api.util.Position. Never null for a valid global_id.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the Position describing the named sensor's location

See Also:

Position

getPositionList

public Position[] getPositionList(int[] ids)

Returns the Positions of the identified sensors as an array. Include com.orange.api.util.Position. Never null for a valid global_id.

Parameters:

ids - an array of unique sensor IDs (global_ids)

Returns:

a Position array describing each named sensor's location

See Also:

Position

getLatestList

public SensorData[] getLatestList(int[] ids)

Returns a list of SensorData objects containing the latest reading and timestamp for each named sensor ID.

Parameters:

ids - an array of unique sensor IDs (global_ids)

Returns:

A list of SensorData objects containing the latest reading and timestamp for each named sensor ID

getDateAdded

public java.util.Date getDateAdded(int global_id)

Returns the timestamp for the very first reading received from the identified sensor. Never null for a valid global_id.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the timestamp for the named sensor's first reading

getDateAddedList

public java.util.Date[] getDateAddedList(int[] ids)

Returns a Date array containing the timestamp for each identified sensor's very first received reading. Never null for a valid global_id.

Parameters:

ids - an array of unique sensor IDs (global_ids)

Returns:

a Date array describing each named sensors' first reading's timestamp

getLastReading

public float getLastReading(int global_id)

Returns the most recently received reading from a given sensor. Never null for a valid global_id.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the latest reading from this sensor

getLastReadingList

public float[] getLastReadingList(int[] ids)

Returns an array composed of the most recently received reading from each sensor identified in ids. Never null for at least one valid global_id.

Parameters:

ids - an array of unique sensor IDs (global_id)

Returns:

an array composed of each named sensor's latest reading

getLastTimestamp

public java.util.Date getLastTimestamp(int global_id)

Returns the timestamp for the most recently received reading from a given sensor. Never null for a valid global_id.

Parameters:

global_id - a sensor's global, unique identifier

Returns:

the timestamp for the named sensor's most recent reading

getLastTimestampList

public java.util.Date[] getLastTimestampList(int[] ids)

Returns an array composed of the timestamp for each identified sensor's latest reading. Never null for at least one valid global_id.

Parameters:

ids - an array of unique sensor ID (global_id)

Returns:

an array of timestamps for each named sensor's latest reading

getDataSince

public SensorData[] getDataSince(int global_id,
                        java.util.Date time)

Returns an array of SensorData types, each describing one single reading update sent by the named sensor by both reading and timestamp.

Parameters:

global_id - a sensor's global, unique identifier

time - an earlier date or time from which all reading updates from the named sensor will be retrieved

Returns:

an array of SenorData objects describing a distinct timestamp and reading value for the named sensor

See Also:

SensorData

getDataBetween

public SensorData[] getDataBetween(int global_id,
                          java.util.Date start,
                          java.util.Date end)

Returns an array of SensorData types, each describing one single reading update sent by the named sensor by both reading and timestamp.

Parameters:

global_id - a sensor's global, unique identifier

start - the date from which data will be retrieved

end - the date to which data will be retrieved

Returns:

an array of SensorData objects describing a distinct timestamp and reading value for the named sensor.

See Also:

SensorData