[CODE] Watchdog Extensions

[Mark Womack <mw...@bevocal.com>]

Enclosed is the latest version of the watchdog extensions I am
proposing for inclusion in the log4j library.  I have not received
much response in the past to previously released versions, so this
time I am trying a different tact.  In this release you will find:

1) All the source code for the proposed extension.

2) A jar file that includes all of the classes, ready for immediate
   evaluation and use.  See the notes below.

3) Examples for all of the implemented watchdogs and some simple
   batch files you can use to run them.  See the notes below.
  
4) Detailed javadoc documentation for all of the classes so you
   can experiment with the design and implement your own watchdog
   classes.  And, of course, there is the ultimate documentation,
   the source files themselves.

All you need to provide is your own log4j.jar (version 1.1.3 or the
current 1.2 beta). I hope you find this code useful.  If you have
any comments, suggestions, insights, please drop me an email at
mwomack@bevocal.com.


Log4j Watchdog Extensions
-------------------------

These are some proposed extensions to the Log4j library
to support the automatic reconfiguration of the Log4j configuration
using data from external sources such as files, web urls, and sockets.
This is done using a "watchdog" design.  When the watchdog detects
the source has new/updated configuration data, it initiates the
reconfiguration using the new data.

This package is not an "official" part of the log4j release.
To reflect its status, the classes are contained in their own
package name space (org.womacknet.log4j.watchdogs.*).  The code
is released under an Apache 1.1 license, free for any use.
This code is a work in progress, and is provided as-is. If these
extensions are accepted into the log4j library, their package
namespace will be changed accordingly.

This implementation was inspired by discussion on the log4j-user
mailing list.  It builds upon some underlying log4j functionality
used to support the configureAndWatch() methods found in the
PropertyConfigurator and DOMConfigurator classes.  But instead of
being tied to a specific configurator class or source type, the
design is generalized to be an independent entity that supports any
configurator class and can be implemented to support any desired
source type.

Implementations for watching a file (FileWatchdog), a web url
(HttpWatchdog), or a socket (SocketWatchdog) are included in this
release.  In addition, interfaces and base classes are also included
so that developers can evaluate the design and experiment with
creating their own watchdog implementations.  Javadoc documentation
is included to aid developers in this effort.  It is hoped
that the current design can be used to easily support other source
types such as JMS, databases, etc.  Feedback on the design would
be greatly appreciated.

This implementation is compatible with log4j 1.1.3 or the current
beta release of log4j 1.2 (see SocketWatchdogExample note below).


Examples
--------

FileWatchdogExample.java - This class demonstrates the basic usage
of the FileWatchdog class.  FileWatchdog will watch a log4j configuration
file, and if the file's modification date changes it will use the contents
of the file to reconfigure log4j.  The example can be run using the
run_filewatchdog.bat file.

HttpWatchdogExample.java - This class demonstrates the basic usage
of the HttpWatchdog class.  HttpWatchdog will watch a log4j configuration
file located on a web server.  When the files "Last-Modified" response
date changes, the watchdog will use the contents of the file to
reconfigure log4j.  The example can be run using the run_httpwatchdog.bat
file.

SocketWatchdogExample.java - This class demonstrates the basic usage
of the SocketWatchdog class.  SocketWatchdog will watch a tcp socket on
the localhost.  When that socket is accessed, it uses the input stream
from the socket to reconfigure log4j.  The example can be run using the
run_socketwatchdog.bat file.  One can use the run_pushdatatosocket.bat
file to send configuration to the watched socket.
Note: due to the way SocketWatchdog is implemented, it requires a version
of the doConfigure() method that takes an InputStream as the source of
the configuration data.  This method does not exist on the current version
of PropertyConfigurator.  The watchdog.jar contains a modified version
of PropertyConfigurator (from log4j 1.2 beta 4) that has this method
added.  To use it, simply place the watchdog.jar before the log4j.jar
in your classpath.  For 1.1.3 users, please email Mark Womack (see
email address below) for a compatible version of PropertyConfigurator.


Feedback
--------

Your feedback on the design and implementation of these classes is
greatly valued, and will be evaluated and integrated into future
versions.  Please feel free to contact Mark Womack at mwomack@bevocal.com
with any comments or insights you have.