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 fetching. 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 fetched.
 double[] getDoubleValues()
          Returns the data values as a double array if the data type of the channel is ChannelInfo.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

public ChannelInfo getChannelInfo()
Returns the ChannelInfo that tells the data properties of the channel from where the data values were fetched.

Returns:
ChannelInfo of the Data

getDoubleValues

public double[] getDoubleValues()

Returns the data values as a double array if the data type of the channel is ChannelInfo.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 ChannelInfo.TYPE_DOUBLE

getIntValues

public 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

getObjectValues

public 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

getTimestamp

public 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

public 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 positive. 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:
 probability:         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
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.

isValid

public 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().


Copyright © 2005-2006 Nokia Corporation. All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.