javax.microedition.sensor
Class SensorManager

java.lang.Object
  javax.microedition.sensor.SensorManager

public final class SensorManager
extends java.lang.Object

The SensorManager class is used to find sensors and monitor their availability.

Finding sensors

SensorManager provides two static methods to find sensors. They both return an array of SensorInfo objects listing the found sensors:

1. findSensors(quantity, contextType)
2. findSensors(URL)

If there are several sensors measuring the same quantity, the application developer may want select a specific sensor based on criteria such as accuracy, or a sampling rate. This is done by examining and comparing the information provided by the SensorInfo instances.

Note: some sensors are intended for restricted use only, to be used in the manufacturer, operator, or trusted party domain applications only, or if the user permits. When the application doesn't have the required permissions, all the found sensors are still returned but they cannot necessary be opened. The Connector.open() and PushRegistry.registerConnection() methods throw SecurityException if the application does not have the required permission to use the sensor.

Monitoring sensors

SensorManager is also responsible for registering and unregistering SensorListener objects. A SensorListener will get sensorAvailable()/ sensorUnavailable() notifications. Only one notification for each matching SensorListener is sent per change in availability.

Method Summary

static void	addSensorListener(SensorListener listener, SensorInfo info) Registers SensorListener to monitor the availability of the given sensor.
static void	addSensorListener(SensorListener listener, java.lang.String quantity) Registers a SensorListener to monitor changes in the availability of any sensor that is measuring the defined quantity.
static SensorInfo[]	findSensors(java.lang.String url) Returns an array of SensorInfo objects of all sensors that match the given sensor URL.
static SensorInfo[]	findSensors(java.lang.String quantity, java.lang.String contextType) Returns an array of SensorInfo objects of sensors that match the given quantity and context type.
static void	removeSensorListener(SensorListener listener) Removes the SensorListener from the list of listeners monitoring the availability of defined sensor(s).

Methods inherited from class java.lang.Object

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

Method Detail

addSensorListener

public static void addSensorListener(SensorListener listener,
                                     SensorInfo info)

Registers SensorListener to monitor the availability of the given sensor. Attempts to register the same combination of listener and SensorInfo that is already registered MUST be ignored by the implementation.

Parameters:

listener - SensorListener to be registered

info - SensorInfo defining the sensor, the availability of which is monitored. The parameter is compared with instance equality with the SensorInfo objects defining the sensors. Therefore, the instance MUST be an object that has previously been returned from the findSensors() method or from SensorConnection with the method getSensorInfo().

Throws:

java.lang.NullPointerException - if either of the parameters is null

java.lang.IllegalArgumentException - if info does not match to any of the provided sensors

addSensorListener

public static void addSensorListener(SensorListener listener,
                                     java.lang.String quantity)

Registers a SensorListener to monitor changes in the availability of any sensor that is measuring the defined quantity. Attempts to register the same combination of listener and quantity as has been previously registered MUST be ignored by the implementation.

Parameters:

listener - SensorListener to be registered

quantity - a quantity in which the application is interested

Throws:

java.lang.NullPointerException - if the listener, or the quantity is null

findSensors

public static SensorInfo[] findSensors(java.lang.String quantity,
                                       java.lang.String contextType)

Returns an array of SensorInfo objects of sensors that match the given quantity and context type. If both parameters are null, all supported sensors are returned. If only one of the parameters is null then only the other is used as search criteria.

Parameters:

quantity - the quantity defining the desired sensor

contextType - the context type qualifying the desired sensor, valid values are: SensorInfo.CONTEXT_TYPE_AMBIENT, SensorInfo.CONTEXT_TYPE_DEVICE, SensorInfo.CONTEXT_TYPE_USER, and SensorInfo.CONTEXT_TYPE_VEHICLE. An equals() comparison is used.

Returns:

array of SensorInfo objects of all supported sensors, with the given quantity and context type; a zero-length SensorInfo array, if no match is found.

Throws:

java.lang.IllegalArgumentException - if contextType is given, but it is none of the valid values

findSensors

public static SensorInfo[] findSensors(java.lang.String url)

Returns an array of SensorInfo objects of all sensors that match the given sensor URL. A sensor URL scheme is defined in the class SensorConnection, the only mandatory field being quantity. All the given parameters in the URL MUST match.

Parameters:

url - the sensor URL to be used as search criteria to find a proper sensor.

Returns:

an array of SensorInfo objects of all supported sensors which match the given url parameter. A zero-length array of SensorInfo objects is returned, if no match is found.

Throws:

java.lang.NullPointerException - if the url parameter is null

java.lang.IllegalArgumentException - if the given sensor URL is malformed according to the sensor URL scheme

removeSensorListener

public static void removeSensorListener(SensorListener listener)

Removes the SensorListener from the list of listeners monitoring the availability of defined sensor(s). Returns silently if the listener has not been previously registered.

Parameters:

listener - the SensorListener to be removed

Throws:

java.lang.NullPointerException - if the listener is null