ceki 01/09/27 02:01:21
Modified: src/docbook architecture.xml intro.xml
Log:
Revision Changes Path
1.9 +61 -49 jakarta-log4j/src/docbook/architecture.xml
Index: architecture.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/architecture.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- architecture.xml 2001/09/19 22:09:10 1.8
+++ architecture.xml 2001/09/27 09:01:21 1.9
@@ -1,12 +1,18 @@
<chapter>
<title>Logger, Appenders and Layouts</title>
-
+
+ <para>The previous chapter presented a very simple usage case for
+ log4j. This chapter discusses the log4j architecture and the rules
+ governing its components.
+ </para>
+
+
<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 their
level and to control at runtime how these messages are formatted
- and where they are reported.
+ and where they are written.
</para>
<sect1>
@@ -31,7 +37,7 @@
<para>Loggers are named entities. Logger names are
- case-sensitive and they follow the hierarchical naming rule:
+ case-sensitive and they follow the >Named Hierarchy Rule:
</para>
<para>
@@ -87,7 +93,7 @@
<para>
<programlisting>
- package org.apache.log4j;
+ package org.apache.log4j;
public <emphasis role="strong">Logger</emphasis> class {
@@ -125,10 +131,11 @@
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>The <emphasis>effective level</emphasis> of a logger is
+ given by its assigned level, if it is assigned one. Otherwise, if
+ the logger has not been assigned a level, then it inherits the
+ level of its closest ancestor with an assigned priority. More
+ formally,
</para>
@@ -157,7 +164,7 @@
<para>
<table>
- <title>Example 1</title>
+ <title>Level Inheritance - Example 1</title>
<tgroup cols="3" align="left">
<thead>
<row>
@@ -203,7 +210,7 @@
<para>
<table>
- <title>Example 2</title>
+ <title>Level Inheritance - Example 2</title>
<tgroup cols="3" align="left">
<thead>
<row>
@@ -244,7 +251,7 @@
<para>
<table>
- <title>Example 3</title>
+ <title>Level Inheritance - Example 3</title>
<tgroup cols="3" align="left">
<thead>
<row>
@@ -279,14 +286,14 @@
<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>
+ the levels <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>
+ <title>Level Inheritance - Example 4</title>
<tgroup cols="3">
<thead>
<row>
@@ -320,7 +327,7 @@
</table>
<para>In example 4, the loggers <varname>root</varname> and
- <varname>X</varname> and are assigned the priorities
+ <varname>X</varname> and are assigned the levels
<varname>Proot</varname> and <varname>DEBUG</varname>
respectively. The loggers <varname>X.Y</varname> and
<varname>X.Y.Z</varname> inherits their level (ERROR) from
@@ -349,18 +356,18 @@
<para>By definition, the printing method determines the level of
- a logging request. For example, if <varname>l</varname> is a
+ a logging request. For example, if <varname>x</varname> is a
logger instance, then the statement
- <function>l.info("..")</function> is a logging request of
- priority INFO.
+ <function>x.info("..")</function> is a logging request of
+ priority <emphasis>info</emphasis>.
</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>A logging request is said to be <emphasis>enabled</emphasis>
+ if its level is higher than or equal to the effective level of
+ its logger. Otherwise, the request is said to be
+ <emphasis>disabled</emphasis>. Remember that a logger without an
+ assigned level will inherit one from the hierarchy. This rule is
+ summarized below.
</para>
@@ -370,9 +377,9 @@
<term><emphasis role="strong">Basic Selection Rule</emphasis></term>
<listitem>
- <para>A log request of priority
+ <para>A log request of level
<emphasis>p</emphasis> in a logger with
- inherited priority <emphasis>q</emphasis>, is
+ effective level <emphasis>q</emphasis>, is
enabled if <emphasis> p >= q</emphasis>.
</para>
</listitem>
@@ -381,9 +388,9 @@
</para>
<para >This rule is at the heart of log4j. It is based on the
- ordering of levels. For the standard levels, we the
- following order <varname>DEBUG < INFO < WARN <
- ERROR < FATAL</varname>.
+ ordering of levels. For the standard levels, we have the
+ following ordering <varname>DEBUG < INFO < WARN < ERROR
+ < FATAL</varname>.
</para>
<para>Here is this rule in action.</para>
@@ -394,8 +401,7 @@
Logger cat = Logger.getLogger("com.foo");
// Now set its priority. Normally you do not need to set the
- // priority of a logger progamitcally. This is usually done
- // in configuration files.
+ // level of a logger programatically but rather in a configuration file.
cat.setLevel(Level.INFO);
Logger barcat = Logger.getLogger("com.foo.Bar");
@@ -404,7 +410,7 @@
cat.warn("Low fuel level.");
// This request is disabled, because DEBUG < INFO.
- cat.debug("Starting search for nearest gas station.");
+ cat.debug("Starting search for nearest gas station.");
// The logger instance barcat, named "com.foo.Bar",
// will inherit its priority from the logger named
@@ -417,39 +423,45 @@
</programlisting>
</para>
+ <para>You really should take the time to understand the basic
+ selection rule.</para>
+
+ <sect2>
+ <title>Once only creation</title>
+
<para>Calling the <varname>getLogger</varname> method
with the same name will always return a reference to
the exact same logger object.
</para>
- <para>For example, in
-
- <programlisting>
- Logger x = Logger.getLogger("wombat");
- Logger y = Logger.getLogger("wombat");
- </programlisting>
+ <para>For example, in</para>
+
+ <para><programlisting>
+ Logger x = Logger.getLogger("wombat");
+ Logger y = Logger.getLogger("wombat");</programlisting></para>
+ <para>
<varname>x</varname> and <varname>y</varname> refer to
<emphasis>exactly</emphasis> the same logger object.
</para>
-
+
<para>Thus, it is possible to configure a logger and then to
retrieve the same instance somewhere else in the code without
- passing around references. In contrast to biological
- parenthood, where parents always preceed their children, log4j
- loggers can be created and configured in any order. In
- particular, a "parent" logger will find and link to its
- descendants even if it is instantiated after them.
+ passing around references. In contrast to biological parenthood,
+ where parents always preceed their children, log4j loggers can
+ be created and configured in any order. In particular, a
+ "parent" logger will find and link to its descendants even if it
+ is instantiated after them.
</para>
-
+
<para>Configuration of the log4j environment is typically done
at application initialization. The preferred way is by reading
a configuration file. This approach will be discussed in <xref
- linkend="configuration"/>.
+ linkend="configuration"/>.
</para>
<para>Log4j makes it easy to name loggers by <emphasis>software
- component</emphasis>. This can be accomplished by statically
+ component</emphasis>. This can be accomplished by statically
instantiating a logger in each class, with the logger name
equal to the fully qualified name of the class. This is a
useful and straightforward method of defining loggers. As the
@@ -461,10 +473,10 @@
logger as she wishes.
</para>
- <para>Nevertheless, naming loggers after the class where they
+ <para>Nevertheless, naming loggers after the class where they
are located seems to be the best strategy known so far.</para>
-
- </sect1>
+ </sect2>
+ </sect1>
<sect1>
<title>Appenders and Layouts</title>
1.8 +17 -8 jakarta-log4j/src/docbook/intro.xml
Index: intro.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/intro.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- intro.xml 2001/09/26 08:37:42 1.7
+++ intro.xml 2001/09/27 09:01:21 1.8
@@ -81,6 +81,17 @@
form but not in printed form.. Translations or modifications of
this document require prior written permission.
</para>
+
+ <para>THE DOCUMENT IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
+ AND NONINFRINGEMENT. IN NO EVENT SHALL CEKI GÜLCÜ OR ANY OTHER
+ CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE DOCUMENT OR THE USE OR OTHER
+ DEALINGS IN THE DOCUMENT.
+ </para>
+
</sect1>
<!-- Section ----------------------------------------------------- -->
@@ -113,8 +124,6 @@
in your <varname>CLASSPATH</varname>, we can try to write a small
program that uses log4j.</para>
- <para>Please also see <xref linkend="faq-threadSafe"/>.</para>
-
<example id="MyApp1">
<title>First attempt</title>
<programlisting linenumbering="numbered">
@@ -136,13 +145,10 @@
<para>
Running this example will not produce any logging output but the
following warning.
- <literallayout>
-<computeroutput>
- log4j:ERROR No appenders could be found for logger (chapter1.MyApp1).
- log4j:ERROR Please initialize the log4j system properly.
-</computeroutput>
- </literallayout>
</para>
+ <screen>
+log4j:ERROR No appenders could be found for logger (chapter1.MyApp1).
+log4j:ERROR Please initialize the log4j system properly.</screen>
</note>
<para>Log4j is complaining because we have not configured it just
@@ -224,6 +230,9 @@
</para>
</step>
</procedure>
+
</sect1>
+
+
</chapter>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
