de.jaetzold.art
Class RawSensor

java.lang.Object
  |
  +--de.jaetzold.art.RawSensor
All Implemented Interfaces:
EventListener, PropertyChangeListener, Sensor, SensorPeer
Direct Known Subclasses:
CombinedSensor, LightSensor, RawActuator, StateSensor

public class RawSensor
extends Object
implements Sensor, SensorPeer

This class represents a basic input-device of a hardware-interface. Each device, such as a Sensor needs to be connected to a Port first. Through connecting with a Port this Object gets its peer which is required for proper use.

See Also:
connectWith(Port)

Inner Class Summary
 class RawSensor.ValueSensorPort
          A SensorPort for the value of this Sensor.
 
Field Summary
protected  PropertyChangeSupport changes
          Now comes the stuff for the events and their listeners
protected  double precision
          The local value for precision.
protected  boolean precisionSet
          This is false by default.
protected  SensorEventDescriptor propertyChangeEventDescriptor
          An instance of AllSensorEventDescriptor.
 
Constructor Summary
RawSensor()
          Contructs a new RawSensor.
 
Method Summary
 void addPropertyChangeListener(PropertyChangeListener l)
          A PropertyChangeListener receives PropertyChangeEvents whenever this Sensor receives a SensorEvent.
 void addSensorListener(SensorListener listener)
          Adds the specified SensorListener to this Sensor so that it receives SensorEvents from it.
 void addSensorListener(SensorListener listener, SensorEventDescriptor eventDescriptor)
          Adds the specified SensorListener to this Sensor so that it receives the SensorEvents which are described by the specified SensorEventDescriptor.
 void connectWith(Port port)
          Connects the Sensor with the given Port.
 void connectWith(SensorPort port)
          Connects this Sensor with the given Port.
protected  double convertToIncoming(double peerValue)
          This is a Template-Method for subclasses.
protected  double convertToOutgoing(double internalValue)
          This is a Template-Method for subclasses.
 void disableEvent(SensorEventDescriptor eventDescriptor)
          Disables the type of Event described by the given SensorEventDescriptor.
 void disconnect()
          Disconnects this Sensor from it's Peer and it's Port.
 void enableEvent(SensorEventDescriptor eventDescriptor)
          Enables the type of Event described by the given SensorEventDescriptor.
protected  boolean getChangeEventsEnabled()
          Tells whether this Sensor is configured to receive Events from its Peer whenever something changes.
 boolean getDeliversFloatingPoint()
          Tells whether this Sensor delivers discrete values or not.
 Conversion getIncomingConversionDelegate()
          Returns the delegate for converting peer-side values to the internal representation of this Sensor.
 int getIntValue()
          The value-retrieving methods
 Conversion getOutgoingConversionDelegate()
          Returns the delegate for converting the internal value-representation of this Sensor to the one that is presented to the outside.
protected  SensorPeer getPeer()
          Returns the Peer this Sensor actually uses.
 boolean getPeerCacheEnabled()
          Tells whether this Sensor tries to minimize traffic to and from the Peer.
 Port getPort()
          Returns the Port to which this Sensor is connected.
 double getPrecision()
          Returns the maximum of the expectable error in the value.
 SensorPort getSensorPort()
          Returns a Port through which other Sensors can be connected to this Sensor.
 double getValue()
          Returns the value this Sensor represents as a double.
 boolean isConnected()
          Tells wether this Sensor has a Peer and whether the Peer is also connected.
protected  boolean isIncomingConversionCacheable()
          This is not the same as isCacheable() from Conversion or StateDecider.
protected  boolean isOutgoingConversionCacheable()
          Same meaning as isIncomingConversionCacheable() but for the outgoingConversion.
 boolean isReversed()
          Tells whether this Sensor treats negative values as positive and the other way round.
 void processEvent(SensorEvent event)
          This Method is called when the value this Sensor resembles has changed and events are enabled.
 void propertyChange(PropertyChangeEvent event)
          This is the method through which a Sensor gets informed about changes in the hardware-value it resembles.
 void removePropertyChangeListener(PropertyChangeListener l)
          Remove the specified listener.
 void removeSensorListener(SensorListener listener)
          Removes the specified SensorListener so that it no longer receives SensorEvents from this Sensor.
 void removeSensorListener(SensorListener listener, SensorEventDescriptor eventDescriptor)
          Removes the specified SensorListener so that it no longer receives from this Sensor the SensorEvents which are described by the specified SensorEventDescriptor.
protected  void setChangeEventsEnabled(boolean enabled)
          Configures whether this Sensor wants to receive Events from its Peer whenever something changes.
 void setIncomingConversionDelegate(Conversion delegate)
          This is the delegate for converting peer-side values to the internal representation of this Sensor.
 void setOutgoingConversionDelegate(Conversion delegate)
          This is the delegate for converting the internal value-representation of this Sensor to the one that is presented to the outside.
 void setPeerCacheEnabled(boolean enabled)
          Should this Sensor try to minimize traffic to and from the Peer? This is enabled by default.
 void setPrecision(double precision)
          Sets the local value for precision.
 void setReversed(boolean reversed)
          Controls whether this Sensor should treat negative values as positive and the other way round.
 void update()
          Causes a new SensorEvent for this Sensor to be generated and delivered.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

precisionSet

protected boolean precisionSet
This is false by default.
See Also:
setPrecision(double)

precision

protected double precision
The local value for precision. This is only valid if precisionSet is true.
See Also:
precisionSet, setPrecision(double)

changes

protected PropertyChangeSupport changes
Now comes the stuff for the events and their listeners

propertyChangeEventDescriptor

protected SensorEventDescriptor propertyChangeEventDescriptor
An instance of AllSensorEventDescriptor. It is used as a descriptor for PropertyChangeEvents.
See Also:
SensorEventDescriptor, AllSensorEventDescriptor
Constructor Detail

RawSensor

public RawSensor()
Contructs a new RawSensor. It still needs a peer. Through connecting with a Port this Object gets its peer which is required for proper use.
See Also:
connectWith(Port)
Method Detail

convertToIncoming

protected double convertToIncoming(double peerValue)
This is a Template-Method for subclasses. It converts the value as it comes from the peer into the internal value of this sensor. It is called whenever a new value comes from the peer. Because this Method also calls the incomingConversionDelegate (if one exists) it should not be overridden without calling super.
See Also:
convertToOutgoing(double), isIncomingConversionCacheable()

convertToOutgoing

protected double convertToOutgoing(double internalValue)
This is a Template-Method for subclasses. It converts the internal value into the value which this sensor represents to the outside. It is called when the Sensor is asked for its value or sends a SensorEvent. Because this Method also calls the outgoingConversionDelegate (if one exists) it should not be overridden without calling super.
See Also:
convertToIncoming(double), isOutgoingConversionCacheable()

isReversed

public boolean isReversed()
Tells whether this Sensor treats negative values as positive and the other way round.
See Also:
setReversed(boolean)

setReversed

public void setReversed(boolean reversed)
Controls whether this Sensor should treat negative values as positive and the other way round. That way this state defines what "+" in the hardware means for the algorithm.

getPrecision

public double getPrecision()
Description copied from interface: Sensor
Returns the maximum of the expectable error in the value. This is just a guess, what means that nothing really important should depend on it. It is meant to give an algorithm using this Sensor an idea of how precise the value is so that it either can refuse to use it or try to compensate if necessary.
Specified by:
getPrecision in interface Sensor

setPrecision

public void setPrecision(double precision)
Sets the local value for precision. This is not required because usually the precision is taken from the peer. However it may be useful to tune the value for precision according to the algorithm which will use this Sensor.
See Also:
precisionSet, setPrecision(double)

isIncomingConversionCacheable

protected boolean isIncomingConversionCacheable()
This is not the same as isCacheable() from Conversion or StateDecider. The Conversion may depend on a delegate and that delegate can be set more than once. Therefore it would be impossible to assure that the Conversion remains cacheable. But the contract is, that as long as the delegate doesn't change you can assume that the incoming conversion remains cacheable once it has become so.
See Also:
isOutgoingConversionCacheable(), setIncomingConversionDelegate(Conversion), Conversion.isCacheable()

isOutgoingConversionCacheable

protected boolean isOutgoingConversionCacheable()
Same meaning as isIncomingConversionCacheable() but for the outgoingConversion.
See Also:
isIncomingConversionCacheable()

setIncomingConversionDelegate

public void setIncomingConversionDelegate(Conversion delegate)
This is the delegate for converting peer-side values to the internal representation of this Sensor. Because there can be only one delegate be careful not to accidentally delete one that is already existent. If a conversion is necessary it is usually also possible to use another Sensor as a decorator which is connected to the SensorPort delivered by getSensorPort().
See Also:
convertToIncoming(double), setOutgoingConversionDelegate(Conversion), getSensorPort()

getIncomingConversionDelegate

public Conversion getIncomingConversionDelegate()
Returns the delegate for converting peer-side values to the internal representation of this Sensor.
See Also:
convertToIncoming(double), setIncomingConversionDelegate(Conversion)

setOutgoingConversionDelegate

public void setOutgoingConversionDelegate(Conversion delegate)
This is the delegate for converting the internal value-representation of this Sensor to the one that is presented to the outside. Because there can be only one delegate be careful not to accidentally delete one that is already existent. If a conversion is necessary it is usually also possible to use another Sensor as a decorator which is connected to the SensorPort delivered by getSensorPort().
See Also:
convertToOutgoing(double), setIncomingConversionDelegate(Conversion), getSensorPort()

getOutgoingConversionDelegate

public Conversion getOutgoingConversionDelegate()
Returns the delegate for converting the internal value-representation of this Sensor to the one that is presented to the outside.
See Also:
convertToOutgoing(double), setOutgoingConversionDelegate(Conversion)

getPeer

protected SensorPeer getPeer()
Returns the Peer this Sensor actually uses.

getPort

public Port getPort()
Description copied from interface: Sensor
Returns the Port to which this Sensor is connected. Note the difference between getSensorPort() and getPort().
Specified by:
getPort in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.getPort()

getDeliversFloatingPoint

public boolean getDeliversFloatingPoint()
Tells whether this Sensor delivers discrete values or not. A result of false means that the result of a getValue() can be cast to int without a loss of precision. The result of this method is only valid as long as no one of the conversion delegates changes.
Specified by:
getDeliversFloatingPoint in interface SensorPeer
See Also:
convertToIncoming(double), setIncomingConversionDelegate(Conversion), setOutgoingConversionDelegate(Conversion)

setPeerCacheEnabled

public void setPeerCacheEnabled(boolean enabled)
Should this Sensor try to minimize traffic to and from the Peer? This is enabled by default. If it is enabled this Sensor caches the values it receives from the Peer. Especially when all change-events are enabled it is assumed that the value of the last received event is still correct and the Peer will not be asked for it again.
See Also:
getPeerCacheEnabled(), setChangeEventsEnabled(boolean)

getPeerCacheEnabled

public boolean getPeerCacheEnabled()
Tells whether this Sensor tries to minimize traffic to and from the Peer.
See Also:
setPeerCacheEnabled(boolean)

getChangeEventsEnabled

protected boolean getChangeEventsEnabled()
Tells whether this Sensor is configured to receive Events from its Peer whenever something changes. If this is true the caching of peer-side values may work.
See Also:
setPeerCacheEnabled(boolean), setChangeEventsEnabled(boolean)

setChangeEventsEnabled

protected void setChangeEventsEnabled(boolean enabled)
Configures whether this Sensor wants to receive Events from its Peer whenever something changes. This must be set to true for the caching of peer-values to work. It is false by default.
See Also:
setPeerCacheEnabled(boolean), getChangeEventsEnabled()

getIntValue

public int getIntValue()
The value-retrieving methods
Specified by:
getIntValue in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.getValue()

getValue

public double getValue()
Description copied from interface: Sensor
Returns the value this Sensor represents as a double.
Specified by:
getValue in interface Sensor

disconnect

public void disconnect()
Description copied from interface: Sensor
Disconnects this Sensor from it's Peer and it's Port. This is implicitly called when the Sensor is already connected and asked to connect with another Port.
Specified by:
disconnect in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.connectWith(Port)

isConnected

public boolean isConnected()
Description copied from interface: Sensor
Tells wether this Sensor has a Peer and whether the Peer is also connected. For example a Peer can be not connected if it is a Peer that only forwards calls to another Peer and that one is not connected or if the RobotInterface this Peer belongs to is not connected.
Specified by:
isConnected in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
SensorPeer.isConnected(), RobotInterface.isConnected(), Sensor.connectWith(Port)

connectWith

public void connectWith(Port port)
Description copied from interface: Sensor
Connects the Sensor with the given Port. The Sensor gets its peer from the Port so it is therefore required before the Sensor can be properly used.
Specified by:
connectWith in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
SensorPort

connectWith

public void connectWith(SensorPort port)
Connects this Sensor with the given Port. The Sensor gets its peer from the Port so it is therefore required before the Sensor can be properly used.
See Also:
RawSensor.ValueSensorPort, connectWith(Port)

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Description copied from interface: Sensor
A PropertyChangeListener receives PropertyChangeEvents whenever this Sensor receives a SensorEvent. The PropertyChangeEvent has the SensorEvent as it's new value and the last SensorEvent as the old value. The property name used for this is value. This mechanism in the Sensor is not really used for anything else right now but may be in future releases.
Specified by:
addPropertyChangeListener in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.addSensorListener(SensorListener), SensorListener.processEvent(SensorEvent)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Description copied from interface: Sensor
Remove the specified listener.
Specified by:
removePropertyChangeListener in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.addPropertyChangeListener(PropertyChangeListener)

addSensorListener

public void addSensorListener(SensorListener listener,
                              SensorEventDescriptor eventDescriptor)
Adds the specified SensorListener to this Sensor so that it receives the SensorEvents which are described by the specified SensorEventDescriptor. If listener is null this method performs no function, nor does it throw an exception. If the EventDescriptor is null the call is forwarded to the method addSensorListener(SensorListener). Note: By now using special SensorEventDescriptors only has the effect that the Events not described are discarded before delivering them to listener but they are still generated.
See Also:
addSensorListener(SensorListener), removeSensorListener(SensorListener,SensorEventDescriptor), SensorListener, SensorEventDescriptor

removeSensorListener

public void removeSensorListener(SensorListener listener,
                                 SensorEventDescriptor eventDescriptor)
Removes the specified SensorListener so that it no longer receives from this Sensor the SensorEvents which are described by the specified SensorEventDescriptor. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added with the specified EventDescriptor to this Sensor. If listener or the EventDescriptor is null, no exception is thrown and no action is performed. Note that after a call to this method, it is still possible that the specified SensorListener receives a SensorEvent which is described by the specified SensorEventDescriptor. That is the case if the intersection of the events described by the given SensorEventDescriptor, with the events described by another SensorEventDescriptor, for which the specified SensorListener is still registered as a listener, is not empty.
See Also:
addSensorListener(SensorListener,SensorEventDescriptor), SensorListener, SensorEventDescriptor

addSensorListener

public void addSensorListener(SensorListener listener)
Description copied from interface: Sensor
Adds the specified SensorListener to this Sensor so that it receives SensorEvents from it. The Events are sent whenever a change in the value is detected but are also allowed to be sent when no change happened.
Specified by:
addSensorListener in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.removeSensorListener(SensorListener), SensorListener.processEvent(SensorEvent)

removeSensorListener

public void removeSensorListener(SensorListener listener)
Description copied from interface: Sensor
Removes the specified SensorListener so that it no longer receives SensorEvents from this Sensor. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to this Sensor. If listener is null, no exception is thrown and no action is performed.
Specified by:
removeSensorListener in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.addSensorListener(SensorListener), SensorListener.processEvent(SensorEvent)

propertyChange

public void propertyChange(PropertyChangeEvent event)
Description copied from interface: Sensor
This is the method through which a Sensor gets informed about changes in the hardware-value it resembles. The internal value of this sensor is set to the new value and a SensorEvent is generated with this Sensor as the source. This new SensorEvent is then passed to processEvent(SensorEvent).
Specified by:
propertyChange in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.processEvent(SensorEvent)

processEvent

public void processEvent(SensorEvent event)
Description copied from interface: Sensor
This Method is called when the value this Sensor resembles has changed and events are enabled. The given SensorEvent is then passed to any registered listeners, the SensorListeners as well as the PropertyChangeListeners. Unlike propertyChange(PropertyChangeEvent) this method is not interested in the new value but in the SensorEvent which resembles the change.
Specified by:
processEvent in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.propertyChange(java.beans.PropertyChangeEvent)

enableEvent

public void enableEvent(SensorEventDescriptor eventDescriptor)
Enables the type of Event described by the given SensorEventDescriptor. This feature is not fully implemented in the sense that it can't be used to specify which events should be generated and which should not. Events can only be enabled once and wiil for now usually never be disabled. Also if events are enabled for any SensorEventDescriptor, they get enabled as if an instance of AllSensorEventDescriptor has been used. It can however be used to enable the caching of the peer-side values without registering a listener for this Sensor.
Specified by:
enableEvent in interface SensorPeer
See Also:
setPeerCacheEnabled(boolean), setChangeEventsEnabled(boolean), AllSensorEventDescriptor

disableEvent

public void disableEvent(SensorEventDescriptor eventDescriptor)
Disables the type of Event described by the given SensorEventDescriptor.
Specified by:
disableEvent in interface SensorPeer
See Also:
enableEvent(SensorEventDescriptor)

update

public void update()
Description copied from interface: Sensor
Causes a new SensorEvent for this Sensor to be generated and delivered. This Event is delivered by the usual Thread which delivers the Events. If this is not the case it is at least a different Thread than the one calling this method.
Specified by:
update in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.processEvent(SensorEvent), SensorPeer.update(), SensorEvent

getSensorPort

public SensorPort getSensorPort()
Description copied from interface: Sensor
Returns a Port through which other Sensors can be connected to this Sensor. This way Sensor-Objects can be cascaded. A Sensor which is connected to the SensorPort returned by this method gets a Peer which represents the value of the Sensor the SensorPort came from. Events are also forwarded. Note the difference between getSensorPort() and getPort().
Specified by:
getSensorPort in interface Sensor
Following copied from interface: de.jaetzold.art.Sensor
See Also:
Sensor.getPort()