Author: ceki Date: Fri Aug 26 21:45:09 2005 New Revision: 199 Added: slf4j/trunk/src/java/org/apache/commons/logging/impl/package.html slf4j/trunk/src/java/org/apache/commons/logging/package.html Removed: slf4j/trunk/src/java/org/apache/commons/logging/impl/LogFactoryImpl.java Modified: slf4j/trunk/src/java/org/apache/commons/logging/Log.java slf4j/trunk/src/java/org/apache/commons/logging/LogConfigurationException.java slf4j/trunk/src/java/org/apache/commons/logging/LogFactory.java slf4j/trunk/src/java/org/apache/commons/logging/impl/SLF4FLogFactory.java slf4j/trunk/src/java/org/apache/commons/logging/impl/SLF4JLog.java Log: improved javadocs
Modified: slf4j/trunk/src/java/org/apache/commons/logging/Log.java ============================================================================== --- slf4j/trunk/src/java/org/apache/commons/logging/Log.java (original) +++ slf4j/trunk/src/java/org/apache/commons/logging/Log.java Fri Aug 26 21:45:09 2005 @@ -55,6 +55,8 @@ * external to the Logging APIs, through whatever mechanism is supported by * that system.</p> * + * <p style="color: #E40; font-weight: bold;">Please note that this interface is identical to that found in JCL 1.0.4.</p> + * * @author <a href="mailto:[EMAIL PROTECTED]">Scott Sanders</a> * @author Rod Waldhoff * @version $Id: Log.java,v 1.19 2004/06/06 21:16:04 rdonkin Exp $ Modified: slf4j/trunk/src/java/org/apache/commons/logging/LogConfigurationException.java ============================================================================== --- slf4j/trunk/src/java/org/apache/commons/logging/LogConfigurationException.java (original) +++ slf4j/trunk/src/java/org/apache/commons/logging/LogConfigurationException.java Fri Aug 26 21:45:09 2005 @@ -21,9 +21,11 @@ * <p>An exception that is thrown only if a suitable <code>LogFactory</code> * or <code>Log</code> instance cannot be created by the corresponding * factory methods.</p> - * + * + * <p>In this version of JCL, this exception will never be thrown in practice. However, it is + * included here to ensure total compile time and run time compatibility with the original JCL 1.0.4. + * * @author Craig R. McClanahan - * @version $Revision: 1.6 $ $Date: 2004/02/28 21:46:45 $ */ public class LogConfigurationException extends RuntimeException { Modified: slf4j/trunk/src/java/org/apache/commons/logging/LogFactory.java ============================================================================== --- slf4j/trunk/src/java/org/apache/commons/logging/LogFactory.java (original) +++ slf4j/trunk/src/java/org/apache/commons/logging/LogFactory.java Fri Aug 26 21:45:09 2005 @@ -20,14 +20,9 @@ /** * <p> - * Factory for creating [EMAIL PROTECTED] Log}instances, with discovery and configuration - * features similar to that employed by standard Java APIs such as JAXP. - * </p> + * Factory for creating [EMAIL PROTECTED] Log} instances, which always delegates to an instance of + * [EMAIL PROTECTED] SLF4FLogFactory}. * - * <p> - * <strong>IMPLEMENTATION NOTE </strong>- This implementation is heavily based - * on the SAXParserFactory and DocumentBuilderFactory implementations - * (corresponding to the JAXP pluggability APIs) found in Apache Xerces. * </p> * * @author Craig R. McClanahan Modified: slf4j/trunk/src/java/org/apache/commons/logging/impl/SLF4FLogFactory.java ============================================================================== --- slf4j/trunk/src/java/org/apache/commons/logging/impl/SLF4FLogFactory.java (original) +++ slf4j/trunk/src/java/org/apache/commons/logging/impl/SLF4FLogFactory.java Fri Aug 26 21:45:09 2005 @@ -30,42 +30,22 @@ /** * <p> - * Concrete subclass of [EMAIL PROTECTED] LogFactory}that implements the following - * algorithm to dynamically select a logging implementation class to instantiate - * a wrapper for. - * </p> - * <ul> - * <li>Use a factory configuration attribute named - * <code>org.apache.commons.logging.Log</code> to identify the requested - * implementation class.</li> - * <li>Use the <code>org.apache.commons.logging.Log</code> system property to - * identify the requested implementation class.</li> - * <li>If <em>Log4J</em> is available, return an instance of - * <code>org.apache.commons.logging.impl.Log4JLogger</code>.</li> - * <li>If <em>JDK 1.4 or later</em> is available, return an instance of - * <code>org.apache.commons.logging.impl.Jdk14Logger</code>.</li> - * <li>Otherwise, return an instance of - * <code>org.apache.commons.logging.impl.SimpleLog</code>.</li> - * </ul> + * Concrete subclass of [EMAIL PROTECTED] LogFactory} which always delegates to the + * [EMAIL PROTECTED] LoggerFactory org.slf4j.LoggerFactory} class. * * <p> - * If the selected [EMAIL PROTECTED] Log}implementation class has a - * <code>setLogFactory()</code> method that accepts a [EMAIL PROTECTED] LogFactory} - * parameter, this method will be called on each newly created instance to - * identify the associated factory. This makes factory configuration attributes - * available to the Log instance, if it so desires. - * </p> + * This factory generates instances of [EMAIL PROTECTED] SLF4JLog}. It will remember + * previously created instances for the same name, and will + * return them on repeated requests to the + * <code>getInstance()</code> method. * - * <p> - * This factory will remember previously created <code>Log</code> instances - * for the same name, and will return them on repeated requests to the - * <code>getInstance()</code> method. This implementation ignores any - * configured attributes. + * <p>This implementation ignores any configured attributes. * </p> * * @author Rod Waldhoff * @author Craig R. McClanahan * @author Richard A. Sitze + * @author <a href="http://www.qos.ch/log4j/";>Ceki Gülcü</a> */ public class SLF4FLogFactory extends LogFactory { @@ -94,14 +74,8 @@ public static final String LOG_PROPERTY = "org.apache.commons.logging.Log"; /** - * The deprecated system property used for backwards compatibility with the - * old [EMAIL PROTECTED] org.apache.commons.logging.LogSource}class. - */ - protected static final String LOG_PROPERTY_OLD = "org.apache.commons.logging.log"; - - /** * <p> - * The name of the [EMAIL PROTECTED] Log}interface class. + * The name of the [EMAIL PROTECTED] Log} interface class. * </p> */ private static final String LOG_INTERFACE = "org.apache.commons.logging.Log"; @@ -175,14 +149,6 @@ * the factory's current set of configuration attributes. * </p> * - * <p> - * <strong>NOTE </strong>- Depending upon the implementation of the - * <code>LogFactory</code> you are using, the <code>Log</code> instance - * you are returned may or may not be local to the current application, and - * may or may not be returned again on a subsequent call with the same name - * argument. - * </p> - * * @param name * Logical name of the <code>Log</code> instance to be returned * (the meaning of this name is only known to the underlying logging @@ -195,7 +161,8 @@ Log instance = (Log) loggerMap.get(name); if (instance == null) { - instance = newInstance(name); + Logger logger = LoggerFactory.getLogger(name); + instance = new SLF4JLog(logger); loggerMap.put(name, instance); } return (instance); @@ -244,22 +211,4 @@ } } - - // ------------------------------------------------------ Protected Methods - - /** - * Create and return a new [EMAIL PROTECTED] org.apache.commons.logging.Log}instance for - * the specified name. - * - * @param name - * Name of the new logger - * - * @exception LogConfigurationException - * if a new instance cannot be created - */ - protected Log newInstance(String name) throws LogConfigurationException { - Logger logger = LoggerFactory.getLogger(name); - return new SLF4JLog(logger); - } - } \ No newline at end of file Modified: slf4j/trunk/src/java/org/apache/commons/logging/impl/SLF4JLog.java ============================================================================== --- slf4j/trunk/src/java/org/apache/commons/logging/impl/SLF4JLog.java (original) +++ slf4j/trunk/src/java/org/apache/commons/logging/impl/SLF4JLog.java Fri Aug 26 21:45:09 2005 @@ -6,8 +6,8 @@ import org.slf4j.Logger; /** - * Implementation of [EMAIL PROTECTED] Log} interface which delegates all processing to - * a [EMAIL PROTECTED] Logger} instance. + * Implementation of [EMAIL PROTECTED] Log org.apache.commons.logging.Log} interface which + * delegates all processing to a wrapped [EMAIL PROTECTED] Logger org.slf4j.Logger} instance. * * <p>JCL's FATAL and TRACE levels are mapped to ERROR and DEBUG respectively. All * other levels map one to one. @@ -16,89 +16,180 @@ */ public class SLF4JLog implements Log { - Logger logger; + private Logger logger; SLF4JLog(Logger logger) { this.logger = logger; } /** - * Delegate to org.slf4j.Logger instance. + * Directly delegates to the wrapped <code>org.slf4j.Logger</code> instance. */ public boolean isDebugEnabled() { return logger.isDebugEnabled(); } + /** + * Directly delegates to the wrapped <code>org.slf4j.Logger</code> instance. + */ public boolean isErrorEnabled() { return logger.isErrorEnabled(); } + /** + * Delegates to the <code>isErrorEnabled<code> method of the wrapped + * <code>org.slf4j.Logger</code> instance. + */ public boolean isFatalEnabled() { return logger.isErrorEnabled(); } - /* - * (non-Javadoc) - * - * @see org.apache.commons.logging.Log#isInfoEnabled() + /** + * Directly delegates to the wrapped <code>org.slf4j.Logger</code> instance. */ public boolean isInfoEnabled() { return logger.isInfoEnabled(); } + /** + * Delegates to the <code>isDebugEnabled<code> method of the wrapped + * <code>org.slf4j.Logger</code> instance. + */ public boolean isTraceEnabled() { return logger.isDebugEnabled(); } + /** + * Directly delegates to the wrapped <code>org.slf4j.Logger</code> instance. + */ public boolean isWarnEnabled() { return logger.isWarnEnabled(); } + /** + * Converts the input parameter to String and then delegates to + * the debug method of the wrapped <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + */ public void trace(Object message) { logger.debug(message.toString()); } + /** + * Converts the first input parameter to String and then delegates to + * the debug method of the wrapped <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + * @param t the exception to log + */ public void trace(Object message, Throwable t) { logger.debug(message.toString(), t); } + /** + * Converts the input parameter to String and then delegates to the wrapped + * <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + */ public void debug(Object message) { logger.debug(message.toString()); } + /** + * Converts the first input parameter to String and then delegates to + * the wrapped <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + * @param t the exception to log + */ public void debug(Object message, Throwable t) { logger.debug(message.toString(), t); } + /** + * Converts the input parameter to String and then delegates to the wrapped + * <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + */ public void info(Object message) { logger.info(message.toString()); } + /** + * Converts the first input parameter to String and then delegates to + * the wrapped <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + * @param t the exception to log + */ public void info(Object message, Throwable t) { logger.info(message.toString(), t); } + /** + * Converts the input parameter to String and then delegates to the wrapped + * <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + */ public void warn(Object message) { logger.warn(message.toString()); } + /** + * Converts the first input parameter to String and then delegates to + * the wrapped <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + * @param t the exception to log + */ public void warn(Object message, Throwable t) { logger.warn(message.toString(), t); } - + /** + * Converts the input parameter to String and then delegates to the wrapped + * <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + */ public void error(Object message) { logger.error(message.toString()); } + /** + * Converts the first input parameter to String and then delegates to + * the wrapped <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + * @param t the exception to log + */ public void error(Object message, Throwable t) { logger.error(message.toString(), t); } + + + /** + * Converts the input parameter to String and then delegates to + * the error method of the wrapped <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + */ public void fatal(Object message) { logger.error(message.toString()); } + /** + * Converts the first input parameter to String and then delegates to + * the error method of the wrapped <code>org.slf4j.Logger</code> instance. + * + * @param message the message to log. Converted to [EMAIL PROTECTED] String} + * @param t the exception to log + */ public void fatal(Object message, Throwable t) { logger.error(message.toString(), t); } Added: slf4j/trunk/src/java/org/apache/commons/logging/impl/package.html ============================================================================== --- (empty file) +++ slf4j/trunk/src/java/org/apache/commons/logging/impl/package.html Fri Aug 26 21:45:09 2005 @@ -0,0 +1,5 @@ +<body> + + <p>SLF4J based implementation of commons-logging wrapper APIs.</p> + +</body> Added: slf4j/trunk/src/java/org/apache/commons/logging/package.html ============================================================================== --- (empty file) +++ slf4j/trunk/src/java/org/apache/commons/logging/package.html Fri Aug 26 21:45:09 2005 @@ -0,0 +1,169 @@ +<!-- + + 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. + +--> + +<body> +<p>Jakarta Commons Logging implemented over SLF4J.</p> + + +<h3>Overview</h3> + +<p>This package contains the same public user interface as <a +href="http://jakarta.apache.org/commons/logging/";>Jakarta Commons +Logging (JCL)</a>. It is intended as a 100% compatible drop-in +replacement for the original JCL version 1.0.4. +</p> + +<p>As the original JCL version 1.0.4, the present version supports +various logging APIs. It differs from the original in implementation +but not the public API. This implementation uses SLF4J under the +covers. As as such, all the logging systems that SLF4J supports, +e.g. NOP, Simple, JDK14, nlog4j are supported by this version of JCL. +</p> + +<h3>Quick Start Guide</h3> + +<p>For those impatient to just get on with it, the following example +illustrates the typical declaration and use of a logger that is named (by +convention) after the calling class: + +<pre> + import org.apache.commons.logging.Log; + import org.apache.commons.logging.LogFactory; + + public class Foo { + + static Log log = LogFactory.getLog(Foo.class); + + public void foo() { + ... + try { + if (log.isDebugEnabled()) { + log.debug("About to do something to object " + name); + } + name.bar(); + } catch (IllegalStateException e) { + log.error("Something bad happened to " + name, e); + } + ... + } +</pre> + +<h3>Configuring the Commons Logging Package</h3> + +<p>In this version of JCL, the selection of the logging system to use +is chosen by the underlying SLF4J API. Consequently, all JCL-specific +configration parameters are ignored. +</p> + +<h4>Choosing a <code>LogFactory</code> Implementation</h4> + +<p>From an application perspective, the first requirement is to +retrieve an object reference to the <code>LogFactory</code> instance +that will be used to create <code><a href="Log.html">Log</a></code> +instances for this application. This is normally accomplished by +calling the static <code>getFactory()</code> method. This method +always returns the same factory, i.e. a unique instance of the <a +href="impl/SLF4FLogFactory.html">SLF4FLogFactory</a> class. +</p> + + + +<h4>Configuring the Underlying Logging System</h4> + +<p>The basic principle is that the user is totally responsible for the +configuration of the underlying logging system. +Commons-logging should not change the existing configuration.</p> + +<p>Each individual <a href="Log.html">Log</a> implementation may +support its own configuration properties. These will be documented in the +class descriptions for the corresponding implementation class.</p> + +<p>Finally, some <code>Log</code> implementations (such as the one for Log4J) +require an external configuration file for the entire logging environment. +This file should be prepared in a manner that is specific to the actual logging +technology being used.</p> + + +<h3>Using the Logging Package APIs</h3> + +<p>Use of the Logging Package APIs, from the perspective of an application +component, consists of the following steps:</p> +<ol> +<li>Acquire a reference to an instance of + <a href="Log.html">org.apache.commons.logging.Log</a>, by calling the + factory method + <a href="LogFactory.html#getInstance(java.lang.String)"> + LogFactory.getInstance(String name)</a>. Your application can contain + references to multiple loggers that are used for different + purposes. A typical scenario for a server application is to have each + major component of the server use its own Log instance.</li> +<li>Cause messages to be logged (if the corresponding detail level is enabled) + by calling appropriate methods (<code>trace()</code>, <code>debug()</code>, + <code>info()</code>, <code>warn()</code>, <code>error</code>, and + <code>fatal()</code>).</li> +</ol> + +<p>For convenience, <code>LogFactory</code> also offers a static method +<code>getLog()</code> that combines the typical two-step pattern:</p> +<pre> + Log log = LogFactory.getFactory().getInstance(Foo.class); +</pre> +<p>into a single method call:</p> +<pre> + Log log = LogFactory.getLog(Foo.class); +</pre> + +<p>For example, you might use the following technique to initialize and +use a <a href="Log.html">Log</a> instance in an application component:</p> +<pre> +import org.apache.commons.logging.Log; +import org.apache.commons.logging.LogFactory; + +public class MyComponent { + + protected static Log log = + LogFactory.getLog(MyComponent.class); + + // Called once at startup time + public void start() { + ... + log.info("MyComponent started"); + ... + } + + // Called once at shutdown time + public void stop() { + ... + log.info("MyComponent stopped"); + ... + } + + // Called repeatedly to process a particular argument value + // which you want logged if debugging is enabled + public void process(String value) { + ... + // Do the string concatenation only if logging is enabled + if (log.isDebugEnabled()) + log.debug("MyComponent processing " + value); + ... + } + +} +</pre> + +</body> _______________________________________________ dev mailing list [email protected] http://slf4j.org/mailman/listinfo/dev
