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/10 14:00:31 UTC
cvs commit: jakarta-log4j/src/docbook architecture.xml configuration.xml manual.xml
ceki 01/09/10 05:00:31
Modified: src/docbook architecture.xml configuration.xml manual.xml
Log:
Various improvements to docs.
Revision Changes Path
1.5 +463 -429 jakarta-log4j/src/docbook/architecture.xml
Index: architecture.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/architecture.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- architecture.xml 2001/09/10 10:51:47 1.4
+++ architecture.xml 2001/09/10 12:00:31 1.5
@@ -1,91 +1,91 @@
<chapter>
- <title>Logger, Appenders and Layouts</title>
+ <title>Logger, Appenders and Layouts</title>
- <para>Log4j has three main components:
- <emphasis>loggers</emphasis>, <emphasis>appenders</emphasis> and
- <emphasis>layouts</emphasis>. These three types of components
- work together to enable developers to log messages according to
- message type and priority, and to control at runtime how these
- messages are formatted and where they are reported.
+ <para>Log4j has three main components:
+ <emphasis>loggers</emphasis>, <emphasis>appenders</emphasis> and
+ <emphasis>layouts</emphasis>. These three types of components
+ work together to enable developers to log messages according to
+ message type and priority, and to control at runtime how these
+ messages are formatted and where they are reported.
+ </para>
+
+ <sect1>
+ <title>Logger hierarchy</title>
+
+ <para>The first and foremost advantage of any logging API over
+ plain <function>System.out.println</function> resides in its
+ ability to disable certain log statements while allowing others
+ to print unhindered. This capability assumes that the logging
+ space, that is, the space of all possible logging statements, is
+ categorized according to some developer-chosen criteria. </para>
+
+ <para>This observation had previously led us to choose
+ <emphasis>category</emphasis> as the central concept of the
+ package. However, since log4j version 1.2, <ulink
+ url="api/org/apache/log4j/Logger.html">Logger</ulink>
+ <classname>Logger</classname> class has replaced the
+ <classname>Category</classname> class.
</para>
- <sect1>
- <title>Logger hierarchy</title>
-
- <para>The first and foremost advantage of any logging API over
- plain <function>System.out.println</function> resides in its
- ability to disable certain log statements while allowing others
- to print unhindered. This capability assumes that the logging
- space, that is, the space of all possible logging statements, is
- categorized according to some developer-chosen criteria. </para>
-
- <para>This observation had previously led us to choose
- <emphasis>category</emphasis> as the central concept of the
- package. However, since log4j version 1.2, <ulink
- url="api/org/apache/log4j/Logger.html">Logger</ulink>
- <classname>Logger</classname> class has replaced the
- <classname>Category</classname> class.
- </para>
-
- <para>Loggers are named entities. Logger names are
- case-sensitive and they follow the hierarchical naming rule:
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term><emphasis role="strong">Named Hierarchy Rule</emphasis></term>
-
- <listitem>
- <para>A category is said to be an
- <emphasis>ancestor</emphasis> of another category if
- its name followed by a dot is a prefix of the
- <emphasis>descendant</emphasis> category name. A
- category is said to be a <emphasis>parent</emphasis>
- of a <emphasis>child</emphasis> category if there are
- no ancestors between itself and the descendant
- category.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <para>Loggers are named entities. Logger names are
+ case-sensitive and they follow the hierarchical naming rule:
+ </para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="strong">Named Hierarchy Rule</emphasis></term>
+
+ <listitem>
+ <para>A category is said to be an
+ <emphasis>ancestor</emphasis> of another category if
+ its name followed by a dot is a prefix of the
+ <emphasis>descendant</emphasis> category name. A
+ category is said to be a <emphasis>parent</emphasis>
+ of a <emphasis>child</emphasis> category if there are
+ no ancestors between itself and the descendant
+ category.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
- <para>For example, the logger named
- <classname>"com.foo"</classname> is a parent of the category
- named <classname>"com.foo.Bar"</classname>. Similarly,
- <classname>"java"</classname> is a parent of
- <classname>"java.util"</classname> and an ancestor of
- <classname>"java.util.Vector"</classname>. This naming scheme
- should be familiar to most developers.
- </para>
-
- <para>The root logger resides at the top of the category
- hierarchy. It is exceptional in two ways:
- </para>
-
- <para>
- <itemizedlist>
- <listitem><para>it always exists,</para></listitem>
- <listitem><para>it cannot be retrieved by name.</para></listitem>
- </itemizedlist>
- </para>
+ <para>For example, the logger named
+ <classname>"com.foo"</classname> is a parent of the category
+ named <classname>"com.foo.Bar"</classname>. Similarly,
+ <classname>"java"</classname> is a parent of
+ <classname>"java.util"</classname> and an ancestor of
+ <classname>"java.util.Vector"</classname>. This naming scheme
+ should be familiar to most developers.
+ </para>
- <para>Invoking the class static <ulink
+ <para>The root logger resides at the top of the category
+ hierarchy. It is exceptional in two ways:
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem><para>it always exists,</para></listitem>
+ <listitem><para>it cannot be retrieved by name.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Invoking the class static <ulink
url="../api/org/apache/log4j/Logger.html#getRootLogger()">Logger.getRootLogger</ulink>
- method retrieves it. All other logger are instantiated and
- retrieved with the class static <ulink
+ method retrieves it. All other logger are instantiated and
+ retrieved with the class static <ulink
url="../api/org/apache/log4j/Logger.html#geLogger()">Logger.getLogger</ulink>
- method. This method takes the name of the desired logger as a
- parameter. Some of the basic methods in the
- <classname>Logger</classname> class are listed below.
- </para>
+ method. This method takes the name of the desired logger as
+ a parameter. Some of the basic methods in the
+ <classname>Logger</classname> class are listed below.
+ </para>
- <para>
+ <para>
- <programlisting>
+ <programlisting>
package org.apache.log4j;
public <emphasis role="strong">Logger</emphasis> class {
@@ -104,190 +104,106 @@
public void log(Priority p, Object message);
}
- </programlisting>
- </para>
+ </programlisting>
+ </para>
- <para>Loggers <emphasis>may</emphasis> be assigned levels. The
- set of possible levels, that is
-
- <ulink url="../api/org/apache/log4j/Level.html#DEBUG">DEBUG</ulink>,
- <ulink url="../api/org/apache/log4j/Level.html#INFO">INFO</ulink>,
- <ulink url="../api/org/apache/log4j/Level.html#WARN">WARN</ulink>,
- <ulink url="../api/org/apache/log4j/Level.html#ERROR">ERROR</ulink> and
- <ulink url="../api/org/apache/log4j/Level.html#FATAL">FATAL</ulink>
+ <para>Loggers <emphasis>may</emphasis> be assigned levels. The
+ set of possible levels, that is
- are defined in the <ulink
- url="../api/org/apache/log4j/Level.html">org.apache.log4j.Level</ulink>
- class. Although we do not encourage it, you may define your
- own levels by sub-classing the <classname>Level</classname>
- class. Possibly a better approach is will be explained later
- on.
- </para>
-
- <para>The <emphasis>effective level</emphasis> of logger is
- given by its assigned level. In case the logger has not been
- assigned a level, then it inherits the level of its closest
- ancestor with an assigned priority. More formally:
- </para>
+ <ulink url="../api/org/apache/log4j/Level.html#DEBUG">DEBUG</ulink>,
+ <ulink url="../api/org/apache/log4j/Level.html#INFO">INFO</ulink>,
+ <ulink url="../api/org/apache/log4j/Level.html#WARN">WARN</ulink>,
+ <ulink url="../api/org/apache/log4j/Level.html#ERROR">ERROR</ulink> and
+ <ulink url="../api/org/apache/log4j/Level.html#FATAL">FATAL</ulink>
+
+ are defined in the <ulink
+ url="../api/org/apache/log4j/Level.html">org.apache.log4j.Level</ulink>
+ class. Although we do not encourage it, you may define your
+ own levels by sub-classing the <classname>Level</classname>
+ class. Possibly a better approach is will be explained later
+ on.
+ </para>
+
+ <para>The <emphasis>effective level</emphasis> of logger is
+ given by its assigned level. In case the logger has not been
+ assigned a level, then it inherits the level of its closest
+ ancestor with an assigned priority. More formally:
+ </para>
-
- <para id="inheritanceRule">
- <variablelist>
- <varlistentry>
- <term><emphasis role="strong">Effective level of a Logger</emphasis></term>
-
- <listitem>
- <para>The <emphasis>effective level</emphasis> of a given
- logger <emphasis>L</emphasis>, is equal to the first
- non-null level in the logger hierarchy, starting at
- <emphasis>L</emphasis> and proceeding upwards in the
- hierarchy towards the root category.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>To ensure that all loggers can eventually inherit a level,
- the root logger always has an assigned priority.</para>
-
- <para>Below are four tables with various assigned levels and the
- resulting effective levels according to the above rule.</para>
+ <para id="inheritanceRule">
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="strong">Effective level of a Logger</emphasis></term>
+
+ <listitem>
+ <para>The <emphasis>effective level</emphasis> of a given
+ logger <emphasis>L</emphasis>, is equal to the first
+ non-null level in the logger hierarchy, starting at
+ <emphasis>L</emphasis> and proceeding upwards in the
+ hierarchy towards the root category.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
- <para>
- <table>
- <title>Example 1</title>
- <tgroup cols="3" align="left">
- <thead>
- <row>
- <entry>Logger name</entry>
- <entry>Assigned level</entry>
- <entry>Effective level</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>root</entry>
- <entry>DEBUG</entry>
- <entry>DEBUG</entry></row>
-
- <row>
- <entry>X </entry>
- <entry>none</entry>
- <entry>DEBUG</entry>
- </row>
-
- <row>
- <entry>X.Y </entry>
- <entry>none</entry>
- <entry>DEBUG</entry>
- </row>
- <row>
- <entry>X.Y.Z</entry>
- <entry>none</entry>
- <entry>DEBUG</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
+ <para>To ensure that all loggers can eventually inherit a level,
+ the root logger always has an assigned priority.</para>
+
+ <para>Below are four tables with various assigned levels and the
+ resulting effective levels according to the above rule.</para>
+
+ <para>
+ <table>
+ <title>Example 1</title>
+ <tgroup cols="3" align="left">
+ <thead>
+ <row>
+ <entry>Logger name</entry>
+ <entry>Assigned level</entry>
+ <entry>Effective level</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>root</entry>
+ <entry>DEBUG</entry>
+ <entry>DEBUG</entry></row>
+
+ <row>
+ <entry>X </entry>
+ <entry>none</entry>
+ <entry>DEBUG</entry>
+ </row>
+
+ <row>
+ <entry>X.Y </entry>
+ <entry>none</entry>
+ <entry>DEBUG</entry>
+ </row>
+ <row>
+ <entry>X.Y.Z</entry>
+ <entry>none</entry>
+ <entry>DEBUG</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
- <para>In example 1 above, only the root logger is assigned a
- level. This level, <varname>DEBUG</varname>, is inherited by
- the other loggers <varname>X</varname>, <varname>X.Y</varname>
- and <varname>X.Y.Z</varname>.
- </para>
-
-
- <para>
- <table>
- <title>Example 2</title>
- <tgroup cols="3" align="left">
- <thead>
- <row>
- <entry>Logger name</entry>
- <entry>Assigned level</entry>
- <entry>Effective level</entry>
- </row>
- </thead>
- <tbody>
-
- <row>
- <entry>root</entry>
- <entry>DEBUG</entry>
- <entry>DEBUG</entry>
- </row>
- <row>
- <entry>X </entry>
- <entry>ERROR</entry>
- <entry>ERROR</entry>
- </row>
- <row>
- <entry>X.Y </entry>
- <entry>INFO</entry>
- <entry>INFO</entry>
- </row>
- <row>
- <entry>X.Y.Z</entry>
- <entry>DEBUG</entry>
- <entry>DEBUG</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
+ <para>In example 1 above, only the root logger is assigned a
+ level. This level, <varname>DEBUG</varname>, is inherited by
+ the other loggers <varname>X</varname>, <varname>X.Y</varname>
+ and <varname>X.Y.Z</varname>.
+ </para>
- <para>In example 2, all loggers have an assigned level. There is
- no need for level inheritence.</para>
- <para>
- <table>
- <title>Example 3</title>
- <tgroup cols="3" align="left">
- <thead>
- <row>
- <entry>Logger name</entry>
- <entry>Assigned level</entry>
- <entry>Effective level</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>root</entry>
- <entry>INFO</entry>
- <entry>INFO</entry></row>
- <row>
- <entry>X </entry>
- <entry>DEBUG</entry>
- <entry>DEBUG</entry></row>
- <row>
- <entry>X.Y </entry>
- <entry>none</entry>
- <entry>DEBUG</entry></row>
- <row>
- <entry>X.Y.Z</entry>
- <entry>WARN</entry>
- <entry>WARN</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
-
- <para>In example 3, the loggers <varname>root</varname>,
- <varname>X</varname> and <varname>X.Y.Z</varname> are
- assigned the priorities <varname>INFO</varname>,
- <varname>DEBUG</varname> and <varname>WARN</varname>
- respectively. The logger <varname>X.Y</varname> inherits
- its level value <varname>DEBUG</varname> from its parent
- <varname>X</varname>.
- </para>
-
+ <para>
<table>
- <title>Example 4</title>
- <tgroup cols="3">
+ <title>Example 2</title>
+ <tgroup cols="3" align="left">
<thead>
<row>
<entry>Logger name</entry>
@@ -295,90 +211,173 @@
<entry>Effective level</entry>
</row>
</thead>
-
<tbody>
- <row><entry>root</entry>
- <entry>DEBUG</entry> <entry>DEBUG</entry>
+ <row>
+ <entry>root</entry>
+ <entry>DEBUG</entry>
+ <entry>DEBUG</entry>
</row>
<row>
- <entry>X </entry>
+ <entry>X </entry>
<entry>ERROR</entry>
<entry>ERROR</entry>
</row>
<row>
<entry>X.Y </entry>
- <entry>none</entry>
- <entry>ERROR</entry>
+ <entry>INFO</entry>
+ <entry>INFO</entry>
+ </row>
+ <row>
+ <entry>X.Y.Z</entry>
+ <entry>DEBUG</entry>
+ <entry>DEBUG</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <para>In example 2, all loggers have an assigned level. There is
+ no need for level inheritence.</para>
+
+ <para>
+ <table>
+ <title>Example 3</title>
+ <tgroup cols="3" align="left">
+ <thead>
+ <row>
+ <entry>Logger name</entry>
+ <entry>Assigned level</entry>
+ <entry>Effective level</entry>
</row>
+ </thead>
+
+ <tbody>
<row>
+ <entry>root</entry>
+ <entry>INFO</entry>
+ <entry>INFO</entry></row>
+ <row>
+ <entry>X </entry>
+ <entry>DEBUG</entry>
+ <entry>DEBUG</entry></row>
+ <row>
+ <entry>X.Y </entry>
+ <entry>none</entry>
+ <entry>DEBUG</entry></row>
+ <row>
<entry>X.Y.Z</entry>
- <entry>none</entry>
- <entry>ERROR</entry></row>
+ <entry>WARN</entry>
+ <entry>WARN</entry>
+ </row>
</tbody>
</tgroup>
</table>
-
- <para>In example 4, the categories <varname>root</varname> and
- <varname>X</varname> and are assigned the priorities
- <varname>Proot</varname> and <varname>DEBUG</varname>
- respectively. The categories <varname>X.Y</varname> and
- <varname>X.Y.Z</varname> inherits their level (ERROR) from
- their nearest parent <varname>X</varname> with an assigned
- level.
- </para>
-
- <para>Logging requests are made by invoking one of the
- printing methods of a logger instance. These printing
- methods are
-
- <ulink url="../api/org/apache/log4j/Category.html#debug(java.lang.Object)">debug</ulink>,
+ </para>
+
+ <para>In example 3, the loggers <varname>root</varname>,
+ <varname>X</varname> and <varname>X.Y.Z</varname> are assigned
+ the priorities <varname>INFO</varname>, <varname>DEBUG</varname>
+ and <varname>WARN</varname> respectively. The logger
+ <varname>X.Y</varname> inherits its level value
+ <varname>DEBUG</varname> from its parent <varname>X</varname>.
+ </para>
+
+ <table>
+ <title>Example 4</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Logger name</entry>
+ <entry>Assigned level</entry>
+ <entry>Effective level</entry>
+ </row>
+ </thead>
+
+ <tbody>
- <ulink url="../api/org/apache/log4j/Category.html#info(java.lang.Object)">info</ulink>,
+ <row><entry>root</entry>
+ <entry>DEBUG</entry> <entry>DEBUG</entry>
+ </row>
+ <row>
+ <entry>X </entry>
+ <entry>ERROR</entry>
+ <entry>ERROR</entry>
+ </row>
+ <row>
+ <entry>X.Y </entry>
+ <entry>none</entry>
+ <entry>ERROR</entry>
+ </row>
+ <row>
+ <entry>X.Y.Z</entry>
+ <entry>none</entry>
+ <entry>ERROR</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>In example 4, the categories <varname>root</varname> and
+ <varname>X</varname> and are assigned the priorities
+ <varname>Proot</varname> and <varname>DEBUG</varname>
+ respectively. The categories <varname>X.Y</varname> and
+ <varname>X.Y.Z</varname> inherits their level (ERROR) from
+ their nearest parent <varname>X</varname> with an assigned
+ level.
+ </para>
+
+ <para>Logging requests are made by invoking one of the
+ printing methods of a logger instance. These printing
+ methods are
+
+ <ulink url="../api/org/apache/log4j/Category.html#debug(java.lang.Object)">debug</ulink>,
+
+ <ulink url="../api/org/apache/log4j/Category.html#info(java.lang.Object)">info</ulink>,
+
+ <ulink
+ url="../api/org/apache/log4j/Category.html#warn(java.lang.Object)">warn</ulink>,
+ <ulink
+ url="../api/org/apache/log4j/Category.html#error(java.lang.Object)">error</ulink>,
+ <ulink
+ url="../api/org/apache/log4j/Category.html#fatal(java.lang.Object)">fatal</ulink>
+ and <ulink
+ url="../api/org/apache/log4j/Category.html#log(org.apache.log4j.Priority,
+ java.lang.Object)">log</ulink>.
+ </para>
+
+
+ <para>By definition, the printing method determines the level of
+ a logging request. For example, if <varname>l</varname> is a
+ logger instance, then the statement
+ <function>l.info("..")</function> is a logging request of
+ priority INFO.
+ </para>
+
+ <para>A logging request is said to be
+ <emphasis>enabled</emphasis> if its level is higher than or
+ equal to the level of its logger. Otherwise, the request is
+ said to be <emphasis>disabled</emphasis>. A logger without an
+ assigned level will inherit one from the hierarchy. This rule
+ is summarized below.
+ </para>
+
+
+ <para id="basicSelectionRule">
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="strong">Basic Selection Rule</emphasis></term>
- <ulink
- url="../api/org/apache/log4j/Category.html#warn(java.lang.Object)">warn</ulink>,
- <ulink
- url="../api/org/apache/log4j/Category.html#error(java.lang.Object)">error</ulink>,
- <ulink
- url="../api/org/apache/log4j/Category.html#fatal(java.lang.Object)">fatal</ulink>
- and <ulink
- url="../api/org/apache/log4j/Category.html#log(org.apache.log4j.Priority,
- java.lang.Object)">log</ulink>.
- </para>
-
-
- <para>By definition, the printing method determines the level of
- a logging request. For example, if <varname>l</varname> is a
- logger instance, then the statement
- <function>l.info("..")</function> is a logging request of
- priority INFO.
- </para>
-
- <para>A logging request is said to be
- <emphasis>enabled</emphasis> if its level is higher than or
- equal to the level of its logger. Otherwise, the request is
- said to be <emphasis>disabled</emphasis>. A logger without an
- assigned level will inherit one from the hierarchy. This rule
- is summarized below.
- </para>
-
-
- <para id="basicSelectionRule">
- <variablelist>
- <varlistentry>
- <term><emphasis role="strong">Basic Selection Rule</emphasis></term>
-
- <listitem>
- <para>A log request of priority
- <emphasis>p</emphasis> in a category with
- inherited priority <emphasis>q</emphasis>, is
- enabled if <emphasis> p >= q</emphasis>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <listitem>
+ <para>A log request of priority
+ <emphasis>p</emphasis> in a category with
+ inherited priority <emphasis>q</emphasis>, is
+ enabled if <emphasis> p >= q</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
<para >This rule is at the heart of log4j. It is based on the
ordering of levels. For the standard levels, we the
@@ -545,120 +544,153 @@
</variablelist>
</para>
- <para>The table below shows an example:</para>
+ <para>The table below shows an example:</para>
- <table>
- <title></title>
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Logger Name</entry>
- <entry>Added Appenders</entry>
- <entry>Additivity Flag</entry>
- <entry>Output Targets </entry>
- <entry>Comment</entry>
- </row>
- </thead>
-
+ <table>
+ <title></title>
+ <tgroup cols="5">
+ <thead>
+ <row>
+ <entry>Logger Name</entry>
+ <entry>Added Appenders</entry>
+ <entry>Additivity Flag</entry>
+ <entry>Output Targets </entry>
+ <entry>Comment</entry>
+ </row>
+ </thead>
+
<tbody>
- <row>
- <entry>root</entry>
+ <row>
+ <entry>root</entry>
<entry>A1</entry>
- <entry>not applicable</entry>
+ <entry>not applicable</entry>
<entry>A1</entry>
- <entry>The root logger is anonymous but can be accessed with the
- Logger.getRoot() method. There is no default appender
- attached to root.
- </entry>
+ <entry>The root logger is anonymous but can be accessed with the
+ Logger.getRoot() method. There is no default appender
+ attached to root.
+ </entry>
</row>
- <row>
- <entry>x</entry>
- <entry>A-x1, A-x2</entry>
- <entry>true</entry>
- <entry>A1, A-x1, A-x2</entry>
- <entry>Appenders of "x" and root.</entry>
- </row>
-
- <row>
- <entry>x.y</entry>
+ <row>
+ <entry>x</entry>
+ <entry>A-x1, A-x2</entry>
+ <entry>true</entry>
+ <entry>A1, A-x1, A-x2</entry>
+ <entry>Appenders of "x" and root.</entry>
+ </row>
+
+ <row>
+ <entry>x.y</entry>
<entry>none</entry>
- <entry>true</entry>
- <entry>A1, A-x1, A-x2</entry>
- <entry>Appenders of "x" and root.</entry>
- </row>
+ <entry>true</entry>
+ <entry>A1, A-x1, A-x2</entry>
+ <entry>Appenders of "x" and root.</entry>
+ </row>
+
+ <row>
+ <entry>x.y.z</entry>
+ <entry>A-xyz1</entry>
+ <entry>true</entry>
+ <entry>A1, A-x1, A-x2, A-xyz1</entry>
+ <entry>Appenders in "x.y.z", "x" and root.</entry>
+ </row>
+ <row>
+ <entry>security</entry>
+ <entry>A-sec</entry>
+ <entry>false</entry>
+ <entry>A-sec</entry>
- <row>
- <entry>x.y.z</entry>
- <entry>A-xyz1</entry>
- <entry>true</entry>
- <entry>A1, A-x1, A-x2, A-xyz1</entry>
- <entry>Appenders in "x.y.z", "x" and root.</entry>
- </row>
- <row>
- <entry>security</entry>
- <entry>A-sec</entry>
- <entry>false</entry>
- <entry>A-sec</entry>
-
- <entry>No appender accumulation since the additivity flag is set to
- <varname>false</varname>.
- </entry>
- </row>
+ <entry>No appender accumulation since the additivity flag is set to
+ <varname>false</varname>.
+ </entry>
+ </row>
- <row>
- <entry>security.access</entry>
- <entry>none</entry>
- <entry> true</entry>
- <entry> A-sec</entry>
-
- <entry>Only appenders of "security" because the additivity
- flag in "security" is set to <varname>false</varname>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <sect1>
- <title>Formatters</title>
-
- <para>More often than not, users wish to customize not only the
- output destination but also the output format. This is
- accomplished by associating a <emphasis>layout</emphasis> with
- an appender. The layout is responsible for formatting the
- logging request according to the user's wishes, whereas an
- appender takes care of sending the formatted output to its
- destination. </para>
-
- <para>The <ulink
- url="../api/org/apache/log4j/PatternLayout.html">PatternLayout</ulink>,
- part of the standard log4j distribution, lets the user
- specify the output format according to conversion patterns
- similar to the C language <varname>printf</varname>
- function.
- </para>
-
- <para>For example, the PatternLayout with the conversion pattern "%r [%t]
- %-5p %c - %m%n" will output something akin to:</para>
-
- <programlisting>
-176 [main] INFO org.foo.Bar - Located nearest gas station.
- </programlisting>
+ <row>
+ <entry>security.access</entry>
+ <entry>none</entry>
+ <entry> true</entry>
+ <entry> A-sec</entry>
+
+ <entry>Only appenders of "security" because the additivity
+ flag in "security" is set to <varname>false</varname>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
- <para>The first field is the number of milliseconds elapsed
-since the start of the program. The second field is the thread making
-the log request. The third field is the priority of the log
-statement. The fourth field is the name of the logger associated with
-the log request. The text after the '-' is the message of the
-statement.</para>
-
- <para>Just as importantly, log4j will render the content of the log
- message according to user specified criteria. For example, if you
- frequently need to log <varname>Oranges</varname>, an object type used in
- your current project, then you can register an
- <varname>OrangeRenderer</varname> that will be invoked whenever an orange
- needs to be logged.
+ <sect1>
+ <title>Formatters</title>
+
+ <para>More often than not, users wish to customize not only the
+ output destination but also the output format. This is
+ accomplished by associating a <emphasis>layout</emphasis> with
+ an appender. The layout is responsible for formatting the
+ logging request according to the user's wishes, whereas an
+ appender takes care of sending the formatted output to its
+ destination. </para>
+
+ <para>The <ulink
+ url="../api/org/apache/log4j/PatternLayout.html">PatternLayout</ulink>,
+ part of the standard log4j distribution, lets the user
+ specify the output format according to conversion patterns
+ similar to the C language <varname>printf</varname>
+ function.
+ </para>
+
+ <para>For example, the PatternLayout with the conversion pattern "%r [%t]
+ %-5p %c - %m%n" will output something akin to:</para>
+
+ <programlisting>
+ 176 [main] INFO org.foo.Bar - Located nearest gas station.
+ </programlisting>
+
+ <para>The first field is the number of milliseconds elapsed
+ since the start of the program. The second field is the
+ thread making the log request. The third field is the
+ priority of the log statement. The fourth field is the name of
+ the logger associated with the log request. The text after the
+ '-' is the message of the statement.
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Object Rendering</title>
+
+ <para>Object renreding is a powerful and unique log4j
+ feature. Log4j will render the content of the log messages
+ according to user specified criteria. For example, if you
+ frequently need to log <varname>Oranges</varname>, an object
+ type used in your current project, then you can register an
+ <classname>OrangeRenderer</classname> that will be invoked
+ whenever an orange object is passed as the message parameter
+ in your logging request. The previously registered
+ <classname>OrangeRenderer</classname> will be invoked to
+ render a string representation of the orange object.
+ </para>
+
+
+ <example>
+ <title>Imaginary orange rendering</title>
+
+ <programlisting>
+ Orange orange = new Orange("89", "jaffa", date);
+ logger.debug("Here is how a rendered orange looks:");
+ logger.debug(orange);
+ </programlisting>
+
+ <para>
+ Here is a possbile outcome.
</para>
+
+ <screen>
+ 4309 DEBUG [main] example.orange - Here is how a rendered orange looks:
+ 4312 DEBUG [main] example.orange - brand=jaffa, weight=89 g., picking date=2001-09-14
+
+ </screen>
+
+ </example>
<para>Object rendering follows the class hierarchy. For example,
assuming oranges are fruits, if you register an
@@ -668,10 +700,18 @@
<varname>OrangeRenderer</varname>.
</para>
- <para>Object renderers have to implement the <ulink
- url="../api/org/apache/log4j/or/ObjectRenderer.html">ObjectRenderer</ulink>
+ <para>Object renderers have to implement the
+ <classname>org.apache.log4j.or.ObjectRenderer</classname>
interface.
</para>
+
+ <para>Log4j comes with a few useful renderers. For example, you
+ can use the
+ <classname>org.apache.log4j.or.sax.AttributesRenderer</classname>
+ to render <classname>org.xml.sax.Attributes</classname> objects.
+
+ </para>
+
</sect1>
<sect1>
@@ -680,9 +720,3 @@
</sect1>
</chapter>
-<!--
- Local Variables:
- sgml-parent-document: ("manual.xml" "book" "chapter")
- End:
- -->
-
\ No newline at end of file
1.3 +293 -231 jakarta-log4j/src/docbook/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/configuration.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- configuration.xml 2001/09/09 21:59:57 1.2
+++ configuration.xml 2001/09/10 12:00:31 1.3
@@ -17,26 +17,27 @@
written in XML or in Java properties (key=value) format.</para>
<para>Let us give a taste of how this is done with the help of an
- imaginary application <code>MyApp</code> that uses log4j.</para>
+ imaginary application <classname>MyApp</classname> that uses log4j.
+ </para>
<para>
<programlisting>
import com.foo.Bar;
// Import log4j classes.
- <b>import org.apache.log4j.Category;
- import org.apache.log4j.BasicConfigurator;</b>
+ import org.apache.log4j.Category;
+ import org.apache.log4j.BasicConfigurator;
public class MyApp {
// Define a static category variable so that it references the
// Category instance named "MyApp".
- <strong>static</strong> Category cat = <strong>Category.getInstance(MyApp.class);</strong>
+ static Category cat = Category.getInstance(MyApp.class);
public static void main(String[] args) {
// Set up a simple configuration that logs on the console.
- <strong>BasicConfigurator.configure();</strong>
+ BasicConfigurator.configure();
cat.info("Entering application.");
Bar bar = new Bar();
@@ -48,21 +49,23 @@
</para>
- <para><code>MyApp</code> begins by importing log4j related classes. It
- then defines a static category variable with the name
- <code>MyApp</code> which happens to be the fully qualified name of the
- class.</para>
+ <para><classname>MyApp</classname> begins by importing log4j related
+ classes. It then defines a static category variable with the name
+ <classname>MyApp</classname> which happens to be the fully
+ qualified name of the class.
+ </para>
- <para><code>MyApp</code> uses the <code>Bar</code> class defined in the
- package <code>com.foo</code>.</para>
+ <para><classname>MyApp</classname> uses the
+ <classname>Bar</classname> class defined in the package
+ <classname>com.foo</classname>.</para>
<para>
<programlisting>
- <b>package com.foo;</b>
+ <emphasis role="bold">package com.foo;</emphasis>
import org.apache.log4j.Category;
public class Bar {
- <strong>static</strong> Category cat = <strong>Category.getInstance(Bar.class);</strong>
+ static Category cat = Category.getInstance(Bar.class);
public void doIt() {
cat.debug("Did it again!");
@@ -71,18 +74,18 @@
</programlisting>
</para>
- <para>The invocation of the <a
- href="api/org/apache/log4j/BasicConfigurator.html#configure()">BasicConfigurator.configure</a>
+ <para>The invocation of the <ulink
+ url="api/org/apache/log4j/BasicConfigurator.html#configure()">BasicConfigurator.configure</ulink>
method creates a rather simple log4j setup. This method is
- hardwired to add to the root category a <a
- href="api/org/apache/log4j/ConsoleAppender.html">
- ConsoleAppender</a>. The output will be formatted using a <a
- href="api/org/apache/log4j/PatternLayout.html">PatternLayout</a>
+ hardwired to add to the root category a <ulink
+ url="api/org/apache/log4j/ConsoleAppender.html">
+ ConsoleAppender</ulink>. The output will be formatted using a <ulink
+ url="api/org/apache/log4j/PatternLayout.html">PatternLayout</ulink>
set to the pattern "%-4r [%t] %-5p %c %x - %m%n".
</para>
<para>Note that by default, the root category is assigned to
- <code>Priority.DEBUG</code>. </para>
+ <classname>Priority.DEBUG</classname>. </para>
<para>The output of MyApp is:
<screen>
@@ -92,33 +95,31 @@
</screen>
</para>
- <para>The figure below depicts the object diagram of <code>MyApp</code>
- after just having called the <code>BasicConfigurator.configure</code>
+ <para>The figure below depicts the object diagram of <classname>MyApp</classname>
+ after just having called the <classname>BasicConfigurator.configure</classname>
method. </para>
<para>
- <center>
- <img src="od.gif" align="center" >
- </center>
+ <!-- <img src="od.gif" align="center"/> -->
</para>
<para>As a side note, let me mention that in log4j child categories
link only to their existing ancestors. In particular, the category
- named <code>com.foo.Bar</code> is linked directly to the
- <code>root</code> category, thereby circumventing the unused
- <code>com</code> or <code>com.foo</code> categories. This
+ named <classname>com.foo.Bar</classname> is linked directly to the
+ <classname>root</classname> category, thereby circumventing the unused
+ <classname>com</classname> or <classname>com.foo</classname> categories. This
significantly increases performance and reduces log4j's memory
footprint.
</para>
- <para>The <code>MyApp</code> class configures log4j by invoking
- <code>BasicConfigurator.configure</code> method. Other classes
- only need to import the <code>org.apache.log4j.Category</code>
+ <para>The <classname>MyApp</classname> class configures log4j by invoking
+ <classname>BasicConfigurator.configure</classname> method. Other classes
+ only need to import the <classname>org.apache.log4j.Category</classname>
class, retrieve the categories they wish to use, and log away.
</para>
<para>The previous example always outputs the same log information.
- Fortunately, it is easy to modify <code>MyApp</code> so that the
+ Fortunately, it is easy to modify <classname>MyApp</classname> so that the
log output can be controlled at run-time. Here is a slightly
modified version.
</para>
@@ -129,7 +130,7 @@
import com.foo.Bar;
import org.apache.log4j.Category;
- <b>import org.apache.log4j.PropertyConfigurator;</b>
+ <emphasis role="bold">import org.apache.log4j.PropertyConfigurator;</emphasis>
public class MyApp {
@@ -139,7 +140,7 @@
// BasicConfigurator replaced with PropertyConfigurator.
- <strong>PropertyConfigurator.configure(args[0]);</strong>
+ PropertyConfigurator.configure(args[0]);
cat.info("Entering application.");
Bar bar = new Bar();
@@ -150,13 +151,13 @@
</programlisting>
</para>
- <para>This version of <code>MyApp</code> instructs
- <code>PropertyConfigurator</code> to parse a configuration file
+ <para>This version of <classname>MyApp</classname> instructs
+ <classname>PropertyConfigurator</classname> to parse a configuration file
and set up logging accordingly.
</para>
<para>Here is a sample configuration file that results in exactly
- same output as the previous <code>BasicConfigurator</code> based
+ same output as the previous <classname>BasicConfigurator</classname> based
example.
</para>
@@ -181,7 +182,7 @@
-->
<para>Suppose we are no longer interested in seeing the output of
- any component belonging to the <code>com.foo</code> package. The
+ any component belonging to the <classname>com.foo</classname> package. The
following configuration file shows one possible way of achieving
this.
</para>
@@ -193,29 +194,29 @@
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
-# <strong>Print the date in ISO 8601 format</strong>
-log4j.appender.A1.layout.ConversionPattern=<strong>%d</strong> [%t] %-5p %c - %m%n
+# <emphasis role="bold">Print the date in ISO 8601 format</emphasis>
+log4j.appender.A1.layout.ConversionPattern=<emphasis role="bold">%d</emphasis> [%t] %-5p %c - %m%n
# Print only messages of priority WARN or above in the package com.foo.
-<strong>log4j.category.com.foo=WARN</strong>
+<emphasis role="bold">log4j.category.com.foo=WARN</emphasis>
</programlisting>
</para>
-<para>The output of <code>MyApp</code> configured with this file is shown below.
+<para>The output of <classname>MyApp</classname> configured with this file is shown below.
</para>
<screen>
-<strong>2000-09-07 14:07:41,508</strong> [main] INFO MyApp - Entering
-application. <strong>2000-09-07 14:07:41,529</strong> [main] INFO
+<emphasis role="bold">2000-09-07 14:07:41,508</emphasis> [main] INFO MyApp - Entering
+application. <emphasis role="bold">2000-09-07 14:07:41,529</emphasis> [main] INFO
MyApp - Exiting application.
</screen>
- <para>As the category <code>com.foo.Bar</code> does not have an
+ <para>As the category <classname>com.foo.Bar</classname> does not have an
assigned priority, it inherits its priority from
- <code>com.foo</code>, which was set to WARN in the configuration
- file. The log statement from the <code>Bar.doIt</code> method has
+ <classname>com.foo</classname>, which was set to WARN in the configuration
+ file. The log statement from the <classname>Bar.doIt</classname> method has
the priority DEBUG, lower than the category priority
- WARN. Consequently, <code>doIt()</code> method's log request is
+ WARN. Consequently, <classname>doIt()</classname> method's log request is
suppressed.</para>
<para>Here is another configuration file that uses multiple
@@ -224,18 +225,18 @@
<para>
<programlisting>
-log4j.rootCategory=debug, <strong>stdout, R</strong>
+log4j.rootCategory=debug, <emphasis role="bold">stdout, R</emphasis>
-log4j.appender.<strong>stdout</strong>=org.apache.log4j.ConsoleAppender
+log4j.appender.<emphasis role="bold">stdout</emphasis>=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
# Pattern to output the caller's file name and line number.
-log4j.appender.stdout.layout.ConversionPattern=%5p [%t] <strong>(%F:%L)</strong> - %m%n
+log4j.appender.stdout.layout.ConversionPattern=%5p [%t] <emphasis role="bold">(%F:%L)</emphasis> - %m%n
-log4j.appender.<strong>R</strong>=org.apache.log4j.RollingFileAppender
+log4j.appender.<emphasis role="bold">R</emphasis>=org.apache.log4j.RollingFileAppender
log4j.appender.R.File=example.log
-log4j.appender.R.MaxFileSize=<strong>100KB</strong>
+log4j.appender.R.MaxFileSize=<emphasis role="bold">100KB</emphasis>
# Keep one backup file
log4j.appender.R.MaxBackupIndex=1
@@ -249,22 +250,22 @@
</para>
<screen>
- INFO [main] <strong>(MyApp2.java:12)</strong> - Entering application.
+ INFO [main] <emphasis role="bold">(MyApp2.java:12)</emphasis> - Entering application.
DEBUG [main] (Bar.java:8) - Doing it again!
INFO [main] (MyApp2.java:15) - Exiting application.
</screen>
<para>In addition, as the root category has been allocated a second
appender, output will also be directed to the
- <code>example.log</code> file. This file will be rolled over when
+ <classname>example.log</classname> file. This file will be rolled over when
it reaches 100KB. When roll-over occurs, the old version of
- <code>example.log</code> is automatically moved to
- <code>example.log.1</code>.
+ <classname>example.log</classname> is automatically moved to
+ <classname>example.log.1</classname>.
</para>
<para>Note that to obtain these different logging behaviors we did
- not need to recompile code. We could just as easily have logged to
- a UNIX Syslog daemon, redirected all <code>com.foo</code> output
+ not need to recompile classname. We could just as easily have logged to
+ a UNIX Syslog daemon, redirected all <classname>com.foo</classname> output
to an NT Event logger, or forwarded logging events to a remote
log4j server, which would log according to local server policy,
for example by forwarding the log event to a second log4j server.
@@ -276,7 +277,7 @@
<para>The log4j library does not make any assumptions about its
environment. In particular, there are no default log4j
appenders. Under certain well-defined circumstances however, the
- static inializer of the <code>Category</code> class will attempt
+ static inializer of the <classname>Category</classname> class will attempt
to automatically configure log4j. The Java language guarantees
that the static initializer of a class is called once and only
once during the loading of a class into memory. It is important
@@ -291,186 +292,245 @@
used as a stand-alone application, as an applet, or as a servlet
under the control of a web-server.
</para>
-
- <para>The exact default initialization algorithm is defined as
- follows:</para>
-
-<ol>
- <li>Skip default initialization if the system property
- <b>log4j.defaultInitOverride</b> is set to any value other than
- "false".
-
- <para><li>Set the <code>resource</code> string variable to the value of
- the <b>log4j.configuration</b> system property. <em>The preferred
- way to specify the default initialization file is thourough the
- <b>log4j.configuration</b> system property.</em> In case the system
- property <b>log4j.configuration</b> is not defined, then set the
- string variable <code>resource</code> to its default value
- "log4j.properties".
-
- <para><li>Attempt to convert the <code>resource</code> variable to a
- URL.
-
- <para><li>If the resource variable cannot be converted to a URL, for
- example due to a <code>MalformedURLException</code>, then search for
- the <code>resource</code> from the classpath by calling
- <code>org.apache.log4j.helpers.Loader.getResource(resource,
- Category.class)</code> which returns a URL. Note that the string
+ <procedure>
+ <title>Default initialization algorithm</title>
+ <para>The exact default initialization algorithm is defined as
+ follows:</para>
+
+ <step>
+ <para>Skip default initialization if the system property
+ <command>log4j.defaultInitOverride</command> is set to any value
+ other than "false".
+ </para>
+ </step>
+
+ <step>
+ <para>Set the <classname>resource</classname> string variable
+ to the value of the <command>log4j.configuration</command> system
+ property. <emphasis>The preferred way to specify the default
+ initialization file is thourough the
+ <emphasis role="bold">log4j.configuration</emphasis> system property.</emphasis> In case the
+ system property <emphasis role="bold">log4j.configuration</emphasis> is not defined,
+ then set the string variable <classname>resource</classname>
+ to its default value "log4j.properties".
+ </para>
+ </step>
+
+ <step>
+ <para>Attempt to convert the <classname>resource</classname>
+ for the list of searched locations.variable to a
+ URL.
+ </para>
+ </step>
+
+ <step>
+ <para>If the resource variable cannot be converted to a URL,
+ for the list of searched locations.for
+ example due to a
+ for the list of searched
+ for the list of searched locations.locations.<classname>MalformedURLException</classname>,
+ for the list of searched locations.then search for
+ the <classname>resource</classname> from the classpath by calling
+ <classname>org.apache.log4j.helpers.Loader.getResource(resource,
+ Category.class)</classname> which returns a URL. Note that the string
"log4j.properties" constitutes a malformed URL.
+ </para>
- <para>See <a
- href="api/org/apache/log4j/helpers/Loader.html#getResource(java.lang.String)">Loader.getResource(java.lang.String)</a>
- for the list of searched locations.
-
- <para><li>If no URL could not be found, abort default
+ <para>See <ulink
+ url="api/org/apache/log4j/helpers/Loader.html#getResource(java.lang.String)">Loader.getResource(java.lang.String)</ulink>
+ for the list of searched locations.</para>
+ </step>
+
+
+ <step>
+ <para>If no URL could not be found, abort default
initialization. Otherwise, configure log4j from the URL.
-
- <para>The <a
- href="api/org/apache/log4j/PropertyConfigurator.html">PropertyConfigurator</a>
- will be used to parse the URL to configure log4j unless the URL ends
- with the ".xml" extension, in which case the <a
- href="api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</a>
- will be used. You can optionaly specify a custom configurator. The
- value of the <b>log4j.configuratorClass</b> system property is taken
- as the fully qualified class name of your custom configurator. The
- custom configurator you specify <em>must</em> implement the <a
- href="api/org/apache/log4j/spi/Configurator.html">Configurator</a>
- interface.
-
-</ol>
-
-<h2>Example Configurations</h2>
-
+ </para>
+ <para>The <ulink
+ url="api/org/apache/log4j/PropertyConfigurator.html">PropertyConfigurator</ulink>
+ will be used to parse the URL to configure log4j unless the
+ for the list of searched locations.URL ends with the ".xml"
+ for the list of searched locations.extension, in which case the
+ for the list of searched locations.<ulink
+ url="api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</ulink>
+ will be used. You can optionaly specify a custom configurator. The
+ value of the <emphasis role="bold">log4j.configuratorClass</emphasis> system property is taken
+ as the fully qualified class name of your custom configurator. The
+ custom configurator you specify <emphasis>must</emphasis> implement
+ the <ulink
+ url="api/org/apache/log4j/spi/Configurator.html">Configurator</ulink>
+ interface.
+ </para>
+ </step>
-<h2>Default Initialization under Tomcat</h2>
-
-<para>The default log4j initialization is particularly useful in
-web-server environments. Under Tomcat 3.x and 4.x, you should place
-the <code>log4j.properties</code> under the
-<code>WEB-INF/classes</code> directory of your web-applications. Log4j
-will find the properties file and initialize itself. This is easy to
-do and it works.
-
-<para>You can also choose to set the system property
-<b>log4j.configuration</b> before starting Tomcat. For Tomcat 3.x The
-<code>TOMCAT_OPTS</code> environment variable is used to set command
-line options. For Tomcat 4.0, set the <code>CATALINA_OPTS</code>
-environment variable instead of <code>TOMCAT_OPTS</code>.
-
-<para><b>Example 1</b>
-
-<para>The Unix shell command
-<pre>
- export TOMCAT_OPTS="-Dlog4j.configuration=foobar.txt"
-</pre>
-
-tells log4j to use the file <code>foobar.txt</code> as the default
-configuration file. This file should be place under the
-<code>WEB-INF/classes</code> directory of your web-application. The
-file will be read using the <a
-href="api/org/apache/log4j/xml/PropertyConfigurator.html">PropertyConfigurator</a>. Each
-web-application will use a different default configuration file because
-each file is relative to a web-application.
-
+ </procedure>
+
+ </sect1>
-<para><b>Example 2</b>
+ <sect1>
+ <title>Example Configurations</title>
+ <sect2>
+ <title>
+ Default Initialization under Tomcat</title>
+
+ <para>The default log4j initialization is particularly useful in
+ web-server environments. Under Tomcat 3.x and 4.x, you should place
+ the <classname>log4j.properties</classname> under the
+ <classname>WEB-INF/classes</classname> directory of your
+ for the list of searched locations.web-applications. Log4j
+ for the list of searched locations.will find the properties file and
+ for the list of searched locations.initialize itself. This is easy to
+ do and it works.
+ </para>
+
+ <para>You can also choose to set the system property
+ <emphasis role="bold">log4j.configuration</emphasis> before starting Tomcat. For Tomcat 3.x The
+ <classname>TOMCAT_OPTS</classname> environment variable is used to set command
+ line options. For Tomcat 4.0, set the <classname>CATALINA_OPTS</classname>
+ environment variable instead of
+ for the list of searched locations.<classname>TOMCAT_OPTS</classname>.
+ </para>
+
+ <example>
+ <title>FIXME FIXME</title>
+ <para>The Unix shell command
+ <computeroutput>
+ export TOMCAT_OPTS="-Dlog4j.configuration=foobar.txt"
+ </computeroutput>
+
+ tells log4j to use the file <classname>foobar.txt</classname>
+ for the list of searched locations.as the default
+ configuration file. This file should be place under the
+ <classname>WEB-INF/classes</classname> directory of your
+ for the list of searched locations.web-application. The file will be
+ for the list of searched locations.read using the <ulink
+ url="api/org/apache/log4j/xml/PropertyConfigurator.html">PropertyConfigurator</ulink>. Each
+ for the list of searched locations.for the list of searched
+ for the list of searched locations.locations.web-application will use
+ for the list of searched locations.a different default configuration
+ for the list of searched locations.for the list of searched
+ for the list of searched locations.locations.file because each file
+ for the list of searched locations.is relative to a web-application.
+ </para>
+ </example>
+
+ <example>
+ <title>FIXME FIXME</title>
+ <para>The Unix shell command
-<para>The Unix shell command
-<pre>
+ <computeroutput>
export TOMCAT_OPTS="-Dlog4j.debug -Dlog4j.configuration=foobar.xml"
-</pre>
+ </computeroutput>
-tells log4j to output log4j-internal debugging information and to use
-the file <code>foobar.xml</code> as the default configuration
-file. This file should be place under the <code>WEB-INF/classes</code>
-directory of your web-application. Since the file ends with a
-<code>.xml</code> extension, it will read using the <a
-href="api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</a>. Each
-web-application will use a different default configuration file because
-each file is relative to a web-application.
-
-<para><b>Example 3</b>
-
-<para>The Windows shell command
-<pre>
+ tells log4j to output log4j-internal debugging information
+ for the list of searched locations.for the list of searched
+ for the list of searched locations.locations.and to use the file for
+ for the list of searched locations.the list of searched for the list
+ for the list of searched locations.of searched
+ for the list of searched locations.locations.locations.<classname>foobar.xml</classname>
+ for the list of searched locations.as the default configuration
+ for the list of searched locations.file. This file should be place
+ for the list of searched locations.under the
+ for the list of searched locations.<classname>WEB-INF/classes</classname>
+ directory of your web-application. Since the file ends with a
+ <classname>.xml</classname> extension, it will read using the <ulink
+ url="api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</ulink>. Each
+ web-application will use a different default configuration file because
+ each file is relative to a web-application.
+ </para>
+ </example>
+
+ <example>
+ <title>FIXME FXME</title>
+
+ <para>The Windows shell command
+ <computeroutput>
set TOMCAT_OPTS=-Dlog4j.configuration=foobar.lcf#com.foo.BarConfigurator
-</pre>
+ </computeroutput>
-tells log4j to use the file <code>foobar.lcf</code> as the default
-configuration file. This file should be place under the
-<code>WEB-INF/classes</code> directory of your web-application. Due to
-the extra reference part, the file will be read using the
-<code>com.foo.BarConfigurator</code> custom configurator. Each
-web-application will use a different default configuration file
-because each file is relative to a web-application. <b>Support for
-custom configurators in the reference part will be dropped in future
-log4j versions. You should not rely on this feature.</b>
-
-
-<para><b>Example 4</b>
-
-<para>The Windows shell command
-<pre>
- set TOMCAT_OPTS=-Dlog4j.configuration=file:/c:/foobar.lcf</pre>
-
-tells log4j to use the file <code>c:\foobar.xml</code> as the default
-configuration file. The configuration file is fully specified by the
-URL <code>file:/c:/foobar.lcf</code>. Thus, the same configuration
-file will be used for all web-applications.
-
-
-<para>Different web-applications will load the log4j classes through
-their respective classloaderss. Thus, each image of the log4j
-environment will act independetly and without any mutual
-synchronization. For example, <code>FileAppenders</code> defined
-exactly the same way in multiple web-application configurations will
-all attempt to write the same file. The results are likely to be less
-than satisfactory. You must make sure that log4j configurations of
-different web-applications do not use the same underlying system
-resource.
-
-
-<para><b>Initialization servlet</b>
-
-<para>It is also possible to use a special servlet for log4j
-initialization. Here is an example,
-
-<para><table bgcolor="CCCCCC"><tr><td>
-<pre>
-package com.foo;
-
-import org.apache.log4j.PropertyConfigurator;
-import javax.servlet.http.HttpServlet;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-import java.io.PrintWriter;
-import java.io.IOException;
+ tells log4j to use the file <classname>foobar.lcf</classname> as the default
+ configuration file. This file should be place under the
+ <classname>WEB-INF/classes</classname> directory of your web-application. Due to
+ the extra reference part, the file will be read using the
+ <classname>com.foo.BarConfigurator</classname> custom configurator. Each
+ web-application will use a different default configuration file
+ because each file is relative to a web-application. <emphasis role="bold">Support for
+ custom configurators in the reference part will be dropped in future
+ log4j versions. You should not rely on this feature.</emphasis>
+ </para>
+ </example>
+
+ <example>
+ <title></title>
+ <para>The Windows shell command
+ <computeroutput>
+ set TOMCAT_OPTS=-Dlog4j.configuration=file:/c:/foobar.lcf
+ </computeroutput>
+
+ tells log4j to use the file <classname>c:\foobar.xml</classname> as the default
+ configuration file. The configuration file is fully specified by the
+ URL <classname>file:/c:/foobar.lcf</classname>. Thus, the same configuration
+ file will be used for all web-applications.
+ </para>
+ </example>
+
+ <para>Different web-applications will load the log4j classes through
+ their respective classloaderss. Thus, each image of the log4j
+ environment will act independetly and without any mutual
+ synchronization. For example, <classname>FileAppenders</classname> defined
+ exactly the same way in multiple web-application configurations will
+ all attempt to write the same file. The results are likely to be less
+ than satisfactory. You must make sure that log4j configurations of
+ different web-applications do not use the same underlying system
+ resource.</para>
-public class Log4jInit extends HttpServlet {
+ </sect2>
+ </sect1>
- public
- void <b>init()</b> {
- String prefix = getServletContext().getRealPath("/");
- String file = getInitParameter("log4j-init-file");
- // if the log4j-init-file is not set, then no point in trying
- if(file != null) {
- PropertyConfigurator.configure(prefix+file);
- }
- }
-
- public
- void doGet(HttpServletRequest req, HttpServletResponse res) {
- }
-}
-</pre>
-</table>
+ <sect1>
+ <title>Initialization servlet</title>
+
+ <para>It is also possible to use a special servlet for log4j
+ initialization. Here is an example,
+
+ <programlisting>
+ package com.foo;
+
+ import org.apache.log4j.PropertyConfigurator;
+ import javax.servlet.http.HttpServlet;
+ import javax.servlet.http.HttpServletRequest;
+ import javax.servlet.http.HttpServletResponse;
+ import java.io.PrintWriter;
+ import java.io.IOException;
-<para>Define the following servlet in the web.xml file for your web-application.
+ public class Log4jInit extends HttpServlet {
+
+ public
+ void init() {
+ String prefix = getServletContext().getRealPath("/");
+ String file = getInitParameter("log4j-init-file");
+ // if the log4j-init-file is not set, then no point in trying
+ if(file != null) {
+ PropertyConfigurator.configure(prefix+file);
+ }
+ }
+
+ public
+ void doGet(HttpServletRequest req, HttpServletResponse res) {
+ }
+ }
+ </programlisting>
+ </para>
-<para><table bgcolor="CCAAAA"><tr><td>
-<pre>
+ <para>Define the following servlet in the web.xml file for your
+ for the list of searched locations.web-application.</para>
+
+
+ <para>
+ <programlisting>
+
<servlet>
<servlet-name>log4j-init</servlet-name>
<servlet-class>com.foo.Log4jInit</servlet-class>
@@ -480,17 +540,19 @@
<param-value>WEB-INF/classes/log4j.lcf</param-value>
</init-param>
- <b><load-on-startup>1</load-on-startup></b>
+ <emphasis role="bold"><load-on-startup>1</load-on-startup></emphasis>
</servlet>
-</pre>
-</table>
+ </programlisting>
+ </para>
-<para>Writing an initialization servlet is the most flexible way for
-initializing log4j. There are no constraints on the code you can place
-in the <code>init()</code> method of the servlet.
+ <para>Writing an initialization servlet is the most flexible
+ for the list of searched locations.way for
+initializing log4j. There are no constraints on the classname you can place
+in the <classname>init()</classname> method of the servlet.</para>
-
+ </sect1>
+
<sect1>
<title>PropertyConfigurator</title>
<para></para>
1.7 +1 -9 jakarta-log4j/src/docbook/manual.xml
Index: manual.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/manual.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- manual.xml 2001/09/10 10:51:47 1.6
+++ manual.xml 2001/09/10 12:00:31 1.7
@@ -3,6 +3,7 @@
<!ENTITY intro SYSTEM "intro.xml">
<!ENTITY architecture SYSTEM "architecture.xml">
<!ENTITY conf SYSTEM "configuration.xml">
+<!ENTITY faq SYSTEM "faq.xml">
<!ENTITY glo SYSTEM "glossary.xml">
]>
@@ -19,15 +20,6 @@
<firstname>Other authors</firstname>
<surname>as appropriate</surname>
</author>
-
-
- <revhistory>
- <revision>
- <revnumber>v1.0</revnumber>
- <date>2001-08-15</date>
- <authorinitials>cgu</authorinitials>
- </revision>
- </revhistory>
<abstract>
<para>
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: log4j-cvs-help@jakarta.apache.org