PollingRS485Server

java.lang.Object
- util.PropertyContainer
- - io.AbstractDriver
  - - io.AbstractSerialDriver
    - - stella.io.RS485Server
      - stella.io.CastingRS485Server
        
        stella.io.WatchdogRS485Server
        
        stella.io.PollingRS485Server

All Implemented Interfaces:

Driver, Cloneable, Remote, CacheChangedCaster, PollerQuery, RmiSerialCaster, ExitCleaning, Initializable, PropertySupplying, RmiCaster

Direct Known Subclasses:

DummyRS485
```
public class PollingRS485Server
extends WatchdogRS485Server
implements CacheChangedCaster, PollerQuery, Initializable
```
An extension to a normal RS485-server. This server additionally reads its input channels in a repetitive thread. It therefore scans the values of its KEY_ACTIVEREAD and KEY_PASSIVEREAD, respectively, which points to a comma-separated list of command strings. These list can be altered during the live-time of the poller only with a call to the property container's PropertyContainer.setProperty(java.lang.String, java.lang.String) command followed by an appropriate switch-state command. In one cycle all of these strings are then sent as commands to the underlying serial port, the actual list used depending on the state of the poller, see setActive() and setPassive(). The incomming replies (i.e. the channel values) are stored in a hashtable for later retrieval. Users of this class can query the results with calls to the servers readChannel(java.lang.String) method. They must provide the correct read string otherwise lookup will fail.
Note that during the recurrent reading operations, no commands can be written to the serial port. Write commands are delayed until reading the channels has completed. To avoid dead-lock situations the polling intervall KEY_POLLBASE should not be set too small.
Two different polling states are distinguished, active and passive. As the name implies, active polling is meant for phases with rapid changes in the read-cache, like during roof movement. The passive phase is intended for low-resolution serial querying, e.g. during weather-only phases. For the read-list, at least one of the two read-keys, KEY_ACTIVEREAD or KEY_PASSIVEREAD must be given.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`PollingRS485Server.CacheDump` Dumps the poller cache of a remote polling rs485.
`static class`	`PollingRS485Server.ConcurrentTest` Test concurrent access to the serial line by polling and additionally using the `CastingRS485Server.writeCommand(java.lang.String)` method to additionally write commands and retrieve replies from the serial line.
`static class`	`PollingRS485Server.Interleave` Writes the second argument on the command line to the polling rs 485 server bound to the registry with the name of the first command line argument.
`protected class`	`PollingRS485Server.Poller` The polling timer task.
`static class`	`PollingRS485Server.Test` Testing purpose.

Nested classes/interfaces inherited from class stella.io.RS485Server
RS485Server.Checksum, RS485Server.Command, RS485Server.Info, RS485Server.Scan

Nested classes/interfaces inherited from class io.AbstractSerialDriver
AbstractSerialDriver.Available

Field Summary

Fields
Modifier and Type	Field and Description
`protected Map`	`cache` The hashtable linking read-commands to results.
`protected Map`	`cachelisten` The hashtable matching keys to registered cache changed listeners.
`private static boolean`	`DEFCASTPOLL` The default value for casting polling commands (false).
`private static int`	`DEFDROP` The default dropping rate.
`private static long`	`DEFPOLLBASE` The default polling base time, 100 ms.
`private static int`	`DEFRESPONDMAX` Maximum number of cycles for blocked reading.
`private static boolean`	`DEFSTARTOPEN` The default value for starting polling at port open (true).
`private boolean`	`isactive` The poller state.
`static String`	`KEY_ACTIVEDROP` The key to the number of steps dropped on active reads.
`static String`	`KEY_ACTIVEREAD` The key linked to the commands sent to the serial port.
`static String`	`KEY_CASTPOLL` The key defining event-casting for polling commands.
`static String`	`KEY_PASSIVEDROP` The key to the number of steps dropped on passive reads.
`static String`	`KEY_PASSIVEREAD` The key linked to the commands sent to the serial port.
`static String`	`KEY_POLLBASE` The key for the basic polling time.
`static String`	`KEY_RESPONDMAX` The key for the response-reading timeout (ms).
`static String`	`KEY_STARTOPEN` Points to true if polling should start after opening of the port.
`private PollingRS485Server.Poller`	`poll` The polling thread.
`protected Map<String,Long>`	`timecurrent` The hashtable linking read-commands to last read-times.
`protected Map<String,Long>`	`timemax` The hashtable linking read-commands to read-time maxima.
`protected Map<String,Long>`	`timemin` The hashtable linking read-commands to read-time minima.
`protected Map`	`validcache` The hashtable linking read-commands to validity of results.

Fields inherited from class stella.io.WatchdogRS485Server
hosttimer, KEY_CASTOK, KEY_COOLDOWN, KEY_HOSTOK, KEY_INCREMENT, KEY_OKTIME, KEY_RESETONCLOSE, KEY_SAFETY, KEY_WATCHDOG, KEY_WATCHTIME

Fields inherited from class stella.io.CastingRS485Server
KEY_BIND

Fields inherited from class stella.io.RS485Server
KEY_CHECKCHAR, KEY_CHECKSUM, KEY_CLOSE, KEY_CR, KEY_ECHO, KEY_FAILTIME, KEY_FAILURES, KEY_INVALID, KEY_MAXBUFFER, KEY_MAXBUSY, KEY_QUERYTIME, KEY_REINIT, KEY_RESPONDTIME, KEY_STARTUP, KEY_TIMEBUSY, lock

Fields inherited from class io.AbstractSerialDriver
inport, KEY_BAUDRATE, KEY_CLOSETIMEOUT, KEY_DATABIT, KEY_FLOWCONTROL, KEY_INBUFFER, KEY_NOTIFYCOOLDOWN, KEY_OUTBUFFER, KEY_PARITYBIT, KEY_PORTNAME, KEY_RECEIVEFRAMING, KEY_RECEIVETHRESHOLD, KEY_RECEIVETIMEOUT, KEY_STOPBIT, KEY_TIMEOUT, LOCK, outport, STATICLOCK

Fields inherited from class io.AbstractDriver
KEY_DRIVERNAME

Fields inherited from class util.PropertyContainer
KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

Fields inherited from interface stella.rmi.RmiSerialCaster
NAMING_EXTENSION

Fields inherited from interface util.PropertySupplying
CONFIG, KEY_CLASS

Constructor Summary

Constructors
Constructor and Description

PollingRS485Server(Map prop)
Construct a new polling server.

Constructors
Constructor and Description
`PollingRS485Server(Map prop)` Construct a new polling server.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCacheChangedListener(CacheChangedListener ear, String key)` Adds a new cache changed listener to this polling instance.
`String`	`blockChannel(String command)` Blocks until data is available on a certain channel.
`boolean`	`close()` Closes the port.
`void`	`exit()` Stops polling before closing the serial port.
`String`	`getPollerCache()` Dumps the current content of the polling cache to a string.
`void`	`init()` Opens the serial port.
`protected void`	`initCache(Set list)` Constructs a hashtable matching read commands to their actual results.
`String`	`interleaveCommand(String cmd)` Writes an arbitrary command to the serial port.
`boolean`	`isActive()` Returns the state of the poller, true if active, false if passive.
`boolean`	`isPolling()` Tests if this server is actually polling.
`boolean`	`open()` Start polling after opening the serial port, if requested.
`String`	`readChannel(String command)` Returns the value of the queried channel.
`void`	`removeCacheChangedListener(CacheChangedListener ear, String key)` Removes a cache changed listener from this polling instance.
`boolean`	`setActive()` Sets the poller in the active state.
`boolean`	`setPassive()` Sets the poller to passive state.
`boolean`	`startPolling()` Starts the polling.
`void`	`stopPolling()` Stops polling.
`String`	`toString()` Returns the driver name.
`boolean`	`validChannel(String command)` Returns true if the cache value associated with the command is valid.

Methods inherited from class stella.io.WatchdogRS485Server
resetWatchdog, startWatchdog

Methods inherited from class stella.io.CastingRS485Server
addRmiSerialListener, bindToRegistry, isValid, notifyListeners, removeRmiSerialListener, unbindFromRegistry, writeCommand, writeCommand, writeString

Methods inherited from class stella.io.RS485Server
deferCommand, ensureCommand, getCheckSum, getCheckSumming, isReading, readString, setCheckSumming, writeString

Methods inherited from class io.AbstractSerialDriver
createPortEventListener, createPortEventListener, deregisterSoleEventListener, disableEvent, enableEvent, getDriverName, isOpen, registerSoleEventListener, resetOriginalParameters

Methods inherited from class io.AbstractDriver
createDriver, equals, hashCode

Methods inherited from class util.PropertyContainer
augment, augment, augment, augment, augment, clone, 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, initProperties, isNew, parseObject, parseObject, reload, reload, removeProperty, requires, rescanned, setObject, setProperties, setProperty, stringProperties

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - KEY_POLLBASE
```
public static final String KEY_POLLBASE
```
    The key for the basic polling time. (ms).
    
    See Also:
    
    Constant Field Values
  - KEY_ACTIVEREAD
```
public static final String KEY_ACTIVEREAD
```
    The key linked to the commands sent to the serial port.
    
    See Also:
    
    Constant Field Values
  - KEY_PASSIVEREAD
```
public static final String KEY_PASSIVEREAD
```
    The key linked to the commands sent to the serial port.
    
    See Also:
    
    Constant Field Values
  - KEY_ACTIVEDROP
```
public static final String KEY_ACTIVEDROP
```
    The key to the number of steps dropped on active reads.
    
    See Also:
    
    Constant Field Values
  - KEY_PASSIVEDROP
```
public static final String KEY_PASSIVEDROP
```
    The key to the number of steps dropped on passive reads.
    
    See Also:
    
    Constant Field Values
  - KEY_STARTOPEN
```
public static final String KEY_STARTOPEN
```
    Points to true if polling should start after opening of the port.
    
    See Also:
    
    Constant Field Values
  - KEY_CASTPOLL
```
public static final String KEY_CASTPOLL
```
    The key defining event-casting for polling commands.
    
    See Also:
    
    Constant Field Values
  - KEY_RESPONDMAX
```
public static final String KEY_RESPONDMAX
```
    The key for the response-reading timeout (ms).
    
    See Also:
    
    Constant Field Values
  - DEFPOLLBASE
```
private static final long DEFPOLLBASE
```
    The default polling base time, 100 ms.
    
    See Also:
    
    Constant Field Values
  - DEFDROP
```
private static final int DEFDROP
```
    The default dropping rate.
    
    See Also:
    
    Constant Field Values
  - DEFSTARTOPEN
```
private static final boolean DEFSTARTOPEN
```
    The default value for starting polling at port open (true).
    
    See Also:
    
    Constant Field Values
  - DEFCASTPOLL
```
private static final boolean DEFCASTPOLL
```
    The default value for casting polling commands (false).
    
    See Also:
    
    Constant Field Values
  - DEFRESPONDMAX
```
private static final int DEFRESPONDMAX
```
    Maximum number of cycles for blocked reading.
    
    See Also:
    
    Constant Field Values
  - cache
```
protected Map cache
```
    The hashtable linking read-commands to results.
  - validcache
```
protected Map validcache
```
    The hashtable linking read-commands to validity of results.
  - timemax
```
protected Map<String,Long> timemax
```
    The hashtable linking read-commands to read-time maxima.
  - timemin
```
protected Map<String,Long> timemin
```
    The hashtable linking read-commands to read-time minima.
  - timecurrent
```
protected Map<String,Long> timecurrent
```
    The hashtable linking read-commands to last read-times.
  - cachelisten
```
protected Map cachelisten
```
    The hashtable matching keys to registered cache changed listeners.
  - poll
```
private PollingRS485Server.Poller poll
```
    The polling thread.
  - isactive
```
private boolean isactive
```
    The poller state.
- Constructor Detail
  - PollingRS485Server
```
public PollingRS485Server(Map prop)
```
    Construct a new polling server. During construction only the validity of the properties is checked. The method initCache(java.util.Set) is called at the end of the construction phase which sets up the cache hashtable. The polling itself is started after open() or with startPolling(). Polling is always started in the passive phase.
    The following proerties get defaults if not preset:
    - KEY_POLLBASE: DEFPOLLBASE
    - KEY_STARTOPEN: DEFSTARTOPEN
    - KEY_CASTPOLL:DEFCASTPOLL
    - KEY_ACTIVEREAD: The value of KEY_PASSIVEREAD. If both are undefined, construction fails.
    - KEY_PASSIVEREAD: The value of KEY_ACTIVEREAD. If both are undefined, construction fails.
- Method Detail
  - init
```
public void init()
```
    Opens the serial port. If KEY_STARTOPEN is enabled polling is started after opening was successful.
    
    Specified by:
    
    init in interface Initializable
    
    Overrides:
    
    init in class CastingRS485Server
  - open
```
public boolean open()
             throws IOException
```
    Start polling after opening the serial port, if requested.
    
    Specified by:
    
    open in interface Driver
    
    Overrides:
    
    open in class RS485Server
    
    Returns:
    
    True if initialization was successful.
    
    Throws:
    
    IOException
  - exit
```
public void exit()
```
    Stops polling before closing the serial port.
    
    Specified by:
    
    exit in interface ExitCleaning
    
    Overrides:
    
    exit in class CastingRS485Server
  - initCache
```
protected void initCache(Set list)
```
    Constructs a hashtable matching read commands to their actual results. In the initializing phase, all values of the hash table are empty strings.
    Additionally, a lookup-table matching the read commands to their reply length is constructed. The table is filled with the matches of the read-commands to integers in the polling server's properties. If for a given read command no match can be found zero is asumed which is interpreted as an unspecified number of reply bytes.
  - startPolling
```
public boolean startPolling()
```
    Starts the polling. This method spawns an individual reader thread that permanently sends all read command strings to the serial server and stores it into this objects cache hashtable.
    If either the port is not open or the I/O streams are not opened or ready this method returns silently.
    
    Returns:
    
    True if polling was successfully enabled.
  - stopPolling
```
public void stopPolling()
```
    Stops polling. Calls the poller's cancel method. Note that after polling stopped calls can still be made to readChannel(java.lang.String) though they return out-of-date values. A call to startPolling() restarts the polling mechanism.
  - isPolling
```
public boolean isPolling()
                  throws RemoteException
```
    Tests if this server is actually polling. Returns the isRunning status of the polling thread.
    
    Specified by:
    
    isPolling in interface PollerQuery
    
    Throws:
    
    RemoteException
  - setActive
```
public boolean setActive()
```
    Sets the poller in the active state. This means setting the actual poll- drop of the poller to the KEY_ACTIVEDROP value and changing the command list to KEY_ACTIVEREAD. If the poller is alive, this method first synchronizes on the poller cache to avoid concurrent acces to the poller list and/or poller time.
    
    Returns:
    
    True, if poller state was changed successfully to active.
  - setPassive
```
public boolean setPassive()
```
    Sets the poller to passive state. This means setting the actual poll- drop of the poller to the KEY_PASSIVEDROP value and changing the command list to KEY_PASSIVEREAD. If the poller is alive, this method first synchronizes on the poller cache to avoid concurrent acces to the poller list and/or poller time.
    
    Returns:
    
    True, if poller state was changed successfully to passive.
  - isActive
```
public boolean isActive()
```
    Returns the state of the poller, true if active, false if passive.
  - blockChannel
```
public String blockChannel(String command)
```
    Blocks until data is available on a certain channel. This method is intended to be called when a new channel has been added to the polling query and the calling object must ensure that data is available on this channel. If the command is not polled or polling is inactive this method returns immediately with the null String.
    This method checks the mapping of the given key in the cache. As long as this mapping points to the empty String, this method falls into a sleep loop, sleeping period equal to the poller's polling interval.
    
    Returns:
    
    The valid channel reading.
  - getPollerCache
```
public String getPollerCache()
                      throws RemoteException
```
    Dumps the current content of the polling cache to a string.
    
    Specified by:
    
    getPollerCache in interface PollerQuery
    
    Throws:
    
    RemoteException
  - readChannel
```
public String readChannel(String command)
```
    Returns the value of the queried channel. The return value is the currently chached value. Even if polling of the channels has stopped (see isPolling()) data retrieval, though outdated, is still possible.
    This method synchronizes on the cache hashtable to avoid concurrent value updating.
  - validChannel
```
public boolean validChannel(String command)
```
    Returns true if the cache value associated with the command is valid. Note that during read-failures the cache value remains the same but the validity drops to false.
    This method synchronizes on the valid hashtable to avoid concurrent value updating.
    
    Returns:
    
    False if the cached value is outdated or not in the cache at all.
  - interleaveCommand
```
public String interleaveCommand(String cmd)
                         throws RemoteException
```
    Writes an arbitrary command to the serial port. This method should only be used for maintenance with a remote process. E.g. if the roof stucks and you do not yet want to kill the rs485 server, one can use this method from a remote VM.
    In version 1.0, this method is hidden from the serial event listeneners.
    
    Specified by:
    
    interleaveCommand in interface PollerQuery
    
    Throws:
    
    RemoteException
  - close
```
public boolean close()
              throws IOException
```
    Closes the port. Prior to closing the polling thread is ended.
    
    Specified by:
    
    close in interface Driver
    
    Overrides:
    
    close in class WatchdogRS485Server
    
    Returns:
    
    True if clean-up was successful.
    
    Throws:
    
    IOException
  - addCacheChangedListener
```
public void addCacheChangedListener(CacheChangedListener ear,
                                    String key)
```
    Adds a new cache changed listener to this polling instance. Note that registering to keys that are not actually polled is allowed. Additionally, it is assumed that the listener's last cache value is null (what else?), so if the key is present in the cache and mapped to a string different to null, the listener is immediately notified that the cache has changed.
    
    Specified by:
    
    addCacheChangedListener in interface CacheChangedCaster
    
    Parameters:
    
    ear - The listener to be notified when the cache value changes.
    
    key - The serial command this listenr is interested in.
  - removeCacheChangedListener
```
public void removeCacheChangedListener(CacheChangedListener ear,
                                       String key)
```
    Removes a cache changed listener from this polling instance. If the listener has not been registered, nthing changes.
    
    Specified by:
    
    removeCacheChangedListener in interface CacheChangedCaster
    
    Parameters:
    
    ear - The listener to be notified when the cache value changes.
    
    key - The serial command this listenr is interested in.
  - toString
```
public String toString()
```
    Returns the driver name.
    
    Overrides:
    
    toString in class RS485Server

Class PollingRS485Server

Nested Class Summary

Nested classes/interfaces inherited from class stella.io.RS485Server

Nested classes/interfaces inherited from class io.AbstractSerialDriver

Field Summary

Fields inherited from class stella.io.WatchdogRS485Server

Fields inherited from class stella.io.CastingRS485Server

Fields inherited from class stella.io.RS485Server

Fields inherited from class io.AbstractSerialDriver

Fields inherited from class io.AbstractDriver

Fields inherited from class util.PropertyContainer

Fields inherited from interface stella.rmi.RmiSerialCaster

Fields inherited from interface util.PropertySupplying

Constructor Summary

Method Summary

Methods inherited from class stella.io.WatchdogRS485Server

Methods inherited from class stella.io.CastingRS485Server

Methods inherited from class stella.io.RS485Server

Methods inherited from class io.AbstractSerialDriver

Methods inherited from class io.AbstractDriver

Methods inherited from class util.PropertyContainer

Methods inherited from class java.lang.Object

Field Detail

KEY_POLLBASE

KEY_ACTIVEREAD

KEY_PASSIVEREAD

KEY_ACTIVEDROP

KEY_PASSIVEDROP

KEY_STARTOPEN

KEY_CASTPOLL

KEY_RESPONDMAX

DEFPOLLBASE

DEFDROP

DEFSTARTOPEN

DEFCASTPOLL

DEFRESPONDMAX

cache

validcache

timemax

timemin

timecurrent

cachelisten

poll

isactive

Constructor Detail

PollingRS485Server

Method Detail

init

open

exit

initCache

startPolling

stopPolling

isPolling

setActive

setPassive

isActive

blockChannel

getPollerCache

readChannel

validChannel

interleaveCommand

close

addCacheChangedListener

removeCacheChangedListener

toString