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<<i>Priority</i>>()</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="<h1>${component.title} (Version ${component.version})</h1>"
+ windowtitle="${component.title} (Version ${component.version})"
+ bottom='Copyright 2002-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.-->'>
+ <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