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/11/27 00:55:36 UTC
cvs commit: jakarta-log4j/src/docbook configuration.xml wider.xml
ceki 01/11/26 15:55:36
Modified: src/docbook configuration.xml wider.xml
Log:
More documentation.
Revision Changes Path
1.16 +160 -14 jakarta-log4j/src/docbook/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/configuration.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- configuration.xml 2001/11/22 21:03:41 1.15
+++ configuration.xml 2001/11/26 23:55:36 1.16
@@ -207,6 +207,10 @@
</para>
</sect1>
+ <!-- ================================================================ -->
+ <!-- DOMConfigurator equivalent ===================================== -->
+ <!-- ================================================================ -->
+
<sect1>
<title><classname>DOMConfigurator</classname> equivalent</title>
@@ -271,9 +275,13 @@
<para></para>
</sect1>
+ <!-- ================================================================ -->
+ <!-- Filtering by logger and by request level (PropertyConfigurator) -->
+ <!-- ================================================================ -->
+
<sect1>
<title>Filtering by logger and by request level
- <classname>PropertyConfigurator</classname></title>
+ (<classname>PropertyConfigurator</classname>)</title>
<para>As was mentioned earlier, one the important features of any
logging library is its support for filtering logging messages
@@ -325,6 +333,10 @@
suppressed.</para>
</sect1>
+
+ <!-- ================================================================ -->
+ <!-- Filtering by logger and by request level (DOMConfigurator) ===== -->
+ <!-- ================================================================ -->
<sect1>
<title>Filtering by logger and by request level (<classname>DOMConfigurator</classname>)</title>
@@ -360,9 +372,13 @@
</para>
</sect1>
+ <!-- ================================================================ -->
+ <!-- Filtering by Appender and by request level (PropertyConfigurator) -->
+ <!-- ================================================================ -->
+
<sect1 id="thresholdFiltering">
<title>Filtering by Appender and by request level
- (<classname>(PropertyConfigutaor</classname>)</title>
+ (<classname>PropertyConfigutaor</classname>)</title>
<para>Setting the <emphasis role="bold">Threshold</emphasis> option
of any appender extending AppenderSkeleton, (most log4j
@@ -413,6 +429,10 @@
events by exact level match.</para>
</sect1>
+ <!-- ================================================================ -->
+ <!-- Filtering by Appender and by request level (DOMConfigurator) -->
+ <!-- ================================================================ -->
+
<sect1>
<title>Filtering by Appender and by request level
(<classname>DOMConfigurator</classname>)</title>
@@ -442,6 +462,10 @@
</programlisting>
</sect1>
+ <!-- ================================================================ -->
+ <!-- Multiple appenders (PropertyConfigurator) ===================== -->
+ <!-- ================================================================ -->
+
<sect1>
<title>Multiple appenders (<classname>PropertyConfigurator</classname>)</title>
@@ -498,6 +522,10 @@
</para>
</sect1>
+ <!-- ================================================================ -->
+ <!-- Multiple appenders (DOMConfigurator) ========================== -->
+ <!-- ================================================================ -->
+
<sect1>
<title>Multiple Appenders (<classname>DOMConfigurator</classname>)</title>
<para>
@@ -536,13 +564,140 @@
</para>
</sect1>
+ <!-- ================================================================ -->
+ <!-- Reloading configuration files ========================== -->
+ <!-- ================================================================ -->
<sect1>
- <title>Reloading configuration files</title>
- <para>Effect on categories, effect on appenders</para>
- <para>Give an example</para>
+ <title>Reloading configuration files</title>
+
+ <para>Reloading of a configuration file or reconfiguration of
+ log4j from a different configuration file is allowed and is also
+ thread safe. The crucial point to rememeber is that invoking any
+ of the log4j configurators does <emphasis>not</emphasis> reset
+ the previous configuration however reconfiguration has obviously
+ some effect on the existing configuration. In particular, all
+ appenders of any logger excplicitly mentioned in the new
+ confuration will be closed and removed from the
+ logger. Appenders attached to loggers not mentioned in the new
+ configuration file remain untouched. If an appender is attached
+ to multiple loggers, then it is possible for the appender to be
+ closed during the reconfiguration but remain attached to a
+ logger not mentioned in the secod configuration file. In this
+ case, log4j will warn you about trying to log to a closed
+ appender.
+ </para>
+
+ <example><title>First configuration file</title></example>
+<screen>
+ <?xml version="1.0" encoding="UTF-8" ?>
+ <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
+
+ <log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
+
+ <appender name="A1" class="org.apache.log4j.FileAppender">
+ <param name="File" value="A1.log">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%r %p [%t] %c - %m%n"/>
+ </layout>
+ </appender>
+
+ <appender name="A2" class="org.apache.log4j.FileAppender">
+ <param name="File" value="A2.log">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%r %p [%t] %c - %m%n"/>
+ </layout>
+ </appender>
+
+ <logger name="com.foo">
+ <appender-ref ref="A2" />
+ </logger>
+
+ <logger name="com.wombat">
+ <appender-ref ref="A2" />
+ </logger>
+
+ <root>
+ <priority value ="debug" />
+ <appender-ref ref="A1" />
+ </root>
+
+ </log4j:configuration>
+</screen>
+
+ <para>The first configuration file defines an appender A1 attached
+ to the root logger, a second appender A2 is attached to loggers
+ "com.foo" and "com.wombat".
+ </para>
+
+ <example><title>Second configuration file</title></example>
+<screen>
+ <?xml version="1.0" encoding="UTF-8" ?>
+ <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
+
+ <log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
+
+ <appender name="A1" class="org.apache.log4j.FileAppender">
+ <param name="File" value="A1.log">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%r %p [%t] %c - %m%n"/>
+ </layout>
+ </appender>
+
+ <logger name="com.foo">
+ <level value=WARN">
+ </logger>
+
+ <root>
+ <priority value ="debug" />
+ <appender-ref ref="A1" />
+ </root>
+
+ </log4j:configuration>
+</screen>
+
+ <para>When the second configuration file is run by the
+ <classname>DOMConfigurator</classname>, since the root logger is
+ mentioned in the second file, all the appenders in the root are
+ closed and then removed from the root logger. A new appender
+ called A1 is intantiated, configured and attached to root.</para>
+
+ <para>Logger <classname>com.foo</classname> is mentioned in the
+ second configuration file. Consequently, A2 will be closed and
+ removed from <classname>com.foo</classname>. However, it will
+ remain attached to <classname>com.wombat</classname>. Trying to
+ log with <classname>com.wombat</classname> logger will cause log4j
+ to emit a warning.
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Error handlers</title>
+ <para></para>
+ </sect1>
+
+
+
+ <sect1 id="configuringFilters">
+ <title>Filters</title>
+ <para></para>
</sect1>
+ <sect1>
+ <title>Multiple applications or libraries sharing a log4j
+ configuration files</title>
+
+
+ <para>Log4j configuration is the responsibility of the end-user or
+ generally the application deployer. Whenever possible, a library
+ should not try to configure logging but leave it to the
+ deployer. After all, logging output is useful only if someone will
+ take the time to look at them. If the end-user wishes to log then
+ she should control the logging configuration. Nevertheless, it is
+ very helpful if the library develop-per provides documentation on
+ logging preferably with working examples.
+ </para>
<sect1>
<title>SMTPAppender</title>
@@ -556,16 +711,7 @@
<para>Talk about EJB implications</para>
<para>Give an example</para>
</sect1>
-
- <sect1 id="configuringFilters">
- <title>Filters</title>
- <para></para>
- </sect1>
- <sect1>
- <title>Error handlers</title>
- <para></para>
- </sect1>
<sect1>
<title>SocketAppender</title>
1.2 +74 -75 jakarta-log4j/src/docbook/wider.xml
Index: wider.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/wider.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- wider.xml 2001/09/26 10:42:08 1.1
+++ wider.xml 2001/11/26 23:55:36 1.2
@@ -1,82 +1,80 @@
<chapter id="wider">
- <title>The wider picture</title>
-
- <para>The intended audience of chapter are the authors of
+ <title>The wider picture</title>
+
+ <para>The intended audience of chapter are the authors of
Application Servers, Servlet Containers and authors of general
purpose libraries.</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. Similiarly, under JDK 1.2 we may can use a
+ Logger implementation that is aware of the Java2 security model
+ whereas under JDK 1.1 use a logger implementation may be oblivious
+ to Java2 security checks. In shipped code, LogManager may be
+ configured to return a <classname>NullLogger</classname> which
+ could sub-class Logger with empty method bodies.
+ </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 compose well with a
+ library which uses log4j but is unaware of multiple
+ hierarchies. In log4j 1.2, a more powerful API was introduced to
+ manage logger creation and retrieval.
+ </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. Similiarly, under JDK 1.2 we
- may can use a Logger implementation that is aware of the Java2
- security model whereas under JDK 1.1 use a logger implementation
- may be oblivious to Java2 security checks. In shipped code,
- LogManager may be configured to return a
- <classname>NullLogger</classname> which could sub-class Logger
- with empty method bodies.
+ <sect1>
+ <title>LogManager</title>
+
+ <para>The <ulink
+ url="../api/org/apache/log4j/LogManager.html">LogManager</ulink>
+ acts as a facade to a sub-system that retrieves
+ <classname>Logger</classname> instances of <emphasis>varying
+ types</emphasis> held in <emphasis>context-dependent
+ repositories</emphasis>.
</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>From the users perspective, LogManager allows us to vary
+ Logger implementation depending on the
+ circumstances. Moreover, it controls the logging repository
+ (i.e. hierarchy) where loggers are held depending on the
+ application context.
</para>
-
- <para>Using multiple hierarchies works well with code that is
- designed to use them. However, it does not compose well with a
- library which uses log4j but is unaware of multiple
- hierarchies. In log4j 1.2, a more powerful API was introduced to
- manage logger creation and retrieval.
+
+ <para>The behavior of LogManager is determined by the <ulink
+ url="../api/org/apache/log4j/spi/RepositorySelector.html">RepositorySelector</ulink>
+ it uses.
</para>
-
- <sect1>
- <title>LogManager</title>
-
- <para>The <ulink
- url="../api/org/apache/log4j/LogManager.html">LogManager</ulink>
- acts as a facade to a sub-system that retrieves
- <classname>Logger</classname> instances of <emphasis>varying
- types</emphasis> held in <emphasis>context-dependent
- repositories</emphasis>.
- </para>
-
- <para>From the users perspective, LogManager allows us to vary
- Logger implementation depending on the
- circumstances. Moreover, it controls the logging repository
- (i.e. hierarchy) where loggers are held depending on the
- application context.
- </para>
-
- <para>The behavior of LogManager is determined by the <ulink
- url="../api/org/apache/log4j/spi/RepositorySelector.html">RepositorySelector</ulink>
- it uses.
- </para>
-
- <para>At a given instance, the <classname>LogManager</classname>
+
+ <para>At a given instance, the <classname>LogManager</classname>
will use one and only one
<classname>RepositorySelector</classname> implementation. The
particular implementation can be set using the <ulink
- url="../api/org/apache/log4j/LogManager.html#setRepositorySelector(org.apache.log4j.spi.RepositorySelector, java.lang.Object)">LogManager.setRepositorySelector</ulink>
+ url="../api/org/apache/log4j/LogManager.html#setRepositorySelector(org.apache.log4j.spi.RepositorySelector, java.lang.Object)">LogManager.setRepositorySelector</ulink>
method. Once set, changing the repository selector requires a
guard.</para>
-
- <para>By default, log4j uses a very simple repository selector
+
+ <para>By default, log4j uses a very simple repository selector
which always returns the same logger repository regardless of
application context. However, a top-level application such as an
Application Server, e.g. JBoss, can set a
@@ -98,13 +96,14 @@
url="../api/org/apache/log4j/spi/LoggerRepository.html">LoggerRepository</ulink>
acts on a set of Loggers. It can be used to instante and
retreive them by name.
- </para>
+ </para>
- <para>One of the distinctive feature of log4j is its ability to
- arrange loggers in a hierarchy. A hierarchy is merely a
- repository of categories which happens to arrange them in a
- tree like structure.
- </para>
- </sect1>
-
+ <para>One of the distinctive feature of log4j is its ability to
+ arrange loggers in a hierarchy. A hierarchy is merely a
+ repository of categories which happens to arrange them in a
+ tree like structure.
+ </para>
+ </sect1>
+
+
</chapter>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>