You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rd...@apache.org on 2005/03/28 12:37:04 UTC

svn commit: r159228 [5/6] - in jakarta/commons/proper/logging/branches/DON_QUIXOTE: ./ classic/ classic/src/ classic/src/conf/ classic/src/java/ classic/src/java/org/ classic/src/java/org/apache/ classic/src/java/org/apache/commons/ classic/src/java/org/apache/commons/logging/ classic/src/java/org/apache/commons/logging/impl/ classic/src/media/ classic/src/test/ classic/src/test/org/ classic/src/test/org/apache/ classic/src/test/org/apache/commons/ classic/src/test/org/apache/commons/logging/ classic/src/test/org/apache/commons/logging/avalon/ classic/src/test/org/apache/commons/logging/jdk14/ classic/src/test/org/apache/commons/logging/log4j/ classic/src/test/org/apache/commons/logging/simple/ classic/xdocs/ classic/xdocs/images/ kernel/ kernel/src/ kernel/src/conf/ kernel/src/java/ kernel/src/java/org/ kernel/src/java/org/apache/ kernel/src/java/org/apache/commons/ kernel/src/java/org/apache/commons/logging/ kernel/src/java/org/apache/commons/logging/impl/ kernel/src/media/ kernel/src/test/ kernel/src/test/org/ kernel/src/test/org/apache/ kernel/src/test/org/apache/commons/ kernel/src/test/org/apache/commons/logging/

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/guide.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/guide.xml?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/guide.xml (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/guide.xml Mon Mar 28 02:36:50 2005
@@ -0,0 +1,766 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Copyright 2001-2004 The Apache Software Foundation.
+ 
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ 
+      http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<document>
+
+ <properties>
+  <title>Users Guide : Jakarta Commons Logging</title>
+  <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
+ </properties>
+
+ <body>
+    <section name='Contents'>
+        <p>
+            <ol>
+                <li><a href='#Introduction'>Introduction</a></li>
+                <li><a href='#Quick Start'>Quick Start</a>
+                    <ol>
+                        <li><a href='#Configuration'>Configuration</a></li>
+                        <li>
+<a href='#Configuring The Underlying Logging System'>Configuring The Underlying Logging System</a>
+                        </li>
+                        <li>
+<a href='#Configuring Log4J'>Configuring Log4J</a>
+                        </li>
+                    </ol>
+                </li>
+                <li><a href='#Developing With JCL'>Developing With JCL</a></li>
+                <li><a href='#Jars Included in the Standard Distribution'>Jars Included in the Standard Distribution</a>
+                     <ol>
+                        <li><a href='#commons-logging.jar'>commons-logging.jar</a></li>
+                        <li><a href='#commons-logging-optional.jar'>commons-logging-optional.jar</a></li>
+                        <li><a href='#commons-logging-api.jar'>commons-logging-api.jar</a></li>
+                     </ol>
+                </li>
+                <li><a href='#JCL Best Practices'>JCL Best Practices</a></li>
+                <li><a href='#Best Practices (General)'>Best Practices (General)</a>
+                    <ol>
+                        <li><a href='#Code Guards'>Code Guards</a></li>
+                        <li><a href='#Message Priorities/Levels'>Message Priorities/Levels</a></li>
+                        <li><a href='#Default Message Priority/Level'>Default Message Priority/Level</a></li>
+                    </ol>
+                </li>
+                <li><a href='#Best Practices (Enterprise)'>Best Practices (Enterprise)</a>
+                    <ol>
+                        <li><a href='#Logging Exceptions'>Logging Exceptions</a></li>
+                        <li><a href='#When Info Level Instead of Debug?'>When Info Level Instead of Debug?</a></li>
+                        <li><a href='#More Control of Enterprise Exception Logging'>More Control of Enterprise Exception Logging</a></li>                    
+                        <li><a href='#National Language Support And Internationalization'>National Language Support And Internationalization</a></li>
+                        <li><a href='#Classloader and Memory Management'>Classloader and Memory Management</a></li>
+                    </ol>
+                </li>
+                <li><a href='#Extending Commons Logging'>Extending Commons Logging</a>
+                    <ol>
+                        <li><a href='#Contract'>Contract</a></li>
+                        <li><a href='#Creating a Log Implementation'>Creating a Log Implementation</a></li>
+                        <li><a href='#Creating A LogFactory Implementation'>Creating A LogFactory Implementation</a></li>
+                    </ol>
+                </li>
+                <li><a href='#Frequently Asked Questions'>Frequently Asked Questions</a>
+                    <ol>
+                        <li><a href='#Is JCL Thread Safe?'>Is JCL Thread Safe?</a></li>
+                        <li><a href='#Why "xxxLogger does not implement Log"?'>Why "xxxLogger does not implement Log"?</a></li>
+                        <li><a href='#How Can I Switch Logging Levels On And Off?'>How Can I Switch Logging Levels On And Off?</a></li>
+                        <li><a href='#How Do I Change The Logging System Configuration?'>How Do I Change The Logging System Configuration?</a></li>
+                    </ol>
+                </li>
+            </ol>
+        </p>
+    </section>
+    <section name="Introduction">
+        <p>
+The Jakarta Commons Logging (JCL) provides a <code>Log</code> interface that
+is intended to be both light-weight and an independent abstraction of other logging toolkits.
+It provides the middleware/tooling developer with a simple
+logging abstraction, that allows the user (application developer) to plug in
+a specific logging implementation.
+    </p>
+<p>JCL provides thin-wrapper <code>Log</code> implementations for
+other logging tools, including
+<a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>,
+<a href="http://jakarta.apache.org/avalon/logkit/index.html">Avalon LogKit</a>,
+the Avalon Framework's logging infrastructure,
+JDK 1.4, and an implementation of JDK 1.4 logging APIs (JSR-47) for pre-1.4
+systems.
+The interface maps closely to Log4J and LogKit.
+</p>
+        <p>
+Familiarity with high-level details of the relevant Logging implementations is presumed.
+    </p>
+</section>
+    <section name="Quick Start">
+        <p>
+As far as possible, JCL tries to be as unobtrusive as possible.
+In most cases, including the (full) <code>commons-logging.jar</code> in the classpath
+should result in JCL configuring itself in a reasonable manner.
+There's a good chance that it'll guess your preferred logging system and you won't
+need to do any configuration at all!
+    </p>
+        <subsection name='Configuration'>
+            <p>
+There are two base abstractions used by JCL: <code>Log</code>
+(the basic logger) and <code>LogFactory</code> (which knows how to create <code>Log</code>
+instances). Using <code>LogFactory</code> implementations other than the default is a
+subject for advanced users only, so let's concentrate on configuring the default
+implementation.
+        </p>
+            <p>
+The default <code>LogFactory</code> implementation uses the following discovery process
+to determine what type of <code>Log</code> implementation it should use
+(the process terminates when the first positive match - in order - is found):
+        </p>
+
+            <ol>
+                <li>
+Look for a configuration attribute of this factory named
+<code>org.apache.commons.logging.Log</code> (for backwards
+compatibility to pre-1.0 versions of this API, an attribute
+<code>org.apache.commons.logging.log</code> is also consulted).
+            </li>
+                <li>
+Look for a system property named
+<code>org.apache.commons.logging.Log</code> (for backwards
+compatibility to pre-1.0 versions of this API, a system property
+<code>org.apache.commons.logging.log</code> is also consulted).
+            </li>
+                <li>
+If the Log4J logging system is available in the application
+class path, use the corresponding wrapper class
+(<a href="http://jakarta.apache.org/commons/logging/api/org/apache/commons/logging/impl/Log4JLogger.html">Log4JLogger</a>).
+            </li>
+                <li>
+If the application is executing on a JDK 1.4 system, use
+the corresponding wrapper class
+(<a href="http://jakarta.apache.org/commons/logging/api/org/apache/commons/logging/impl/Jdk14Logger.html">Jdk14Logger</a>).
+            </li>
+                <li>
+Fall back to the default simple logging wrapper
+(<a href="http://jakarta.apache.org/commons/logging/api/org/apache/commons/logging/impl/SimpleLog.html">SimpleLog</a>).
+            </li>
+        </ol>
+            <p>
+Consult the JCL javadocs for details of the various <code>Log</code>
+implementations that ship with the component. (The discovery process is also covered in more
+detail there.)
+        </p>
+    </subsection>
+        <subsection name='Configuring The Underlying Logging System'>
+            <p>
+The JCL SPI
+can be configured to use different logging toolkits (see <a href='#Configuration'>above</a>).
+JCL provides only a bridge for writing log messages. It does not (and will not) support any
+sort of configuration API for the underlying logging system. 
+        </p>
+            <p>
+Configuration of the behavior of the JCL ultimately depends upon the
+logging toolkit being used. Please consult the documentation for the chosen logging system.
+        </p>
+            <subsection name='Configuring Log4J'>
+                <p>
+Log4J is a very commonly used logging implementation (as well as being the JCL primary default), 
+so a <i>few</i> details are presented herein to get the developer/integrator going.
+Please see the <a href='http://logging.apache.org/log4j'>Log4J Home</a> for more details
+on Log4J and it's configuration.
+            </p>
+                <p>
+Configure Log4J using system properties and/or a properties file:
+            </p>
+                <ul>
+                    <li>
+<strong>log4j.configuration=<em>log4j.properties</em></strong>
+Use this system property to specify the name of a Log4J configuration file.
+If not specified, the default configuration file is <i>log4j.properties</i>.
+                </li>
+                    <li>
+<strong>log4j.rootCategory=<i>priority</i> [, <i>appender</i>]*</strong>
+                </li>
+Set the default (root) logger priority.
+                    <li>
+<strong>log4j.logger.<i>logger.name</i>=<i>priority</i></strong>
+Set the priority for the named logger
+and all loggers hierarchically lower than, or below, the
+named logger.
+<i>logger.name</i> corresponds to the parameter of
+<code>LogFactory.getLog(<i>logger.name</i>)</code>,
+used to create the logger instance.  Priorities are:
+<code>DEBUG</code>,
+<code>INFO</code>,
+<code>WARN</code>,
+<code>ERROR</code>,
+or <code>FATAL</code>.
+<br/>
+Log4J understands hierarchical names,
+enabling control by package or high-level qualifiers:
+<code>log4j.logger.org.apache.component=DEBUG</code>
+will enable debug messages for all classes in both
+<code>org.apache.component</code>
+and
+<code>org.apache.component.sub</code>.
+Likewise, setting
+<code>log4j.logger.org.apache.component=DEBUG</code>
+will enable debug message for all 'component' classes,
+but not for other Jakarta projects.
+                </li>
+                    <li>
+<strong>log4j.appender.<i>appender</i>.Threshold=<i>priority</i></strong>
+                </li>
+Log4J <i>appenders</i> correspond to different output devices:
+console, files, sockets, and others.
+If appender's <i>threshold</i>
+is less than or equal to the message priority then
+the message is written by that appender.
+This allows different levels of detail to be appear
+at different log destinations.
+For example: one can capture DEBUG (and higher) level information in a logfile,
+while limiting console output to INFO (and higher).
+            </ul>
+        </subsection>
+    </subsection>
+</section>
+    <section name='Developing With JCL'>
+        <p>
+To use the JCL SPI from a Java class,
+include the following import statements:
+    </p>
+        <ul>
+            <code>
+import org.apache.commons.logging.Log;
+<br/>
+import org.apache.commons.logging.LogFactory;
+<br/>
+        </code>
+    </ul>
+        <p>
+Note that some components using JCL may
+either extend Log,
+or provide a component-specific LogFactory implementation.
+Review the component documentation for guidelines
+on how commons-logging should be used in such components.
+    </p>
+        <p>
+For each class definition, declare and initialize a
+<code>log</code> attribute as follows:
+    </p>
+        <ul>
+            <source>
+public class CLASS
+{
+    private static Log log = LogFactory.getLog(CLASS.class);
+    ...
+    ;
+        </source>
+    </ul>
+        <p>
+Messages are logged to a <em>logger</em>, such as <code>log</code>
+by invoking a method corresponding to <em>priority</em>.
+The <code>org.apache.commons.logging.Log</code> interface defines the
+following methods for use
+in writing log/trace messages to the log:
+    </p>
+        <ul>
+            <source>
+    log.fatal(Object message);
+    log.fatal(Object message, Throwable t);
+    log.error(Object message);
+    log.error(Object message, Throwable t);
+    log.warn(Object message);
+    log.warn(Object message, Throwable t);
+    log.info(Object message);
+    log.info(Object message, Throwable t);
+    log.debug(Object message);
+    log.debug(Object message, Throwable t);
+    log.trace(Object message);
+    log.trace(Object message, Throwable t);
+        </source>
+    </ul>
+        <p>
+Semantics for these methods are such that it is expected
+that the severity, from highest to lowest, of messages is ordered as above.
+    </p>
+        <p>
+In addition to the logging methods, the following are provided for code guards:
+    </p>
+        <ul>
+            <source>
+    log.isFatalEnabled();
+    log.isErrorEnabled();
+    log.isWarnEnabled();
+    log.isInfoEnabled();
+    log.isDebugEnabled();
+    log.isTraceEnabled();
+        </source>
+    </ul>
+</section>
+<section name="Jars Included in the Standard Distribution">
+    <subsection name="commons-logging.jar">
+      <p>
+The <code>commons-logging.jar</code> file includes the JCL API, the default 
+<code>LogFactory</code> implemenation and thin-wrapper <code>Log</code> 
+implementations for
+<a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>,
+<a href="http://jakarta.apache.org/avalon/logkit/index.html">Avalon LogKit</a>,
+the Avalon Framework's logging infrastructure,
+JDK 1.4, as well as an implementation of JDK 1.4 logging APIs (JSR-47) for 
+pre-1.4 systems.
+   </p>
+   <p>
+In most cases, including <code>commons-logging.jar</code> and your preferred 
+logging implementation in the classpath should be all that is required to 
+use JCL.
+   </p>
+    </subsection>
+    <subsection name="commons-logging-optional.jar">
+    <p>
+The optional jar includes, oddly enough, optional classes that are useful but 
+not strictly required to make JCL functional.  As these classes introduce 
+dependencies on JDK 1.3+ JVMs and a goal of JCL is to be usable on JDK 1.2 
+and earlier JVMs, these optional classes are not included in the main 
+<code>commons-logging.jar</code>.
+   </p>
+   <p>
+Included in the optional jar are classes which allow JCL to (potentially) improve
+it's memory utilization (see 
+<a href='#Classloader and Memory Management'>Classloader and Memory Management</a> 
+below). It is therefore recommended that (when running on a 1.3+ JDK) the optional jar 
+be deployed alongside the 
+main <code>commons-logging.jar</code>.  It should be deployed such that it will be loaded 
+by the same classloader that loads <code>LogFactory</code>. When so deployed, JCL will
+discover the appropriate classes and configure itself to use them.
+   </p>
+    </subsection>
+    <subsection name="commons-logging-api.jar">
+    <p>
+The <code>commons-logging-api.jar</code> file includes the JCL API and the 
+default <code>LogFactory</code> implementation, but does not include the 
+wrapper <code>Log</code> implementations for <code>Log4j</code>,
+<code>Avalon</code> and <code>Lumberjack</code>.  This jar is intended for 
+use in specialized containers such as 
+<a href='http://jakarta.apache.org/tomcat'>Tomcat</a> that wish to use 
+JCL internally but also need to make JCL available for use by deployed 
+applications.
+   </p>
+  <p>
+  If this jar is used, in order to benefit from improved memory management in modern JVMs (1.3+),
+  it is recommended that the <code>commons-logging-optional.jar</code> is deployed in 
+  the same classloader as this jar.
+  </p>
+    </subsection>
+</section>
+        <section name='JCL Best Practices'>
+            <p>
+Best practices for JCL are presented in two categories:
+General and Enterprise.
+The general principles are fairly clear.Enterprise practices are a bit more involved
+and it is not always as clear as to why they are important.
+        </p>
+            <p>
+Enterprise best-practice principles apply to middleware components
+and tooling that is expected to execute in an "Enterprise" level
+environment.
+These issues relate to Logging as Internationalization,
+and fault detection.
+Enterprise requires more effort and planning, but are strongly encouraged (if not required)
+in production level systems.  Different corporate enterprises/environments have different
+requirements, so being flexible always helps.
+        </p>
+    </section>
+    <section name='Best Practices (General)'>
+        <subsection name='Code Guards'>
+            <p>
+Code guards are typically used to guard code that
+only needs to execute in support of logging,
+that otherwise introduces undesirable runtime overhead
+in the general case (logging disabled).
+Examples are multiple parameters, or expressions (i.e. string + " more") for parameters.
+Use the guard methods of the form <code>log.is&lt;<i>Priority</i>&gt;()</code> to verify
+that logging should be performed, before incurring the overhead of the logging method call.
+Yes, the logging methods will perform the same check, but only after resolving parameters.
+            </p>
+        </subsection>
+           <subsection name='Message Priorities/Levels'>
+                <p>
+It is important to ensure that log message are
+appropriate in content and severity.
+The following guidelines are suggested:
+        </p>
+            <ul>
+                <li>
+<b>fatal</b> - Severe errors that cause premature termination.
+Expect these to be immediately visible on a status console.
+See also <a HREF="#National%20Language%20Support%20And%20Internationalization">
+Internationalization</a>.
+            </li>
+                <li>
+<b>error</b> - Other runtime errors or unexpected conditions.
+Expect these to be immediately visible on a status console.
+See also <a HREF="#National%20Language%20Support%20And%20Internationalization">
+Internationalization</a>.
+            </li>
+                <li>
+<b>warn</b> - Use of deprecated APIs, poor use of API, 'almost' errors,
+other runtime situations that are undesirable or unexpected, but not
+necessarily "wrong".
+Expect these to be immediately visible on a status console.
+See also <a HREF="#National%20Language%20Support%20And%20Internationalization">
+Internationalization</a>.
+            </li>
+                <li>
+<b>info</b> - Interesting runtime events (startup/shutdown).
+Expect these to be immediately visible on a console,
+so be conservative and keep to a minimum.
+See also <a HREF="#National%20Language%20Support%20And%20Internationalization">
+Internationalization</a>.
+            </li>
+                <li>
+<b>debug</b> - detailed information on the flow through the system.
+Expect these to be written to logs only.
+            </li>
+                <li>
+<b>trace</b> - more detailed information.
+Expect these to be written to logs only.
+            </li>
+        </ul>
+        </subsection>
+            <subsection name='Default Message Priority/Level'>
+                <p>
+By default the message priority should be no lower than <b>info</b>.
+That is, by default <b>debug</b> message should not be seen in the logs.
+            </p>
+        </subsection>
+    </section>
+    <section name='Best Practices (Enterprise)'>
+          <subsection name='Logging Exceptions'>
+               <p>
+The general rule in dealing with exceptions is to assume that
+the user (developer using a tooling/middleware API) isn't going
+to follow the rules.
+Since any problems that result are going to be assigned to you,
+it's in your best interest to be prepared with the proactive
+tools necessary to demonstrate that your component works correctly,
+or at worst that the problem can be analyzed from your logs.
+For this discussion, we must make a distinction between different types of exceptions
+based on what kind of boundaries they cross:
+           </p>
+               <ul>
+                   <li>
+<b>External Boundaries - Expected Exceptions</b>.
+This classification includes exceptions such as <code>FileNotFoundException</code>
+that cross API/SPI boundaries, and are exposed to the user of a component/toolkit.
+These are listed in the 'throws' clause of a method signature.
+<br/>
+Appropriate handling of these exceptions depends upon the type
+of code you are developing.
+API's for utility functions and tools should log these at the <b>debug</b> level,
+if they are caught at all by internal code.
+<br/>
+For higher level frameworks and middleware components,
+these exceptions should be caught immediatly prior to crossing
+the API/SPI interface back to user code-space,
+logged with full stack trace at <b>info</b> level,
+and rethrown.
+The assures that the log contains a record of the root cause for
+future analysis <i>in the event that the exception is not caught and resolved
+as expected by the user's code</i>.
+<br/>
+            </li>
+               <li>
+<b>External Boundaries - Unexpected Exceptions</b>.
+This classification includes exceptions such as <code>NullPointerException</code>
+that cross API/SPI boundaries, and are exposed to the user of a component/toolkit.
+These are runtime exceptions/error that are NOT
+listed in the 'throws' clause of a method signature.
+<br/>
+Appropriate handling of these exceptions depends upon the type
+of code you are developing.
+API's for utility functions and tools should log these at the <b>debug</b> level,
+if they are caught at all.
+<br/>
+For higher level frameworks and middleware components,
+these exceptions should be caught immediatly prior to crossing
+the API/SPI interface back to user code-space,
+logged with full stack trace at <b>info</b> level,
+and rethrown/wrapped as <code><i>Component</i>InternalError</code>.
+The assures that the log contains a record of the root cause for
+future analysis <i>in the event that the exception is not caught and
+logged/reported as expected by the user's code</i>.
+            </li>
+                <li>
+<b>Internal Boundaries</b>.
+Exceptions that occur internally and are resolved internally.
+These should be logged when caught as <b>debug</b> or <b>info</b> messages,
+at the programmer's discretion.
+            </li>
+                <li>
+<b>Significant Internal Boundaries</b>.
+This typically only applies to middleware components
+that span networks or runtime processes.
+Exceptions that cross over significant internal component boundaries, such as networks.
+These should be logged when caught as <b>info</b> messages.
+Do not assume that such a (process/network) boundary will deliver exceptions to the 'other side'.
+                </li>
+            </ul>
+    </subsection>
+        <subsection name='When Info Level Instead of Debug?'>
+                <p>
+You want to have exception/problem information available for
+first-pass problem determination in a production level
+enterprise application without turning on <b>debug</b>
+as a default log level.  There is simply too much information
+in <b>debug</b> to be appropriate for day-to-day operations.
+            </p>
+        </subsection>
+            <subsection name='More Control of Enterprise Exception Logging'>
+                <p>
+If more control is desired for the level of detail of these
+'enterprise' exceptions, then consider creating a special
+logger just for these exceptions:
+            </p>
+                <ul>
+<source>
+   Log log = LogFactory.getLog("org.apache.<i>component</i>.enterprise");
+</source>
+            </ul>
+                <p>
+This allows the 'enterprise' level information to be turned on/off explicitly
+by most logger implementations.
+            </p>
+        </subsection>
+        <subsection name='National Language Support And Internationalization'>
+            <p>
+NLS internationalization involves looking up messages from
+a message file by a message key, and using that message for logging.
+There are various tools in Java, and provided by other components,
+for working with NLS messages.
+                </p>
+            <p>
+NLS enabled components are particularly appreciated
+(that's an open-source-correct term for 'required by corporate end-users' :-)
+for <strong>tooling</strong> and <strong>middleware</strong> components.
+                </p>
+            <p>
+NLS internationalization SHOULD be strongly considered for used for
+<b>fatal</b>, <b>error</b>, <b>warn</b>, and <b>info</b> messages.
+It is generally considered optional for <b>debug</b> and <b>trace</b> messages.
+                </p>
+            <p>
+Perhaps more direct support for internationalizing log messages
+can be introduced in a future or alternate version of the <code>Log</code> interface.
+                </p>
+            </subsection>
+            <subsection name="Classloader and Memory Management">
+            <p>
+The <code>LogFactory</code> discovery process (see 
+<a href='#Configuration'>Configuration</a> above) is a fairly expensive 
+operation, so JCL certainly should not perform it each time user code 
+invokes: 
+</p>
+<source>LogFactory.getLog()</source> 
+<p>
+Instead JCL caches the 
+<code>LogFactory</code> implementation created as a result of the discovery 
+process and uses the cached factory to return <code>Log</code> objects.  
+Since in J2EE and similar multi-classloader environments, the result of the 
+discovery process can vary depending on the thread context classloader 
+(e.g. one webapp in a web container may be configured to use Log4j and 
+another to use JDK 1.4 logging), JCL internally caches the 
+<code>LogFactory</code> instances in a static hashtable, keyed by classloader.
+            </p>
+            <p>
+While this approach is efficient, it can lead to memory leaks if container
+implementors are not careful to call 
+</p>
+<source>LogFactory.release()</source> 
+<p>
+whenever a classloader that has utilized JCL is undeployed.  If 
+<code>release()</code> is not called, a reference to the undeployed 
+classloader (and thus to all the classes loaded by it) will be
+held in <code>LogFactory</code>'s static hashtable.
+            </p>
+            <p>
+Beginning with JCL 1.0.5, <code>LogFactory</code> will attempt to cache factory
+implementations in a 
+<a href='http://jakarta.apache.org/commons/logging/optional/apidocs/org/apache/commons/logging/impl/WeakHashtable.html'>WeakHashtable</a>.  
+This class is analogous to <code>java.util.WeakHashMap</code> in that it holds 
+<code>WeakReference</code>s to its keys, thus allowing classloaders to be GC'd 
+even if <code>LogFactory.release()</code> is never invoked.
+            </p>
+            <p>
+Because <code>WeakHashtable</code> depends on JDK 1.3+ features, it cannot 
+be included in the main <code>commons-logging.jar</code> file.  It is found 
+in <code>commons-logging-optional.jar</code>.  <strong>J2EE container 
+implementors who distribute JCL with their application are strongly 
+encouraged to place <code>commons-logging-optional.jar</code> on the classpath 
+in the same location where <code>LogFactory</code> is loaded.</strong>
+            </p>
+            <p>
+In a particular usage scenario, <code>WeakHashtable</code> alone will
+be insufficent to allow garbage collection of a classloader without a call to
+<code>release</code>.  If the abstract class <code>LogFactory</code> is 
+loaded by a parent classloader and a concrete subclass implementation of 
+<code>LogFactory</code> is loaded by a child classloader, the concrete
+implementation will have a strong reference to the child classloader via the
+chain <code>getClass().getClassLoader()</code>. The <code>WeakHashtable</code>
+will have a strong reference to the <code>LogFactory</code> implementation as
+one of the values in its map. This chain of references will prevent 
+collection of the child classloader.
+           </p>
+           <p>
+Such a situation would typically only occur if commons-logging.jar were
+loaded by a parent classloader (e.g. a server level classloader in a
+servlet container) and a custom <code>LogFactory</code> implementation were
+loaded by a child classloader (e.g. a web app classloader).  If use of
+a custom <code>LogFactory</code> subclass is desired, ensuring that the
+custom subclass is loaded by the same classloader as <code>LogFactory</code>
+will prevent problems.  In normal deployments, the standard implementations 
+of <code>LogFactory</code> found in package <code>org.apache.commons.logging.impl</code> 
+will be loaded by the same classloader that loads <code>LogFactory</code> 
+itself, so use of the standard <code>LogFactory</code> implementation
+should not pose problems.
+         </p>
+            </subsection>
+    </section>
+    <section name='Extending Commons Logging'>
+        <p>
+JCL is designed to encourage extensions to be created that add functionality. 
+Typically, extensions to JCL fall into two categories:
+    </p>
+        <ul>
+            <li>new <code>Log</code> implementations that provide new bridges to logging systems</li>
+            <li>
+new <code>LogFactory</code> implementations that provide alternative discovery strategies
+            </li>
+    </ul>
+        <subsection name='Contract'>
+            <p>
+When creating new implementations for <code>Log</code> and <code>LogFactory</code>,
+it is important to understand the implied contract between the factory 
+and the log implementations:
+                <ul>
+                    <li><b>Life cycle</b>
+                        <blockquote>
+The JCL LogFactory implementation must assume responsibility for
+either connecting/disconnecting to a logging toolkit,
+or instantiating/initializing/destroying a logging toolkit.
+                        </blockquote>
+                </li>
+                    <li><b>Exception handling</b>
+                        <blockquote>
+The JCL Log interface doesn't specify any exceptions to be handled,
+the implementation must catch any exceptions.
+                    </blockquote>
+                </li>
+                    <li><b>Multiple threads</b>
+                        <blockquote>
+The JCL Log and LogFactory implementations must ensure
+that any synchronization required by the logging toolkit
+is met.
+                    </blockquote>
+                </li>
+            </ul>
+        </p>
+    </subsection>
+    <subsection name='Creating a Log Implementation'>
+        <p>
+The minimum requirement to integrate with another logger
+is to provide an implementation of the
+<code>org.apache.commons.logging.Log</code> interface.
+In addition, an implementation of the
+<code>org.apache.commons.logging.LogFactory</code> interface
+can be provided to meet
+specific requirements for connecting to, or instantiating, a logger.
+    </p>
+            <p>
+The default <code>LogFactory</code> provided by JCL
+can be configured to instantiate a specific implementation of the
+<code>org.apache.commons.logging.Log</code> interface
+by setting the property of the same name (<code>org.apache.commons.logging.Log</code>).
+This property can be specified as a system property,
+or in the <code>commons-logging.properties</code> file,
+which must exist in the CLASSPATH.
+        </p>
+     </subsection>
+        <subsection name='Creating A LogFactory Implementation'>
+            <p>
+If desired, the default implementation of the
+<code>org.apache.commons.logging.LogFactory</code>
+interface can be overridden,
+allowing the JDK 1.3 Service Provider discovery process
+to locate and create a LogFactory specific to the needs of the application.
+Review the Javadoc for the <code>LogFactoryImpl.java</code>
+for details.
+        </p>
+    </subsection>
+</section>
+    <section name='Frequently Asked Questions'>
+        <subsection name='Is JCL Thread Safe?'>
+            <p>
+JCL doesn't (and cannot) impose any requirement on thread safety on the underlying implementation
+and thus its SPI contract doesn't guarantee thread safety.
+However, JCL can be safely used in a multi-threaded environment
+as long as the underlying implementation is thread-safe.
+        </p>
+            <p>
+It would be very unusual for a logging system to be thread unsafe.
+Certainly, JCL is thread safe when used with the distributed Log implementations.
+        </p>
+    </subsection>
+        <subsection name='Why "xxxLogger does not implement Log"?'>
+            <p>    
+Upon application startup (especially in a container environment), an exception is thrown
+with message 'xxxLogger does not implement Log'! What's the cause and how can 
+I fix this problem?
+        </p>
+            <p>
+This almost always a classloader issue. Log has been loaded by a different 
+classloader from the logging implementation. Please ensure that:
+        </p>
+            <ul>
+                <li>
+all the logging classes (both Log and the logging implementations) 
+are deployed by the same classloader
+            </li>
+        </ul>
+            <ul>
+                <li>
+there is only copy of the classes to be found within the classloader hierarchy. 
+In application container environments this means ensuring that if the classes 
+are found in a parent classloader, they are not also present in the leaf classloader 
+associated with the application. 
+So, if the jar is deployed within the root classloader of the container then it 
+should be removed from the application's library.
+            </li>
+        </ul>
+    </subsection>
+        <subsection name='How Can I Switch Logging Levels On And Off?'>
+            <p>
+See <a href='#How Do I Change The Logging System Configuration?'>
+How Can I Change The Logging System Configuration?</a>
+        </p>
+    </subsection>
+        <subsection name='How Do I Change The Logging System Configuration?'>
+            <p>
+The configuration supported by JCL is limited to choosing the underlying logging system.
+JCL does not (and will never) support changing the configuration of the wrapped logging system.
+Please use the mechanisms provided by the underlying logging system.
+        </p>
+    </subsection>
+</section>
+</body>
+</document>

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/images/logo.png
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/images/logo.png?view=auto&rev=159228
==============================================================================
Binary file - no diff available.

Propchange: jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/images/logo.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/index.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/index.xml?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/index.xml (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/index.xml Mon Mar 28 02:36:50 2005
@@ -0,0 +1,113 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Copyright 2001-2004 The Apache Software Foundation.
+ 
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ 
+      http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<document>
+
+ <properties>
+  <title>Commons</title>
+  <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
+ </properties>
+
+ <body>
+
+<section name="The Logging Component">
+
+<p>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.</p>
+
+<p>The Logging package is an ultra-thin bridge between different logging
+libraries.  Commons components may use the Logging API to remove
+compile-time and run-time dependencies on any particular logging package,
+and contributors may write Log implementations for the library of
+their choice.</p>
+
+</section>
+
+
+<section name="Documentation">
+
+<p>The <a href="http://jakarta.apache.org/commons/logging/RELEASE-NOTES.txt">
+Release Notes</a> document the new features and bug fixes that have been
+included in the latest release.</p>
+
+<p>The <a href="http://jakarta.apache.org/commons/logging/api/index.html">
+JavaDoc API documents</a> for the latest release are available online.
+In particular, you should read the package overview of the <code>org.apache.commons.logging</code>
+package. In addition, there is a (short)
+<a href="guide.html">User Guide</a>.</p>
+
+</section>
+
+
+<section name="Releases">
+    <subsection name='1.0.5 Release (Proposed)'>
+    		<p>
+    <strong>Note:</strong> <em>release candidate is currently under preparation.</em>
+    		</p>
+        <p>
+JCL 1.0.5 is a service release adding optional improved automatic memory management
+for containers which do not support JCL explicit memory release
+during hot reployment (1.4+ JVMs only). For more details see the
+<a href='guide.html#Classloader%20and%20Memory%20Management'>user guide</a>.
+        </p>
+    </subsection>
+    <subsection name='1.0.4 Release'>
+        <p>
+The 1.0.4 release of commons-logging is a service
+release containing support for both the 1.2.x and 1.3.x series of Log4J releases. 
+        </p>
+    </subsection>
+    <subsection name='Mirrored Releases'>
+<p>
+Releases after 1.0.2 should be downloaded from a mirror. Please remember to verify the
+signature of the release from the 
+<a href='http://www.apache.org/dist/jakarta/commons/logging/'>main apache site</a>
+when downloading from a mirror.
+</p>
+<p>
+    Binary releases are available
+       <a href="http://jakarta.apache.org/site/binindex.cgi">here</a>.
+    Source releases are available
+       <a href="http://jakarta.apache.org/site/sourceindex.cgi">here</a>
+</p>
+<p>
+<ul>
+       <li>Version 1.0.4 (latest) - 16 Jun 2004</li>
+       <li>Version 1.0.3 - 7 Apr 2003</li>
+</ul>
+</p>
+    </subsection>
+    <subsection name='Older Releases (Not Mirrored)'>
+    <p>
+    <ul>
+<ul>
+<li><a href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-logging/v1.0.2/">Version 1.0.2</a></li>
+<li><a href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-logging/v1.0.1/">Version 1.0.1</a></li>
+<li><a href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-logging/v1.0/">Version 1.0</a></li>
+</ul>
+    </ul>
+    </p>
+    </subsection>
+</section>
+
+
+</body>
+</document>

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/navigation.xml?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/navigation.xml (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/navigation.xml Mon Mar 28 02:36:50 2005
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!--
+
+ Copyright 2001-2004 The Apache Software Foundation.
+ 
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ 
+      http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<!DOCTYPE org.apache.commons.menus SYSTEM '../../commons-build/menus/menus.dtd'>
+<project name="Logging">
+
+  <title>Logging</title>
+  <organizationLogo href="/images/jakarta-logo.gif">
+   Jakarta
+  </organizationLogo>
+
+  <body>
+    <links>
+      <item name="Jakarta Commons"
+            href="http://jakarta.apache.org/commons/"/>
+    </links>
+
+    <menu name="Commons Logging">
+      <item name="Overview"
+            href="/index.html"/>
+      <item name="User Guide"
+            href="/guide.html"/>
+      <item name="Wiki"
+            href="http://wiki.apache.org/jakarta-commons/Logging"/>
+      <item name='1.0.4 Release'>
+            <item   name='Documentation'
+                    href='http://jakarta.apache.org/commons/logging/commons-logging-1.0.4/docs/'/>
+            <item   name='Release Notes'
+                    href='http://jakarta.apache.org/commons/logging/commons-logging-1.0.4/RELEASE-NOTES.txt'/>
+      </item>
+      <item name='1.0.3 Release'>
+            <item   name='Userguide'
+                    href='http://jakarta.apache.org/commons/logging/commons-logging-1.0.3/usersguide.html'/>
+            <item   name='API'
+                    href='http://jakarta.apache.org/commons/logging/commons-logging-1.0.3/docs/api/'/>
+            <item   name='Release Notes'
+                    href='http://jakarta.apache.org/commons/logging/commons-logging-1.0.3/RELEASE-NOTES.txt'/>
+      </item>      
+      <item name='1.0.2 Release'>
+            <item   name='API'
+                    href='http://jakarta.apache.org/commons/logging/commons-logging-1.0.2/docs/api/'/>
+      </item>  
+    </menu>
+    
+    &common-menus;
+
+  </body>
+</project>
+

Propchange: jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/navigation.xml
------------------------------------------------------------------------------
    svn:executable = *

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/proposal.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/proposal.xml?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/proposal.xml (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/classic/xdocs/proposal.xml Mon Mar 28 02:36:50 2005
@@ -0,0 +1,126 @@
+<!--
+
+ Copyright 2001-2004 The Apache Software Foundation.
+ 
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ 
+      http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<document>
+<properties>
+<title>Proposal for Logging Library Package</title>
+</properties>
+<body>
+
+
+<section name="Proposal for Logging Package">
+
+
+
+<subsection name="(0) Rationale">
+
+<p>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.
+</p>
+
+<p>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.
+</p>
+
+</subsection>
+<subsection name="(1) Scope of the Package">
+
+<p>The package shall create and maintain a package that provides extremely
+basic logging functionality and bridges to other, more sophisticated logging
+implementations.
+</p>
+
+<p>
+The package should :
+<ul>
+<li>Have an API which should be as simple to use as possible</li>
+<li>Provide support for log4j</li>
+<li>Provide pluggable support for other logging APIs</li>
+</ul>
+</p>
+
+<p>
+Non-goals:
+<ul>
+<li>This package will not perform logging itself, except at the most basic
+    level.</li>
+<li>We do not seek to become a "standard" API.</li>
+</ul>
+</p>
+
+</subsection>
+<subsection name="(1.5) Interaction With Other Packages">
+
+<p><em>Logging</em> relies on:
+</p>
+
+<ul>
+  <li>Java Development Kit (Version 1.1 or later)</li>
+  <li>Avalon Framework (compile-time dependency only unless this Log
+      implementation is selected at runtime)</li>
+  <li>Avalon LogKit (compile-time dependency only unless this Log
+      implementation is selected at runtime)</li>
+  <li>JDK 1.4 (compile-time dependency only unless this log implementation
+      is selected at runtime).</li>
+  <li>Log4J (compile-time dependency only unless this Log
+      implementation is selected at runtime)</li>
+  <li><a href="http://sourceforge.net/projects/lumberjack/">Lumberjack</a>
+      (compile-time dependency only unless this Log
+      implementation is selected at runtime)</li>
+</ul>
+
+</subsection>
+<subsection name="(2) Required Jakarta-Commons Resources">
+
+<ul>
+<li>CVS Repository - New directory <code>logging</code> in the 
+<code>jakarta-commons</code> CVS repository.</li>
+
+<li>Initial Committers - The list is provided below. </li>
+
+<li>Mailing List - Discussions will take place on the general
+<em>commons-dev@jakarta.apache.org</em> 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].</li>
+
+<li>Bugzilla - New component "Logging" under the "Commons" product
+category, with appropriate version identifiers as needed.</li>
+
+<li>Jyve FAQ - New category "commons-logging" (when available).</li>
+</ul>
+
+
+</subsection>
+<subsection name="(4) Initial Committers">
+
+<p>The initial committers on the Logging component shall be:</p>
+
+<ul>
+  <li>Morgan Delagrange</li>
+  <li>Rodney Waldhoff</li>
+  <li>Craig McClanahan</li>
+</ul>
+
+</subsection>
+</section>
+</body>
+</document>

Propchange: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/
------------------------------------------------------------------------------
--- svn:ignore (added)
+++ svn:ignore Mon Mar 28 02:36:50 2005
@@ -0,0 +1,4 @@
+.*
+target
+build.properties
+dist

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/LICENSE.txt
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/LICENSE.txt?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/LICENSE.txt (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/LICENSE.txt Mon Mar 28 02:36:50 2005
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/NOTICE.txt
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/NOTICE.txt?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/NOTICE.txt (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/NOTICE.txt Mon Mar 28 02:36:50 2005
@@ -0,0 +1,3 @@
+This product includes software developed by
+The Apache Software Foundation (http://www.apache.org/).
+

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/RELEASE-NOTES.txt
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/RELEASE-NOTES.txt?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/RELEASE-NOTES.txt (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/RELEASE-NOTES.txt Mon Mar 28 02:36:50 2005
@@ -0,0 +1,14 @@
+# Copyright 2005 The Apache Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#      http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
\ No newline at end of file

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/build.properties.sample
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/build.properties.sample?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/build.properties.sample (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/build.properties.sample Mon Mar 28 02:36:50 2005
@@ -0,0 +1,19 @@
+# Copyright 2001-2004 The Apache Software Foundation.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#      http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#
+# if you want to run the test cases, junit needs to be in the classpath.
+# the build.xml uses a default value so you might not need to set this property.
+#
+junit.jar=/home/robert/.maven/repository/junit/jars/junit-3.8.1.jar

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/build.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/build.xml?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/build.xml (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/build.xml Mon Mar 28 02:36:50 2005
@@ -0,0 +1,266 @@
+<!--
+
+ Copyright 2005 The Apache Software Foundation.
+ 
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ 
+      http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<project name="JCL Kernel" default="compile" basedir=".">
+
+
+<!--
+        Kernel of "Logging" component of the Jakarta Commons Subproject
+        $Id: build.xml 153296 2005-02-10 21:57:11Z rdonkin $
+-->
+
+
+<!-- ========== Initialize Properties ===================================== -->
+
+
+  <property file="build.properties"/>                <!-- Sub Component local   -->
+  <property file="../build.properties"/>                <!-- Component local   -->
+  <property file="../../build.properties"/>             <!-- Commons local     -->
+  <property file="${user.home}/build.properties"/>   <!-- User local        -->
+
+
+<!-- ========== External Dependencies ===================================== -->
+
+
+  <!-- The directories corresponding to your necessary dependencies -->
+  <property name="junit.home"              value="/usr/local/junit3.5"/>
+  <property name="jakarta.home"            value="../.."/>
+
+
+<!-- ========== Derived Values ============================================ -->
+
+
+  <!-- The locations of necessary jar files -->
+  <property name="junit.jar"               value="${junit.home}/junit.jar"/>
+
+
+<!-- ========== Component Declarations ==================================== -->
+
+
+  <!-- The name of this component -->
+  <property name="component.name"          value="logging-kernel"/>
+
+  <!-- The primary package name of this component -->
+  <property name="component.package"       value="org.apache.commons.logging"/>
+
+  <!-- The title of this component -->
+  <property name="component.title"         value="Logging Wrapper Library Kernel"/>
+
+  <!-- The current version number of this component -->
+  <property name="component.version"       value="2.0-dev"/>
+
+  <!-- The base directory for compilation targets -->
+  <property name="build.home"              value="${basedir}/target"/>
+
+  <!-- The base directory for component configuration files -->
+  <property name="conf.home"               value="src/conf"/>
+
+  <!-- The base directory for distribution targets -->
+  <property name="dist.home"               value="dist"/>
+
+  <!-- The base directory for component sources -->
+  <property name="source.home"             value="src/java"/>
+
+  <!-- The base directory for unit test sources -->
+  <property name="test.home"               value="src/test"/>
+  
+<!-- ========== Compiler Defaults ========================================= -->
+
+
+  <!-- Should Java compilations set the 'debug' compiler option? -->
+  <property name="compile.debug"           value="true"/>
+
+  <!-- Should Java compilations set the 'deprecation' compiler option? -->
+  <property name="compile.deprecation"     value="false"/>
+
+  <!-- Should Java compilations set the 'optimize' compiler option? -->
+  <property name="compile.optimize"        value="false"/>
+
+  <!-- Construct compile classpath -->
+  <path id="compile.classpath">
+    <pathelement location="${build.home}/classes"/>
+    <pathelement location="${junit.jar}"/>
+  </path>
+
+
+<!-- ========== Test Execution Defaults =================================== -->
+
+
+  <!-- Construct unit test classpath (generic tests) -->
+  <path id="test.classpath">
+    <pathelement location="${build.home}/classes"/>
+    <pathelement location="${build.home}/tests"/>
+    <pathelement location="${junit.jar}"/>
+  </path>
+
+  <!-- Should all tests fail if one does? -->
+  <property name="test.failonerror"        value="true"/>
+
+  <!-- The test runner to execute -->
+  <property name="test.runner"             value="junit.textui.TestRunner"/>
+
+<!-- ========== Executable Targets ======================================== -->
+
+
+  <target name="init"
+   description="Initialize and evaluate conditionals">
+    <echo message="-------- ${component.title} ${component.version} --------"/>
+    <filter  token="name"                  value="${component.name}"/>
+    <filter  token="package"               value="${component.package}"/>
+    <filter  token="version"               value="${component.version}"/>
+  </target>  
+  
+  <target name="prepare" depends="init"
+   description="Prepare build directory">
+
+    <mkdir dir="${build.home}"/>
+    <mkdir dir="${build.home}/classes"/>
+    <mkdir dir="${build.home}/conf"/>
+    <mkdir dir="${build.home}/docs"/>
+    <mkdir dir="${build.home}/docs/api"/>
+    <mkdir dir="${build.home}/tests"/>
+  </target>
+
+
+  <target name="static" depends="prepare"
+   description="Copy static files to build directory">
+    <tstamp/>
+    <copy  todir="${build.home}/conf" filtering="on">
+      <fileset dir="${conf.home}" includes="*.MF"/>
+      <fileset dir="${conf.home}" includes="*.properties"/>
+    </copy>
+  </target>
+
+  <target name="compile" depends="static,init" >
+
+    <javac srcdir="${source.home}"
+           destdir="${build.home}/classes"
+           debug="${compile.debug}"
+           deprecation="${compile.deprecation}"
+           optimize="${compile.optimize}">
+      <classpath refid="compile.classpath"/>
+    </javac>
+    <copy  todir="${build.home}/classes" filtering="on">
+      <fileset dir="${source.home}" excludes="**/*.java"/>
+    </copy>
+    <mkdir      dir="${build.home}/classes/META-INF"/>
+    <copy      file="LICENSE.txt"
+              todir="${build.home}/classes/META-INF"/>
+    <copy      file="NOTICE.txt"
+              todir="${build.home}/classes/META-INF"/>
+
+    <jar jarfile="${build.home}/commons-${component.name}.jar"
+         basedir="${build.home}/classes"
+         manifest="${build.home}/conf/MANIFEST.MF">
+      <include name="org/apache/commons/logging/**" />
+      <include name="META-INF/LICENSE.txt"/>
+      <include name="META-INF/NOTICE.txt"/>
+    </jar>
+  </target>
+
+
+  <target name="compile.tests" depends="compile"
+   description="Compile unit test cases">
+    <javac  srcdir="${test.home}"
+           destdir="${build.home}/tests"
+             debug="${compile.debug}"
+       deprecation="${compile.deprecation}"
+          optimize="${compile.optimize}">
+      <classpath refid="test.classpath"/>
+    </javac>
+    <copy    todir="${build.home}/tests" filtering="on">
+      <fileset dir="${test.home}" excludes="**/*.java"/>
+    </copy>
+  </target>
+
+
+  <target name="clean"
+   description="Clean build and distribution directories">
+    <delete    dir="${build.home}"/>
+    <delete    dir="${dist.home}"/>
+  </target>
+
+
+  <target name="all" depends="clean,compile"
+   description="Clean and compile all components"/>
+
+
+  <target name="javadoc" depends="compile"
+   description="Create component Javadoc documentation">
+    <mkdir      dir="${dist.home}"/>
+    <mkdir      dir="${dist.home}/docs"/>
+    <mkdir      dir="${dist.home}/docs/api"/>
+    <javadoc sourcepath="${source.home}"
+                destdir="${dist.home}/docs/api"
+               overview="${source.home}/overview.html"
+           packagenames="org.apache.commons.*"
+                 author="true"
+                private="true"
+                version="true"
+               doctitle="&lt;h1&gt;${component.title} (Version ${component.version})&lt;/h1&gt;"
+            windowtitle="${component.title} (Version ${component.version})"
+                 bottom='Copyright 2002-2004 The Apache Software Foundation.&lt;!--
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+ 
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.--&gt;'>
+      <classpath refid="test.classpath"/>
+    </javadoc>
+  </target>
+
+
+  <target name="dist" depends="compile,javadoc"
+   description="Create binary distribution">
+    <mkdir      dir="${dist.home}"/>
+    <copy      file="LICENSE.txt"
+              todir="${dist.home}"/>
+    <copy      file="NOTICE.txt"
+              todir="${dist.home}"/>
+    <copy      file="RELEASE-NOTES.txt"
+              todir="${dist.home}"/>
+    <copy file="${build.home}/commons-${component.name}.jar"
+          tofile="${dist.home}/commons-${component.name}.jar" />
+    <mkdir      dir="${dist.home}/src"/>
+    <copy     todir="${dist.home}/src" filtering="on">
+      <fileset  dir="${source.home}"/>
+    </copy>
+  </target>
+
+
+<!-- ========== Unit Test Targets ========================================= -->
+
+
+  <target name="test"
+       depends=" compile.tests"
+   description="Run all unit test cases">
+      <java    classname="${test.runner}" fork="yes"
+             failonerror="${test.failonerror}">
+        <arg       value="org.apache.commons.logging.TestJCL"/>
+        <classpath refid="test.classpath"/>
+      </java>
+  </target>
+
+</project>

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/checkstyle.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/checkstyle.xml?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/checkstyle.xml (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/checkstyle.xml Mon Mar 28 02:36:50 2005
@@ -0,0 +1,42 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Copyright 2001-2004 The Apache Software Foundation.
+ 
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ 
+      http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<!DOCTYPE module PUBLIC
+    "-//Puppy Crawl//DTD Check Configuration 1.1//EN"
+    "http://www.puppycrawl.com/dtds/configuration_1_1.dtd">
+
+<!-- commons codec customization of default Checkstyle behavior -->
+<module name="Checker">
+  <property name="basedir" value="src/checkstyle"/>
+  <property name="localeLanguage" value="en"/>
+
+  <module name="TreeWalker">
+    <!-- Verify that EVERY source file has the appropriate license -->
+    <module name="Header">
+      <property name="headerFile" value="LICENSE.txt"/>
+      <property name="ignoreLines" value="2,3,4,10"/>
+    </module>
+
+    <module name="OperatorWrap">
+      <property name="option" value="eol"/>
+    </module>
+  </module>
+</module>
+

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/conf/MANIFEST.MF
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/conf/MANIFEST.MF?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/conf/MANIFEST.MF (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/conf/MANIFEST.MF Mon Mar 28 02:36:50 2005
@@ -0,0 +1,5 @@
+Extension-Name: org.apache.commons.logging
+Specification-Vendor: Apache Software Foundation
+Specification-Version: 1.0
+Implementation-Vendor: Apache Software Foundation
+Implementation-Version: 1.0.5

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/java/org/apache/commons/logging/Log.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/java/org/apache/commons/logging/Log.java?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/java/org/apache/commons/logging/Log.java (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/java/org/apache/commons/logging/Log.java Mon Mar 28 02:36:50 2005
@@ -0,0 +1,233 @@
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 
+
+
+package org.apache.commons.logging;
+
+/**
+ * <p>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.</p>
+ *
+ * <p> The six logging levels used by <code>Log</code> are (in order):
+ * <ol>
+ * <li>trace (the least serious)</li>
+ * <li>debug</li>
+ * <li>info</li>
+ * <li>warn</li>
+ * <li>error</li>
+ * <li>fatal (the most serious)</li>
+ * </ol>
+ * The mapping of these log levels to the concepts used by the underlying
+ * logging system is implementation dependent.
+ * The implemention should ensure, though, that this ordering behaves
+ * as expected.</p>
+ *
+ * <p>Performance is often a logging concern.
+ * By examining the appropriate property,
+ * a component can avoid expensive operations (producing information
+ * to be logged).</p>
+ *
+ * <p> For example,
+ * <code><pre>
+ *    if (log.isDebugEnabled()) {
+ *        ... do something expensive ...
+ *        log.debug(theResult);
+ *    }
+ * </pre></code>
+ * </p>
+ *
+ * <p>Configuration of the underlying logging system will generally be done
+ * external to the Logging APIs, through whatever mechanism is supported by
+ * that system.</p>
+ *
+ * @author <a href="mailto:sanders@apache.org">Scott Sanders</a>
+ * @author Rod Waldhoff
+ * @version $Id: Log.java 139042 2004-06-06 21:16:04Z rdonkin $
+ */
+public interface Log {
+
+
+    // ----------------------------------------------------- Logging Properties
+
+
+    /**
+     * <p> Is debug logging currently enabled? </p>
+     *
+     * <p> Call this method to prevent having to perform expensive operations
+     * (for example, <code>String</code> concatenation)
+     * when the log level is more than debug. </p>
+     */
+    public boolean isDebugEnabled();
+
+
+    /**
+     * <p> Is error logging currently enabled? </p>
+     *
+     * <p> Call this method to prevent having to perform expensive operations
+     * (for example, <code>String</code> concatenation)
+     * when the log level is more than error. </p>
+     */
+    public boolean isErrorEnabled();
+
+
+    /**
+     * <p> Is fatal logging currently enabled? </p>
+     *
+     * <p> Call this method to prevent having to perform expensive operations
+     * (for example, <code>String</code> concatenation)
+     * when the log level is more than fatal. </p>
+     */
+    public boolean isFatalEnabled();
+
+
+    /**
+     * <p> Is info logging currently enabled? </p>
+     *
+     * <p> Call this method to prevent having to perform expensive operations
+     * (for example, <code>String</code> concatenation)
+     * when the log level is more than info. </p>
+     */
+    public boolean isInfoEnabled();
+
+
+    /**
+     * <p> Is trace logging currently enabled? </p>
+     *
+     * <p> Call this method to prevent having to perform expensive operations
+     * (for example, <code>String</code> concatenation)
+     * when the log level is more than trace. </p>
+     */
+    public boolean isTraceEnabled();
+
+
+    /**
+     * <p> Is warn logging currently enabled? </p>
+     *
+     * <p> Call this method to prevent having to perform expensive operations
+     * (for example, <code>String</code> concatenation)
+     * when the log level is more than warn. </p>
+     */
+    public boolean isWarnEnabled();
+
+
+    // -------------------------------------------------------- Logging Methods
+
+
+    /**
+     * <p> Log a message with trace log level. </p>
+     *
+     * @param message log this message
+     */
+    public void trace(Object message);
+
+
+    /**
+     * <p> Log an error with trace log level. </p>
+     *
+     * @param message log this message
+     * @param t log this cause
+     */
+    public void trace(Object message, Throwable t);
+
+
+    /**
+     * <p> Log a message with debug log level. </p>
+     *
+     * @param message log this message
+     */
+    public void debug(Object message);
+
+
+    /**
+     * <p> Log an error with debug log level. </p>
+     *
+     * @param message log this message
+     * @param t log this cause
+     */
+    public void debug(Object message, Throwable t);
+
+
+    /**
+     * <p> Log a message with info log level. </p>
+     *
+     * @param message log this message
+     */
+    public void info(Object message);
+
+
+    /**
+     * <p> Log an error with info log level. </p>
+     *
+     * @param message log this message
+     * @param t log this cause
+     */
+    public void info(Object message, Throwable t);
+
+
+    /**
+     * <p> Log a message with warn log level. </p>
+     *
+     * @param message log this message
+     */
+    public void warn(Object message);
+
+
+    /**
+     * <p> Log an error with warn log level. </p>
+     *
+     * @param message log this message
+     * @param t log this cause
+     */
+    public void warn(Object message, Throwable t);
+
+
+    /**
+     * <p> Log a message with error log level. </p>
+     *
+     * @param message log this message
+     */
+    public void error(Object message);
+
+
+    /**
+     * <p> Log an error with error log level. </p>
+     *
+     * @param message log this message
+     * @param t log this cause
+     */
+    public void error(Object message, Throwable t);
+
+
+    /**
+     * <p> Log a message with fatal log level. </p>
+     *
+     * @param message log this message
+     */
+    public void fatal(Object message);
+
+
+    /**
+     * <p> Log an error with fatal log level. </p>
+     *
+     * @param message log this message
+     * @param t log this cause
+     */
+    public void fatal(Object message, Throwable t);
+
+
+}

Added: jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/java/org/apache/commons/logging/LogManager.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/java/org/apache/commons/logging/LogManager.java?view=auto&rev=159228
==============================================================================
--- jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/java/org/apache/commons/logging/LogManager.java (added)
+++ jakarta/commons/proper/logging/branches/DON_QUIXOTE/kernel/src/java/org/apache/commons/logging/LogManager.java Mon Mar 28 02:36:50 2005
@@ -0,0 +1,203 @@
+/*
+ * Copyright 2005 The Apache Software Foundation.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 
+package org.apache.commons.logging;
+
+/**
+ * <p>Simplified superclass for <code>LogFactory</code>.
+ * Suitable for static or dynamic binding.
+ * </p><p>
+ * When dynamically bound, 
+ * a single system property {@link #DISCOVERY_CONFIGURATION}
+ * is used to choose a discovery implementation 
+ * (any <code>LogManager</code> subclass) for the entire environment.
+ * For backwards compatibility
+ * </p>
+ * <p>
+ * This class should be simple enough to be compiled on reduced Java 
+ * platforms. 
+ * </p>
+ * <p>
+ * The symantics of this basic discovery differ from <code>LogFactory</code>.
+ * In the event of a failure within discovery, a safe but minimal log 
+ * will be returned.
+ * </p>
+ * <p>
+ * It is of great importance that a truely <strong>minimal</strong>
+ * interface is maintained. All members which are not part of the minimal
+ * public interface should be private.
+ * </p>
+ */
+public class LogManager {
+	
+    /** 
+     * <code>org.apache.commons.logging.DISCOVERY</code>
+     * when set should contain the fully qualified class name
+     * of a <code>LogManager</code> implementation
+     */
+	public static final String DISCOVERY_CONFIGURATION = "org.apache.commons.logging.DISCOVERY";
+	
+    /**
+     * Discovers a <code>LogManager</code> implementation.
+     * This is a very simple implementation.
+     * The only way of setting this is through a system property.
+     * No complex ClassLoader magic is used.
+     * It is intended that the implmentations should be
+     * bundled within the same jar.
+     * @return <code>LogManager</code>
+     */
+	private static final LogManager discover() {
+		LogManager result = null;
+		try {
+			String discoveryProperty = System.getProperty(DISCOVERY_CONFIGURATION);
+			if (discoveryProperty == null) {
+				try {
+					Class discoveryClass = Class.forName("org.apache.commons.logging.LogFactory");
+					result = (LogManager) discoveryClass.newInstance();
+				} catch (Throwable t) {
+					// swallow
+                    // todo: probably want to think about a diagnostic property which would print out useful information here
+				}
+				
+				if (result == null) {
+					result = new LogManager();
+				}
+			} else {
+				Class discoveryClass = Class.forName(discoveryProperty);
+				result = (LogManager) discoveryClass.newInstance();
+			}
+		} catch (Throwable t) {
+            // todo: probably want to think about a diagnostic property which would print out useful information here
+			result = new LogManager();
+		}
+		return result;
+	}
+	
+    /** Discovery implementation */
+	private static final LogManager manager = discover();
+	
+    /** Singleton fallback logger */
+	private static final Log fallbackLog = new MinimalLog();
+	
+    /**
+     * Gets a <code>Log</code> implementation.
+     * @param param <code>Object</code> identifying the <code>Log</code>, not null
+     * @return <code>Log</code>, not null
+     */
+	public static Log getLog(Object param) {
+		return manager.getLogImpl(param);
+	}
+	
+    /**
+     * Gets a <code>Log</code> implementation.
+     * Hook for subclassing.
+     * @param param  <code>Object</code> identifying the <code>Log</code>, not null
+     * @return <code>Log</code>, not null
+     */
+	protected Log getLogImpl(Object param) {
+		return fallbackLog;
+	}
+	
+    /**
+     * Implements {@link Log} in a safe but minimal fashion.
+     * Logs <code>error</code> and <code>fatal</code> 
+     * messages to {@link System#err}, printing
+     * stack traces for <code>Throwable</code>'s.
+     * All other messages are discarded. 
+     */
+	private static final class MinimalLog implements Log {
+
+        /** Message discarded */
+		public void debug(Object message, Throwable t) {}
+        /** Message discarded */
+		public void debug(Object message) {}
+		
+        /** 
+         * Logs message to <code>System.err</code>.
+         * Stack trace is printed for <code>Throwable</code>.
+         */
+		public void error(Object message, Throwable t) {
+			System.err.println(message);
+			t.printStackTrace();
+		}
+		
+        /** Logs message to <code>System.err</code> */
+		public void error(Object message) {
+			System.err.println(message);
+		}
+        
+        /** 
+         * Logs message to <code>System.err</code>.
+         * Stack trace is printed for <code>Throwable</code>.
+         */
+		public void fatal(Object message, Throwable t) {
+			System.err.println(message);
+			t.printStackTrace();
+		}
+		
+        /** Logs message to <code>System.err</code> */
+		public void fatal(Object message) {
+			System.err.println(message);
+		}
+
+        /** Message discarded */
+		public void info(Object message, Throwable t) {}
+        /** Message discarded */
+		public void info(Object message) {}
+        /** Message discarded */
+        public void trace(Object message, Throwable t) {}
+        /** Message discarded */
+        public void trace(Object message) {}
+        /** Message discarded */
+        public void warn(Object message, Throwable t) {}
+        /** Message discarded */
+        public void warn(Object message) {}
+        
+		/** Not enabled */
+		public boolean isDebugEnabled() {
+			return false;
+		}
+
+        /** Enabled */
+		public boolean isErrorEnabled() {
+			return true;
+		}
+        
+        /** Enabled */
+        public boolean isFatalEnabled() {
+			return true;
+		}
+		
+        /** Not enabled */
+		public boolean isInfoEnabled() {
+			return false;
+		}
+
+        /** Not enabled */
+		public boolean isTraceEnabled() {
+			return false;
+		}
+        
+        /** Not enabled */
+		public boolean isWarnEnabled() {
+			return false;
+		}
+
+		/** Indicates that this is the minimal <code>Log</code> implementation */
+		public String toString() {
+			return "JCL Minimal Log";
+		}
+}
+}



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org