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/09/26 10:37:42 UTC
cvs commit: jakarta-log4j/src/xdocs documentation.xml download.xml
ceki 01/09/26 01:37:42
Modified: build build.xml
docs documentation.html download.html
src/docbook configuration.xml intro.xml manual.xml
src/java/org/apache/log4j PropertyConfigurator.java
src/xdocs documentation.xml download.xml
Added: src/docbook changes.xml
Log:
Doc changes.
Revision Changes Path
1.50 +1 -1 jakarta-log4j/build/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/build/build.xml,v
retrieving revision 1.49
retrieving revision 1.50
diff -u -r1.49 -r1.50
--- build.xml 2001/09/25 10:29:04 1.49
+++ build.xml 2001/09/26 08:37:42 1.50
@@ -9,7 +9,7 @@
<!-- ================================================================= -->
<project name="log4j" default="usage" basedir=".." >
- <property name="version" value="1.2alpha"/>
+ <property name="version" value="1.2alpha0"/>
<!-- The base directory relative to which most targets are built -->
<property name="base" value="."/>
1.16 +0 -6 jakarta-log4j/docs/documentation.html
Index: documentation.html
===================================================================
RCS file: /home/cvs/jakarta-log4j/docs/documentation.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- documentation.html 2001/09/25 10:06:35 1.15
+++ documentation.html 2001/09/26 08:37:42 1.16
@@ -95,12 +95,6 @@
<p>
<li>
- <a href="deepExtension.html"><b>extending log4j</b></a>,
- </li>
- </p>
-
- <p>
- <li>
<a href="critique.html"><b>JSR47 vs. log4j</b></a> and
<a href="critique2.html"><b>follow up</b></a>.
</li>
1.36 +6 -6 jakarta-log4j/docs/download.html
Index: download.html
===================================================================
RCS file: /home/cvs/jakarta-log4j/docs/download.html,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -r1.35 -r1.36
--- download.html 2001/09/25 10:29:04 1.35
+++ download.html 2001/09/26 08:37:42 1.36
@@ -79,18 +79,18 @@
<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.2 apha"><strong>log4j version 1.2 apha</strong></a>
+ <a name="log4j version 1.2 alpha0"><strong>log4j version 1.2 alpha0</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
- <p>A alpha version of log4j 1.2 is now available in in <a href="../jakarta-log4j-1.2alpha.tar.gz"><b>TAR.GZ</b></a>
- format or in <a href="../jakarta-log4j-1.2alpha.zip"><b>ZIP</b></a> format.
+ <p>An alpha version of log4j 1.2 is now available in in <a href="../jakarta-log4j-1.2alpha0.tar.gz"><b>TAR.GZ</b></a>
+ format or in <a href="../jakarta-log4j-1.2alpha0.zip"><b>ZIP</b></a> format.
</p>
<p>Log4j version 1.2 is still in alpha stage. It is not
- feature-omplete, requries fair amount of testing, nor is the
- documentation up to date. We have gone to great lengths to
- ensure that version 1.2 is backward compatible with earlier
+ feature-complete, still requries fair amount of testing, nor
+ is the documentation up to date. We have gone to great lengths
+ to ensure that version 1.2 is backward compatible with earlier
versions. However, some previously deprecated APIs are now
removed. Moreover, users who have written sub-classes of
Category will need to modify their code. See the HISTORY file
1.7 +30 -0 jakarta-log4j/src/docbook/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/configuration.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- configuration.xml 2001/09/24 22:43:04 1.6
+++ configuration.xml 2001/09/26 08:37:42 1.7
@@ -275,6 +275,36 @@
for example by forwarding the log event to a second log4j server.
</para>
+ <sect1>
+ <title>Directing log output to different appenders depending on level</title>
+
+ <para>Setting the <emphasis role="bold">Threshold</emphasis> option
+ of any appender extending AppenderSkeleton, (most log4j
+ appenders extend AppenderSkeleton) to filter out all log events
+ with lower priority than the value of the threshold option.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>This policy usually best encapsulates what the user actually
+ wants to do, as opposed to her mind-projected solution.
+ </para>
+
+ <para>See sort4.lcf for an example threshold configuration. </para>
+
+ <para>If you must filter events by exact priority match, then you can
+ attach a PriorityMatchFilter to any appender to filter out logging
+ events by exact priority match.</para>
+ </sect1>
+
<sect1 id="defaultInit">
<title>Default Initialization Procedure</title>
1.7 +1 -1 jakarta-log4j/src/docbook/intro.xml
Index: intro.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/intro.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- intro.xml 2001/09/19 22:09:10 1.6
+++ intro.xml 2001/09/26 08:37:42 1.7
@@ -9,7 +9,7 @@
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 <ulink
- url="../LICENSE.txt">Apache Software License</ulink>, a
+ url="../../LICENSE.txt">Apache Software License</ulink>, a
fully-fledged open source license certified by the <ulink
url="http://www.opensource.org">open source</ulink>
initiative. The latest log4j version, including full-source code,
1.10 +2 -0 jakarta-log4j/src/docbook/manual.xml
Index: manual.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/manual.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- manual.xml 2001/09/20 22:19:07 1.9
+++ manual.xml 2001/09/26 08:37:42 1.10
@@ -3,6 +3,7 @@
<!ENTITY intro SYSTEM "intro.xml">
<!ENTITY architecture SYSTEM "architecture.xml">
<!ENTITY conf SYSTEM "configuration.xml">
+<!ENTITY changes SYSTEM "changes.xml">
<!ENTITY faq SYSTEM "faq.xml">
<!ENTITY glo SYSTEM "glossary.xml">
<!ENTITY trouble SYSTEM "trouble.xml">
@@ -38,6 +39,7 @@
&intro
&architecture
&conf
+ &changes
&faq
&trouble
&glo
1.1 jakarta-log4j/src/docbook/changes.xml
Index: changes.xml
===================================================================
<chapter id="Changes">
<title>Changes</title>
<sect1>
<title>Between log4j version 1.1.x and 1.2</title>
<para>Log4j version 1.2 introduced many changes. In most cases, it
can be considered as a drop in replacement for log4j version
1.1.x. This section discusses the changes and backward
compatiblity issues.
</para>
<sect2>
<title>Logger instead of Category</title> <para>The most
important change in 1.2 is the replacement of the Category class
with the Logger class. To preserve backward compatibility, the
Logger class extends the Category class such that it is always
possible to use a logger object where a category object is
expected. Whenever log4j is asked to produce a Category object,
it will instead produce a Logger object. Methods that previously
accepted category objects will continue to accept category
objects.
</para>
<para>For example, the following are all legal and will work as
expected.
<programlisting>
// Deprecated forms:
Category cat = Category.getInstance("foo.bar")
Logger logger = Logger.getInstance("foo.bar")
Category cat = Logger.getLogger("foo.bar")
// Preferred form for retrieving loggers:
Logger logger = Logger.getLogger("foo.bar")
</programlisting>
</para>
<para>There is absolutely no need for new client code to use or
refer to the <classname>Category</classname> class. Please avoid
referring to it or using it.</para>
<para>It is important to note that the introduction of the Logger
and Level classes is backward compatible. You can still use the
older Category and Priority classes in your existing code.
</para>
<para>One caveat is that the
<classname>org.apache.log4j.spi.CategoryFactory</classname> has
been removed. It has been replaced with the
<classname>org.apache.log4j.spi.LoggerFactory</classname>
class. For most users this change is invisible. However, if you
have sub-classed the Category class then you must modify your
sub-class to extend Logger instead of Category. You must also use
<classname>LoggerFactory</classname> instead of
<classname>CategoryFactory</classname>.
</para>
<para>We also strongly recommend against sub-classing Logger (or
Category) to introduce new printing methods, you can use the
general purpose <ulink
url="../api/org/apache/log4j/Category.html#log(org.apache.log4j.Priority,
java.lang.Object)">log</ulink> method instead.
</para>
</sect2>
<sect2>
<title>Level instead of Priority</title>
<para>In a very similar fashion, the
<classname>Priority</classname> class has been replaced by the
<classname>Level</classname> class. Level extends Priority.
Whenever log4j is asked to produce a Priority object, it will
instead produce a Level object.
</para>
</sect2>
<sect2>
<title>LogManager, RepositorySelector and LoggerRepository classes</title>
<para>The <classname>LogManager</classname> provides a flexible
method for retrieving <classname>Logger</classname> instances
of <emphasis>varying types</emphasis> held in
<emphasis>context-dependent repositories</emphasis>.
</para>
<para>Log4j is a a low level API used in a variety of
projects. Consequently, it is hard to make a priori
assumptions about the environment where log4j will run. The
problem is particularly acute in embedded components
(e.g. libraries) which rely on log4j for their logging. The
author of embedded component can rarely afford to make
restrictive assumptions about the surrounding environment, a
fortiori assumtions about logging. It might be the case that
the end user is not interested in logging at all. It would be
a total waste to generate logging output for a user who will
never look at them. Under such circumstances, the embedded
component will want to use a <classname>NullLogger</classname>
which would not genereate any log output at all.
</para>
<para>Logging in Application Servers and Servlet Containers also
create unique problems. It is often desirable to separate
logging output originating from different applications (or
web-application in the case of Servlet Containers). In the
current version of log4j it is possible to have different
applications live in their own parallel universe by using a
different hierarchy for each application. For more details,
refer to my <ulink
url="http://apache.org/~ceki/multHierarchy.tar.gz">multiple
hierarchy tutorial</ulink> for Servlet Containers.
</para>
<para>Using multiple hierarchies works well with code that is
designed to use them. However, it does not entend to a library
which uses log4j but is unaware of multiple hierarchies.
</para>
<para>LogManager allows us to vary Logger implementation
depending on the circumstances. Moreover, we would like to be
able to control the logging repository (i.e. hierarchy) where
loggers are held depending on the application context.
</para>
<para>One of the advantages of the LogManager approach is that
the getInstance method can return totally different Logger
implementations. For example, under JDK 1.2 we can return a
Logger implementation that is aware of the Java2 security
model whereas under JDK 1.1 the returned logger implementation
may be oblivious to Java2 security checks. In shipped code,
LogManager may be configured to return a NullLogger which
could implement the Logger (abstract) class with empty method
bodies.
</para>
<para>The behavior of LogManager is mostly determined by the
RepositorySelector it uses. However, it may also be influenced
by system properties or by parameters passed as a result of
LogManager method invocations.
</para>
<para>The RepositorySelector returns a repository of logger
objects offering primitives for retreiving individual loggers or
acting on collections of loggers.
</para>
<para>One of the distinctive feature of log4j is its ability to
arrange loggers (categories) in a hierarchy. A hierarchy is
merely a repository of categories which happens to arrange
them in a tree like structure.
</para>
</sect2>
<sect2>
<title>Hierarchy wide enabling/disabling</title>
<para>
</para>
</sect2>
</sect1>
</chapter>
1.41 +55 -55 jakarta-log4j/src/java/org/apache/log4j/PropertyConfigurator.java
Index: PropertyConfigurator.java
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/java/org/apache/log4j/PropertyConfigurator.java,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- PropertyConfigurator.java 2001/09/25 10:06:35 1.40
+++ PropertyConfigurator.java 2001/09/26 08:37:42 1.41
@@ -136,51 +136,51 @@
log4j.appender.appenderName.layout.optionN=valueN
</pre>
- <h3>Configuring categories</h3>
+ <h3>Configuring loggers</h3>
- <p>The syntax for configuring the root category is:
+ <p>The syntax for configuring the root logger is:
<pre>
- log4j.rootCategory=[priority], appenderName, appenderName, ...
+ log4j.rootLogger=[level], appenderName, appenderName, ...
</pre>
- <p>This syntax means that an optional <em>priority value</em> can
- be supplied followed by appender names separated by commas.
+ <p>This syntax means that an optional <em>level</em> can be
+ supplied followed by appender names separated by commas.
- <p>The priority value can consist of the string values FATAL,
- ERROR, WARN, INFO, DEBUG or a <em>custom priority</em> value. A
- custom priority value can be specified in the form
- <code>priority#classname</code>.
-
- <p>If a priority value is specified, then the root priority is set
- to the corresponding priority. If no priority value is specified,
- then the root priority remains untouched.
+ <p>The level value can consist of the string values FATAL,
+ ERROR, WARN, INFO, DEBUG or a <em>custom level</em> value. A
+ custom level value can be specified in the form
+ <code>level#classname</code>.
+
+ <p>If a level value is specified, then the root level is set
+ to the corresponding level. If no level value is specified,
+ then the root level remains untouched.
- <p>The root category can be assigned multiple appenders.
+ <p>The root logger can be assigned multiple appenders.
<p>Each <i>appenderName</i> (separated by commas) will be added to
- the root category. The named appender is defined using the
+ the root logger. The named appender is defined using the
appender syntax defined above.
<p>For non-root categories the syntax is almost the same:
<pre>
- log4j.category.category_name=[priority|INHERITED], appenderName, appenderName, ...
+ log4j.logger.logger_name=[level|INHERITED], appenderName, appenderName, ...
</pre>
- <p>The meaning of the optional priority value is discussed above
- in relation to the root category. In addition however, the value
- INHERITED can be specified meaning that the named category should
- inherit its priority from the category hierarchy.
-
- <p>If no priority value is supplied, then the priority of the
- named category remains untouched.
-
- <p>By default categories inherit their priority from the
- hierarchy. However, if you set the priority of a category and
- later decide that that category should inherit its priority, then
- you should specify INHERITED as the value for the priority value.
+ <p>The meaning of the optional level value is discussed above
+ in relation to the root logger. In addition however, the value
+ INHERITED can be specified meaning that the named logger should
+ inherit its level from the logger hierarchy.
+
+ <p>If no level value is supplied, then the level of the
+ named logger remains untouched.
+
+ <p>By default categories inherit their level from the
+ hierarchy. However, if you set the level of a logger and
+ later decide that that logger should inherit its level, then
+ you should specify INHERITED as the value for the level value.
- <p>Similar to the root category syntax, each <i>appenderName</i>
- (separated by commas) will be attached to the named category.
+ <p>Similar to the root logger syntax, each <i>appenderName</i>
+ (separated by commas) will be attached to the named logger.
<p>See the <a href="../../../../manual.html#additivity">appender
additivity rule</a> in the user manual for the meaning of the
@@ -212,17 +212,17 @@
<h3>Class Factories</h3>
In case you are using your own subtypes of the
- <code>Category</code> class and wish to use configuration files,
- then you <em>must</em> set the <code>categoryFactory</code> for
+ <code>Logger</code> class and wish to use configuration files,
+ then you <em>must</em> set the <code>loggerFactory</code> for
the subtype that you are using.
<p>The syntax is:
<pre>
- log4j.categoryFactory=fully.qualified.name.of.categoryFactory.class
+ log4j.loggerFactory=fully.qualified.name.of.loggerFactory.class
</pre>
- See {@link org.apache.log4j.examples.MyCategory} for an example.
+ See {@link org.apache.log4j.examples.MyLogger} for an example.
<h3>Example</h3>
@@ -242,8 +242,8 @@
# A1's layout is a PatternLayout, using the conversion pattern
# <b>%r %-5p %c{2} %M.%L %x - %m\n</b>. Thus, the log output will
# include # the relative time since the start of the application in
- # milliseconds, followed by the priority of the log request,
- # followed by the two rightmost components of the category name,
+ # milliseconds, followed by the level of the log request,
+ # followed by the two rightmost components of the logger name,
# followed by the callers method name, followed by the line number,
# the nested disgnostic context and finally the message itself.
# Refer to the documentation of {@link PatternLayout} for further information
@@ -262,24 +262,24 @@
log4j.appender.A2.layout.ContextPrinting=enabled
log4j.appender.A2.layout.DateFormat=ISO8601
- # Root category set to DEBUG using the A2 appender defined above.
- log4j.rootCategory=DEBUG, A2
+ # Root logger set to DEBUG using the A2 appender defined above.
+ log4j.rootLogger=DEBUG, A2
- # Category definitions:
- # The SECURITY category inherits is priority from root. However, it's output
+ # Logger definitions:
+ # The SECURITY logger inherits is level from root. However, it's output
# will go to A1 appender defined above. It's additivity is non-cumulative.
- log4j.category.SECURITY=INHERIT, A1
+ log4j.logger.SECURITY=INHERIT, A1
log4j.additivity.SECURITY=false
- # Only warnings or above will be logged for the category "SECURITY.access".
+ # Only warnings or above will be logged for the logger "SECURITY.access".
# Output will go to A1.
- log4j.category.SECURITY.access=WARN
+ log4j.logger.SECURITY.access=WARN
- # The category "class.of.the.day" inherits its priority from the
- # category hierarchy. Output will go to the appender's of the root
- # category, A2 in this case.
- log4j.category.class.of.the.day=INHERIT
+ # The logger "class.of.the.day" inherits its level from the
+ # logger hierarchy. Output will go to the appender's of the root
+ # logger, A2 in this case.
+ log4j.logger.class.of.the.day=INHERIT
</pre>
<p>Refer to the <b>setOption</b> method in each Appender and
@@ -570,7 +570,7 @@
StringTokenizer st = new StringTokenizer(value, ",");
// If value is not in the form ", appender.." or "", then we should set
- // the priority of the loggeregory.
+ // the level of the loggeregory.
if(!(value.startsWith(",") || value.equals(""))) {
@@ -578,20 +578,20 @@
if(!st.hasMoreTokens())
return;
- String priorityStr = st.nextToken();
- LogLog.debug("Priority token is [" + priorityStr + "].");
+ String levelStr = st.nextToken();
+ LogLog.debug("Level token is [" + levelStr + "].");
- // If the priority value is inherited, set category priority value to
+ // If the level value is inherited, set category level value to
// null. We also check that the user has not specified inherited for the
// root category.
- if(priorityStr.equalsIgnoreCase(BasicConfigurator.INHERITED) &&
+ if(levelStr.equalsIgnoreCase(BasicConfigurator.INHERITED) &&
!loggerName.equals(INTERNAL_ROOT_NAME)) {
logger.setLevel(null);
} else {
- logger.setLevel(OptionConverter.toLevel(priorityStr,
- Priority.DEBUG));
+ logger.setLevel(OptionConverter.toLevel(levelStr,
+ Level.DEBUG));
}
- LogLog.debug("Category " + loggerName + " set to " + logger.getPriority());
+ LogLog.debug("Category " + loggerName + " set to " + logger.getLevel());
}
// Remove all existing appenders. They will be reconstructed below.
1.10 +0 -6 jakarta-log4j/src/xdocs/documentation.xml
Index: documentation.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/xdocs/documentation.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- documentation.xml 2001/09/25 10:06:36 1.9
+++ documentation.xml 2001/09/26 08:37:42 1.10
@@ -46,12 +46,6 @@
<p>
<li>
- <a href="deepExtension.html"><b>extending log4j</b></a>,
- </li>
- </p>
-
- <p>
- <li>
<a href="critique.html"><b>JSR47 vs. log4j</b></a> and
<a href="critique2.html"><b>follow up</b></a>.
</li>
1.35 +7 -7 jakarta-log4j/src/xdocs/download.xml
Index: download.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/xdocs/download.xml,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -r1.34 -r1.35
--- download.xml 2001/09/25 10:29:04 1.34
+++ download.xml 2001/09/26 08:37:42 1.35
@@ -57,18 +57,18 @@
</section>
- <section name="log4j version 1.2 apha">
- <p>A alpha version of log4j 1.2 is now available in in <a
- href="../jakarta-log4j-1.2alpha.tar.gz"><b>TAR.GZ</b></a>
+ <section name="log4j version 1.2 alpha0">
+ <p>An alpha version of log4j 1.2 is now available in in <a
+ href="../jakarta-log4j-1.2alpha0.tar.gz"><b>TAR.GZ</b></a>
format or in <a
- href="../jakarta-log4j-1.2alpha.zip"><b>ZIP</b></a> format.
+ href="../jakarta-log4j-1.2alpha0.zip"><b>ZIP</b></a> format.
</p>
<p>Log4j version 1.2 is still in alpha stage. It is not
- feature-omplete, requries fair amount of testing, nor is the
- documentation up to date. We have gone to great lengths to
- ensure that version 1.2 is backward compatible with earlier
+ feature-complete, still requries fair amount of testing, nor
+ is the documentation up to date. We have gone to great lengths
+ to ensure that version 1.2 is backward compatible with earlier
versions. However, some previously deprecated APIs are now
removed. Moreover, users who have written sub-classes of
Category will need to modify their code. See the HISTORY file
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: log4j-cvs-help@jakarta.apache.org