javax.microedition.sensor
Interface Data

public interface Data

This interface represents data values retrieved from one channel of a sensor. The Data object may contain also the uncertainties, timestamps, and validities of the corresponding data values. The content of the Data depends on the parameters the application specified when starting the data retrieval. The additional information may be omitted from the Data objects if the application didn't specify them. The different configuration options are defined in the descriptions of the data retrieval methods of SensorConnection.

Data from all the channels is returned simultaneously as an array of Data objects. Several data values may be buffered inside one Data object. Depending on the data type of the channel, the method used to retrieve the values is different. The data type can be queried using the method ChannelInfo.getDataType().

Data types and corresponding get methods

Data type	Method to get values
ChannelInfo.TYPE_INT	getIntValues()
ChannelInfo.TYPE_DOUBLE	getDoubleValues()
ChannelInfo.TYPE_OBJECT	getObjectValues()

If the channel uses scaling, the data values MUST be presented in the scaled format. See the method ChannelInfo.getScale() for more details.

Method Summary

ChannelInfo	getChannelInfo() Returns the ChannelInfo that tells the data properties of the channel from where the data values were retrieved.
double[]	getDoubleValues() Returns the data values as a double array if the data type of the channel is TYPE_DOUBLE.
int[]	getIntValues() Returns the data values as an int array if the data type of this channel is ChannelInfo.TYPE_INT.
java.lang.Object[]	getObjectValues() Returns the data values as an array of Objects if the data type of this channel is ChannelInfo.TYPE_OBJECT.
long	getTimestamp(int index) Returns the timestamp corresponding to the time when the data value indicated by the index was measured.
float	getUncertainty(int index) Returns the estimate of the error of the measured data value.
boolean	isValid(int index) Returns the validity of the data value at the given index.

Method Detail

getChannelInfo

ChannelInfo getChannelInfo()

Returns the ChannelInfo that tells the data properties of the channel from where the data values were retrieved.

Returns:

ChannelInfo of the Data

getDoubleValues

double[] getDoubleValues()

Returns the data values as a double array if the data type of the channel is TYPE_DOUBLE.

Returns:

the data values as a double array, a zero-length double array if no values have been measured

Throws:

java.lang.IllegalStateException - if the data type of the channel is not TYPE_DOUBLE

getIntValues

int[] getIntValues()

Returns the data values as an int array if the data type of this channel is ChannelInfo.TYPE_INT.

Returns:

the data values as an int array, a zero-length int array if no values have been measured

Throws:

java.lang.IllegalStateException - if the data type of the channel is not ChannelInfo.TYPE_INT

getTimestamp

long getTimestamp(int index)

Returns the timestamp corresponding to the time when the data value indicated by the index was measured. The timestamp is the point in time when the referenced data value was measured. The method returns the corresponding timestamp value as long. The same format as used in the method java.lang.System.currentTimeMillis() is used to represent the time. It returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

Parameters:

index - the index of the data value

Returns:

the timestamp indicating when the data value was retrieved

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of the closed range [0, (size of the data buffer - 1)]

java.lang.IllegalStateException - if the timestamp was not requested according to the parameters of the SensorConnection.getData() or the SensorConnection.setDataListener() methods.

getUncertainty

float getUncertainty(int index)

Returns the estimate of the error of the measured data value. Uncertainty is given as the value of the standard deviation, which is always non-negative.

If data values are normally distributed, then approximately 68% of values should reside within ± 1 sigma (the standard deviation).

The uncertainty and the data value MUST be in the same scale and have the same unit. For example, if values are:

 data value:          524
 uncertainty:         8
 scale:               -3
 unit:                second
 

The real, resolved values can be calculated in the following manner:

 data value:          524 * 10^-3 s = 0.524 s
 uncertainty:         8 * 10^-3 s = 0.008 s
 

The probability of actual value residing within the defined value range, if measurements are normally distributed, is:

 P( 0.516 s < data value < 0.532 s) ≈ 68%

Parameters:

index - the index of the data value

Returns:

the uncertainty of the data value. If the sensor is not providing uncertainty value and the accuracy of the channel is -1, then the uncertainty value MUST always be 0.

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of the closed range [0,(size of the data buffer - 1)]

java.lang.IllegalStateException - if the uncertainty was not requested according to the parameters of the SensorConnection.getData() or the SensorConnection.setDataListener() methods.

getObjectValues

java.lang.Object[] getObjectValues()

Returns the data values as an array of Objects if the data type of this channel is ChannelInfo.TYPE_OBJECT.

Returns:

the data values as an Object array, a zero-length Object array if no values have been measured

Throws:

java.lang.IllegalStateException - if the data type of the channel is not ChannelInfo.TYPE_OBJECT

isValid

boolean isValid(int index)

Returns the validity of the data value at the given index. Provides a way to inform of invalid values such as "no data received".

Parameters:

index - the index of the data value

Returns:

the validity of the data value

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of the closed range [0,(size of the data buffer - 1)]

java.lang.IllegalStateException - if the validity was not requested according to the parameters of the method SensorConnection.getData() or SensorConnection.setDataListener().