iObserver v0.1 - A directory tree monitoring application

===================

This code should be considered an example and is highly EXPERIMENTAL!
Use at your own risk!

===================

1. Classes

1.1 iObserver

    This is the main application class. 
    It starts a separate thread that serves as the main application
    control loop - waiting for a notification of an error or termination.
    The class also is a "plugin" to the iWatch (see below) instances
    that monitor the application configuration file and plugins directory.

    When changes in the configuration file is detected, the new configuration
    is compared with the old one, any changes are being reflected and
    iWatch instances are stopped or started as needed. iWatch instances
    that are still active are updated with the new configuration.

    When a new plugin is detected, it is loaded at runtime and is
    made available to any watch to use. In order the watches to
    begin using such a plugin, the configuratin file should be updated
    (which, as stated above, is also automatically monitored).

1.2 iWatch

    This class represents a single watched object.
    iWatch instances are created by the main iObserver instance.
    They start their own separate threads in which they do the
    monitoring, each using its own instance of pyinotify.

    The iWatch instances implement also the management
    of plugins, dispatching the received events to each plugin.
    
    There are some events that don't originate from the pyinotify
    instance. These events are generated by the watch itself and
    are sent to plugins to notify them of certain stages of the life
    of the watch - init, death, configuration change...

1.3 iPollWatch

    This class is a derivative of iWatch.
    It reimplements only the monitoring loop of the iWatch, implementing
    a polling monitoring of an object.
    This class is only internally used to monitor the configuration file
    and does not support recursive monitoring. However, it illustrates
    how easily iWatch can be exteneded to implement any custom mechanism
    of watching, keeping any event processing and plugin management logic
    intact.

1.4 Other

    iCache - implements a persistent (for the duration of the main iObserver
    instance) shared storage, alowing access from multiple threads.
    It is used by the plugin instances to store any persistent data,
    because plugin instances are not themselves persistent - they are
    created each time an event needs to be processed. This allow for
    existing plugins to be reloaded and changes to the code to be made
    imediately available to the application.

    iError and derivatives - these are the exception classes.
    However, throughout the application these are mostly not
    used as ordinary exceptions - i.e. they are not "raised".
    This is because an exception raised in a thread, cannot be
    catched in another one, thus making error notification
    impossible.

    Instead, instantiating an exception notifies the main iObserver
    instance of the error condition. The iObserver instance then
    can act accordingly - stopping all work, or just stopping a
    specific iWatch instance. The main iObserver thread is not
    raising any exceptions due to the same fact. The user, however,
    can poll the iObserver thread if there are any errors.

    iPlugin - the base class for plugins.
    There is one method that should be reimplemented: the process_event
    method. A plugin is sent all events that an iWatch instance detects
    and also the iWatch specific events mentioned above.

    A plugin instance is given a reference to the global iCache instance
    and also a reference to the iWatch instance it belongs to.


===================
2. Plugins

2.1 Scribe

    This is the logging plugin.

    It keeps track of changes that occur, logging the events using
    human readable messages.

    It is able to track movement (renaming) of files if both the source
    and destination directories are being monitored (by either the same
    iWatch instance or different ones).

    The logger can be configured to write to a log file or to print
    to the standard output.

2.2 Mirror

    The mirroring plugin.

    This plugin keeps track of the changes in a directory tree, reflecting
    the same changes to a target directory, keeping both syncronized.

    Note that no file locking is done, so rapidly changing files could cause
    trouble - being written to, while they are being copied to the mirror.
    This is quite possible impossible to avoid. Otherwise live backups of
    file systems and databases wouldn't be so hard to accomplish.

    The plugin can detect if an object was moved (renamed) within the watched
    directory tree and will apply the renaming in the mirror, without
    copying all the data once again. This is done at the cost of waiting
    to receive both inotify events, describing a move. As a result, a file
    being moved outside the scope of the watched directory tree will be removed
    from the mirror when the next change event is received or alternatively
    when the iWatch's internal termination event is received.

    Mirroring the file and directory metadata is also supported (access mode
    bits, time stampt). Mirroring file ownershit is not supported as we DON'T
    want to run as root.

    Mirroring symbolyc links is not currently supported.

    Another bug in the current implementation is the following: if a directory
    tree gets created quickly enough (i.e. with mkdir -p command), pyinotify
    fails to detect all the subfolders because inotify events are not recursive.
    As a result only the top newly created directory gets monitored.