diff --git a/.cvsignore b/.cvsignore
new file mode 100644
index 0000000..b1e4b87
--- /dev/null
+++ b/.cvsignore
@@ -0,0 +1,3 @@
+build.properties
+dist
+target
diff --git a/PROPOSAL.html b/PROPOSAL.html
new file mode 100644
index 0000000..e5081c6
--- /dev/null
+++ b/PROPOSAL.html
@@ -0,0 +1,92 @@
+
+
+Proposal for Logging Library Package
+
+
+
+
+
Proposal for Logging Package
+
+
+(0) Rationale
+
+There is a great need for debugging and logging information inside of
+Commons components such as HTTPClient and dbcp. However, there are many
+logging APIs out there and it is difficult to choose among them.
+
+
+The Logging package will be an ultra-thin bridge between different logging
+libraries. Commons components may use the Logging JAR to remove
+compile-time/runtime dependencies on any particular logging package,
+and contributors may write Log implementations for the library of their choice.
+
+
+(1) Scope of the Package
+
+The package shall create and maintain a package that provides extremely
+basic logging functionality and bridges to other, more sophisticated logging
+implementations.
+
+
+
+The package should :
+
+- Have an API which should be as simple to use as possible
+- Provide support for log4j
+- Provide pluggable support for other logging APIs
+
+
+
+
+Non-goals:
+
+- This package will not perform logging itself, except at the most basic
+ level.
+- We do not seek to become a "standard" API.
+
+
+
+(1.5) Interaction With Other Packages
+
+Logging relies on:
+
+
+
+ - Java Development Kit (Version 1.1 or later)
+
+ - log4j (compile-time dependency only)
+
+
+(2) Required Jakarta-Commons Resources
+
+
+- CVS Repository - New directory
logging in the
+jakarta-commons CVS repository.
+
+- Initial Committers - The list is provided below.
+
+- Mailing List - Discussions will take place on the general
+commons-dev@jakarta.apache.org mailing list. To help list
+subscribers identify messages of interest, it is suggested that the
+message subject of messages about this component be prefixed with
+[Logging].
+
+- Bugzilla - New component "Logging" under the "Commons" product
+category, with appropriate version identifiers as needed.
+
+- Jyve FAQ - New category "commons-logging" (when available).
+
+
+
+(4) Initial Committers
+
+The initial committers on the Logging component shall be:
+
+
+ - Morgan Delagrange
+ - Rodney Waldhoff
+ - Craig McClanahan
+
+
+
+
diff --git a/build.properties.sample b/build.properties.sample
new file mode 100644
index 0000000..736b6c2
--- /dev/null
+++ b/build.properties.sample
@@ -0,0 +1,2 @@
+# log4j.jar - log4j classes (see http://jakarta.apache.org/log4j)
+log4j.jar=/java/log4j/log4j.jar
diff --git a/build.xml b/build.xml
new file mode 100644
index 0000000..4977c6a
--- /dev/null
+++ b/build.xml
@@ -0,0 +1,216 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/src/java/org/apache/commons/logging/Log.java b/src/java/org/apache/commons/logging/Log.java
new file mode 100644
index 0000000..c75535e
--- /dev/null
+++ b/src/java/org/apache/commons/logging/Log.java
@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included with this distribution in
+ * the LICENSE file.
+ */
+
+package org.apache.commons.logging;
+
+/**
+ * A simple logging interface abstracting logging APIs. In order to be
+ * instantiated successfully by {@link LogFactory}, classes that implement
+ * this interface must have a constructor that takes a single String
+ * parameter representing the "name" of this Log.
+ *
+ * @author Rod Waldhoff
+ * @version $Id: Log.java,v 1.6 2001/12/04 04:28:03 craigmcc Exp $
+ */
+public interface Log {
+ public void debug(Object message);
+ public void debug(Object message, Throwable t);
+ public void info(Object message);
+ public void info(Object message, Throwable t);
+ public void warn(Object message);
+ public void warn(Object message, Throwable t);
+ public void error(Object message);
+ public void error(Object message, Throwable t);
+ public void fatal(Object message);
+ public void fatal(Object message, Throwable t);
+ public boolean isDebugEnabled();
+ public boolean isInfoEnabled();
+ public void setLevel(int level);
+ public int getLevel();
+
+ /** All logging level. */
+ public static final int ALL = Integer.MIN_VALUE;
+ /** "Debug" level logging. */
+ public static final int DEBUG = 10000;
+ /** "Info" level logging. */
+ public static final int INFO = 20000;
+ /** "Warn" level logging. */
+ public static final int WARN = 30000;
+ /** "Error" level logging. */
+ public static final int ERROR = 40000;
+ /** "Fatal" level logging. */
+ public static final int FATAL = 50000;
+ /** No logging level. */
+ public static final int OFF = Integer.MAX_VALUE;
+}
diff --git a/src/java/org/apache/commons/logging/Log4JCategoryLog.java b/src/java/org/apache/commons/logging/Log4JCategoryLog.java
new file mode 100644
index 0000000..ff40f69
--- /dev/null
+++ b/src/java/org/apache/commons/logging/Log4JCategoryLog.java
@@ -0,0 +1,108 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included with this distribution in
+ * the LICENSE file.
+ */
+
+package org.apache.commons.logging;
+
+import org.apache.log4j.Category;
+import org.apache.log4j.Priority;
+
+/**
+ * Implementation of {@link Log} that maps directly to a Log4J
+ * Category. Initial configuration of the corresponding
+ * Category instances should be done in the usual manner, as outlined in
+ * the Log4J documentation.
+ *
+ * @author Rod Waldhoff
+ * @version $Id: Log4JCategoryLog.java,v 1.6 2001/12/04 04:28:03 craigmcc Exp $
+ */
+public class Log4JCategoryLog implements Log {
+ Category _category = null;
+
+ public Log4JCategoryLog(String name) {
+ _category = Category.getInstance(name);
+ }
+
+ public final void debug(Object message) {
+ _category.debug(message);
+ }
+
+ public final void debug(Object message, Throwable t) {
+ _category.debug(message,t);
+ }
+
+ public final void info(Object message) {
+ _category.info(message);
+ }
+
+ public final void info(Object message, Throwable t) {
+ _category.info(message,t);
+ }
+
+ public final void warn(Object message) {
+ _category.warn(message);
+ }
+ public final void warn(Object message, Throwable t) {
+ _category.warn(message,t);
+ }
+
+ public final void error(Object message) {
+ _category.error(message);
+ }
+
+ public final void error(Object message, Throwable t) {
+ _category.error(message,t);
+ }
+
+ public final void fatal(Object message) {
+ _category.fatal(message);
+ }
+
+ public final void fatal(Object message, Throwable t) {
+ _category.fatal(message,t);
+ }
+
+ public final boolean isDebugEnabled() {
+ return _category.isDebugEnabled();
+ }
+
+ public final boolean isInfoEnabled() {
+ return _category.isInfoEnabled();
+ }
+
+ public final boolean isEnabledFor(Priority p) {
+ return _category.isEnabledFor(p);
+ }
+
+ public final void setLevel(int level) {
+ switch(level) {
+ case Log.DEBUG:
+ _category.setPriority(Priority.DEBUG);
+ break;
+ case Log.INFO:
+ _category.setPriority(Priority.INFO);
+ break;
+ case Log.WARN:
+ _category.setPriority(Priority.WARN);
+ break;
+ case Log.ERROR:
+ _category.setPriority(Priority.ERROR);
+ break;
+ case Log.FATAL:
+ _category.setPriority(Priority.FATAL);
+ break;
+ default:
+ _category.setPriority(Priority.toPriority(level));
+ break;
+ }
+ }
+
+ public final int getLevel() {
+ return _category.getPriority().toInt();
+ }
+
+}
diff --git a/src/java/org/apache/commons/logging/LogSource.java b/src/java/org/apache/commons/logging/LogSource.java
new file mode 100644
index 0000000..e617d35
--- /dev/null
+++ b/src/java/org/apache/commons/logging/LogSource.java
@@ -0,0 +1,175 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included with this distribution in
+ * the LICENSE file.
+ */
+
+package org.apache.commons.logging;
+
+import java.util.HashMap;
+import java.lang.reflect.Constructor;
+import java.util.Iterator;
+import java.lang.reflect.InvocationTargetException;
+
+/**
+ * Factory for creating {@link Log} instances. Applications should call
+ * the makeNewLogInstance() method to instantiate new instances
+ * of the configured {@link Log} implementation class.
+ *
+ * @author Rod Waldhoff
+ * @version $Id: LogSource.java,v 1.4 2001/12/04 04:28:03 craigmcc Exp $
+ */
+public class LogSource {
+ static protected HashMap _logs = new HashMap();
+ static protected boolean _log4jIsAvailable = false;
+ static {
+ try {
+ if(null != Class.forName("org.apache.log4j.Category")) {
+ _log4jIsAvailable = true;
+ } else {
+ _log4jIsAvailable = false;
+ }
+ } catch(ClassNotFoundException e) {
+ _log4jIsAvailable = false;
+ } catch(ExceptionInInitializerError e) {
+ _log4jIsAvailable = false;
+ } catch(LinkageError e) {
+ _log4jIsAvailable = false;
+ }
+ }
+
+ static protected Constructor _logimplctor = null;
+ static {
+ try {
+ setLogImplementation(System.getProperty("org.apache.commons.logging.log","org.apache.commons.logging.NoOpLog"));
+ } catch(SecurityException e) {
+ _logimplctor = null;
+ } catch(LinkageError e) {
+ _logimplctor = null;
+ } catch(NoSuchMethodException e) {
+ _logimplctor = null;
+ } catch(ClassNotFoundException e) {
+ _logimplctor = null;
+ }
+ }
+
+ private LogSource() {
+ }
+
+ /**
+ * Set the log implementation/log implementation factory
+ * by the name of the class. The given class
+ * must implement {@link Log}, and provide a constructor that
+ * takes a single {@link String} argument (containing the name
+ * of the log).
+ */
+ static public void setLogImplementation(String classname) throws
+ LinkageError, ExceptionInInitializerError,
+ NoSuchMethodException, SecurityException,
+ ClassNotFoundException {
+ Class logclass = Class.forName(classname);
+ Class[] argtypes = new Class[1];
+ argtypes[0] = "".getClass();
+ _logimplctor = logclass.getConstructor(argtypes);
+ }
+
+ /**
+ * Set the log implementation/log implementation factory
+ * by class. The given class must implement {@link Log},
+ * and provide a constructor that takes a single {@link String}
+ * argument (containing the name of the log).
+ */
+ static public void setLogImplementation(Class logclass) throws
+ LinkageError, ExceptionInInitializerError,
+ NoSuchMethodException, SecurityException {
+ Class[] argtypes = new Class[1];
+ argtypes[0] = "".getClass();
+ _logimplctor = logclass.getConstructor(argtypes);
+ }
+
+ static public Log getInstance(String name) {
+ Log log = (Log)(_logs.get(name));
+ if(null == log) {
+ log = makeNewLogInstance(name);
+ _logs.put(name,log);
+ }
+ return log;
+ }
+
+ static public Log getInstance(Class clazz) {
+ return getInstance(clazz.getName());
+ }
+
+ /**
+ * Create a new {@link Log} implementation, based
+ * on the given name
+ *
+ * The specific {@link Log} implementation returned
+ * is determined by the value of the
+ * org.apache.commons.logging.log property.
+ * The value of org.apache.commons.logging.log may be set to
+ * the fully specified name of a class that implements
+ * the {@link Log} interface. This class must also
+ * have a public constructor that takes a single
+ * {@link String} argument (containing the name
+ * of the {@link Log} to be constructed.
+ *
+ * When httpclient.log is not set,
+ * or when no corresponding class can be found,
+ * this method will return a {@link Log4JCategoryLog}
+ * if the log4j {@link org.apache.log4j.Category} class is
+ * available in the {@link LogSource}'s classpath, or
+ * a {@link NoOpLog} if it is not.
+ *
+ * @param name the log name (or category)
+ */
+ static public Log makeNewLogInstance(String name) {
+ Log log = null;
+ try {
+ Object[] args = new Object[1];
+ args[0] = name;
+ log = (Log)(_logimplctor.newInstance(args));
+ } catch (InstantiationException e) {
+ log = null;
+ } catch (IllegalAccessException e) {
+ log = null;
+ } catch (IllegalArgumentException e) {
+ log = null;
+ } catch (InvocationTargetException e) {
+ log = null;
+ } catch (NullPointerException e) {
+ log = null;
+ }
+ if(null == log) {
+ if(_log4jIsAvailable) {
+ return new Log4JCategoryLog(name);
+ } else {
+ log = new NoOpLog(name);
+ }
+ }
+ return log;
+ }
+
+ /**
+ * Sets the log level for all {@link Log}s known
+ * to me.
+ */
+ static public void setLevel(int level) {
+ Iterator it = _logs.entrySet().iterator();
+ while(it.hasNext()) {
+ Log log = (Log)(it.next());
+ log.setLevel(level);
+ }
+ }
+
+ /**
+ * Returns a {@link String} array containing the names of
+ * all logs known to me.
+ */
+ static public String[] getLogNames() {
+ return (String[])(_logs.keySet().toArray(new String[_logs.size()]));
+ }
+
+}
diff --git a/src/java/org/apache/commons/logging/NoOpLog.java b/src/java/org/apache/commons/logging/NoOpLog.java
new file mode 100644
index 0000000..1abdc4b
--- /dev/null
+++ b/src/java/org/apache/commons/logging/NoOpLog.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included with this distribution in
+ * the LICENSE file.
+ */
+
+package org.apache.commons.logging;
+
+/**
+ *
Default implementation of Log that throws away all messages. No
+ * configurable system properties are supported.
+ *
+ * @author Rod Waldhoff
+ * @version $Id: NoOpLog.java,v 1.6 2001/12/04 04:28:03 craigmcc Exp $
+ */
+public final class NoOpLog implements Log {
+ public NoOpLog() { }
+ public NoOpLog(String name) { }
+ public void debug(Object message) { }
+ public void debug(Object message, Throwable t) { }
+ public void info(Object message) { }
+ public void info(Object message, Throwable t) { }
+ public void warn(Object message) { }
+ public void warn(Object message, Throwable t) { }
+ public void error(Object message) { }
+ public void error(Object message, Throwable t) { }
+ public void fatal(Object message) { }
+ public void fatal(Object message, Throwable t) { }
+ public final boolean isDebugEnabled() { return false; }
+ public final boolean isInfoEnabled() { return false; }
+ public final void setLevel(int level) { }
+ public final int getLevel() { return Log.OFF; }
+}
diff --git a/src/java/org/apache/commons/logging/SimpleLog.java b/src/java/org/apache/commons/logging/SimpleLog.java
new file mode 100644
index 0000000..e1475b5
--- /dev/null
+++ b/src/java/org/apache/commons/logging/SimpleLog.java
@@ -0,0 +1,206 @@
+/*
+ * Copyright (C) The Apache Software Foundation. All rights reserved.
+ *
+ * This software is published under the terms of the Apache Software License
+ * version 1.1, a copy of which has been included with this distribution in
+ * the LICENSE file.
+ */
+
+package org.apache.commons.logging;
+
+import java.util.Properties;
+import java.util.Enumeration;
+import java.io.InputStream;
+import java.text.SimpleDateFormat;
+import java.text.DateFormat;
+import java.util.Date;
+
+/**
+ * Simple implementation of Log that sends all enabled log messages,
+ * for all defined loggers, to System.out. The following system properties
+ * are supported to configure the behavior of this logger:
+ *
+ * org.apache.commons.logging.simplelog.defaultlog -
+ * Default logging detail level for all instances of SimpleLog.
+ * Must be one of ("debug", "info", "warn", "error", or "fatal").
+ * If not specified, defaults to "error".org.apache.commons.logging.simplelog.log.xxxxx -
+ * Logging detail level for a SimpleLog instance named "xxxxx".
+ * Must be one of ("debug", "info", "warn", "error", or "fatal").
+ * If not specified, the default logging detail level is used.org.apache.commons.logging.simplelog.showlogname -
+ * Set to true if you want the Log instance name to be
+ * included in output messages.org.apache.commons.logging.simplelog.showtime -
+ * Set to true if you want the current date and time
+ * to be included in output messages.
+ *
+ * In addition to looking for system properties with the names specified
+ * above, this implementation also checks for a class loader resource named
+ * "simplelog.properties", and includes any matching definitions
+ * from this resource (if it exists).
+ *
+ * @author Rod Waldhoff
+ * @version $Id: SimpleLog.java,v 1.6 2001/12/04 04:28:03 craigmcc Exp $
+ */
+public class SimpleLog implements Log {
+ static protected final String _prefix =
+ "org.apache.commons.logging.simplelog.";
+ static protected final Properties _simplelogProps = new Properties();
+ static protected boolean _showlogname = false;
+ static protected boolean _showtime = false;
+ static protected DateFormat _df = null;
+
+ static {
+ // add all system props that start with the specified prefix
+ Enumeration enum = System.getProperties().propertyNames();
+ while(enum.hasMoreElements()) {
+ String name = (String)(enum.nextElement());
+ if(null != name && name.startsWith(_prefix)) {
+ _simplelogProps.setProperty(name,System.getProperty(name));
+ }
+ }
+
+ // add props from the resource simplelog.properties
+ InputStream in =
+ ClassLoader.getSystemResourceAsStream("simplelog.properties");
+ if(null != in) {
+ try {
+ _simplelogProps.load(in);
+ in.close();
+ } catch(java.io.IOException e) {
+ // ignored
+ }
+ }
+ try {
+ } catch(Throwable t) {
+ // ignored
+ }
+ _showlogname = "true".equalsIgnoreCase(_simplelogProps.getProperty(_prefix + "showlogname","true"));
+ _showtime = "true".equalsIgnoreCase(_simplelogProps.getProperty(_prefix + "showdate","true"));
+ if(_showtime) {
+ _df = new SimpleDateFormat(_simplelogProps.getProperty(_prefix + "dateformat","yyyy/MM/dd HH:mm:ss:SSS zzz"));
+ }
+ }
+
+ protected static final int DEBUG = 5;
+ protected static final int INFO = 4;
+ protected static final int WARN = 3;
+ protected static final int ERROR = 2;
+ protected static final int FATAL = 1;
+ protected int _logLevel = 2;
+
+ protected String _name = null;
+
+ public SimpleLog(String name) {
+ _name = name;
+
+ String lvl = _simplelogProps.getProperty(_prefix + "log." + _name);
+ int i = String.valueOf(name).lastIndexOf(".");
+ while(null == lvl && i > -1) {
+ name = name.substring(0,i);
+ lvl = _simplelogProps.getProperty(_prefix + "log." + name);
+ i = String.valueOf(name).lastIndexOf(".");
+ }
+ if(null == lvl) {
+ lvl = _simplelogProps.getProperty(_prefix + "defaultlog");
+ }
+
+ if("debug".equalsIgnoreCase(lvl)) {
+ _logLevel = DEBUG;
+ } else if("info".equalsIgnoreCase(lvl)) {
+ _logLevel = INFO;
+ } else if("warn".equalsIgnoreCase(lvl)) {
+ _logLevel = WARN;
+ } else if("error".equalsIgnoreCase(lvl)) {
+ _logLevel = ERROR;
+ } else if("fatal".equalsIgnoreCase(lvl)) {
+ _logLevel = FATAL;
+ }
+ }
+
+ protected void log(int type, Object message, Throwable t) {
+ if(_logLevel >= type) {
+ StringBuffer buf = new StringBuffer();
+ if(_showtime) {
+ buf.append(_df.format(new Date()));
+ buf.append(" ");
+ }
+ switch(type) {
+ case DEBUG: buf.append("[DEBUG] "); break;
+ case INFO: buf.append("[INFO] "); break;
+ case WARN: buf.append("[WARN] "); break;
+ case ERROR: buf.append("[ERROR] "); break;
+ case FATAL: buf.append("[FATAL] "); break;
+ }
+ if(_showlogname) {
+ buf.append(String.valueOf(_name)).append(" - ");
+ }
+ buf.append(String.valueOf(message));
+ if(t != null) {
+ buf.append(" <");
+ buf.append(t.toString());
+ buf.append(">");
+ t.printStackTrace();
+ }
+ System.out.println(buf.toString());
+ }
+ }
+
+ public final void debug(Object message) {
+ log(DEBUG,message,null);
+ }
+
+ public final void debug(Object message, Throwable t) {
+ log(DEBUG,message,t);
+ }
+
+ public final void info(Object message) {
+ log(INFO,message,null);
+ }
+
+ public final void info(Object message, Throwable t) {
+ log(INFO,message,t);
+ }
+
+ public final void warn(Object message) {
+ log(WARN,message,null);
+ }
+ public final void warn(Object message, Throwable t) {
+ log(WARN,message,t);
+ }
+
+ public final void error(Object message) {
+ log(ERROR,message,null);
+ }
+
+ public final void error(Object message, Throwable t) {
+ log(ERROR,message,t);
+ }
+
+ public final void fatal(Object message) {
+ log(FATAL,message,null);
+ }
+
+ public final void fatal(Object message, Throwable t) {
+ log(FATAL,message,t);
+ }
+
+ public final boolean isDebugEnabled() {
+ return (_logLevel >= DEBUG);
+ }
+
+ public final boolean isInfoEnabled() {
+ return (_logLevel >= INFO);
+ }
+
+ public final void setLevel(int level) {
+ _logLevel = level;
+ }
+
+ public final int getLevel() {
+ return _logLevel;
+ }
+
+}
diff --git a/src/java/org/apache/commons/logging/package.html b/src/java/org/apache/commons/logging/package.html
new file mode 100644
index 0000000..123daba
--- /dev/null
+++ b/src/java/org/apache/commons/logging/package.html
@@ -0,0 +1,123 @@
+
+Simple wrapper API around multiple logging APIs.
+
+Overview
+
+This package provides an API for logging in server-based applications that
+can be used around a variety of different logging implementations, including
+prebuilt support for the following:
+
+- Log4J from Apache's
+ Jakarta project. Each named Log instance is
+ connected to a corresponding Log4J Category.
+
+- NoOpLog implementation that simply swallows
+ all log output, for all named Log isntances.
+- SimpleLog implementation that writes all
+ log output, for all named Log instances, to
+ System.out.
+
+
+Configuring the Logging Package APIs
+
+The Logging Package APIs are configured based on the values of system
+properties, which are normally set on the command line that started your
+application. The following system properties are global to all
+Log implementations:
+
+org.apache.commons.logging.log - Fully qualified class name
+ of the org.apache.commons.logging.Log implementation to be
+ used.
+
+If you do not specify the class name of the Log implementation to use, the
+following algorithm is applied:
+
+- If Log4J is available, return an instance of
+ Log4JCategoryLog that wraps a
+ Log4J Category instance of the specified name.
+
+- Return an instance of NoOpLog that
+ throws away all logged output.
+
+
+
+Additionally, each individual Log implementation may
+support its own configuration properties. These will be documented in the
+class descriptions for the corresponding implementation class.
+
+Finally, some Log implementations (such as the one for Log4J)
+require an external configuration file for the entire logging environment.
+This file should be prepared in a manner that is specific to the actual logging
+technology being used.
+
+Using the Logging Package APIs
+
+Use of the Logging Package APIs, from the perspective of an application
+component, consists of the following steps:
+
+- Acquire a reference to an instance of
+ org.apache.commons.logging.Log, by calling the
+ factory method
+
+ LogSource.makeNewLogInstance(). Your application can contain
+ references to multiple loggers that are used for different
+ purposes. A typical scenario for a server application is to have each
+ major component of the server use its own Log instance.
+- Optionally, you can dynamically change the logging detail level by
+ calling Log.setLevel() with
+ an appropriate constant from the
Log interface. Note that,
+ in most cases, the underlying logging system configuration will have
+ been preconfigured by the system administrator.
+- Cause messages to be logged (if the corresponding detail level is enabled)
+ by calling appropriate methods (
debug(), info(),
+ warn(), error, and fatal()).
+
+
+For example, you might use the following technique to initialize and
+use a Log instance in an application component:
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogSource;
+
+public class MyComponent {
+
+ protected Log log = LogSource.makeNewInstance("mycomponent");
+
+ // Called once at startup time
+ public void start() {
+ ...
+ log.info("MyComponent started");
+ ...
+ }
+
+ // Called once at shutdown time
+ public void stop() {
+ ...
+ log.info("MyComponent stopped");
+ ...
+ }
+
+ // Called repeatedly to process a particular argument value
+ // which you want logged if debugging is enabled
+ public void process(String value) {
+ ...
+ // Do the string concatenation only if logging is enabled
+ if (log.isDebugEnabled())
+ log.debug("MyComponent processing " + value);
+ ...
+ }
+
+}
+
+
+