ceki 01/06/07 14:10:11
Modified: docs HISTORY download.html manual.html
src/java/org/apache/log4j/helpers Loader.java
src/xdocs download.xml
Log:
Documentation changes.
Revision Changes Path
1.52 +10 -9 jakarta-log4j/docs/HISTORY
Index: HISTORY
===================================================================
RCS file: /home/cvs/jakarta-log4j/docs/HISTORY,v
retrieving revision 1.51
retrieving revision 1.52
diff -u -r1.51 -r1.52
--- HISTORY 2001/06/06 16:07:04 1.51
+++ HISTORY 2001/06/07 21:09:59 1.52
@@ -5,18 +5,19 @@
client code.
[***] Changes requiring important modifications to existing client code.
- June ??, 2001
+ June 7, 2001
- Release of version 1.1.2
- Corrected a problem with the static initializer of the Category
class which would use the wrong class loader to search for the
- log4j.properties file. The search algorithm has been also
- simplified. The preferred method to specify the automatic
- configuration file is setting the log4j.configration system
- property. [*]
+ default configuration file. The associated search algorithm has
+ been also simplified. Nevertheless, the preferred method to specify
+ the automatic configuration file is by setting the
+ log4j.configuration system property. [*]
- - Documentation improvements. [*]
+ - Documentation improvements. Added a new section to the manual
+ explaining the default initialization procedure [*]
- Enhancements to the org.apache.log4j.examples.appserver package. [*]
@@ -52,8 +53,8 @@
- The configureAndWatch methods in Configurators did not close the
configuration file, preventing its editing. See bug 1686. [*]
- - In DOMConfigurator.setParameter special charater conversion now
- preceeds variable substitution. This change was suggested by Steven
+ - In DOMConfigurator.setParameter special character conversion now
+ precedes variable substitution. This change was suggested by Steven
Velez. The vast majority of users should be oblivious to it. [*]
- The TextPaneAppender is no longer maintained and has been
@@ -68,7 +69,7 @@
- Aaron Greenhouse from Carnegie Mellon SCS found a series of
multi-threading related bugs in Category and AsyncAppender. See bug
- ids 1505 and 1507 in our bug database for examplary bug
+ ids 1505 and 1507 in our bug database for exemplary bug
reports. They are worth the detour. [*]
- InvalidJarIndexException is only available in JDK 1.3. Referring
1.27 +5 -5 jakarta-log4j/docs/download.html
Index: download.html
===================================================================
RCS file: /home/cvs/jakarta-log4j/docs/download.html,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -r1.26 -r1.27
--- download.html 2001/05/20 15:03:06 1.26
+++ download.html 2001/06/07 21:10:00 1.27
@@ -116,19 +116,19 @@
<table
border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <a name="log4j version 1.1.1"><strong>log4j version 1.1.1</strong></a>
+ <a name="log4j version 1.1.2"><strong>log4j version 1.1.2</strong></a>
</font>
</td></tr>
<tr><td><br/></td></tr>
<tr><td>
<blockquote>
- <p>Download version 1.1.1 including <i>full
source code</i>, class files
+ <p>Download version 1.1.2 including <i>full
source code</i>, class files
and documentation in
-<a href="../jakarta-log4j-1.1.1.tar.gz"><b>TAR.GZ</b></a> format or in
-<a href="../jakarta-log4j-1.1.1.zip"><b>ZIP</b></a> format. You may
+<a href="../jakarta-log4j-1.1.2.tar.gz"><b>TAR.GZ</b></a> format or in
+<a href="../jakarta-log4j-1.1.2.zip"><b>ZIP</b></a> format. You may
elect to browse log4j <a href="documentation.html"><b>documentation</b></a> online.
</p>
- <p><a
href="http://www.javaworld.com/javaworld/jw-05-2001/jw-0504-finalists.html";><img
src="images/ecaward_finalist_logo.gif" align="right" border="0" /></a>Version 1.1.1 is
the 21st major public release of
+ <p><a
href="http://www.javaworld.com/javaworld/jw-05-2001/jw-0504-finalists.html";><img
src="images/ecaward_finalist_logo.gif" align="right" border="0" /></a>Version 1.1.2 is
the 21st major public release of
log4j. It is backward compatible with log4j version 1.0.x.</p>
<p>We also maintain a list of <a
href="earlier.html">earlier
versions</a> of log4j for download, intended for the curious
1.20 +139 -14 jakarta-log4j/docs/manual.html
Index: manual.html
===================================================================
RCS file: /home/cvs/jakarta-log4j/docs/manual.html,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- manual.html 2001/06/06 16:07:06 1.19
+++ manual.html 2001/06/07 21:10:01 1.20
@@ -10,7 +10,7 @@
"Ceki Gülcü"
- December 2000 <br><br>
+ June 2001 <br><br>
</center>
<hr>
@@ -39,7 +39,7 @@
own tracing API. This was in early 1996. After countless enhancements,
several incarnations and much work that API has evolved to become
log4j, a popular logging package for Java. The package is distributed
-under the <a href=../LICENSE.APL>Apache Public License</a>, a
+under the <a href=../LICENSE.APL>Apache Software License</a>, a
fully-fledged open source license certified by the <a
href="http://www.opensource.org";>open source</a> initiative. The
latest log4j version, including full-source code, class files and
@@ -742,20 +742,18 @@
<ol>
- <li>Skip default initialization if the
- <b>log4j.defaultInitOverride</b> system property is set to any value
- other than "false".
+ <li>Skip default initialization if the system property
+ <b>log4j.defaultInitOverride</b> is set to any value other than
+ "false".
<p><li>Set the <code>resource</code> string variable to the value of
the <b>log4j.configuration</b> system property. <em>The preferred
way to specify the default initialization file is thourough the
<b>log4j.configuration</b> system property.</em> In case the system
- property is not defined, then set <code>resource</code> to the
- default value "log4j.properties".
+ property <b>log4j.configuration</b> is not defined, then set the
+ string variable <code>resource</code> to its default value
+ "log4j.properties".
-
-
-
<p><li>Attempt to convert the <code>resource</code> variable to a
URL.
@@ -764,8 +762,7 @@
the <code>resource</code> from the classpath by calling
<code>org.apache.log4j.helpers.Loader.getResource(resource,
Category.class)</code> which returns a URL. Note that the string
- "log4j.properties" constitutes a malformed URL and falls into this
- case.
+ "log4j.properties" constitutes a malformed URL.
<p>See <a
href="api/org/apache/log4j/helpers/Loader.html#getResource(java.lang.String,
java.lang.Class)">Loader.getResource(java.lang.String, java.lang.Class)</a>
@@ -795,9 +792,137 @@
extension, then the <a
href="api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</a>
will be used to parse the URL.
+</ol>
+<h2>Default Initialization under Tomcat</h2>
-</ol>
+<p>The default log4j initialization is particularly useful in
+web-server environments. Under Tomcat 3.x and 4.x, you should place
+the <code>log4j.properties</code> under the
+<code>WEB-INF/classes</code> directory of your web-applications. Log4j
+will find the properties file and initialize itself.
+
+<p>You can also choose to set the system property
+<b>log4j.configuration</b> before starting Tomcat. For Tomcat 3.x The
+<code>TOMCAT_OPTS</code> environment variable is used to set command
+line options. For Tomcat 4.0, set the <code>CATALINA_OPTS</code>
+environment variable instead of <code>TOMCAT_OPTS</code>.
+
+<p><b>Example 1</b>
+
+<p>The Unix shell command
+<pre>
+ export TOMCAT_OPTS="-Dlog4j.configuration=foobar.txt"
+</pre>
+
+tells log4j to use the file <code>foobar.txt</code> as the default
+configuration file. This file should be place under the
+<code>WEB-INF/classes</code> directory of your web-application. The
+file will be read using the <a
+href="api/org/apache/log4j/xml/PropertyConfigurator.html">PropertyConfigurator</a>.
Each
+web-application will use a different default configuration file because
+each file is relative to a web-application.
+
+
+<p><b>Example 2</b>
+
+<p>The Unix shell command
+<pre>
+ export TOMCAT_OPTS="-Dlog4j.debug -Dlog4j.configuration=foobar.xml"
+</pre>
+
+tells log4j to output log4j-internal debugging information and to use
+the file <code>foobar.xml</code> as the default configuration
+file. This file should be place under the <code>WEB-INF/classes</code>
+directory of your web-application. Since the file ends with a
+<code>.xml</code> extension, it will read using the <a
+href="api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</a>. Each
+web-application will use a different default configuration file because
+each file is relative to a web-application.
+
+<p><b>Example 3</b>
+
+<p>The Windows shell command
+<pre>
+ set TOMCAT_OPTS=-Dlog4j.configuration=foobar.lcf#com.foo.BarConfigurator
+</pre>
+
+tells log4j to use the file <code>foobar.lcf</code> as the default
+configuration file. This file should be place under the
+<code>WEB-INF/classes</code> directory of your web-application. Due to
+the extra reference part, the file will be read using the
+<code>com.foo.BarConfigurator</code> custom configurator. Each
+web-application will use a different default configuration file because
+each file is relative to a web-application.
+
+
+<p><b>Example 4</b>
+
+<p>The Windows shell command
+<pre>
+ set TOMCAT_OPTS=-Dlog4j.configuration=file:/c:/foobar.lcf</pre>
+
+tells log4j to use the file <code>c:\foobar.xml</code> as the default
+configuration file. The configuration file is fully specified by the
+URL <code>file:/c:/foobar.lcf</code>. Thus, the same configuration
+file will be used for all web-applications -- in other words, disaster
+waiting to happen.
+
+
+<p><b>Initialization servlet</b>
+
+<p>It is also possible to use a special servlet for log4j
+initialization. Here is an example,
+
+<pre>
+package com.foo;
+
+import org.apache.log4j.PropertyConfigurator;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.PrintWriter;
+import java.io.IOException;
+
+public class Log4jInit extends HttpServlet {
+
+ public
+ void <b>init()</b> {
+ String prefix = getServletContext().getRealPath("/");
+ String file = getInitParameter("log4j-init-file");
+ // if the log4j-init-file is not set, then no point in trying
+ if(file != null) {
+ PropertyConfigurator.configure(prefix+file);
+ }
+ }
+
+ public
+ void doGet(HttpServletRequest req, HttpServletResponse res) {
+ }
+}
+</pre>
+
+Define the following servlet in the web.xml file for your web-application.
+
+<pre>
+ <servlet>
+ <servlet-name>log4j-init</servlet-name>
+ <servlet-class>com.foo.Log4jInit</servlet-class>
+
+ <init-param>
+ <param-name>log4j-init-file</param-name>
+ <param-value>WEB-INF/classes/log4j.lcf</param-value>
+ </init-param>
+
+ <b><load-on-startup>1</load-on-startup></b>
+ </servlet>
+</pre>
+
+<p>Writing an initialization servlet is the most flexible way for
+initializing log4j. There are no constraints on the code you can place
+in the <code>init()</code> method of the servlet.
+
+
<h2> Nested Diagnostic Contexts</h2>
@@ -1000,7 +1125,7 @@
appender inheritance, JSR47 doesn't. In log4j categories can be
initialized in any order, in JSR47 parents must be initialized before
children. See also the <a
-href="http://www.qos.ch/ac2001/F11-200.html";>slide</a> fromn my <a
+href="http://www.qos.ch/ac2001/F11-200.html";>slides</a> from my <a
href="http://apachecon.com/2001/US/";>ApacheCon 2001</a> presentation
on precisely this subject.
1.10 +1 -1 jakarta-log4j/src/java/org/apache/log4j/helpers/Loader.java
Index: Loader.java
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/java/org/apache/log4j/helpers/Loader.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- Loader.java 2001/06/06 16:07:20 1.9
+++ Loader.java 2001/06/07 21:10:05 1.10
@@ -28,7 +28,7 @@
<ol>
- <p><li>Search for <code>resource</code> with same the class
+ <p><li>Search for <code>resource</code> using the same class
loader that loaded <code>clazz</code>.
<p><li>Try one last time with
1.25 +1 -1 jakarta-log4j/src/xdocs/download.xml
Index: download.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/xdocs/download.xml,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- download.xml 2001/06/06 16:07:31 1.24
+++ download.xml 2001/06/07 21:10:09 1.25
@@ -31,7 +31,7 @@
</table>
-->
-
+
<section name="log4j version 1.1.2">
<p>Download version 1.1.2 including <i>full source code</i>, class files
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
