mdb
4af8953a19
samskivert to use logging services without creating a dependency on a logging
implementation.
This is basically what JCL (Jakarta Commons Logging) does except they do
auto-detection based on what's in the classpath and we're only going to
auto-detect log4j and only use it if we see that a log4j configuration has been
provided via a system property (or maybe not at all, I'm not sure yet). The
point is avoid the major gripe about JCL which is that when you stick some
logging system's jar file into your classpath for some other dependency (or
it's there for unknown reasons like maybe your servlet container uses it), all
of a sudden your log output disappears or breaks.
I had an idea while doing this and couldn't resist slipping it in: all of the
logging methods take varargs additional parameters which are a set of key/value
pairs to append to the log message in our standard format with an optional
final exception to be logged as well.
So instead of:
log.warning("Oh crap, the fibbleminscher has exploded [state=" + 15 +
", monkeys=" + StringUtil.toString(_monkeys) + "].");
You do:
log.warning("Oh crap, the fibbleminscher has exploded.", "state", 15,
"monkeys", _monkeys);
The formatter automatically does the StringUtil.toString magic on the arguments
(and does it safely so that if toString throws an exception the log message
isn't lost). You can also throw an exception in the mix:
log.warning("Oh crap, the fibbleminscher has exploded.", "state", 15,
"monkeys", _monkeys, ioe);
Or supply one with no parameters:
log.warning("Oh mammy!", ioe);
Or even just log an exception if you have nothing pithy to add:
log.warning(ioe);
Some research shows that other people have started doing this in their logging
systems as well under the fancier name of parameterized logging. The big
benefit is that you can pass objects that are expensive to toString() and avoid
toString()ing them unless you're actually going to generate the log message.
In our case we also get the benefit of our standard formatting and less
cluttered code (begone lots of + ", ...=" + typing).
I'm going to be doing away with the old samskivert Log code and converting all
of our libraries (and projects) to use this new shim so that we can easily
switch to using log4j, which for other reasons we want to use instead of Java's
built-in logging.
git-svn-id: https://samskivert.googlecode.com/svn/trunk@2311 6335cc39-0255-0410-8fd6-9bcaacd3b74c
The samskivert library ---------------------- The samskivert library (SL) aims to provide useful reusable Java routines that do things for which I've been unable to find useful reusable implementations on the net. Given the emphasis on reusability, SL attempts to closely adhere to the following principles: * Each individual module should depend as little as possible on other SL modules. Obvious exceptions include modules that are a logical extension of other modules and modules that clearly require a service that is implemented by another SL module and would have to implement that service themselves in the absence of dependence on the other module. * Modules should be both simple to use and as general purpose as possible. To meet these two competing requirements, a balance must be struck at that sweet spot where reusability is maximized. * Code included in SL will freely depend on JDK packages available in the Java 2 platform and beyond. SL is initially a repository of software useful for server-side or stand alone applications and therefore need not make compromises to function in the jungle of JVMs in commonly available web browsers. * We are not here to reinvent the wheel, nor to provide a uniform interface to every software service under the sun. If something is available in a freely redistributable and reusable form from someone else, it won't be found in SL. If SL depends on such software from another source, it will provide clear documentation on how to get that software and make use of it within the scope of SL's particular needs. Again a balance of reusability will be struck here and software that is sufficiently difficult to make usable in an arbitrary environment will not be used by SL and may be "reinvented". Building -------- Building the library is very simple. First ensure that the necessary third party jar files are available either in the lib/ directory or in the system wide jar file location specified in build.xml. See lib/README for a list of the necessary third party jar files and how to get them. The library is built using ant, a modern build tool available from The Jakarta Project. If you aren't already using ant for other projects, it can be found here: http://jakarta.apache.org/ant/ Invoke ant with any of the following targets: all: builds the class files and javadoc documentation compile: builds only the class files (dist/classes) javadoc: builds only the javadoc documentation (dist/docs) dist: builds the distribution jar file (dist/samskivert.jar) Look at the build.xml file for configurable build parameters. Distribution ------------ The samskivert library is released under the LGPL. The most recent version of the library is available here: http://samskivert.com/code/samskivert/ Contribution ------------ Contributions to SL are welcome. Control of the CVS repository is presently in the hands of mdb@samskivert.com, who should be emailed about submissions. Facilities for management of major contributions by external parties (ie. publicly accessible CVS server) will be provided if circumstances dictate. Contact Information ------------------- The person primarily responsible for SL is Michael Bayne and can be contacted at <mdb@samskivert.com>. $Id: README,v 1.7 2001/08/12 00:00:42 mdb Exp $