javax.microedition.sensor
Interface SensorInfo

public interface SensorInfo

SensorInfo contains a variety of information about the physical sensor. The SensorInfo MUST include the following data. The returned value MUST NOT be null and in the case of String object type it MUST NOT be an empty string:

• the quantity, which defines the quantity the sensor is measuring. Standard quantity names are listed below:

    absorbed_dose, absorbed_dose_rate, acceleration, activity, alcohol,
    altitude, amount_of_substance, amount_of_substance_concentration,
    angle, angular_acceleration, angular_velocity, area, battery_charge,
    blood_glucose_level, blood_oxygen_level, blood_pressure,
    body_fat_percentage, capacitance, catalytic_activity,
    catalytic_concentration, character, charger_state, current_density, direction,
    direction_of_motion, dose_equivalent, double_tap, duration, dynamic_viscosity,
    electric_charge, electric_charge_density, electric_conductance,
    electric_currency, electric_current, electric_field_strength,
    electric_flux_density, electric_potential_difference, electric_resistance,
    energy, energy_density, entropy, exposure, fingerprint, flip_state,
    force,  frequency, heart_rate, heat_capacity,
    heat_flux_density, humidity, illuminance, inductance, irradiance,
    kerma, length, location, luminance, luminous_flux, luminous_intensity,
    magnetic_field_strength, magnetic_flux, magnetic_flux_density, mass,
    mass_density, molar_energy, molar_entropy, molar_heat_capacity,
    moment_of_force, percentage, permeability, permittivity, plane_angle,
    power, pressure, proximity, quantity_of_heat, radiance, radiant_flux,
    radiant_intensity, RR_interval, solid_angle, sound_intensity, specific_energy,
    specific_entropy, specific_heat_capacity, specific_volume,
    step_count, stress, surface_tension, temperature,
    thermal_conductivity, time, wave_number, velocimeter, velocity,
    wind_speed, volume, work
   

  These names MUST be used if they are fit. If not, new names can be also introduced. Names MUST be chosen to be unique. This is ensured by prefixing implementation specific quantity names with the same inverted domain name as is used in naming Java packages, for example:

   com.some_company.attitude
   

  Quantity names without a prefix (i.e. not containing a "." character) are defined only by this specification and later versions of it. Some of the quantities relate to units listed in the tables of Unit class. Sensor examples in the table of Appendix A "Finding sensors" illustrate the use of the rest of the quantities.
• the context type, which defines from where the measurement is taken
• the sensor connection type, which specifies the way the underlying physical sensor is connected to the device (embedded, wired, short-range wireless, or remote)
• the model of the sensor
• the sensor URL needed to open the connection to the sensor
• the description, the verbal description of the purpose of the sensor, and its channels
• ChannelInfo objects, which encapsulates the information of the properties of data related to one channel, like the unit, the scale and the measurement ranges. SensorInfo contains information of the sensor as a whole.

Information of the push support provided for the sensor can be queried with the following two methods:

• isAvailabilityPushSupported()
• isConditionPushSupported()

Optional information is offered as properties. Property names are defined and briefly explained in the table below. The property value returned from getProperty() method MUST match the type given in the second column for the requested property name. The property value MUST not be null or in the case of String object type it MUST NOT be null or empty string:

Property names for optional sensor information

Property name	Object type	Short description
PROP_IS_CONTROLLABLE	Boolean	If the sensor is controllable, the value MUST equal Boolean.TRUE. The property MUST NOT be defined if the sensor cannot be controlled.
PROP_IS_REPORTING_ERRORS	Boolean	If the sensor is reporting errors, the value MUST equal Boolean.TRUE. The property MUST NOT be defined if the sensor does not report errors.
PROP_LATITUDE	Double	The latitude coordinate, part of the geographical coordinates indicating the location of the sensor. The geographical coordinates are provided here to differentiate between several sensors of the same type. This property is not meant to provide primary information about the dynamic location of the mobile device. The latitude is defined as an angular distance in degrees north or south of the equator. Positive values indicate northern latitude and negative values southern latitude. The latitude is given using the WGS84 datum. The latitude of the sensor may change. When requested, the current latitude MUST be returned. If PROP_LATITUDE is defined PROP_LONGITUDE MUST also be defined. Value MUST be within the range [-90.0,90.0].
PROP_LOCATION	String	The location string, verbal description of location object. If it exists, it is part of the sensor URL, thus it is not allowed to contain reserved characters described in RFC 2396. The location of the sensor may change. The current location MUST be returned.
PROP_LONGITUDE	Double	The longitude coordinate, part of the geographical coordinates indicating the location of the sensor. The geographical coordinates are provided here to differentiate between several sensors of the same type. This property is not meant to provide primary information about the dynamic location of the mobile device. The longitude is defined as an angular distance in degrees east or west of the prime meridian at 0 ° measured by the angle between the plane of the prime meridian and that of the meridian through the point in question. Positive values indicate eastern longitude and negative values western longitude. The longitude given using the WGS84 datum. The longitude of the sensor may change. When requested, the current longitude MUST be returned. If PROP_LONGITUDE is defined PROP_LATITUDE MUST also be defined. Value MUST be within the range [-180.0,180.0).
PROP_MAX_RATE	Float	Maximum sampling rate of the sensor defined in hertz
PROP_PERMISSION	String	Required permissions to use this sensor. Allowed values are: "javax.microedition.sensor.PrivateSensor", "javax.microedition.sensor.ProtectedSensor", and "javax.microedition.sensor.PrivateSensor, javax.microedition.sensor.ProtectedSensor"
PROP_VENDOR	String	The vendor of the physical sensor module (the format is vendor-specific)
PROP_VERSION	String	The version of the sensor implementation (the format is vendor-specific)

If the optional property is not defined, then the getProperty() method throws IllegalArgumentException.

Properties provide also implementation specific way to expand the content of the SensorInfo object. By defining properties the implementer of the sensor module can supply more information about the sensor to the application. The property is identified by the name; the value of the property can be any Object. New names MUST not overlap with the property names defined here. Proprietary names MUST be prefixed with inverted domain names, for example:

 com.some_company.altitude
 

Field Summary

static int	CONN_EMBEDDED A sensor is embedded into the mobile device.
static int	CONN_REMOTE A remote sensor is connected to the device, for example, via GPRS or HTTP.
static int	CONN_SHORT_RANGE_WIRELESS A short-range wireless sensor.
static int	CONN_WIRED A sensor is plugged into a device with a wire, for example, into a serial or USB port.
static java.lang.String	CONTEXT_TYPE_AMBIENT This context type defines ambient, environmental sensors.
static java.lang.String	CONTEXT_TYPE_DEVICE This context type defines device-related sensors.
static java.lang.String	CONTEXT_TYPE_USER This context type defines user-related sensors.
static java.lang.String	CONTEXT_TYPE_VEHICLE This context type defines sensors, which gives information of a vehicle.
static java.lang.String	PROP_IS_CONTROLLABLE Property name for informing that the sensor is reporting errors with DataAndErrorListener.errorReceived() notifications.
static java.lang.String	PROP_IS_REPORTING_ERRORS Property name for informing that the sensor is reporting errors with DataAndErrorListener.errorReceived() notifications.
static java.lang.String	PROP_LATITUDE Property name for getting the latitude of the sensor.
static java.lang.String	PROP_LOCATION Property name for getting the location of the sensor as a human readable string.
static java.lang.String	PROP_LONGITUDE Property name for getting the longitude of the sensor.
static java.lang.String	PROP_MAX_RATE Property name for getting the maximum sampling rate of the sensor.
static java.lang.String	PROP_PERMISSION Property name for getting permission information of this sensor.
static java.lang.String	PROP_VENDOR Property name for getting the vendor of the sensor.
static java.lang.String	PROP_VERSION Property name for getting the version of the sensor.

Method Summary

ChannelInfo[]	getChannelInfos() This method returns the ChannelInfo array representing channels of the sensor.
int	getConnectionType() Return the connection type of the sensor.
java.lang.String	getContextType() Returns the context type of the sensor.
java.lang.String	getDescription() This method returns a readable description of the sensor.
int	getMaxBufferSize() Returns the maximum buffer size of the data value buffer in Data objects.
java.lang.String	getModel() Returns the model of the sensor, the model is a vendor-specific string.
java.lang.Object	getProperty(java.lang.String name) The method returns the property value for the given name
java.lang.String[]	getPropertyNames() This method will return all the names of optional and implementation specific properties.
java.lang.String	getQuantity() Returns the quantity of the sensor.
java.lang.String	getUrl() Returns the URL needed to open a SensorConnection.
boolean	isAvailabilityPushSupported() This method tells if the sensor supports the push mechanism based on availability of the sensor.
boolean	isAvailable() This method tells if the sensor is available.
boolean	isConditionPushSupported() This method tells if the sensor supports the push mechanism based on conditions.

Field Detail

CONN_EMBEDDED

static final int CONN_EMBEDDED

A sensor is embedded into the mobile device.

See Also:

Constant Field Values

CONN_REMOTE

static final int CONN_REMOTE

A remote sensor is connected to the device, for example, via GPRS or HTTP.

See Also:

Constant Field Values

CONN_SHORT_RANGE_WIRELESS

static final int CONN_SHORT_RANGE_WIRELESS

A short-range wireless sensor. A sensor is connected to the device, for example, via Bluetooth, infrared, or WLAN.

See Also:

Constant Field Values

CONN_WIRED

static final int CONN_WIRED

A sensor is plugged into a device with a wire, for example, into a serial or USB port.

See Also:

Constant Field Values

CONTEXT_TYPE_AMBIENT

static final java.lang.String CONTEXT_TYPE_AMBIENT

This context type defines ambient, environmental sensors.

See Also:

Constant Field Values

CONTEXT_TYPE_VEHICLE

static final java.lang.String CONTEXT_TYPE_VEHICLE

This context type defines sensors, which gives information of a vehicle.

See Also:

Constant Field Values

CONTEXT_TYPE_DEVICE

static final java.lang.String CONTEXT_TYPE_DEVICE

This context type defines device-related sensors.

See Also:

Constant Field Values

CONTEXT_TYPE_USER

static final java.lang.String CONTEXT_TYPE_USER

This context type defines user-related sensors.

See Also:

Constant Field Values

PROP_IS_CONTROLLABLE

static final java.lang.String PROP_IS_CONTROLLABLE

Property name for informing that the sensor is reporting errors with DataAndErrorListener.errorReceived() notifications.

See Also:

Constant Field Values

PROP_IS_REPORTING_ERRORS

static final java.lang.String PROP_IS_REPORTING_ERRORS

Property name for informing that the sensor is reporting errors with DataAndErrorListener.errorReceived() notifications.

See Also:

Constant Field Values

PROP_LATITUDE

static final java.lang.String PROP_LATITUDE

Property name for getting the latitude of the sensor.

See Also:

Constant Field Values

PROP_LOCATION

static final java.lang.String PROP_LOCATION

Property name for getting the location of the sensor as a human readable string.

See Also:

Constant Field Values

PROP_LONGITUDE

static final java.lang.String PROP_LONGITUDE

Property name for getting the longitude of the sensor.

See Also:

Constant Field Values

PROP_MAX_RATE

static final java.lang.String PROP_MAX_RATE

Property name for getting the maximum sampling rate of the sensor.

See Also:

Constant Field Values

PROP_PERMISSION

static final java.lang.String PROP_PERMISSION

Property name for getting permission information of this sensor.

See Also:

Constant Field Values

PROP_VENDOR

static final java.lang.String PROP_VENDOR

Property name for getting the vendor of the sensor.

See Also:

Constant Field Values

PROP_VERSION

static final java.lang.String PROP_VERSION

Property name for getting the version of the sensor.

See Also:

Constant Field Values

Method Detail

getChannelInfos

ChannelInfo[] getChannelInfos()

This method returns the ChannelInfo array representing channels of the sensor. At least one object MUST exist. The majority of sensors still provide information from one channel only, in which case the length of an array is 1.

Returns:

ChannelInfo objects representing channels of the sensor

getConnectionType

int getConnectionType()

Return the connection type of the sensor. Possible values are:

• CONN_EMBEDDED
• CONN_REMOTE
• CONN_SHORT_RANGE_WIRELESS
• CONN_WIRED

Returns:

the connection type of sensor

getContextType

java.lang.String getContextType()

Returns the context type of the sensor. Together with the quantity, the context type defines the purpose and use of the sensor. They are like a "WHAT" and "WHERE" pair: quantity defines the quantity to be measured; the context type defines, where the measurement is taken. For example, if the quantity to be measured is "temperature" and the context type of the measurement is "user", the sensor is likely to be a clinical thermometer.

The returned value MUST be one of the following values:

• CONTEXT_TYPE_USER
• CONTEXT_TYPE_DEVICE
• CONTEXT_TYPE_AMBIENT
• CONTEXT_TYPE_VEHICLE

A purpose of the division is to ease the finding of the targeted sensor.

A "user" qualifies sensors which are measuring user initiated stimulus (gesture), or characteristics/properties of the user (body temperature, mass, heart rate).

A "device" context type is for sensors, which are producing information of the device itself such as a state of resources or the connection; other examples could be battery charge level, flip state, or field intensity sensors.

An "ambient" category contains sensors measuring some generic, common features of the environment such as pressure or temperature of the air, sound intensity, or state of the weather.

An "vehicle" category contains sensors monitoring a vehicle related sensors, for example a speedometer or a engine oil level sensor.

For example, if there are thermometers for air and body temperature, quantity for both is "temperature". These thermometers can be separated with the context types:

• CONTEXT_TYPE_AMBIENT
• CONTEXT_TYPE_USER

Returns:

the context type of the sensor

getDescription

java.lang.String getDescription()

This method returns a readable description of the sensor. Description tells the essentials of the sensor, including at least the sensor type (accelerometer, microphone, thermometer), the channels used, and meaning of the channels. It is recommended to inform if the sensor cannot be switched off and is therefore always available. The returned string MUST not be null or an empty string.

Returns:

the description of the sensor

getMaxBufferSize

int getMaxBufferSize()

Returns the maximum buffer size of the data value buffer in Data objects. The defined size MUST be >= 256.

Returns:

the maximum buffer size

getModel

java.lang.String getModel()

Returns the model of the sensor, the model is a vendor-specific string. The model is part of the sensor URL, thus it's not allowed to contain reserved characters described in RFC 2396.

Returns:

the model of the sensor

getPropertyNames

java.lang.String[] getPropertyNames()

This method will return all the names of optional and implementation specific properties. Optional property names are listed in the table in the class description of this class. Arbitrary properties are implementation specific. The method is intended to be used in conjunction with the method getProperty().

Returns:

names of the properties as a String array. Returns a zero-length String array if no properties are set

getProperty

java.lang.Object getProperty(java.lang.String name)

The method returns the property value for the given name

Parameters:

name - the property name

Returns:

a property value

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalArgumentException - if the name is not any of the property names returned with getPropertyNames() method.

getQuantity

java.lang.String getQuantity()

Returns the quantity of the sensor. The quantity is the aspect or the property, the application is interested in getting measured. The standard quantities are listed in the class description of this class.

The quantity is the main qualifier to help in finding the proper sensor. The query is intended to be further refined with the context type.

Returns:

the quantity of the sensor

getUrl

java.lang.String getUrl()

Returns the URL needed to open a SensorConnection. The implementation MUST return always a connection to the same sensor when this URL is used, except when the location of the sensor changes. For example, if there are two identical sensors, one in the kitchen and one in the living room, and their locations are switched, then the URL referring to the sensor in the kitchen returns a connection to the different sensor.

The URL MUST conform to the sensor URL scheme for Connector.open() defined in SensorConnection. All the mandatory fields, quantity, contextType, and model, MUST be present in the returned string. Methods getQuantity(), getContextType(), and getModel() return the needed values, respectively. If the location is defined, it MUST be also included. If defined, the location can be obtained with the method getProperty(SensorInfo.PROP_LOCATION).

Returns:

the sensor URL

isAvailable

boolean isAvailable()

This method tells if the sensor is available.

Returns:

true if the sensor is available, false otherwise.

isAvailabilityPushSupported

boolean isAvailabilityPushSupported()

This method tells if the sensor supports the push mechanism based on availability of the sensor. For example, embedded sensors, which cannot be switched off and are therefore always on, MUST return false.

Returns:

true if the availability-based push for this sensor is supported.

isConditionPushSupported

boolean isConditionPushSupported()

This method tells if the sensor supports the push mechanism based on conditions. For example, embedded sensors, which are always on, might still support condition-based push even when they do not support availability-based push. Sensors that provide Object data MUST return false.

Returns:

true if the condition-based push for this sensor is supported