[slf4j-dev] svn commit: r199 - in slf4j/trunk/src/java/org/apache/commons/logging: . impl
ceki at slf4j.org
ceki at slf4j.org
Fri Aug 26 21:45:10 CEST 2005
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:sanders at apache.org">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 {@link Log}instances, with discovery and configuration
- * features similar to that employed by standard Java APIs such as JAXP.
- * </p>
+ * Factory for creating {@link Log} instances, which always delegates to an instance of
+ * {@link 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 {@link 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 {@link LogFactory} which always delegates to the
+ * {@link LoggerFactory org.slf4j.LoggerFactory} class.
*
* <p>
- * If the selected {@link Log}implementation class has a
- * <code>setLogFactory()</code> method that accepts a {@link 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 {@link 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 {@link org.apache.commons.logging.LogSource}class.
- */
- protected static final String LOG_PROPERTY_OLD = "org.apache.commons.logging.log";
-
- /**
* <p>
- * The name of the {@link Log}interface class.
+ * The name of the {@link 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 {@link 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 {@link Log} interface which delegates all processing to
- * a {@link Logger} instance.
+ * Implementation of {@link Log org.apache.commons.logging.Log} interface which
+ * delegates all processing to a wrapped {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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>
More information about the slf4j-dev
mailing list