Class AbstractDeviceMonitor

  • All Implemented Interfaces:
    java.lang.Runnable
    Direct Known Subclasses:
    ChainMonitor, DeviceMonitor, NetworkDeviceMonitor

    public abstract class AbstractDeviceMonitor
    extends java.lang.Object
    implements java.lang.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 NewLine 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", a departure event is generated for the device. @see #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. @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 before finally reporting the exception.

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

    • Field Detail

      • sync_flag

        protected final java.lang.Object sync_flag
        object used for synchronization
      • deviceAddressHash

        protected final java.util.Hashtable<java.lang.Long,​java.lang.Integer> deviceAddressHash
        Addresses of all current devices, mapped to their state count
      • deviceContainerHash

        protected static final java.util.Hashtable<java.lang.Long,​OneWireContainer> deviceContainerHash
        hashtable for holding device containers, static to keep only a single instance of each OneWireContainer.
      • listeners

        protected final java.util.Vector<DeviceMonitorEventListener> listeners
        Listeners who receive notification of events generated by this device Monitor
      • max_state_count

        protected int max_state_count
        Number of searches that a button should be "missing" before it is removed
      • max_error_count

        protected int max_error_count
        Number of searches that an error occurs before a dialog is displayed
      • keepRunning

        protected volatile boolean keepRunning
        Flag for overall thread running state
      • hasCompletelyStopped

        protected volatile boolean hasCompletelyStopped
        Flag for overall thread running state
      • startRunning

        protected volatile boolean startRunning
        Flag to indicate thread has begin to run
      • isRunning

        protected volatile boolean isRunning
        Flag to indicate thread is running now
      • adapter

        protected DSPortAdapter adapter
        the adapter to search for devices
    • 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​(java.util.Vector<java.lang.Long> arrivals,
                                    java.util.Vector<java.lang.Long> 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.
        Throws:
        OneWireException
        OneWireIOException
      • 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 java.lang.Runnable
      • msSleep

        protected void msSleep​(long msTime)
        Sleep for the specified number of milliseconds
        Parameters:
        msTime - number of milliseconds to sleep
      • addDeviceMonitorEventListener

        public void addDeviceMonitorEventListener​(DeviceMonitorEventListener dmel)
        Add a listener, to be notified of arrivals, departures, and exceptions.
        Parameters:
        dmel - Listener of monitor events.
      • fireArrivalEvent

        protected void fireArrivalEvent​(DSPortAdapter adapter,
                                        java.util.Vector<java.lang.Long> address)
        Notify the listeners of the arrival event
        Parameters:
        address - Vector of Long objects representing the address of new arrivals.
      • fireDepartureEvent

        protected void fireDepartureEvent​(DSPortAdapter adapter,
                                          java.util.Vector<java.lang.Long> address)
        Notify the listeners of the departure event
        Parameters:
        address - Vector of Long objects representing the address of departed devices.
      • 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​(java.lang.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​(java.lang.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 java.util.Enumeration<java.lang.Long> 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,
                                                          java.lang.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,
                                                          java.lang.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​(java.lang.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​(java.lang.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