com.dalsemi.onewire.application.monitor
Class AbstractDeviceMonitor

java.lang.Object
  |
  +--com.dalsemi.onewire.application.monitor.AbstractDeviceMonitor

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

DeviceMonitor, NetworkDeviceMonitor

public abstract class AbstractDeviceMonitor

extends Object

implements Runnable

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 search method directly {@see #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" {@see #getMaxStateCount()}, a departure event is generated for the device. 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 {@see #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 {@see #getMaxErrorCount()} before finally reporting the exception. To disable this feature, set the max error count to 1 {@see #setMaxErrorCount(int)}.

To receive events, an object must implement the DeviceMonitorEventListener interface {@see DeviceMonitorEventListener} and must be added to the list of listeners {@see #addDeviceMonitorEventListener}.

Version:

1.00

Author:

SH

Constructor Summary

AbstractDeviceMonitor()

Method Summary

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

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractDeviceMonitor

public AbstractDeviceMonitor()

Method Detail

cleanUpStaleContainerReferences

public 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.

cleanUpStalePathReferences

public 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.

resetSearch

public void resetSearch()

Resets this device monitor. All known devices will be marked as "departed" and departure events will be fired.

getMaxStateCount

public 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.

setMaxStateCount

public 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.

getMaxErrorCount

public 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

setMaxErrorCount

public 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

getAdapter

public DSPortAdapter getAdapter()

Returns the DSPortAdapter this device is searching

Parameters:

the - DSPortAdapter this monitor is searching

setAdapter

public abstract void setAdapter(DSPortAdapter adapter)

Sets this monitor to search a new DSPortAdapter

Parameters:

the - DSPortAdapter this monitor should search

search

public abstract void search(Vector arrivals,
                            Vector departures)
                     throws OneWireException,
                            OneWireIOException

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.

pauseMonitor

public boolean pauseMonitor(boolean blocking)

Pause this monitor

Parameters:

blocking - if true, this method will block until the monitor is paused.

resumeMonitor

public boolean resumeMonitor(boolean blocking)

Resume this monitor

Parameters:

blocking - if true, this method will block until the monitor is resumed.

isMonitorRunning

public boolean isMonitorRunning()

Check if this monitor is running.

Returns:

true if monitor is running

killMonitor

public void killMonitor()

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

run

public 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.

Specified by:

run in interface Runnable

addDeviceMonitorEventListener

public void addDeviceMonitorEventListener(DeviceMonitorEventListener dmel)

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

Parameters:

dmel - Listener of monitor events.

getDevicePath

public 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.

getDevicePath

public 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.

getDevicePath

public 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.

getDevicePath

public abstract OWPath getDevicePath(Long address)

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.

getAllAddresses

public Enumeration getAllAddresses()

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

Returns:

Enumeration of Long objects

getDeviceContainer

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

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

getDeviceContainer

public static OneWireContainer getDeviceContainer(DSPortAdapter adapter,
                                                  String address)

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

getDeviceContainer

public static OneWireContainer getDeviceContainer(DSPortAdapter adapter,
                                                  long address)

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

getDeviceContainer

public static OneWireContainer getDeviceContainer(DSPortAdapter adapter,
                                                  Long longAddress)

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

putDeviceContainer

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

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

putDeviceContainer

public static void putDeviceContainer(String address,
                                      OneWireContainer owc)

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

putDeviceContainer

public static void putDeviceContainer(long address,
                                      OneWireContainer owc)

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

putDeviceContainer

public static void putDeviceContainer(Long longAddress,
                                      OneWireContainer owc)

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