AbstractDeviceMonitor Class Reference

Inherited by ChainMonitor, DeviceMonitor, and NetworkDeviceMonitor.

List of all members.


Detailed Description

Abstract super-class for 1-Wire Monitors, a optionally-threadable object for searching 1-Wire networks. If this object is not run in it's own thread, it is possible to perform single-step searches by calling the NewLine method directly.
See also:
search(Vector, Vector). The monitor will generate events for device arrivals, device departures, and exceptions from the DSPortAdapter.

In a touch-contact environment, it is not suitable to say that a device has "departed" because it was missing for one cycle of searching. In the time it takes to get an iButton into a blue-dot receptor, the monitor could have generated a handful of arrival and departure events. To circumvent this problem, the device monitor keeps a "missing state count" for each device on the network. Each search cycle that passes where the device is missing causes it's "missing state count" to be incremented. Once the device's "missing state count" is equal to the "max state count", a departure event is generated for the device.

See also:
getMaxStateCount(). If the 1-Wire Network is not in a touch environment, it may be unnecessary to use this "missing state count". In those instances, setting the state count to 1 will disable the feature.

setMaxStateCount(int).

Similarly, the reporting of exceptions could be spurious in a touch-contact environment. Instead of reporting the exception on each failed search attempt, the monitor will default to retrying the search a handful of times before finally reporting the exception.

See also:
getMaxErrorCount(). To disable this feature, set the max error count to 1.

setMaxErrorCount(int).

To receive events, an object must implement the DeviceMonitorEventListener interface.

See also:
DeviceMonitorEventListener. And the object must be added to the list of listeners.

addDeviceMonitorEventListener.

Author:
SH
Version:
1.00

Public Member Functions

void cleanUpStaleContainerReferences ()
 The device monitor will internally cache OneWireContainer objects for each 1-Wire device.
void cleanUpStalePathReferences ()
 The device monitor will internally cache OWPath objects for each 1-Wire device.
void resetSearch ()
 Resets this device monitor.
int getMaxStateCount ()
 The number of searches that a button should be "missing" before it is removed.
void setMaxStateCount (int stateCnt)
 The number of searches that a button should be "missing" before it is removed.
int getMaxErrorCount ()
 Number of searches that an error occurs before listener's are notified.
void setMaxErrorCount (int errorCnt)
 Number of searches that an error occurs before listener's are notified.
DSPortAdapter getAdapter ()
 Returns the DSPortAdapter this device is searching.
abstract void setAdapter (DSPortAdapter adapter)
 Sets this monitor to search a new DSPortAdapter.
abstract void search (Vector arrivals, Vector departures) throws OneWireException, OneWireIOException
 Performs a search of the 1-Wire network.
boolean pauseMonitor (boolean blocking)
 Pause this monitor.
boolean resumeMonitor (boolean blocking)
 Resume this monitor.
boolean isMonitorRunning ()
 Check if this monitor is running.
void killMonitor ()
 Kill this monitor.
void run ()
 Monitor run method that performs a periodic search of the entire 1-Wire network.
void addDeviceMonitorEventListener (DeviceMonitorEventListener dmel)
 Add a listener, to be notified of arrivals, departures, and exceptions.
OWPath getDevicePath (byte[] address)
 Returns the OWPath of the device with the given address.
OWPath getDevicePath (String address)
 Returns the OWPath of the device with the given address.
OWPath getDevicePath (long address)
 Returns the OWPath of the device with the given address.
abstract OWPath getDevicePath (Long address)
 Returns the OWPath of the device with the given address.
Enumeration getAllAddresses ()
 Returns all addresses known by this monitor as an Enumeration of Long objects.

Static Public Member Functions

static OneWireContainer getDeviceContainer (DSPortAdapter adapter, byte[] address)
 Returns the OneWireContainer object of the device with the given address.
static OneWireContainer getDeviceContainer (DSPortAdapter adapter, String address)
 Returns the OneWireContainer object of the device with the given address.
static OneWireContainer getDeviceContainer (DSPortAdapter adapter, long address)
 Returns the OneWireContainer object of the device with the given address.
static OneWireContainer getDeviceContainer (DSPortAdapter adapter, Long longAddress)
 Returns the OneWireContainer object of the device with the given address.
static void putDeviceContainer (byte[] address, OneWireContainer owc)
 Sets the OneWireContainer object of the device with the given address.
static void putDeviceContainer (String address, OneWireContainer owc)
 Sets the OneWireContainer object of the device with the given address.
static void putDeviceContainer (long address, OneWireContainer owc)
 Sets the OneWireContainer object of the device with the given address.
static void putDeviceContainer (Long longAddress, OneWireContainer owc)
 Sets the OneWireContainer object of the device with the given address.

Protected Member Functions

void msSleep (long msTime)
 Sleep for the specified number of milliseconds.
void fireArrivalEvent (DSPortAdapter adapter, Vector address)
 Notify the listeners of the arrival event.
void fireDepartureEvent (DSPortAdapter adapter, Vector address)
 Notify the listeners of the departure event.

Protected Attributes

final Object sync_flag = new Object()
 object used for synchronization
final Hashtable deviceAddressHash = new Hashtable()
 Addresses of all current devices, mapped to their state count.
final Vector listeners = new Vector()
 Listeners who receive notification of events generated by this device Monitor.
int max_state_count = 3
 Number of searches that a button should be "missing" before it is removed.
int max_error_count = 6
 Number of searches that an error occurs before a dialog is displayed.
volatile boolean keepRunning = true
 Flag for overall thread running state.
volatile boolean startRunning = true
 Flag to indicate thread has begin to run.
volatile boolean isRunning = false
 Flag to indicate thread is running now.
DSPortAdapter adapter = null
 the adapter to search for devices

Static Protected Attributes

static final Hashtable deviceContainerHash = new Hashtable()
 hashtable for holding device containers, static to keep only a single instance of each OneWireContainer.

Member Function Documentation

void cleanUpStaleContainerReferences (  ) 

The device monitor will internally cache OneWireContainer objects for each 1-Wire device.

Use this method to clean up all stale container objects. A stale container object is a OneWireContainer object which references a 1-Wire device address which has not been seen by a recent search. This will be essential in a touch-contact environment which could run for some time and needs to conserve memory.

void cleanUpStalePathReferences (  ) 

The device monitor will internally cache OWPath objects for each 1-Wire device.

Use this method to clean up all stale OWPath objects. A stale path object is a OWPath which references a branching path to a 1-Wire device address which has not been seen by a recent search. This will be essential in a touch-contact environment which could run for some time and needs to conserve memory.

Reimplemented in NetworkDeviceMonitor.

void resetSearch (  ) 

Resets this device monitor.

All known devices will be marked as "departed" and departure events will be fired.

int getMaxStateCount (  ) 

The number of searches that a button should be "missing" before it is removed.

Returns:
The number of searches that a button should be "missing" before it is removed.

void setMaxStateCount ( int  stateCnt  ) 

The number of searches that a button should be "missing" before it is removed.

Parameters:
stateCnt The number of searches that a button should be "missing" before it is removed.

int getMaxErrorCount (  ) 

Number of searches that an error occurs before listener's are notified.

Returns:
Number of searches that an error occurs before listener's are notified

void setMaxErrorCount ( int  errorCnt  ) 

Number of searches that an error occurs before listener's are notified.

Parameters:
errorCnt Number of searches that an error occurs before listener's are notified

DSPortAdapter getAdapter (  ) 

Returns the DSPortAdapter this device is searching.

Parameters:
the DSPortAdapter this monitor is searching

abstract void setAdapter ( DSPortAdapter  adapter  )  [pure virtual]

Sets this monitor to search a new DSPortAdapter.

Parameters:
the DSPortAdapter this monitor should search

Implemented in ChainMonitor, DeviceMonitor, and NetworkDeviceMonitor.

abstract void search ( Vector  arrivals,
Vector  departures 
) throws OneWireException, OneWireIOException [pure virtual]

Performs a search of the 1-Wire network.

Parameters:
arrivals A vector of Long objects, represent new arrival addresses.
departures A vector of Long objects, represent departed addresses.

Implemented in ChainMonitor, DeviceMonitor, and NetworkDeviceMonitor.

boolean pauseMonitor ( boolean  blocking  ) 

Pause this monitor.

Parameters:
blocking if true, this method will block until the monitor is paused.
Returns:
true if the monitor was successfully paused.

boolean resumeMonitor ( boolean  blocking  ) 

Resume this monitor.

Parameters:
blocking if true, this method will block until the monitor is resumed.
Returns:
true if the monitor was successfully resumed.

boolean isMonitorRunning (  ) 

Check if this monitor is running.

Returns:
true if monitor is running

void killMonitor (  ) 

Kill this monitor.

Wait util this thread is no longer alive (with timeout).

void run (  ) 

Monitor run method that performs a periodic search of the entire 1-Wire network.

Listeners that have registered are notified when changes in the network are detected.

void msSleep ( long  msTime  )  [protected]

Sleep for the specified number of milliseconds.

Parameters:
msTime number of milliseconds to sleep

void addDeviceMonitorEventListener ( DeviceMonitorEventListener  dmel  ) 

Add a listener, to be notified of arrivals, departures, and exceptions.

Parameters:
dmel Listener of monitor events.

void fireArrivalEvent ( DSPortAdapter  adapter,
Vector  address 
) [protected]

Notify the listeners of the arrival event.

Parameters:
address Vector of Long objects representing the address of new arrivals.

void fireDepartureEvent ( DSPortAdapter  adapter,
Vector  address 
) [protected]

Notify the listeners of the departure event.

Parameters:
address Vector of Long objects representing the address of departed devices.

OWPath getDevicePath ( byte[]  address  ) 

Returns the OWPath of the device with the given address.

Parameters:
address a byte array representing the address of the device
Returns:
The OWPath representing the network path to the device.

OWPath getDevicePath ( String  address  ) 

Returns the OWPath of the device with the given address.

Parameters:
address a string representing the address of the device
Returns:
The OWPath representing the network path to the device.

OWPath getDevicePath ( long  address  ) 

Returns the OWPath of the device with the given address.

Parameters:
address a long representing the address of the device
Returns:
The OWPath representing the network path to the device.

abstract OWPath getDevicePath ( Long  address  )  [pure virtual]

Returns the OWPath of the device with the given address.

Parameters:
address a Long object representing the address of the device
Returns:
The OWPath representing the network path to the device.

Implemented in ChainMonitor, DeviceMonitor, and NetworkDeviceMonitor.

Enumeration getAllAddresses (  ) 

Returns all addresses known by this monitor as an Enumeration of Long objects.

Returns:
Enumeration of Long objects

static OneWireContainer getDeviceContainer ( DSPortAdapter  adapter,
byte[]  address 
) [static]

Returns the OneWireContainer object of the device with the given address.

Parameters:
adapter The DSPortAdapter that the device is connected to.
address a byte array representing the address of the device
Returns:
The specific OneWireContainer object of the device

static OneWireContainer getDeviceContainer ( DSPortAdapter  adapter,
String  address 
) [static]

Returns the OneWireContainer object of the device with the given address.

Parameters:
adapter The DSPortAdapter that the device is connected to.
address a String representing the address of the device
Returns:
The specific OneWireContainer object of the device

static OneWireContainer getDeviceContainer ( DSPortAdapter  adapter,
long  address 
) [static]

Returns the OneWireContainer object of the device with the given address.

Parameters:
adapter The DSPortAdapter that the device is connected to.
address a long representing the address of the device
Returns:
The specific OneWireContainer object of the device

static OneWireContainer getDeviceContainer ( DSPortAdapter  adapter,
Long  longAddress 
) [static]

Returns the OneWireContainer object of the device with the given address.

Parameters:
adapter The DSPortAdapter that the device is connected to.
address a Long object representing the address of the device
Returns:
The specific OneWireContainer object of the device

static void putDeviceContainer ( byte[]  address,
OneWireContainer  owc 
) [static]

Sets the OneWireContainer object of the device with the given address.

Parameters:
address a byte array object representing the address of the device
owc The specific OneWireContainer object of the device

static void putDeviceContainer ( String  address,
OneWireContainer  owc 
) [static]

Sets the OneWireContainer object of the device with the given address.

Parameters:
address a String object representing the address of the device
owc The specific OneWireContainer object of the device

static void putDeviceContainer ( long  address,
OneWireContainer  owc 
) [static]

Sets the OneWireContainer object of the device with the given address.

Parameters:
address a long object representing the address of the device
owc The specific OneWireContainer object of the device

static void putDeviceContainer ( Long  longAddress,
OneWireContainer  owc 
) [static]

Sets the OneWireContainer object of the device with the given address.

Parameters:
address a Long object representing the address of the device
owc The specific OneWireContainer object of the device


The documentation for this class was generated from the following file:

Generated on Thu Aug 28 15:42:30 2008 for 1-Wire API for .NET by  doxygen 1.5.6