stella.sensor
Class TimerTaskSensor

java.lang.Object
  util.PropertyContainer
      util.PropertyResources
          util.PropertyBundles
              util.rmi.RmiPropertyContainer
                  util.rmi.AbstractRmiCaster
                      stella.sensor.AbstractSensor
                          stella.sensor.TimerTaskSensor

All Implemented Interfaces:

Cloneable, Remote, RmiErrorCaster, Telemetering, ExitCleaning, Initializable, LocalizedSupplying, PropertySupplying, ResourceSupplying, RmiCaster, RmiPropertyBearing

Direct Known Subclasses:

DataSensor

public abstract class TimerTaskSensor
extends AbstractSensor

The abstract base class used for reading abstract sensors. It is implemented as a demon thread, which, once started, keeps reading the sensor values at fixed time intervalls, until the method cancel() is called. The stop() method of Thread is deprecated and should not be used.
To work for different kind of sensors, it is assumed that any sensor has the following properties.

• Every sensor has one measured quantity. This quantity can be represented by a single double.
• Every sensor knows how to read-in this quantity. Normally, this will envolve reading in from a port.
• Every sensor has a unique properties object that can be retrieved from an ascii-file. A required property is a property that must be present in the properties file, otherwise a default value is assigned to the property.
• Any type of Sensor that guarantes such a certain property to be set should provide a public get/is...() method that returns this property in its appropriate type. (e.g. getRespawn())

The properties for this class contain at least the following keys (values in parentheses are the default values):

• sensorname (Unnamed): The name of the sensor. Used for binding and equality. Must be unique.
• respawn (1000): The respawning intervall, in ms.
• daemon (true): If true the sensor is a daemon thread, otherwise it gets the default priority.
• bindproperties (false): If true the stella.rmi.RmiPropertyBearing are automatically bound.
• binderror (false): If true the RmiErrorCaster functionality is automatically bound.

As from version 1.0.1, the timing of the readings is taking into account the readout time of the sensor: At start up, the actual time is recorded, and re-reads of the sensor are timed to occur on modulos of the respawn time. Additionally, the time consumed for reading out the sensor is checked and a warning message is issued, if the respawning is too fast. This warning message is issued to any registered RmiErrorListener.

This class and therefore all its subclasses support RMI access. In the basic version a sensor exports its properties to rmi clients via the stella.rmi.RmiPropertyBearing interface and allows rmi error listeners to register via the RmiErrorListener interface. Methods for registering this services to the rmi-registry are provided but must be called seperately. If the appropriate property is set the binding is done at construct.

As from version 1.1, sensors are split into threadless and threaded sensors. Only threaded sesnors with a defined, fixed read-time may be used as cumulating, smoothing and/or deriving sensors due to the necessety of identical step-size used for smoothing and the like.

See Also:

ConvertToPhysical, SmoothingSensor, CumulativeSensor

Nested Class Summary

protected class

TimerTaskSensor.SensorRead The timer task helper class to allow this sensor to be scheduled via a Timer object.

Nested classes/interfaces inherited from class util.PropertyResources

PropertyResources.URLResource

Field Summary

private static long	DEFRESPAWN The default re-read time, in ms.
private boolean	isnew Is true, if a new measurement is available.
static String	KEY_RESPAWN The key in the Map list referring to the respawning intervall.
private double	reading The actual (read-only) measurement.
private TimerTask	sensorThread The thread this sensor runs in.
private Date	timeofread The (approximate) date of the measurement (read-only).

Fields inherited from class stella.sensor.AbstractSensor

KEY_BIND, KEY_BINDNAME, KEY_CONVERT, KEY_DESCRIPTION, KEY_SENSORNAME

Fields inherited from class util.rmi.AbstractRmiCaster

ALTERNATEHOST, ALTERNATEPORT, KEY_EXPORTPORT, KEY_REGISTRYHOST, KEY_REGISTRYPORT

Fields inherited from class util.PropertyBundles

KEY_LOCALECOUNTRY, KEY_LOCALELANGUAGE, KEY_RESOURCEBUNDLES

Fields inherited from class util.PropertyResources

KEY_NOINITONCREATE, localurl, locate, POSTFIX_DIR, POSTFIX_EXT, POSTFIX_FILE, POSTFIX_LIST, POSTFIX_URL, urlset

Fields inherited from class util.PropertyContainer

KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

Fields inherited from interface util.PropertySupplying

CONFIG, KEY_CLASS

Fields inherited from interface util.ResourceSupplying

KEY_URLRESOURCES, KEY_URLUSECONFIG, KEY_URLUSECURRENT, KEY_URLUSEHOME

Constructor Summary

protected

TimerTaskSensor(Map qualify) Constructs a fully-qualified sensor.

Method Summary

void	cancel() Stops the execution of this thread.
protected void	conductOneMeasure() Conducts a single measurement of the sensor value.
boolean	equals(Object that) Tests for equality of two sensors.
String	getRawToggleInfo() Further information on toggle events.
double	getReading() Returns the raw value of the sensor reading.
long	getRespawn() Returns the respawning for this sensor, in ms.
Date	getTimeOfRead() Returns the approximate time of the last sensor reading.
int	hashCode() Returns a hash code for this sensor.
TimerTask	initSensorTimerTask() Initializes this sensors thread.
boolean	isReady() Checks if a new measurement is available.
protected void	newData(double raw, Date time) This method is called immediately after ne data is available.
protected abstract double	readSensor() This method reads the sensor value.
double	regetRaw() Returns the raw value of the sensor reading.
protected void	setTimeOfRead(Date time) Sets the time of the reading.
boolean	validReading(double raw) Checks if a reading is valid.

Methods inherited from class stella.sensor.AbstractSensor

addRmiErrorListener, createSensor, exit, getBindName, getConvert, getSensorDescription, getSensorInitInfo, getSensorName, init, notifyErrorListener, removeRmiErrorListener, setConvert, status, toString

Methods inherited from class util.rmi.AbstractRmiCaster

bindAlternate, bindToRegistry, bindToRegistry, bindToRegistry, casterExit, casterExit, getBindName, isValid, unbindFromRegistry, unbindFromRegistry

Methods inherited from class util.rmi.RmiPropertyContainer

containsRemoteProperty, getRemoteProperties, getRemoteProperty, setRemoteProperty

Methods inherited from class util.PropertyBundles

clone, getLocalized, getLocalized, getLocalizedString, getLocalizedString, loadResource

Methods inherited from class util.PropertyResources

createFrom, createFrom, createFrom, getApplet, getAsResources, getLocalClassLoader, getPropertiesToKey, getPropertiesToKey, getResource, getResourceAsStream, getResourceFromKey, getResources, keyCreate, keyCreate, reload, setApplet

Methods inherited from class util.PropertyContainer

augment, augment, augment, defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsEnums, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, isNew, parseObject, reload, removeProperty, rescanned, setObject, setProperties, setProperty, stringProperties

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface stella.sensor.Telemetering

validReading

Methods inherited from interface util.PropertySupplying

defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, parseObject, removeProperty, setObject, setProperty, stringProperties

Methods inherited from interface util.rmi.RmiCaster

bindToRegistry, isValid, unbindFromRegistry

Methods inherited from interface util.ResourceSupplying

getResource, getResourceAsStream, getResources

Field Detail

KEY_RESPAWN

public static final String KEY_RESPAWN

The key in the Map list referring to the respawning intervall.

See Also:

Constant Field Values

DEFRESPAWN

private static final long DEFRESPAWN

The default re-read time, in ms.

See Also:

Constant Field Values

reading

private double reading

The actual (read-only) measurement.

isnew

private boolean isnew

Is true, if a new measurement is available. A call to getreading() clears this boolean.

timeofread

private Date timeofread

The (approximate) date of the measurement (read-only). The system time is checked before and after the call to readSensor(). This date is the average of both.

sensorThread

private transient TimerTask sensorThread

The thread this sensor runs in.

Constructor Detail

TimerTaskSensor

protected TimerTaskSensor(Map qualify)

Constructs a fully-qualified sensor. The name and the default respawn time is used to construct a default Map object, if the given Map object is null. Use of this constructor guarantees that the Map keys name and respawn are always set.
The Sensor automatically sets its priority to a daemon thread.

Parameters:

qualify - The Map object describing this sensor.

Method Detail

initSensorTimerTask

public TimerTask initSensorTimerTask()

Initializes this sensors thread. The name of the thread is the sensor name, the thread group is given in the argument. If this sensor should run as a daemon, the returned thread has its daemon flag set.

This method does not start the thread.

Specified by:

initSensorTimerTask in interface Telemetering

Overrides:

initSensorTimerTask in class AbstractSensor

Returns:

The ready-to-start timer-task of this sensor.

See Also:

Telemetering.getRespawn()

conductOneMeasure

protected void conductOneMeasure()

Conducts a single measurement of the sensor value. This method is called by the Sensor's public run method. Subclasses may override this method to add further treatment of data.

newData

protected void newData(double raw,
                       Date time)

This method is called immediately after ne data is available. Daugther classes may need implementations for this method.

readSensor

protected abstract double readSensor()

This method reads the sensor value. Implementation should override this method and provide a conversion of the sensor reading to some double value. It is not necessary that this double has a concrete physical meaning (like Celsius for a temperature sensor). This conversion is done by an ConvertToPhysical- implementation.

See Also:

ConvertToPhysical

isReady

public boolean isReady()

Checks if a new measurement is available.

Returns:

True, if a previously unread measurement is available.

validReading

public boolean validReading(double raw)

Checks if a reading is valid. The double handed over is checked for NaN. In this case, false is returned.

getReading

public double getReading()

Returns the raw value of the sensor reading. It has no physical meaning, and is normally the result of an A/D conversion. Additionally, the isnew flag is cleared.

Returns:

A double value representing the raw sensor reading.

See Also:

ConvertToPhysical

regetRaw

public double regetRaw()

Returns the raw value of the sensor reading. This is a version for internal use only. It leaves the isnew flag intact.

Returns:

A double value representing the raw sensor reading.

See Also:

getReading()

getTimeOfRead

public Date getTimeOfRead()

Returns the approximate time of the last sensor reading. The time is estimated by averaging the system time before and after the call to readSensor. This implies, that readSensor should either read the sensor value symmetric in time, or that this method should be overriden by subclasses that cannot provide a symmetric readout behaviuor.
This method leaves the isnew flag untouched.

Returns:

A Date representation of the readout time.

setTimeOfRead

protected void setTimeOfRead(Date time)

Sets the time of the reading.

getRespawn

public long getRespawn()

Returns the respawning for this sensor, in ms. Note that this method returns the same value as Integer.parseInt(getProperty(KEY_RESPAWN)), but defaults to the default respawning value, if a conversion error occured.

Specified by:

getRespawn in interface Telemetering

Overrides:

getRespawn in class AbstractSensor

Returns:

Zero, if this sensor does not need a thread.

cancel

public void cancel()

Stops the execution of this thread. The use of Thread.stop() is decouraged, because it is deprecated. This method leaves the memory heap in a clean state.

hashCode

public int hashCode()

Returns a hash code for this sensor. It uses the hash code of the sensors name as defined in the String class.

Overrides:

hashCode in class Object

equals

public boolean equals(Object that)

Tests for equality of two sensors. Two sensors are considered equal if their names match.

Overrides:

equals in class Object

Parameters:

that - The sensor to compare to.

Returns:

True, if both sensor have identical names.

getRawToggleInfo

public String getRawToggleInfo()

Further information on toggle events. Null if no further info is needed. This info is called forth on weather toggle events, not when the weather really gets bad or good (retardation for both events).