javax.microedition.sensor
Interface Channel

public interface Channel

Objects implementing the Channel interface provide information about the channel and maintain conditions for monitoring the data. The Channel interface offers methods to add, get, and remove Condition objects.

The measured data values will be tested against each condition defined in the Channel. A separate ConditionListener.conditionMet() notification is sent for each condition that the measured data value meets. Thus, there may be several notifications for one measured value. Once a data value meets the condition and the notification is sent, this Condition is removed from the Channel. The Condition is removed in order to prevent the application from getting flooded with notifications, because it is quite likely that many successive measurement values would meet the condition. It is the responsibility of the application to determine when to add the condition back, if necessary.

A Channel object MUST check that the Condition object is of appropriate type for the channel, when the Condition is being added. For example, for Channel having Object data type, the only valid Condition this API provides is the ObjectCondition. It is possible to add several Condition objects for the same ConditionListener, where the Condition objects have overlaps, for example, in range. However, an attempt to add the same pair of ConditionListener and Condition object instances as are already registered will be ignored.

Method Summary

void	addCondition(ConditionListener listener, Condition condition) Sets a Condition object to be monitored.
ChannelInfo	getChannelInfo() Returns the ChannelInfo object associated with the Channel.
java.lang.String	getChannelUrl() This method returns a string identifying the channel and listing all its unique conditions.
Condition[]	getConditions(ConditionListener listener) Returns the Condition objects set for the given listener
void	removeAllConditions() Removes all Condition and ConditionListener objects registered in this Channel.
void	removeCondition(ConditionListener listener, Condition condition) Removes a given Condition and ConditionListener object pair from this Channel.
void	removeConditionListener(ConditionListener listener) Removes a given ConditionListener and all Condition objects associated with it.

Method Detail

addCondition

void addCondition(ConditionListener listener,
                  Condition condition)

Sets a Condition object to be monitored. If the same ConditionListener and Condition instance pair already exists, the method returns silently without making the addition.

Parameters:

listener - the ConditionListener to which the ConditionListener.conditionMet() notifications are sent

condition - the Condition object defining the condition to be monitored. The null value passed as a parameter has a special meaning in the case of automatically launched application: the application will be immediately notified after this registration, if there is a pending push condition, which caused the automatic launch of the application. If the parameter value is null but there is no pending push condition, this registration has no effect and no notification will be made.

Throws:

java.lang.NullPointerException - if the listener is null or in the case of the application is not automatically launched by the push mechanism and the condition is null

java.lang.IllegalArgumentException - if the data type of the channel is TYPE_INT or TYPE_DOUBLE and an ObjectCondition is passed in; or if the data type is TYPE_OBJECT and a LimitCondition or a RangeCondition is passed in

java.lang.IllegalStateException - if the SensorConnection is in the STATE_CLOSED state

getChannelInfo

ChannelInfo getChannelInfo()

Returns the ChannelInfo object associated with the Channel. The ChannelInfo contains the properties of the channel data.

Returns:

a ChannelInfo object

getConditions

Condition[] getConditions(ConditionListener listener)

Returns the Condition objects set for the given listener

Parameters:

listener - the ConditionListener whose Condition objects are requested

Returns:

the Condition objects set for the listener object. A zero-length Condition array is returned if the given listener has no Condition objects.

Throws:

java.lang.NullPointerException - if listener is null

getChannelUrl

java.lang.String getChannelUrl()

This method returns a string identifying the channel and listing all its unique conditions. The format of the string conforms to the sensor URL scheme part defined in SensorConnection for one channel: see the <channel> part. When concatenated with the URL of the SensorInfo, the result is an URL that conforms to <push_sensor_url>. This URL can be registered to PushRegistry in order to get the defined application launched automatically.

 String push_url = sensorInfo.getUrl() + "?" + channel.getChannelUrl();
 

Only unique Condition objects are presented. If multiple ConditionListener objects have the same Condition, the Condition will be presented only once in the channel URL.

The values of the limits MUST be presented in basic units, in resolved format as a single value with the scaling factor of 0. Resolved values provide portability and allow the same URL to be used to refer to sensors, regardless of the scaling factor used by the sensor.

removeAllConditions

void removeAllConditions()

Removes all Condition and ConditionListener objects registered in this Channel.

Throws:

java.lang.IllegalStateException - if the SensorConnection is in the STATE_CLOSED state

removeCondition

void removeCondition(ConditionListener listener,
                     Condition condition)

Removes a given Condition and ConditionListener object pair from this Channel. If the given Condition and ConditionListener pair is not registered in this Channel, this method returns silently. The application must pass in the same Condition object instance as has been earlier added. The application might have stored the Condition to be removed or it can retrieve it using the getConditions() method. Instance equality is used for the comparison of the Condition objects.

Parameters:

listener - the ConditionListener whose Condition will be removed

condition - the Condition to be removed

Throws:

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

java.lang.IllegalStateException - if the SensorConnection is in the STATE_CLOSED state

removeConditionListener

void removeConditionListener(ConditionListener listener)

Removes a given ConditionListener and all Condition objects associated with it. If this ConditionListener object has not been previously registered, the request is ignored and the method returns silently.

Parameters:

listener - the ConditionListener to be removed

Throws:

java.lang.NullPointerException - if the listener is null

java.lang.IllegalStateException - if the SensorConnection is in the STATE_CLOSED state