commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From skitch...@apache.org
Subject svn commit: r371225 - /jakarta/commons/proper/logging/trunk/xdocs/guide.xml
Date Sun, 22 Jan 2006 07:29:57 GMT
Author: skitching
Date: Sat Jan 21 23:29:54 2006
New Revision: 371225

URL: http://svn.apache.org/viewcvs?rev=371225&view=rev
Log:
Add info about use of commons-logging.properties, including new "priority" feature.
Document problems with Use of static log members in library code.

Modified:
    jakarta/commons/proper/logging/trunk/xdocs/guide.xml

Modified: jakarta/commons/proper/logging/trunk/xdocs/guide.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/trunk/xdocs/guide.xml?rev=371225&r1=371224&r2=371225&view=diff
==============================================================================
--- jakarta/commons/proper/logging/trunk/xdocs/guide.xml (original)
+++ jakarta/commons/proper/logging/trunk/xdocs/guide.xml Sat Jan 21 23:29:54 2006
@@ -95,8 +95,8 @@
 <p>JCL provides thin-wrapper <code>Log</code> implementations for
 other logging tools, including
 <a href="http://logging.apache.org/log4j/docs/index.html">Log4J</a>,
-<a href="http://avalon.apache.org/logkit/index.html">Avalon LogKit</a>,
-the Avalon Framework's logging infrastructure,
+<a href="http://avalon.apache.org/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.
@@ -117,9 +117,10 @@
             <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.
+instances). Specifying a particular Log implementation is very useful (whether that is
+one provided by commons-logging or a user-defined one). Specifying a 
+<code>LogFactory</code> implementation other than the default is a subject for
+advanced users only, so will not be addressed here.
         </p>
             <p>
 The default <code>LogFactory</code> implementation uses the following discovery
process
@@ -130,9 +131,23 @@
             <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> (for backwards compatibility to
+pre-1.0 versions of this API, an attribute
 <code>org.apache.commons.logging.log</code> is also consulted).
+<p>
+Configuration attributes can be set explicitly by java code, but they are more
+commonly set by placing a file named commons-logging.properties in the classpath.
+When such a file exists, every entry in the properties file becomes an "attribute"
+of the LogFactory. When there is more than one such file in the classpath, releases
+of commons-logging prior to 1.1 simply use the first one found. From release 1.1,
+each file may define a <code>priority</code> key in each file, and the file with
+the highest priority is used (no priority definition implies priority of zero).
+When multiple files have the same priority, the first one found is used.
+</p>
+<p>
+Defining this property in a commons-logging.properties file is the recommended
+way of explicitly selecting a Log implementation.
+</p>
             </li>
                 <li>
 Look for a system property named
@@ -262,11 +277,20 @@
             <source>
 public class CLASS
 {
-    private static Log log = LogFactory.getLog(CLASS.class);
+    private Log log = LogFactory.getLog(CLASS.class);
     ...
     ;
         </source>
     </ul>
+    <p>
+Note that for application code, declaring the log member as "static" is more
+efficient as one Log object is created per class, and is recommended.
+However this is not safe to do for a class which may be deployed via a "shared"
+classloader in a servlet or j2ee container or similar environment. If the class
+may end up invoked with different thread-context-classloader values set then the
+member must <i>not</i> be declared static. The use of "static" should therefore
+be avoided in code within any "library" type project.
+    </p>
         <p>
 Messages are logged to a <em>logger</em>, such as <code>log</code>
 by invoking a method corresponding to <em>priority</em>.



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


Mime
View raw message