You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4j-cvs@jakarta.apache.org by ce...@apache.org on 2001/01/11 12:59:40 UTC
cvs commit: jakarta-log4j/xdocs documentation.xml
ceki 01/01/11 03:59:39
Modified: . INSTALL build.inc
doc earlier.html overview.html
xdocs documentation.xml
Added: doc FAQ.html HISTORY TROUBLESHOOT.html
Removed: . FAQ.html HISTORY TROUBLESHOOT.html
Log:
Preparing release 1.0.3. Moved some documenation files around so that they
can be browsed more consistently by the user.
Revision Changes Path
1.6 +3 -3 jakarta-log4j/INSTALL
Index: INSTALL
===================================================================
RCS file: /home/cvs/jakarta-log4j/INSTALL,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- INSTALL 2000/12/27 23:27:03 1.5
+++ INSTALL 2001/01/11 11:59:27 1.6
@@ -7,11 +7,11 @@
2) Assuming you chose to extract the distribution in to the
PATH_OF_YOUR_CHOICE, untarring the distribution file should create
- a log4j-vXX directory, where XX is the log4j version number, under
- PATH_OF_YOUR_CHOICE.
+ a jakarta-log4j-X.X directory, where X.X is the log4j version
+ number, under PATH_OF_YOUR_CHOICE.
-3) Add PATH_OF_YOUR_CHOICE\log4j-vXXX\classes to the CLASSPATH
+3) Add PATH_OF_YOUR_CHOICE\jakarta-log4j-X.X\classes to the CLASSPATH
variable.
4) You can now test your installation. To do this issue the command:
1.8 +1 -10 jakarta-log4j/build.inc
Index: build.inc
===================================================================
RCS file: /home/cvs/jakarta-log4j/build.inc,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- build.inc 2001/01/11 10:31:25 1.7
+++ build.inc 2001/01/11 11:59:28 1.8
@@ -75,7 +75,7 @@
<property name="classes" value="classes" />
<property name="stem" value="org/apache/log4j" />
<property name="build.compiler" value="jikes"/>
- <property name="version" value="1.0.2"/>
+ <property name="version" value="1.0.3"/>
</target>
@@ -200,15 +200,6 @@
<target name="javadoc" depends="init">
<mkdir dir="javadoc" />
-
- <copy file="doc/od.gif"
- tofile="javadoc/od.gif" />
-
- <copy file="doc/manual.html"
- tofile="javadoc/manual.html" />
-
- <copy file="doc/deepExtension.html"
- tofile="javadoc/deepExtension.html" />
<javadoc sourcepath="${srcdir}"
destdir="javadoc"
1.2 +138 -29 jakarta-log4j/doc/earlier.html
Index: earlier.html
===================================================================
RCS file: /home/cvs/jakarta-log4j/doc/earlier.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- earlier.html 2001/01/11 10:36:47 1.1
+++ earlier.html 2001/01/11 11:59:32 1.2
@@ -1,38 +1,147 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
-<html> <head>
-<title>Older distributions of log4j</title>
-</head>
+<!-- Content Stylesheet for Site -->
-<body bgcolor=white>
-<h1>Older distributions of the log4j package</h1>
-
-<hr>
-<b>BEWARE:</b> For some reason Internet Explorer decides to rename
+
+<!-- start the processing -->
+ <!-- ====================================================================== -->
+ <!-- Main Page Section -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+
+ <meta name="author" value="Ceki Gulcu">
+ <meta name="email" value="cgu@apache.org">
+
+ <title>Log4j project - log4j project</title>
+ </head>
+
+ <body bgcolor="#ffffff" text="#000000" link="#525D76">
+ <table border="0" width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align="left">
+<a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" border="0"/></a>
+</td>
+<td align="right">
+<a href="http://jakarta.apache.org/"><img src="images/logo.jpg" alt="The log4j Project" border="0"/></a>
+</td>
+ </tr>
+ </table>
+ <table border="0" width="100%" cellspacing="4">
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+
+ <tr>
+ <!-- LEFT SIDE NAVIGATION -->
+ <td valign="top" nowrap="true">
+ <strong>Log4j Project</strong>
+ <ul>
+ <li> <a href="./index.html">Introduciton</a>
+</li>
+ <li> <a href="./download.html">Download</a>
+</li>
+ <li> <a href="./documentation.html">Documentation</a>
+</li>
+ <li> <a href="./contactUs.html">Contact us</a>
+</li>
+ <li> <a href="./history.html">History</a>
+</li>
+ </ul>
+ <strong>Get Involved</strong>
+ <ul>
+ <li> <a href="http://jakarta.apache.org/site/getinvolved.html">Overview</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/site/cvsindex.html">CVS Repositories</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/site/mail.html">Mailing Lists</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/site/library.html">Reference Library</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/site/bugs.html">Bug Database</a>
+</li>
+ </ul>
+ <strong>Other Projects</strong>
+ <ul>
+ <li> <a href="http://jakarta.apache.org/ant/index.html">Ant</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/oro/index.html">ORO</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/regexp/index.html">Regexp</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/slide/index.html">Slide</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/struts/index.html">Struts</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/taglibs/index.html">Taglibs</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/tomcat/index.html">Tomcat</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/velocity/index.html">Velocity</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/watchdog/index.html">Watchdog</a>
+</li>
+ </ul>
+ <strong>Misc</strong>
+ <ul>
+ <li> <a href="http://jakarta.apache.org/site/whoweare.html">Who We Are</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/site/acknowledgements.html">Acknowledgements</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/site/contact.html">Contact</a>
+</li>
+ <li> <a href="http://jakarta.apache.org/site/legal.html">Legal</a>
+</li>
+ </ul>
+ </td>
+ <td align="left" valign="top">
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <strong>Older distributions of the log4j package</strong>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <hr />
+ <p><b>BEWARE:</b> For some reason Internet Explorer decides to rename
".tgz" files as ".tar". You should rename the files back to tgz after
-the download completes.
-<hr>
+the download completes.</p>
+ <hr />
+ <dl>
+ <dt><b>jakarta-log4j-1.0.2</b></dt>
+ <dd>
+ Download full package in <a href="jakarta-log4j-1.0.2.tgz">TGZ</a> format.
+ </dd>
+
+</dl>
+ </blockquote>
+ </td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <div align="center"><font color="{#525D76" size="-1"><em>
+ Copyright © 1999-2000, Apache Software Foundation
+ </em></font></div>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+<!-- end the processing -->
-<dl
- <dt><b>log4j-v0.9.0</b>
- <dd>Download full package in <a href=log4j-v0.9.0.tgz>TGZ</a> format
- <dt><b>log4j-v0.8.5b</b>
- <dd>Download full package in <a href=log4j-v0.8.5b.tgz>TGZ</a> format
- <dt><b>log4j-v0.8.4d</b>
- <dd>Download full package in <a href=log4j-v0.8.4d.tgz>TGZ</a> format
-
- <dt><b>log4j-v0.8.3b</b>
- <dd>Download full package in <a href=log4j-v0.8.3b.tgz>TGZ</a> format
-
-</dl>
+
+
+
+
-<hr>
-<address></address>
-<!-- hhmts start -->
-Last modified: Tue May 2 18:28:08 MDT 2000
-<!-- hhmts end -->
-</body> </html>
1.2 +2 -2 jakarta-log4j/doc/overview.html
Index: overview.html
===================================================================
RCS file: /home/cvs/jakarta-log4j/doc/overview.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- overview.html 2000/12/14 10:17:46 1.1
+++ overview.html 2001/01/11 11:59:32 1.2
@@ -5,7 +5,7 @@
</head>
<body>
-<p>Make sure to read the <a href="manual.html"><b>user manual</b></a>
-in addition to this javadoc documentation.
+<p>Make sure to read the <a href="../doc/manual.html"><b>user
+manual</b></a> in addition to this javadoc documentation.
</body> </html>
1.1 jakarta-log4j/doc/FAQ.html
Index: FAQ.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>log4j FAQ</title>
</head>
<body bgcolor=#FFFFFF>
<h1 align=center>Frequently Asked Questions about log4j</h1>
<h2 align=center>Ceki Gülcü
<br>October 2000</h2>
<ul>
<li><p><a href=#whatIs>What is log4j?</a> <br>
<li><p><a href=#reliable>Is log4j a reliable logging system?</a>
<li><p><a href=#prerequisites>What are the prerequisites for log4j?</a>
<li><p><a href=#javadoc>Is there javadoc documentation for log4j?</a>
<li><p><a href=#alternatives>What other logging packages are there?</a>
<li><p><a HREF=#usageExample>Is there example code for using log4j?</a>
<li><p><a href=#features>What are the features of log4j?</a>
<li><p><a href=#sample>What does log output look like?</a>
<li><p><a href=#category>What are <em>Categories</em>?</a>
<li><p><a href=#behavior>How can I change log behavior at runtime?</a>
<li><p><a HREF=#reduce>How can I reduce the computational cost of
debug and info statements?</a>
<li><p><a HREF=#fastLogging>What is the fastest way of (not) logging?</a>
<li><p><a HREF=#arrayDebug>What is the use of the <code>debug</code> method
expecting a <code>String</code> array as one of its parameters?</a>
<li><p><a href=#introCat>Why was the Category class introduced and how do
I migrate from the previous String based implementation?</a>
<li><p><a href=#namingCategories>Are there any suggested ways for naming
categories?</a></br>
<li><p><a href=#className>How do I get the fully-qualified name of a class in
a static block?</a>
<li><p><a href=#customLayouts>Can the log output format be
customized?</a>
<li><p><a href=#NDC>Can the outputs of multiple client request go to
different log files?</a>
<li><p><a href=#rm>Category instances seem to be create only. Why isn't
there a method to remove category instances?</a>
<li><p><a href=#filterByPriority>Is it possible to direct log output
to different appenders by priority?</a>
<li><p><a href=#tax>Why should I donate my log4j extensions back to the
project?</a>
<li><p><a href=#help>What should I keep in mind when contributing code?</a>
<li><p><a href=#bugCorrection>How fast do bugs in log4j get fixed?</a>
<li><p><a href=#history>What is the history of log4j?</a>
<li><p><a href=#bugs>How do I report bugs?</a>
<li><p><a href=#download>Where can I find the latest distribution of log4j?</a>
</ul>
<hr>
<p><a name=whatIs><h4 id="whatIs">What is log4j?</h4>
log4j is a tool to help the programmer output log statements to a
variety of output targets.
<p>In case of problems with an application, it is helpful to enable
logging so that the problem can be located. With log4j it is possible
to enable logging at runtime without modifying the application binary.
The log4j package is designed so that log statements can remain in
<i>shipped</i> code without incurring a high performance cost. It
follows that the speed of logging (or rather not logging) is capital.
<p>At the same time, log output can be so voluminous that it quickly
becomes overwhelming. One of the distinctive features of log4j is the
notion of <i>hierarchical categories</i>. Using categories it is
possible to selectively control which log statements are output at
arbitrary granularity.
<p>log4j is designed with two distinct goals in mind: speed and
flexibility. There is a tight balance between these two
requirements. I believe that log4j strikes the right balance.
<a name=reliable><h4>Is log4j a reliable logging system?</h4>
No. log4j is not reliable. It is a best-effort and <em>fail-stop</em>
logging system.
<p>By fail-stop, we mean that log4j will not throw unexpected
exceptions at run-time potentially causing your application to
crash. <b>If for any reason, log4j throws an uncaught exception,
please contact the <a href="mailto:cgu@urbanet.ch">current
maintainer</a>.</b> Uncaught exceptions are handled as serious bugs
requiring immediate attention.
<p>Moreover, log4j will not revert to System.out or System.err
when its designated output stream is not opened, is not writable or
becomes full. This avoids corrupting an otherwise working program by
flooding the user's terminal because logging fails. However, log4j
will output a single message to System.err indicating that logging can
not be performed.
<a name=prerequisites><h4>What are the prerequisites for log4j?</h4>
<ul>
<p><li>Log4j is JDK 1.1.x compatible.
<p><li>The DOMConfigurator is based on the DOM Level 1 API. The
DOMConfigurator.configure(Element) method will work with any
XML parser that will pass it a DOM tree.
<p>The DOMConfigurator.configure(String filename) method and its
variants require a JAXP compatible XML parser, for example <a
href="http://xml.apache.org/">Xerces</a> or Sun's
parser. Ccompiling the DOMConfigurator requires the presence of a
JAXP parser in the classpath.
<p><li>The <code>org.apache.log4j.net.SMTPAppender</code> relies on
the <a href="http://java.sun.com/products/javamail/">JavaMail
API</a>. It has been tested with JavaMail API version 1.2. The
JavaMail API requires the <a
href="http://java.sun.com/beans/glasgow/jaf.html">JavaBeans
Activation Framework</a> package.
<p><li>The <code>org.apache.log4j.net.JMSAppender</code> requries the
presence of the JMS API as well as JNDI.
<p><li>The <code>org.apache.log4j.gui.TextPaneAppender</code> requries Swing.
<p><li>log4j test code relies on the <a
href="http://www.junit.org">JUnit</a> testing framework.
</ul>
<a name=javadoc><h4>Is there javadoc documentation for log4j?</h4>
The javadoc <a href=javadoc/index.html>documentation</a> is part of
the log4j package. There is also an <b><a
href="javadoc/manual.html">introductory manual</a></b>. In case
problems make sure to have a look at <a href="TROUBLESHOOT.html">log4j
troubleshooting</a> document.
<a name=alternatives><h4>What other logging packages are there?</h4>
There are many other logging packages out there. I know of <a
href=http://www.homestead.com/JavaLog/>Grace Software's JavaLog</a>,
<a href=http://www.sw-zoo.org/>Software ZOO's toolkit</a>, <a
href=http://www.eli.sdsu.edu/java-SDSU/>SDSU logging package</a> and
many others.
<p>Many users confuse <a
href=http://www.alphaworks.ibm.com/tech/loggingtoolkit4j>JLog</a> with
log4j. The two packages originated at different parts of IBM. JLog was
developed at IBM Tivoli whereas log4j was independently developed at
the IBM Research Laboratory. Both packages are listed on IBM's
alphaWorks, although, as of April 2000, log4j moved to <a
href="http://www.log4j.org">greener pastures</a>.
<p>Please note that log4j is not an IBM controlled nor IBM sponsored
project.
<a name=usageExample><h4>Is there example code for using log4j?</h4>
<p>There is a directory containing examples in
<code>org/log4j/examples</code>. See also
<code>org/log4j/xml/examples</code>.
<a name=features><h4 id="">What are the features of log4j?</h4>
<ul>
<p><li>log4j is optimized for speed.
<p><li>log4j is based on a named category hierarchy.
<p><li>log4j is fail-stop but not reliable.
<p><li>log4j is not restricted to a predefined set of facilities.
<p><li>Logging behavior can be set at runtime using a configuration
file. Configuration files can be property files or in XML format.
<p><li>log4j is designed to handle Java Exceptions from the start.
<p><li>log4j can direct its output to a file, the console, an
<code>java.io.OutputStream</code>, <code>java.io.Writer</code>,
a remote server using TCP, a remote Unix Syslog daemon, to a
remote listener using JMS, to the NT EventLog or even send e-mail.
<p><li>log4j uses 5 priority levels, namely DEBUG, INFO, WARN, ERROR
and FATAL.
<p><li>The format of the log output can be easily changed by
extending the Layout class.
<p><li>The target of the log output as well as the writing strategy
can be altered by implementations of the Appender interface.
<p><li>log4j supports multiple output appenders per category.
<p><li>log4j supports internationalization.
</ul>
<a name=sample><h4 id="">What does log output look like?</h4>
The log output can be customized in many ways. Moreover, one can completely
override the output format by implementing one's own Layout.
<p>Here is an example output using <em>PattenLayout</em> with
the conversion pattern <b>"%r [%t] %-5p %c{2} %x - %m%n"</b>
<pre>
176 [main] INFO examples.Sort - Populating an array of 2 elements in reverse order.
225 [main] INFO examples.SortAlgo - Entered the sort method.
262 [main] DEBUG SortAlgo.OUTER i=1 - Outer loop.
276 [main] DEBUG SortAlgo.SWAP i=1 j=0 - Swapping intArray[0] = 1 and intArray[1] = 0
290 [main] DEBUG SortAlgo.OUTER i=0 - Outer loop.
304 [main] INFO SortAlgo.DUMP - Dump of interger array:
317 [main] INFO SortAlgo.DUMP - Element [0] = 0
331 [main] INFO SortAlgo.DUMP - Element [1] = 1
343 [main] INFO examples.Sort - The next log statement should be an error message.
346 [main] ERROR SortAlgo.DUMP - Tried to dump an uninitialized array.
at org.log4j.examples.SortAlgo.dump(SortAlgo.java:58)
at org.log4j.examples.Sort.main(Sort.java:64)
467 [main] INFO examples.Sort - Exiting main method.
</pre>
<p>The first field is the number of milliseconds elapsed since the
start of the program. The second field is the thread outputting the
log statement. The third field is the priority of the log
statement. The fourth field is the rightmost two components of the
category making the log request. The fifth field (just before the '-')
is the <em>nested diagnostic context</em> (NDC). Note the nested diagnostic
context may be empty as in the first two statements. The text after
the '-' is the message of the statement.
<a name=category><h4 id="">What are <em>Categories</em>?</h4>
The notion of categories lies at the heart of log4j. Categories define
a hierarchy and give the programmer <em>run-time</em> control on which
statements are printed or not.
<p>Categories are assigned priorities. A log statement is printed
depending on its priority <em>and</em> its category.
<p>Make sure to read the <a href=javadoc/manual.html>log4j manual</a>
for more information.
<a name=behavior><h4 id="">How can I change log behavior at runtime?</h4>
<p>Log behavior can be set using configuration files which are parsed
at runtime. Using configuration files the programmer can define
categories and set their priorities.
<p>The <code>PropertiesConfigurator</code> defines a particular format
of a configuration file. See also the
<code>org.log4j.examples.Sort</code> example and associated
configuration files.
<p>Configuration files can be specified in XML. See
<code>log4j.dtd</code> and
<code>org.log4j.xml.DOMConfigurator</code> for more details.
<p>See the various Layout and Appender components for specific
configuration options.
<p>In addition to configuration files, the user may disable all
messages belonging to a set of priorities. See next item.
<a name=reduce><h4 id="">How can I reduce the computational cost of
debug and info statements?</h4>
<p>For public releases of your code, calling the
<codeI>BasicConfigurator.disable(pri)</code> method will disable
all messages of priority <code>pri</code> and below.
<p>In cases of problems with an application, technical support can
re-enable logging by setting the <b>log4j.disableOverride</b> system
property without changing the binary at the client's site.
<a name=fastLogging><h4>What is the fastest way of (not) logging?</h4>
<p> For some category <code>cat</code>, writing, <pre>
cat.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
</pre>
<p>incurs the cost of constructing the message parameter, that is
converting both integer <code>i</code> and <code>entry[i]</code> to a
String, and concatenating intermediate strings. This, regardless of
whether the message will be logged or not.
<p>If you are worried about speed, then write
<pre>
if(cat.isDebugEnabled()) {
cat.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
}
</pre>
<p>This way you will not incur the cost of parameter construction if
debugging is disabled for category <code>CAT</code>. On the other
hand, if the category is debug enabled, you will incur the cost of
evaluating whether the category is enabled or not, twice: once in
<code>debugEnabled</code> and once in <code>debug</code>. This is an
insignificant overhead since evaluating a category takes less than 1%
of the time it takes to actually log a statement.
<a name=arrayDebug><h4 id="">What is the use of the <code>debug</code>
method expecting a <code>String</code> array as one of its parameters?</h4>
This method no longer exists. Use the
<code>Category.isDebugEnabled</code> method instead.
<a name=introCat><h4>Why was the Category class introduced and how do
I migrate from the previous String based implementation?</h4>
<p>The reason was speed, speed, speed.
<p>In the former implementation, when evaluating whether a category
should be logged or not, we potentially computed a hash and performed
an equality check multiple times, once for each higher ranking
category. For example, if the category name was "x.y.z", we computed
the hash of "x.y.z" and checked if it was already defined (costing an
equality check). If not, we parsed "x.y.z" to discover that "x.y" was
higher ranking, then computed the hash of "x.y" and checked whether it
was defined (costing another equality check). So on, until a valid
category was found or there were no possible categories left.
<p>It turns out that for long strings, hash computations and an
equality checks are computationally expensive operations.
<p>The new Category class retains the flexibility of the former
implementation and offers much much better performance. I would go as
far as to claim that the performance cannot be improved upon without
loosing functionality. <em>Please do not hesitate to debunk this
assertion</em>. Contributions from <a
href="mailto:Alex.Blewitt@ioshq.com">Alex Blewitt</a>, F. Hoering and
M. Oestreicher were instrumental to these performance improvements.
<p>The new syntax for defining a category is
<pre>
Category cat = Category.getInstance("x.y.z");
cat.setPriority(Priority.DEBUG);
</pre>
<p>Previously, to achieve a similar effect, one had to write
<pre>
log.setCategory("x.y.z", "DEBUG"); // where log is an instance of Log
</pre>
<p>As of release 0.8.0, the syntax was further modified so
that log statements (debug, info, ... methods) no longer need a log
singleton but use a Category instance instead.
<p>For some class <code>X</code> one previously wrote,
<pre>
package a.b.c;
class X {
static String cat = "a.b.c.X";
void foo() {
log.debug(cat, "Some foo message").
...
}
}
</pre>
This code needs to be modified as follows
<pre>
package a.b.c;
import org.log4j.Category;
class X {
static Category cat = Category.getInstance("a.b.c.X");
void foo() {
cat.debug("Some foo message").
...
}
}
</pre>
<a name=namingCategories><h4>Are there any suggested ways for naming
categories?</a></h4>
<p>Yes, there are.
<p>You can name categories by <strong>locality</strong>. It turns out
that instantiating a category in each class, with the category name
equal to the fully-qualified name of the class, is a useful and
straightforward approach of defining categories. This approach has
many benefits:
<ul>
<li>It is very simple to implenent.
<li>It is very simple to explain to new developpers.
<li>It automatically mirrors your application's own modular design.
<li>It can be further refined at will.
<li>Printing the category automatically gives information on the locality
of the log statement.
</ul>
<p>However, this is not the only way for naming categories. A common
alternative is to name categories by <strong>functional
areas</strong>. For example, the "database" category, "RMI" category,
"security" category, or the "XML" category.
<p>You may choose to name categories by functionality and
sub-categorize by locatily, as in "DATABASE.com.ibm.some.package.someClass" or
"DATABASE.com.ibm.some.other.package.someOtherClass".
<p><em>You are totally free in choosing the names of your
categories.</em> The log4j package merely allows you to manage your
names in a hierarchy. However, it is your responsibility to define
this hierarchy.
<p>Note by naming categories by locality one tends to name things by
functionality, since in most cases the locatility relates closely to
functionality.
<a name=className><h4>How do I get the fully-qualified name of a class
in a static block?</a></h4>
<p>You can easily retrieve the fully-qualified name of a class in a
static block for class X, with the statement
<code>X.class.getName()</code>. Note that <code>X</code> is the class
name and not an instance. The <code>X.class</code> statement does
<i>not</i> create a new instance of class <code>X</code>.
<p>Here is the suggested usage template:
<font color=BLUE><pre>
package a.b.c;
public class Foo {
static Category cat = Category.getInstance(Foo.class.getName());
... other code
}
</pre></font>
<a name=customLayouts><h4>Can the log output format be customized?</h4>
<p>Yes. Since release 0.7.0, you can extend the <code>Layout</code>
class to create you own customized log format. Appenders can be
parameterized to use the layout of your choice.
<a name=NDC><h4>Can the outputs of multiple client request go to
different log files?</h4>
Many developers are confronted with the problem of distinguishing the
log output originating from the same class but different client
requests. They come up with ingenous mechanisms to fan out the log
output to different files. In most cases, this is not the right
approach.
<p>It is simpler to use a nested diagnostic context (NDC). Typically,
one would <em>NDC.push()</em> client specific information, such as the
client's hostname, ID or any other distinguishing information when
starting to handle the client's request. Thereafter, log output will
automagically include the nested diagnostic context so that you can
distinguish logs from different client requests even if they are
output to the same file.
<p>See the <code>NDC</code> and the <code>PatternLayout</code> classes
for more information. The <code>NumberCruncher</code> example shows
how the NDC can be used to distinguish the log output from multiple
clients even if they share the same log file.
<p>For select applications, such as virtual hosting web-servers, the
NDC solution is not sufficient. As of version 0.9.0, log4j supports
multiple hierarchy trees. Thus, it is possible to log to different
targets from the same category depending on the current context.
<p><a name=rm><h4>Category instances seem to be create only. Why isn't
there a method to remove category instances?</h4>
It is quite non-trivial to define the semantics of a "removed"
category which is still referenced by the user.
<p>Future releases <em>may</em> include a remove method in the
Category class.
<a name=filterByPriority><h4>Is it possible to direct log output to
different appenders by priority?</h4>
<p>Yes it is. Setting the <b>Threshold</b> option of any appender
extending <a
href="javadoc/org/log4j/AppenderSkeleton.html">AppenderSkeleton</a>,
(most log4j appenders extend AppenderSkeleton) to filter out all log
events with <em>lower</em> priority than the value of the threshold
option.
<p>For example, setting the threshold of an appender to DEBUG also
allow INFO, WARN, ERROR and FATAL messages to log along with DEBUG
messages. (DEBUG is the lowest priority). This is usually acceptable
as there is little use for DEBUG messages without the surrounding
INFO, WARN, ERROR and FATAL messages. Similarly, setting the threshold
of an appender to ERROR will filter out DEBUG, INFO and ERROR messages
but not FATAL messages.
<p>This policy usually best encapsulates what the user actually wants
to do, as opposed to her mind-projected solution.
<p>See <a
href="javadoc/org/apache/log4j/examples/doc-files/sort4.lcf">sort4.lcf</a>
for an example threshold configuration.
<p>If you must filter events by exact priority match, then you can
attach a <a
href="javadoc/org/apache/log4j/varia/PriorityMatchFilter.html">PriorityMatchFilter</a>
to any appender to filter out logging events by exact priority match.
<a name=tax><h4>Why should I donate my extensions to log4j back to the
project?</h4>
Contrary to the GNU Public License (GPL) the Apache Public License
does not make any claims over your extensions. <em>You are free to do
whatever you wish with your proprietary log4j extensions.</em> In
particlular, you may choose to never release your extensions to the
wider public.
<p>We are very careful not to change the log4j client API so that
newer log4j releases are backward compatible with previous
versions. We are a lot less scrupulous with the internal log4j
API. Thus, if your extension is designed to work with log4j version
<code>n</code>, then when log4j release version <code>n+1</code> comes
out, you will probably need to adapt your proprietary extensions to
the new release.
Thus, you will be forced to spend precious resources in order to keep
up with log4j changes. This is commonly referred to as the
"stupid-tax." By donating the code and making it part of the standard
distribution, you save yourself the unncessary maintanance work.
<p>If your extensions are useful then someone will eventually write an
extension providing the same or very similar functionality. Your
developement effort will be wasted.
<p>Unless the proprietary log4j extension is business critical, there
is little reason for not donating your extensions back to the project.
<a name=help><h4>What should I keep in mind when contributing
code?</h4>
<ol>
<li>Stick to the existing indentation style even if you hate it.
<p>Alternating between indentation styles makes it hard to
understand the source code. Make it hard on yourself but easier
on others. Log4j follows the <a
href=http://java.sun.com/docs/codeconv/>Code Conventions for
the JavaTM Programming Language</a>.
<p><li>Make every effort to stick to the JDK 1.1 API.
<p>One of the important advantages of log4j is its compatibility with
JDK 1.1.x.
<p><li><b>Throughly test your code.</b>
<p>There is nothing more irritating than finding the bugs
in debugging (i.e. logging) code.
<p><li>Keep it simple, small and fast.
<p>It's all about the application not about logging.
<p><li>Identify yourself as the contributor at the top of the
relevant file.
<p><li>Take responsibility for your code.
<p>Authoring software is like parenting. It takes many
years to raise a child.
<p><li>Did I mention sticking with the indentation style?
</ol>
<a name=bugCorrection><h4>How fast do bugs in log4j get fixed?</h4>
<p>Rather than wait for the next release to be ready, we get bug fixes
out of the door as soon as possible. Moreover, once a bug is found or
reported, it is treated as <em>fire in the house</em>. All other
activites stop until the bug is fixed.
<p>Consequently, confirmed bugs are fixed after a short period
following the initial bug report.
<a name=history><h4>What is the history of log4j?</h4>
The first ancestor of log4j was written for the <a
href="http://www.semper.org">SEMPER</a> project. Jose-Luis Abad-Peiro
wrote the initial 30 liner version that was picked up by Ceki
Gülcü and enhanced by Andreas Fleuti. Michael Steiner,
N. Asokan, Ceki Gülcü proposed category/priority based
evaluation which has remained conceptually the same since 1996.
<a name=bugs><h4 id="bugs">How do I report bugs?</h4>
Report bugs using the <a
href=http://nagoya.apache.org/bugzilla>Apache Bug Database</a>.
<p>Please specify the version of log4j you are using. It is helpful to
include log configurations files if any, plus source code. A short
example reproducing the problem is very much appreciated.
<a name=download><h4>Where can I find the latest distribution of log4j?</h4>
<p>The log4j project is hosted at <a
href="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j/</a>.
<p>
<hr>
</body> </html>
1.1 jakarta-log4j/doc/HISTORY
Index: HISTORY
===================================================================
[*] Changes that are 100% compatible with existing client code.
[**] Changes that requiring little or no modification to existing
client code.
[***] Changes requiring important modifications to existing client code.
January 11th, 2001
- Release of version 1.0.2 (the 20th major release)
- Added the missing build.inc file to the distribution. No code
changed.
January 10th, 2001
- Release of version 1.0.1 (the 20th major release)
- This version corrects some documentation and build script bugs;
code has not changed.
January 8th, 2001
- Release of version 1.0 (the 20th major release)
- Package hierarchy now starts at org.apache.log4j. [***]
- Added the fatal() family of methods to the Category
class. Moreoever, the EMERG priority has been removed from the
Priority class. This priority has been replaced by the FATAL
priority that is more widely accepted. This change will
require EMERG log statements to be replaced by FATAL log
statements. Assuming EMERG log statements are rare, this should
have a small but bearable impact on existing client code.
Moreover, the Unix Syslog priorities ALERT, CRIT and NOTICE are no
longer recognized. Support for these priorities was mininal and
few users should suffer from these changes. [**]
- Removed the methods setRootPriority, getRootPriority as these
methods were redundant and had been previously deprecated. [**]
- Removed the DOM Level 2 dependency in DOMConfigurator. This makes
log4j XML configurable using Sun's parser or Apache's Xerces. [*]
- The static initializer of the Category class now takes the
log4j.configuration system property to search for its configuration
file. The type of the configurator used to parse the configuration
file depends on the value of the log4j.configuration system
property. [*]
- Enhanced the PropertyConfigurator and DOMConfigurator to support
customization of independent Hierarchy instances. The
org.apache.log4j.net.SocketServer has been enhanced to take
advantage of this functionality. The old code of SocketServer has
been moved to SimpleSocketServer. [**]
- Enhanced the PropertyConfigurator to support variable substitution
for all options *values* (but not keys!). [*]
- Categories are now aware of the Hierarchy they are linked to. This
will provide a basis for several performance enhancements planned
for the future. [*]
- Added support for object rendering. It is now possible to register
an object renderer for a given object type. When the given object
needs to be logged log4j will invoke the corresponding renderer to
transform the object into a String.
As a result of this enhancement, all the String forms of all the
printing methods such as debug(String), info(String) have been
removed as they are no longer necessary. This change should be
perfectly backward compatible. [*]
- Added support for user defined category factories in the
PropertyConfigurator. Thus, it is now possible to configure log4j
with a properties file and still use custem Category
sub-classes. The DOMConfigurator had already a finer grain
support. [*]
- Addeed the SMTPAppender that in case of an error or fatal event
sends an e-mail containing latest N logging events in its buffer,
where N is chosen by the user. [*]
- Added the method getInstance(Class) to the Category class. [*]
- Corrected a bug in configureAndWatch method of configurators that
would confgure log4j only after an unnecessary delay. [*]
November 30, 2000
- Release of version 0.9.1 (the 19th public release)
- Corrected a typo making NTEventLogAppender.dll register the wrong
category message file. Thanks to Peter Hayes for accurately
reporting this bug. [*]
- The DOMConfigurator and PropertyConfigurator can now automatically
detect modified configuration files and re-read them. [*]
- Added AsyncAppender which buffers log requests and serves them
at a later time. AsyncAppender can increase logging performance
tremendously if logging operations are interspersed with long
and blocking non CPU-intensive operations, typically I/O or network
access. For CPU intensive applications, using the AsyncAppender
will actualy degrade logging performance by 10 to 25 percent. [*]
- The log4j.dtd has been modified to allow appenders to refer to
other appenders by IDREF. [*]
- The DOMConfigurator has been modified to take advantage of ID/IDREF
attributes when referring to appenders. This change requires a
DOM Level-2 API compliant parser. DOM Level-2 java bindings are
available at
http://www.w3.org/TR/1999/WD-DOM-Level-2-19990923/java-binding.html.
- Added the configure(String filename) method to DOMConfigurator.
This method requires the presence of a JAXP compatible parser.
At this time, the only DOM2 and JAXP compatible parser seems to be
the Apache xerces parser.
- Added the PriorityMatchFilter allowing filtering by exact priority
match. This was a common request by users. [*]
- The configuration of a category is now an atomic operation. This
ensures that log requests are not lost while configuration is in
progress. Anders Kristensen was to first to observe the potential
problems in non-atomic configurations. [*]
November 20th, 2000
- Release of version 0.9.0 (the 18th public release)
- The "log4j" element has been renamed to "configuration" in the
log4j DTD. This change requires that log4j configuration files
written in XML be modified. Since the log4j element figures only
once in the XML file, this change should take little time. [**]
- ResourceBundles are now category instance specific and no longer
class static. Moreover, like other properties resource bundles
are inherited from the category hierarchy. [**]
- The jar files log4j.jar and log4j-full.jar now contain versioning
information in their respective manifest files. [*]
- Corrected an inconsistecy in the NTEventLogAppender which broke it.
- Fixed a bug where configuration files were not parsed correctely
due to trailing spaces in option values as returned by
java.util.Properties. Trailing spaces are now removed from option
values. This bug was quite disconcerting because the
trailing spaces cannot be seen without careful examination of the
configuration file. [*]
- Added the XMLLayout.
The output of the XMLLayout consists of a series of log4j:event
elements. It does not output a complete XML file. The output is designed to
be included as an external entity to form a well-formed XML file. [*]
- Added a new abstract class org.log4j.helpers.DateLayout. The TTCCLayout
now extends DateLayout. [*]
- Corrected a rather subtle performance bug in the buffer management code
in PatternLayout. Thanks to Vladislav Dutov and Constantine
A. Plotnikov for for insisting on the correction of this bug. [*]
- Created a new package called org.log4j.spi. This new package
holds classes that are hidden from the casual user but are needed
to extend log4j. [*]
- Added org.log4j.varia.ExternallyRolledFileAppender to handle
externally triggered file rollovers. [*]
- Added support for multiple hierarchy trees. [*]
- PatternLayout can now be subclassed to support new conversion
patterns. [*]
- Extended the DOMConfigurator and the log4j DTD to properly handle
sub-classing of Category and Priority classes.
There have been also minor adjustments to other classes to handle
sub-classing. These changes should be invisible to users.
All categories except the root category can be sub-classed and also
assigned priorities sub-classing org.log4j.Priority.
The root category always exists and CANNOT be subclassed.
The ProppertyConfigurator remains unchanged. Thus, it does not
handle extensions of the Category class. [*]
- Added filter support in appenders. The DOMConfigurator and the
log4j.dtd have been enhanced to support filters. [*]
- Added error handling support to appenders. The DOMConfigurator and the
log4j.dtd have been enhanced to support filters. [*]
- Added support for correct interpretation of location information in
IBM's Visual Age environment. Thanks to Wolf Siberski for supplying
the relevant patch. [*]
- Added getAdditivity method to Category. This feature was requested
by Constantin Mitran. (mitran at ecircle.de) [*]
August 27, 2000
- Release of version 0.8.5b.
- Corrected multiple bugs in default initialization code of
Category class. Thanks to Jeff Turner for identifying and supplying
corrective patches. [*]
August 24, 2000
- Release of version 0.8.5a.
- Added the %n conversion character to PatternLayout so that a line
separator can be specified in a platform independent way. [*]
- In 0.8.5 internal Priority integer values were decoupled from the
Unix Syslog values. This broke SyslogAppedder. A new function
Priority.toSyslogInt is introduced to solve this bug. [*]
Corrected a bug where the internal prtar tzvf iority integer
August 23, 2000
- Release of version 0.8.5.
- All log4j internal output is now prepended with the string
"log4j: ". This makes is easier to differentiate log4j internal
logs from messages output by other sources. [*]
- Sub-classes of Category class must now specify their fully
qualified name when constructing logging events. This allows the %C
conversion specifier in PatternLayout to work properly even with
sub-classes or wrappers of Category. [*]
- Added the method disableDebug to BasicConfigurator. This method
disables all print requests of debug priority regardless its
category. Similar methods disableInfo, disable, disableAll and
enableAll have also been added. Disable type methods can be
overriden by setting the log4j.disableOverride system property.
Calling BasicConfigurator.disableInfo is equivalent to the now
deprecated flagAsShippedCode method. [*]
- Given the above changes, the system property
log4j.shippedCodeFlagOverride is no longer honored. [**]
- It is now possible to sub-class Category. The sub-classes may
continue to adhere to the category hierarchy. This was a frequently
requested feature. [*]
- Corrected a problem with the additivity flag being ignored in
categories without appenders. This bug was discovered by Anders
Kristensen. [*]
- Added a method BasicConfigurator.resetConfiguration to reset the
log4j environment. This method should be used sparingly. [*]
- At the initialization of the Category class, the file
log4j.properties will now be searched from the search path used to
load classes. If the file can be found, then it is fed to the
PropertyConfigurator.configure(java.net.URL) method. [*]
- Failing to access system properties within the static initializer
of BasicConfigurator class is no longer reported as an error but as
a debug message. Thanks to Gilles Schlienger for reporting this
problem with applets. [*]
- Corrected a bug which caused infinite loops when using conversion
patterns with a single element, fortunately under very rare
circumstances. This bug was first reported by Igor Potraev, the
author of log4p. It was independently reported by Joe Haberl from
IBM Global Services. [*]
- Added a mechanism to lazily remove references to dead threads in
the NDC class. Indeed, in previous versions calling NDC.pop within
a thread but forgetting to call to NDC.remove before exiting (that
thread) resulted in a memory leak. [*]
- Corrected a huge memory leak in SocketAppender. This leak was due
to the ObjectOutputStream indefinitely holding a reference for each
written to the stream. Thanks to Dan MacDonald for very accurately
describing this bug. [*]
- The log and l7dlog methods in Category no longer ignore the shipped
code flag. This bug was reported by Mario Schomburg. [*]
- Added missing NDC information to LoggingEvent.writeObject
method. [*]
- Corrected handling of SocketException in SocketNode. Thanks to
Gerald Gutierez (ggutierez@emobiledata.com) for reporting this and
the previous problem. [*]
- Phased out custom shell scripts to build java documentation and jar
files in favor of Jakarta's ANT. It was becoming a nuisance to keep
the ANT build file in sync with the custom shell scripts. [*]
May 11, 2000
- Release of version 0.8.4d.
- The NT EventViewer no longer complains about missing message 4096.
- Minor corrections in documentation.
- Added missing icons GIFs into the distribution.
- SocketNode now attempts to close the socket when exiting. Thanks to
Moses Hohman (mmhohman@rainbow.uchicago.edu) for noting this.
- Removed the com.ibm.log4j from the javadoc directory. This seems to
confuse VAJ. Thanks to Steve Ashcroft for reporting this problem.
May 5, 2000
- Release of version 0.8.4c.
- As a result of the infinite loop problem (see next item), added
over 800 new test cases to stress-test the code in CategoryFactory
class where category creation occurs. [*]
- Under certain rare circumstances the Category.getInstance method
entered an infinite loop. Thanks to Mario Schomburg from IBM Global
Services / Hannover for identifying this problem and proposing a
patch. [*]
- DOMConfigurator and the log4j.dtd were out of sync on the type of
the priority directive. As a result, priority directives all
defaulted to DEBUG. Thanks to Peter (petervt@users.sourceforge.net)
for accurately reporting this bug. [*]
- Minor additions to the FAQ. [*]
- Added the NumberCruncher example showing how the NDC class can be
used to distinguish output from different clients. [*]
- Added the %x conversion specifier to the TTCC_CONVERSION_PATTERN in
the PatternLayout class. This is consistent expected output of
Trivial.java example. Thanks to Jerome (schrom@users.sourceforge.net)
for reporting this bug. [*]
May 3, 2000
- Release of version 0.8.4b.
- The value of the additivity option would not be parsed properly by
the ProperytConfigurator if the line containing the option
contained trailing spaces. [*]
- Release of version 0.8.4a.
- The localized logging methods (l7dlog) omitted priority based
evaluation and erroneously logged all requests. [*]
May 1, 2000
- Release of version 0.8.4.
- The close method was added to the Appender interface allowing
appender implementations to release any resources they may have
allocated. [*]
- The package naming scheme of changed from "com.ibm.log4j.*" to
"org.log4j.*". The new naming reflects the open source nature of
the project and is consistent with the URL http://www.log4j.org. [***]
- Added internationalization support. See the newly introduced l7dlog
methods in Category class. [*]
- In the FileAppender, the File option now admits variable
substitution. For example, if "java.home" system property is set
to /home/xyz and the File option is given the value
"%{java.home}/test.log", then File option will be interpreted as
"/home/xyz/test.log".
Thanks to Avy Sharell (sharell@online.fr) for contributing this
feature. [*]
- SocketAppender is now officially part of the package. It is capable
of sending logging events to a remote SocketNode. The SocketNode
logs events according to server (local) policy. For example, a
client can log events to a local file and also send them to a
remote server (a SocketNode). This server can log the event to any
number of files, to the console, to any number of TextPaneAppenders
and even re-transmit the event to another server, and so forth.
This paradigm is common in most logging systems, e.g. Syslog and NT
Event Log. Many thanks to Andrew Harrison for showing a way to
actually implement the paradigm. [*]
- The Category.callAppenders method now accepts a LoggingEvent
instead of creating one itself. This was necessary to accommodate
events generated at a remote client. [*]
- LoggingEvent class changed slightly to support remote logging. The
category field (a Category) has been replaced by the categoryName
field (a String). [*]
April 14, 2000
Release of version 0.8.3b
- Corrected a bug in Category.removeAppender(String) which would
never remove the desired appender. Thanks to Moses Hohman for
reporting this bug.
Release of version 0.8.3a
- Corrected a bug RollingFileAppender which would throw an uncaught
exception in case output file could not be opened for
writing. Thanks to Vinay Aggarwal for signaling this problem.
April 13, 2000
- Release of version 0.8.3.
- The log4j.override key defined in BasicConfigurator has been
renamed to log4j.shippedCodeFlagOverride. [**]
- The getCurrentCategories method in the Category class would not
return the correct value. Thanks to Timothy Potter
(tpotter@agency.com) for reporting this problem. [*]
- Appenders now admit a priority threshold as an option. All requests
with a priority lower than the appender's threshold priority are
ignored by the appender. [*]
- Integrated Christopher Taylor's DOMConfigurator parsing XML
configuration files. [*]
- The jar file log4j-net.jar has been replaced by log4j-full.jar. It
contains DOMConfigurator.class in addition to the com.ibm.log4j.net
package. [**]
- Added support for the ANT build tool. Thanks to Christopher Taylor
for supplying the build.xml file. ANT is available form
http://jakarta.apache.org. [*]
- FileAppender's File option now accepts the values "System.out" or
"System.err". If one these values is suppiled in a configuration
file then the output is directed to the corresponding stream.
Moreover, the default constructor of FileAppender no longer sets
System.out as an output target nor does it define a default
layout. [*]
- Added caller class (C), caller file name (F), caller line number
(L), caller method name (M) conversion specifiers to the
PatternLayout class.
The category conversion specifier now takes an optional precision
modifier allowing the user to control the number of right most
components in the category name that will be printed.
Corrected a bug occuring when the caller file name and line number
information were unavilable due to JIT compilation. In that case,
the PatternLayout would not properly use the rest of the available
location information. [*]
The above enhancements and bug-fixes originate from comments by
Nelson Minar (nelson@monkey.org).
March 23, 2000
- Release of version 0.8.2.
- The SimpleLayout and TTCCLayout are replaced by the PatternLayout
in the log4j.jar file to keep its size small. These two layouts are
still part of the package.
- The PatternLayout class is introduced. This new layout is
configurable using a conversion pattern which is parsed at
runtime. This allows the user to choose the output layout without
writing any code and only at a marginal performance cost compared
to the dedicated layouts such as SimpleLayout and TTCCLayout. The
PatternLayout also allows the user to determine minimum and maximum
field lengths.
The PatternLayout was written by Jim Cakalic
(jim_cakalic@na.biomerieux.com). [*]
- All internal components now use LoggingEvent instances to specifiy
logging information.
- Corrected a problem with a missing variable initialization in
SyslogAppender. This caused NullPinterException to be thrown when
logging exceptions.
Added a default constructor to SyslogAppender. The lack of this
constructor caused PropertyConfigurator to throw a
java.lang.InstantiationException when the appender type was set to
be SyslogAppender.
Thanks to Yves Bossel (ybossel@opengets.cl) for accurately
identifying these bugs.
Modified some other related option handling code in
SyslogAppender. [*]
- Made NDC.get public access instead of default access. Thanks to
Y. J. Chun (monac@softonnet.com) for reporting this problem. [*]
- PropertyConfigurator now parses the additivity option for
categories. [*]
- Corrected the value of the ADDITIVITY_PREFIX constant to match the
documented value, that is "log4j.additivity". [**]
- Corrected a really bad bug where System.out would be closed when
PropertyConfigurator.configure was called. Thanks to Christopher
Taylor (cstaylor@pacbell.net) for tracking and reporting this bug. [*]
- The PropertyConfiguator now prints debug messages if the flag
"log4j.configDebug" is defined in the configuration
file. Previously, only if the system property "log4j.configDebug"
was set would debug messages be printed. A question by Shawn
Kircher (skircher@vninet.com) induced this change. [*]
- In AbsoluteTimeDateFormat, DateTimeDateFormat and ISO8601DateFormat
the separator between the seconds and milliseconds has been changed
to comma from full stop, in order to be compliant with ISO8601's
preferred sign. Thanks to Jim Cakalic
(jim_cakalic@na.biomerieux.com) for pointing out this discrepancy
with the standard. [*]
- Corrected a bug where RollingFileAppender would not work
properly on Windows systems. Thanks to Heinz Richter
(heinz.richter@ecmwf.int) for noting this problem.
February 19, 2000
- Release of version 0.8.1.
- Core classes are now independent of the format of the options
file. Configurable core classes implement the OptionHandler
interface. OptionHandlers allows configurators to learn the
relevant option names. The configurator feeds option values to the
OptionHandler which configures itself.
As a result of these changes, the Init class has been broken down
to two separate classes: the BasicConfigurator and the
PropertiesConfigurator. [**]
An XML configurator for 0.8.0 has been already written by
Christopher Taylor (cstaylor@pacbell.net).
- Added multiple appender support per category. The appenders follow
the category hierarchy, i.e. a child category inherits the
appenders of its parents.
- Added an assert() method to the Category class. Steven Marcus
(srnm@awaretechnologies.com) requested this addition. [*]
- Atomatic stack printing is no longer supported. This was an unused
and unreliable feature which unnecessarily complicated the
code. [*]
- log4j now emits a single warning message when no appender to write to
could be found. This is typically the case when the user forgets
to configure the log4j environment. This change was suggested by
Jim Cakalic (jim_cakalic@na.biomerieux.com). [*]
- RollingFileAppender adds file roll over capability--implemented by
Heinz Richter (heinz.richter@ecmwf.int). [*]
- Corrected a bug where a java.lang.NoClassDefFoundError would be
thrown because com.ibm.log4j.helpers.SyslogTracerPrintWriter was
not included in log4j.jar. Thanks to Jim Cakalic (jim_cakalic@na.biomerieux.com)
for signaling this bug. [*]
February 9, 2000
- Release of version 0.8.0.
- There has been an important API changes. The Log, NOPLog and ILog
classes have been removed. Their functionality has been migrated to
the Category class. [***]
In this release, instead of writing
ILog.debug(CAT, "Some message.");
one will write
CAT.debug("Some message.");
Arndt Schoenewald <ar...@ibm23093i821.mc.schoenewald.de> observed that
one could use the Category objects directly for logging.
- It is no longer possible to instantiate Category objects directly.
Instead, one would use the factory method
Category.getInstance(String name). [***]
There category instantiation code was moved to CateogryFactory
class. This class has package visibility and remains hidden from
the user.
This stylistic improvement was suggested by Luke Blanshard
(luke@quiq.com).
- The Init class offers methods to initialize the log4j
environment. The Init.flagAsShippedCode method replaces the NOPLog
class.
- Changes in the documentation to reflect the API changes.
- The NDC.cloneStack and inherit methods now tolerate null-stacks. [*]
January 29, 2000
- Release of version 0.7.5.
- TTCCLayout now takes a java.text.DateFormat object as a
parameter. The task of formatting the date is delegated to this
object.
Added four classes extending the java.text.DateFormat class. These
are RelativeTimeDateFormat, AbsoluteTimeDateFormat,
DateTimeDateFormat and ISO8601DateFormat classes.
Thanks to Arndt Schoenewald <ar...@ibm23093i821.mc.schoenewald.de>
for suggesting the ISO8601 date format.
These four classes can be parametrized with a particular
TimeZone. The TTCCLayout class now accepts a new configuration file
option called "TimeZone".
These four DateFormats are less malleable than the
java.text.SimpleDateFormat but they are also much faster.
As a consequence of these changes, the setRelativeTime,
setDatePrinting methods in TTCCLayout have been removed along with
the associated configuration file options RelativeTime,
DatePrinting and TimePrinting. [**]
The current code is inspired by code contributed by
Heinz Richter (heinz.richter@ecmwf.int).
- The Log.emerg method has been deprecated. If you use statements of
EMERG priority, please use the Log.log form instead. [**]
- Added getDepth and setMaxdepth methods to the NDC class. This makes
it easier to manage the nested context depth especially when
callees push but forget to pop.
- Moved the documentation in com/ibm/log4j/package.html to
com/ibm/log4j/overview.html. Many users were failing to read the
com/ibm/log4j/package.html description due to the unfortunate
layout of the text. Hopefully more people will read the package
overview in its present location.
- Added the com.ibm.log4j.net package for doing remote logging using
TCP sockets. This is still experimental code.
- Added new debug, .., emerg methods that do not require a category
parameter. They assume the "root" category, that is the decision to
whether print or not is made by comparing the statement's priority
with the default priority. [*]
January 21, 2000
- Release of version 0.7.4.
- Added a new ILog.init method accepting an Appender and a
configuration file as parameters.
- FileAppender's setWriter and setFile methods where not instantiating
a new tracer. This caused stack traces to be lost! SyslogAppender
had a similar problem. [*]
- The FileAppender and SyslogAppender where not calling the layout's
readConfig method to set layout specific options. Thanks to Heinz
Richter (heinz.richter@ecmwf.int) for reporting this bug. [*]
- Corrected a bug in Log.log() method where the appender was always
called with Priority.DEBUG. Thanks to Oliver Boehm
(Oliver.Boehm@abaxx.de) for reporting this bug. [*]
January 14, 2000
- Release of version 0.7.3.
- Added Syslog compatibility. One can now choose (at runtime) between
remote syslog logging or file logging. [*]
Syslog logging performance, although not appalling, is significantly
slower than file logging.
- Priority class was enriched with the previously missing priorities
NOTICE, ALERT and CRIT. The internal constants were also aligned with
the syslog counterparts. [*]
- Added the Log.log method to support the new priorities. [*]
- TracerPrintWriter is now an independent class instead of being a
nested top-level class in Tracer. [*]
- A number of writers, namely the SyslogWriter, SyslogQuietWriter,
SyslogTracerPrintWriter, were added to the helper package. [*]
- Log.force method was removed. The various Appender.doAppend
implementations take over its functionality. [*]
- FileAppender and SyslogAppender now use QuietWriter. QuietWriter is
a FilterWriter which hides exceptions and instead emits a single
warning message to System.err. [*]
- The layout is now an initialization parameter to the appender
type. Previously, the layout and the appender where independent
parameters to the Log constructor. [**]
- Many small improvements and corrections in the documentation.
Syslog related documentation remains sparse.
- ILog.init() and ILog.init(String configFile) have been changed to
call ILog.init(,,,) with "com.ibm.log4j.Log.class" as the first
parameter. This makes it easier for people to get familiar with log4j. [**]
- Added missing files to the make directory. These files are useful
for those wishing to use the log4j make environment. Thanks to "Lee
Hall" <LH...@JavaFoundry.com> for reporting this omission. [*]
Until recently the make environment failed to compile RMI stubs in
a single run. This nagging problem has been corrected thanks to
help from Thomas Eirich (IBM Zurich Research Lab).
January 4, 2000
- Release of version 0.7.2.
- Some users have been rightly complaining about the verbosity
TTCCLayout's date output. The full date output is now shortened to
"dd MMM YYYY HH:mm:ss.SSS" for example, "06 Nov 1994 08:49:37.459"
In addition, users may now choose to print only time information,
as in "08:49:37.459". [*]
- The package now uses Writer instead of OutputStream as its output
target. This makes the log4j code smaller and easier to
understand at the cost of a slight performance degradation. As a
result of this change a few method names in FileAppender class were
changed. [**]
- Preliminary experiments with SyslogAppedner and SyslogLayout show
that syslog compatibility is not far away. The difficultly is
adding syslog compatibility without making radical changes to the
current log4j architecture.
- Corrected a bug in the NOPLog.createInstance method which always
created a Log singleton even if the system property "log4j.logType"
was set to NOPLog. Thanks to Robert Gottofrey
(Robert.Gottofrey@wdr.com) for reporting this bug and the
associated test case.
- Removed the inconsistent "Layout" configuration option in
Log.readConfig(). This change should be transparent to most
users. [*/**]
December 20, 1999
- Release of version 0.7.1.
- The LogCreationManager class has been removed. Its functionality
has been transfered to the createInstance and getInstance methods
in the Log and NOPLog classes. The new way of creating instances is
both simpler and less error prone although just as flexible. [**]
As a result of these changes, the init family of methods in the
ILog class have been adjusted to the new way of creating the log
singleton.
- The Appender interface has been introduced. The method of writing a
log statement into an output stream can now be varied by using a
different Appender. The new FileAppender offers the same
functionality that was previously part of the Log class. [**]
- Changed the time format used in TTCCLayout to be of the form "Day,
dd MMM YYYY HH:mm:ss.SSS GMT" for example, "Sun, 06 Nov 1994
22:49:37.459 GMT". This format is almost the same as the format
specified in RFC 1123 and also the format recommended in RFC
2616. The only difference is the additional milliseconds
information. [*]
- The layout specific options were not read from the configuration
file due to a missing instruction. Many thanks to Vikram Sridharan
(Vikram.Sridharan@alysis.com) to patiently pointing out this
omission to an unbelieving maintainer. [*]
December 16, 1999
- Release of version 0.7.0.
- Version 0.7.0 and above will be distributed under the IBM Public
License (IPL). The IPL is an approved open source license (see
http://www.opensource.org/licenses/ for a list). It grants similar
rights to the previous ALPHAWORKS license agreement, in particular,
the right to redistribute and to modify the package.
- The Log class can now be parameterized with a Layout object.
Layouts determine the format of what is printed, where as the Log
class decides when to print and to where. [**]
As a result of this modularization, the CGULog and NOPCGULog
classes no longer exists. CGULog class has been replaced with the
TTCCLayout (Time Thread Context Category). This should make it
easier to create new log output formats.
Some time in the near future, the Log class will be further broken
down to allow different strategies for writing to output streams.
- Renamed com.ibm.util.log hierarchy to to com.ibm.log4j. I wanted to
do this for some time. I feel release 0.7.0 was the last
opportunity to do so. I am sorry for the the trouble caused by this
change. [**/***]
- New NDC class. This class implements nested diagnostic contexts as
suggested by Neil Harrison in the article "Patterns for Logging
Diagnostic Messages" part of the book "Pattern Languages of Program
Design 3" edited by Martin et al. Nested diagnostic contexts is a
nifty feature that was missing up to now. [*]
The StressNDC test class seems to break JDK 1.2.2 beta on AIX. On
Linux and NT using sun's JDK 1.2.2 it seem to work OK. In any case,
tests done with StressNDC and associated perl script seem to
indicate that the NDC class is bug-free.
- Corrected a date formatting bug in CGULog class where on some
environments the wrong month was printed. Thanks to Christopher
Williams (Christopher_Williams@mail.northgrum.com) for signaling
this bug. Also changed the month format from a number to a three
letter abbreviation such as "Jan", "Feb", ..., "Dec". The new
format is unambiguous regardless of local date format. [*]
December 8, 1999
- Release of version 0.6.2.
- Clearer documentation with still much room for improvement.
- Corrected a bug in the Tracer class which always used the Unix line
separator instead of the system specific separator. Thanks to
Vikram Sridharan (Vikram.Sridharan@alysis.com) for singaling this
bug. [*]
- Corrected a runaway comment which gulped the CGULog.readConfig
method. [*]
- Added the init family of methods to the ILog class to ease the
setup of a basic logging environment. Thanks to Mark Donszelmann
(Mark.Donszelmann@cern.ch) for this enhancement. [*]
- Just an hour after releasing version 0.6.1 detected and corrected a
bug where the Tracer class would correctly print Exception stack
trace but not the type of the Exception. Replaced the
distribution on www.zurich.ibm.com without changing the version
number. I hope nobody is using the intermediary (and buggy) release
of 0.6.1. [*]
November 16, 1999
- Release of log4j version 0.6.1.
- Better documentation with still much room for improvement.
- For consistence sake, added setDefaultPriority and
getDefaultPriority methods to the Category class and deprecated
setDefaultPriority in the Log.class. [**]
- Corrected a major bug where if two categories were homonyms the
second instance would not be properly initialized.
- Increased the speed of Exception logging from about 4000
microseconds to about 1000. It seems that for some people Exception
logging is performance critical. Improved implementation is a
variant of Nocolai's (XNH@crisplant.com) implementation. [*]
November 9, 1999
- Release of log4j 0.6.0 with incomplete documentation.
- Added a stress test program to debug the new Category class. It
turns out that the test program was as hard to get right as the
Category class. Given the favorable results of the stress test I am
quite confident that the new class is now bug free. This assumption
has been proven to be wrong. See above.
- Created a new class called Category to manipulate categories
instead of plain Strings. The new class is just as easy to use.
However, the evaluation of whether to log or not to log is at least
10 times faster. The NOP class performance remain unaffected by the
change. (You can't improve on the performance of an empty function
call.)
Many thanks to Alex Blewitt "Alex.Blewitt@ioshq.com" for his
valuable comments. He was the first to observe that finding Strings
in a hash table was an expensive operation.
This change will require some recoding on your part. See the FAQ
for more details. [***]
- Modified the force in Log and CGULog method to use a byte[] buffer
instead of a StringBuffer. The old code was clearer but the new one
is at least 25% faster. [*]
- Added regression testing.
- We now enforce a policy where the OutputStream set by
setOutputStream is a user managed resource whereas the OutputStream
opened using setLogFile is the Log class' responsibility.
The setLogFile method now closes any previous OutputStream if only
if opened through setLogFile. If the previous OutputStream was
opened by the user and set through setOutputStream the previous
OutputStream is untouched.
Similarly, setOutputStream will close any previous OutputStream if
and only if it was opened using setLogFile.
- Added a new method logOutputStreamExists to the Log class allowing
the programmer to check if there is already an opened stream before
trying to set a new one. A stream can be opened as a byproduct of
reading the configuration file.
- Changed the behavior of the (private) Log.Append method in case of
failure to write to the OutputStream.
Previously, in case of failure, we reverted to System.err. Now, we
emit a warning message and discard all future log messages. The
new behavior is consistent with our current unreliable logging
semantics. The change prevents an otherwise functional program
from failing because the terminal is flooded with logging messages.
- Renamed the iLog to ILog to remain consistent with our class naming
scheme. The initial intention was to add ILog and deprecate
iLog. However, I am running CVS on a fat16 partition, causing
serious problems when files differ only in case.
- Corrected a bug where the LogFileName was not remembered. Thanks to
Jens for signaling this bug.
October 28, 1999
- Release of log4j v0.5a
- Now the programmer can choose to truncate the log file instead of
always appending to it. This functionality was first requested and
intially implemented by "Jens Uwe Pipka" jens.pipka@gmx.de. [*]
- setLogFile now opens the requested file instead of having the
Append function open it later. Cleaned up some related code in the
Append function. Although nobody has requested it, there is still
no method to close the log file. This is harder to implement
reliably than it sounds. [*]
- Simplified setLogOutputStream so that it does no longer return the
previously set OutputStream. [*]
October 27, 1999
- Released log4j v0.5
- Joe Walker (joe@eireneh.com) observed that the
LogCreationManager.getSingleton mechanism was cumbersome. There is
now a new class iLog (indirect Log) which hides the need to call
getSingleton. Performance testing on my 233Mhz Thinkpad shows that
this indirection has small performance impact on non-logged calls
in the order of 40 nanoseconds. The impact on logged calls is
negligible. [*]
- Added a jar file to the distribution. The jar file contains only
the files you would need to use log but not other classes needed
for testing nor examples.
- Corrected a bug where CGUNOPLog was not integrated to the Makefile.
- Added new public methods isDebugEnabled and isInfoEnabled to allow
programmers to check whether a debug/info statement will be logged
without incurring the cost of message parameter construction. This
addition was suggested by Luke Blanshard Luke@quiq.com. [*]
- Renamed the private method evaluate to isEnabled. Also made it
final with no apparent speed gains. In addition, made the
Log.force method public. [*]
- New syntactic sugar debug, ..., emerg, methods to log objects. [*]
- Modified the interface to deal with Throwables and not just
Exceptions. My thanks to Luke Blanshard for signaling this "bug". [*]
- Added more tests to the LogPerformance class. In particular, to
test the influence of indirect debug calls.
- Added a "make" mini-tutorial for those who want to modify the code.
- License updated to standard alphaWorks license allowing
modifications to source code. However, this license explicitly
requires that modifications be communicated back to alphaWorks.
October 15, 1999
- Initial availability on alphaWorks.
Refer to the FAQ for the lineage of the package.
1.1 jakarta-log4j/doc/TROUBLESHOOT.html
Index: TROUBLESHOOT.html
===================================================================
<html>
<head>
<title>Troubleshooting log4j</title>
</head>
<body bgcolor=#FFFFFF>
<h1 align=center>Log4j troubleshooting</h1>
<h2 align=center>Ceki Gülcü
<br>November 2000</h2>
<hr>
<p>Here is a list of commonly encoutered problems when using log4j:
<ul>
<li><p><a href=#noAppenders>log4j tells me to initialize
properly.</a>
<li><p><a href=#duplicates>Duplicates in log4j output.</a>
<li><p><a href=#space>Options are not parsed correctly.</a>
<li><p><a href=#jit>Location information is printed as a "?" character.</a>
<li><p><a href=#cce>ClassCastException when instantiating a Category subclasses.</a>
</ul>
<hr>
<p><a name=noAppenders><h4>log4j tells me to initialize properly.</h4>
Logging output is written to a target by using an appender. If no
appenders are attached to a category nor to any of its ancestors, you
will get the following message when trying to log:
<pre>
log4j: No appenders could be found for category (some.category.name).
log4j: Please initialize the log4j system properly.
</pre>
<em>Log4j does not have a default logging target.</em> It is the
user's responsability to ensure that all categories can inherit an
appender. This can be easily achieved by attaching an appender to the
root category.
<p><a name=duplicates><h4>Duplicates in log4j output.</h4>
<p>The reason for observing duplicates in log4j output is either due
to having added the same appender multiple times to the same category
(typically root) or having added the same appender to different
categories not knowing that appenders are inherited cumulatively.
<p>log4j does not eliminate appender duplicates. In other words, if
you add the same appender to a categoty <i>n</i> times, that appender
will be invoked <i>n</i> times to append to its target.
<p>A slightly different cause is adding different appenders all
sharing the same underlying output target to some category. In the
most common occurance of this phenomenon, the
BasicConfigurator.configure() method is invoked multiple times. Each
time it is invoked, this method adds an appender with a
<code>System.out</code> target to the root category. See <a
href="http://sourceforge.net/support/?func=detailsupport&support_id=107779&group_id=2666">[
Support #107779]</a> for an example.
<p>One other common mistake is to forget that appenders are inherited
cumulatively from the hierarchy. For example, if you add an appender,
say <code>A</code>, to the root category, all other categories will
inherit <code>A</code> as an appender. Thus, if you add <code>A</code>
to a categoy, say <code>C</code>, then an enabled statement of
category <code>C</code>, will print to <code>A</code> twice, once
because <code>A</code> is in root and once because it is in
<code>C</code>. See <a
href="http://sourceforge.net/bugs/?func=detailbug&bug_id=121892&group_id=2666">[
Bug #121892 ]</a> for an example.
<p><a name=space><h4>Options are not parsed correctly.</h4>
The PropertyConfigurator relies on <code>java.util.Properties</code>
class to read in the configuration file. This class preserves spaces
in options. For example,
<pre>
fruit=orange
</pre>
is returned as an option having the key <code>"fruit"</code> and the
value <code>"orange "</code>.
<p>The spaces in the value, i.e. <code>"orange "</code>, are due to
invisible spaces at the end of the example shown above. Thus, some of
the options might not be interpreted correctly due to trailing
spaces. See <a
href="http://sourceforge.net/bugs/?func=detailbug&bug_id=121903&group_id=2666">[Bug
#121903]</a> for an example of this problem.
<p>In log4j version 0.9.0, all spaces are removed from <em>both</em>
ends of option values. In version 0.9.1 log4j reverted to the old
behaviour where option values are not all automatically trimmed.
<p><a name=jit><h4>Location information is printed as a "?" character.</h4>
Location information is extracted automatically by the PatternLayout
conversion patterns %C, %F, %M and %L. However, some just-in-time
(JIT) compilers make it impossible to extract location information. It
is also possible that the complier that generated the byte code may
have ommitted the LineNumber table as is done by -O option of javac
and jikes.
<p>You can remedy this problem by disabling the JIT compiler and by
compiling the code without the -O option.
<p>See <a href="http://sourceforge.net/support/?func=detailsupport&group_id=2666&support_id=108314">[Support
#108314]</a> for an example of this problem.
<p><a name=cce><h4><code>ClassCastException</code> when instantiating
a <code>Category</code> subclasses.</a></h4>
<p>This exception is thrown because log4j does not support
homonyms. For example, the following will systematically throw a
<code>ClassCastException</code>
<pre>
Category c1 = Category.getInstance("bad");
MyCategory c2 = (MyCategory) MyCategory.getInstance("bad");
</pre>
where <code>MyCategory</code> is a sub-class of
<code>Category</code>. The problem occurs because the second
<code>getInstance</code> invocation will retrieve the category created
in the fist invocation. This instance is a <code>Category</code>
object and cannot be cast to <code>MyCategory</code>.
<p>By default, the <code>PropertyConfigurator</code> will create and
configure <code>org.log4j.Category</code> objects. Thus, if you try to
instantiate a category sub-class for an already existing category, and
try to cast it to the sub-class type, you will systematically get a
<code>ClassCastException</code>.
To address this problem, the <code>PropertyConfigurator</code> admits the
</body>
</html>
1.2 +5 -5 jakarta-log4j/xdocs/documentation.xml
Index: documentation.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/xdocs/documentation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- documentation.xml 2001/01/10 18:33:10 1.1
+++ documentation.xml 2001/01/11 11:59:37 1.2
@@ -15,31 +15,31 @@
<ul>
<p>
- <li><a href="log4j/javadoc/manual.html"><b>introductory manual</b></a>,
+ <li><a href="manual.html"><b>introductory manual</b></a>,
</li>
</p>
<p>
<li>
- <a href="log4j/javadoc/index.html"><b>javadoc documentation</b></a>,
+ <a href="../javadoc/index.html"><b>javadoc documentation</b></a>,
</li>
</p>
<p>
<li>
- <a href="log4j/FAQ.html"><b>FAQ</b></a>,
+ <a href="FAQ.html"><b>FAQ</b></a>,
</li>
</p>
<p>
<li>
- <a href="log4j/TROUBLESHOOT.html"><b>troubleshooting guide</b></a> and
+ <a href="TROUBLESHOOT.html"><b>troubleshooting guide</b></a> and
</li>
</p>
<p>
<li>
- <a href="log4j/javadoc/deepExtension.html"><b>extending log4j</b></a>.
+ <a href="deepExtension.html"><b>extending log4j</b></a>.
</li>
</p>
</ul>