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/10/01 23:14:54 UTC
cvs commit: jakarta-log4j/src/docbook defaultInit.xml architecture.xml changes.xml configuration.xml intro.xml manual.xml
ceki 01/10/01 14:14:54
Modified: src/docbook architecture.xml changes.xml configuration.xml
intro.xml manual.xml
Added: src/docbook defaultInit.xml
Log:
More examples in doc.
Revision Changes Path
1.13 +1 -1 jakarta-log4j/src/docbook/architecture.xml
Index: architecture.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/architecture.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- architecture.xml 2001/09/28 15:30:54 1.12
+++ architecture.xml 2001/10/01 21:14:54 1.13
@@ -589,7 +589,7 @@
any time.</para>
<sect2 id="additivityRule" xreflabel="Appender Additivity Rule">
- <title>Appedner Additivity</title>
+ <title>Appender Additivity</title>
<para>The <ulink
url="../api/org/apache/log4j/Category.html#addAppender(org.apache.log4j.Appender)">addAppender</ulink>
1.5 +95 -32 jakarta-log4j/src/docbook/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/changes.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- changes.xml 2001/09/28 15:30:54 1.4
+++ changes.xml 2001/10/01 21:14:54 1.5
@@ -11,15 +11,17 @@
</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.
+ <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 <emphasis>extends</emphasis> the
+ Category class such that it is always possible to use a logger
+ object where a category object is expected. In addition,
+ whenever log4j is asked to produce a
+ <classname>Category</classname> object, it will instead produce
+ a <classname>Logger</classname> object. Methods that previously
+ accepted category objects will continue to accept them.
</para>
<para>For example, the following are all legal and will work as
@@ -36,26 +38,71 @@
</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>
+ refer to the <classname>Category</classname> class in newly
+ written code. Please avoid referring to it or using it. It is
+ important to note that the introduction of the
+ <classname>Logger</classname> class is backward
+ compatible. You can still use the older
+ <classname>Category</classname> class in your existing code,
+ just avoid writing new code using it.
+ </para>
+
+ <para>You may contend that having <classname>Logger</classname>
+ extend <classname>Category</classname> is unintuitive -- in
+ particular because the <classname>Logger</classname> class is
+ almost empty and relies entirely on the
+ <classname>Category</classname> class for its
+ implementation. Don't be fooled by the appearances. The
+ <classname>Category</classname> class will eventually be removed
+ and most of its contents transferred to
+ <classname>Logger</classname>.</para>
+
+ </sect2>
+ <sect2>
+ <title>Compatibility issues with <classname>Category</classname>
+ sub-classes</title>
- <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>For most users the introduction of the Logger class is
+ fully backward compatible. However, if you have sub-classed
+ the Category class, then you need to heed the following
+ points.</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>
+ <itemizedlist>
+ <listitem>
+ <para>Sub-classes of Category <emphasis>must</emphasis>
+ extend <classname>org.apache.log4j.Logger</classname> and
+ not <classname>org.apache.log4j.Category</classname>.
+ </para>
+ </listitem>
+
+ <listitem> <para>The
+ <classname>org.apache.log4j.spi.CategoryFactory</classname>
+ class has been removed. It has been replaced with the
+ <classname>org.apache.log4j.spi.LoggerFactory</classname>
+ class. Thus, your subclass' factory must be of type
+ <classname>LoggerFactory</classname>.
+ </para>
+ </listitem>
+
+ <listitem><para>The <function>Category.getInstance(String,
+ CategoryFactory)</function> method has been removed. You
+ need to invoke the <function>LogManager.getLogger(String,
+ LoggerFactory)</function> method to create loggers of your
+ subclass type.
+ </para>
+
+ </listitem>
+
+ <listitem><para> In configuration scripts parsed by
+ <classname>PropertyConfigurator</classname> the
+ <varname>log4j.categoryFactory</varname> keyword has been
+ replaced with <varname>log4j.loggerFactory</varname>.</para>
+ </listitem>
+ </itemizedlist>
+
+
<para>We also strongly recommend against sub-classing Logger (or
Category) to introduce new printing methods, you can use the
general purpose <ulink
@@ -65,12 +112,28 @@
</sect2>
<sect2>
- <title>Level instead of Priority</title>
+ <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.
+ <classname>Priority</classname> class has been replaced by the
+ <classname>Level</classname> class. Level
+ <emphasis>extends</emphasis> Priority. Whenever log4j is asked
+ to produce a <classname>Priority</classname> object, it will
+ instead produce a <classname>Level</classname> object. The
+ constants <varname>Priority.FATAL</varname>,
+ <varname>Priority.ERROR</varname>,
+ <varname>Priority.WARN</varname>,
+ <varname>Priority.INFO</varname>,
+ <varname>Priority.DEBUG</varname> are now of type
+ <classname>Level</classname>. However, this should be
+ transparent to all log4j users.
+ </para>
+
+ <para>The <function>Priority.getPriority()</function> family of
+ methods returning Priority, have been replaced with the
+ <function>Priority.getLevel()</function> family of methods
+ returning a <classname>Level</classname>. This implies that
+
</para>
</sect2>
@@ -89,8 +152,8 @@
<para>
In the <classname>Hierarchy</classname> class The
<function>disable</function> family of methods have been
- removed and replaced by <function>setThresold</function> and
- <function>getThresold</function> methods. This change is not
+ removed and replaced by <function>setThreshold</function> and
+ <function>getThreshold</function> methods. This change is not
backward compatible.
</para>
</sect2>
1.9 +224 -359 jakarta-log4j/src/docbook/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/configuration.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- configuration.xml 2001/09/28 13:37:47 1.8
+++ configuration.xml 2001/10/01 21:14:54 1.9
@@ -29,24 +29,24 @@
import com.foo.Bar;
// Import log4j classes.
- import org.apache.log4j.Category;
+ import org.apache.log4j.Logger;
import org.apache.log4j.BasicConfigurator;
public class MyApp {
// Define a static category variable so that it references the
- // Category instance named "MyApp".
- static Category cat = Category.getInstance(MyApp.class);
+ // Logger instance named "MyApp".
+ static Logger logger = Logger.getLogger(MyApp.class);
public static void main(String[] args) {
// Set up a simple configuration that logs on the console.
BasicConfigurator.configure();
- cat.info("Entering application.");
+ logger.info("Entering application.");
Bar bar = new Bar();
bar.doIt();
- cat.info("Exiting application.");
+ logger.info("Exiting application.");
}
}
</programlisting>
@@ -54,7 +54,7 @@
<para><classname>MyApp</classname> begins by importing log4j related
- classes. It then defines a static category variable with the name
+ classes. It then defines a static logger variable with the name
<classname>MyApp</classname> which happens to be the fully
qualified name of the class.
</para>
@@ -66,30 +66,31 @@
<para>
<programlisting>
<emphasis role="bold">package com.foo;</emphasis>
- import org.apache.log4j.Category;
+ import org.apache.log4j.Logger;
public class Bar {
- static Category cat = Category.getInstance(Bar.class);
+ static final Logger logger = Logger.getInstance(Bar.class);
public void doIt() {
- cat.debug("Did it again!");
+ logger.debug("Did it again!");
}
}
</programlisting>
</para>
<para>The invocation of the <ulink
- url="api/org/apache/log4j/BasicConfigurator.html#configure()">BasicConfigurator.configure</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 <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>
+ hardwired to add to the root logger 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
- <classname>Priority.DEBUG</classname>. </para>
+ <para>Note that by default, the root logger is assigned to
+ <classname>Level.DEBUG</classname>. </para>
<para>The output of MyApp is:
<screen>
@@ -107,38 +108,42 @@
<!-- <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
+ <para>As a side note, let me mention that in log4j child loggers
+ link only to their existing ancestors. In particular, the logger
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
+ <classname>root</classname> logger, thereby circumventing the unused
+ <classname>com</classname> or <classname>com.foo</classname> loggers. This
significantly increases performance and reduces log4j's memory
footprint.
</para>
<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.
+ only need to import the <classname>org.apache.log4j.Logger</classname>
+ class, retrieve the loggers they wish to use, and log away.
</para>
-
- <para>The previous example always outputs the same log information.
- 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>
-
- <para>
- <programlisting>
+
+ <sect1>
+ <title><classname>BasicConfigurator</classname> equivalent using
+ <classname>PropertyConfigurator</classname></title>
+
+ <para>The previous example always outputs the same log information.
+ 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>
+
+ <para>
+ <programlisting>
import com.foo.Bar;
- import org.apache.log4j.Category;
- <emphasis role="bold">import org.apache.log4j.PropertyConfigurator;</emphasis>
+ import org.apache.log4j.Logger;
+ <emphasis role="strong">import org.apache.log4j.PropertyConfigurator;</emphasis>
public class MyApp {
- static Category cat = Category.getInstance(MyApp.class.getName());
+ static Logger cat = Logger.getInstance(MyApp.class.getName());
public static void main(String[] args) {
@@ -155,20 +160,21 @@
</programlisting>
</para>
- <para>This version of <classname>MyApp</classname> instructs
+ <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 <classname>BasicConfigurator</classname> based
- example.
- </para>
-
- <para>
- <screen>
-# Set root category priority to DEBUG and its only appender to A1.
-log4j.rootCategory=DEBUG, A1
+ and set up logging accordingly.
+ </para>
+
+ <para>Here is a sample configuration file that results in exactly
+ same output as the previous <classname>BasicConfigurator</classname> based
+ example.
+ </para>
+
+ <para>
+ <example><title>BasicConfigurator equivalent configuration file</title>
+ <screen>
+# Set root logger priority to DEBUG and its only appender to A1.
+log4j.rootLogger=DEBUG, A1
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender
@@ -176,25 +182,88 @@
# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
- </screen>
- </para>
+ </screen>
+ </example>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>DOMConfigurator equivalent</title>
+
+ <para>As mention previously, log4j also supports configuration
+ files written in XML. These configuration files are parsed with
+ <classname>org.apache.log4j.xml.DOMConfigurator</classname>. Here
+ is how.
+ </para>
+
+ <para>
+ <programlisting>
-<!-- <para>Please note that if you copy and paste the examples, then result is
-likely to include trailing spaces on some lines. These trailing spaces
-are not trimmed out but interpreted by the PropertyConfigurator. By
-the time you read this article the problem should be corrected.
--->
-
- <para>Suppose we are no longer interested in seeing the output of
- any component belonging to the <classname>com.foo</classname> package. The
- following configuration file shows one possible way of achieving
- this.
+ import com.foo.Bar;
+
+ import org.apache.log4j.Logger;
+ <emphasis role="strong">import org.apache.log4j.xml.DOMConfigurator;</emphasis>
+
+ public class MyApp {
+
+ static Logger cat = Logger.getInstance(MyApp.class.getName());
+
+ public static void main(String[] args) {
+
+ DOMConfigurator.configure(args[0]);
+
+ cat.info("Entering application.");
+ Bar bar = new Bar();
+ bar.doIt();
+ cat.info("Exiting application.");
+ }
+ }
+ </programlisting>
</para>
+
+ <para>
+ <example><title>XML equivalent configuration file</title>
+ <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="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+
+ <root>
+ <priority value ="debug" />
+ <appender-ref ref="STDOUT" />
+ </root>
+
+</log4j:configuration>
+
+ </screen>
+ </example>
+ </para>
+
+
+ <para></para>
+ </sect1>
-<para>
-<programlisting>
+ <sect1>
+ <title>Filtering by logger level</title>
+
+ <para>Suppose we are no longer interested in seeing the output of
+ any component belonging to the <classname>com.foo</classname> package. The
+ following configuration file shows one possible way of achieving
+ this.
+ </para>
+
+ <para>
+ <screen>
-log4j.rootCategory=DEBUG, A1
+log4j.rootLogger=DEBUG, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
@@ -202,9 +271,9 @@
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.
-<emphasis role="bold">log4j.category.com.foo=WARN</emphasis>
- </programlisting>
- </para>
+<emphasis role="bold">log4j.logger.com.foo=WARN</emphasis>
+ </screen>
+ </para>
<para>The output of <classname>MyApp</classname> configured with this file is shown below.
</para>
@@ -215,21 +284,61 @@
MyApp - Exiting application.
</screen>
- <para>As the category <classname>com.foo.Bar</classname> does not have an
+ <para>As the logger <classname>com.foo.Bar</classname> does not have an
assigned priority, it inherits its priority from
<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
+ the priority DEBUG, lower than the logger priority
WARN. Consequently, <classname>doIt()</classname> method's log request is
suppressed.</para>
+ </sect1>
+
+ <sect1>
+ <title>Filtering by logger level using <classname>DOMConfigurator</classname></title>
+
+ <para>
+ <example><title>XML equivalent configuration file</title>
+ <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="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+
+ <logger name="com.foo">
+ <level value=WARN">
+ </logger>
+
+ <root>
+ <priority value ="debug" />
+ <appender-ref ref="STDOUT" />
+ </root>
+
+</log4j:configuration>
+
+ </screen>
+ </example>
+ </para>
+ </sect1>
+
+
+ <sect1>
+ <title>Multiple appenders</title>
+
<para>Here is another configuration file that uses multiple
appenders.</para>
<para>
<programlisting>
-log4j.rootCategory=debug, <emphasis role="bold">stdout, R</emphasis>
+log4j.rootLogger=debug, <emphasis role="bold">stdout, R</emphasis>
log4j.appender.<emphasis role="bold">stdout</emphasis>=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
@@ -259,7 +368,7 @@
INFO [main] (MyApp2.java:15) - Exiting application.
</screen>
- <para>In addition, as the root category has been allocated a second
+ <para>In addition, as the root logger has been allocated a second
appender, output will also be directed to the
<classname>example.log</classname> file. This file will be rolled over when
it reaches 100KB. When roll-over occurs, the old version of
@@ -274,8 +383,49 @@
log4j server, which would log according to local server policy,
for example by forwarding the log event to a second log4j server.
</para>
+ </sect1>
<sect1>
+ <title>Multiple Appenders using <classname>DOMConfigurator</classname>
+ <para>
+ <example><title>XML equivalent configuration file</title>
+ <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="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+
+ <appender name="R" class="org.apache.log4j.RollingFileAppender">
+ <param name="MaxFileSize" value="100KB">
+ <param name="MaxBackupIndex" value="1">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%p %t %c - %m%n"/>
+ </layout>
+ </appender>
+
+ <root>
+ <priority value ="debug" />
+ <appender-ref ref="STDOUT" />
+ </root>
+
+</log4j:configuration>
+
+ </screen>
+ </example>
+ </para>
+ </sect1>
+
+ </sect1>
+
+ <sect1>
<title>Directing log output to different appenders depending on level</title>
<para>Setting the <emphasis role="bold">Threshold</emphasis> option
@@ -305,306 +455,21 @@
events by exact priority match.</para>
</sect1>
- <sect1 id="defaultInit">
- <title>Default Initialization Procedure</title>
- <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 <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
- to remember that different classloaders may load distinct copies
- of the same class. These copies of the same class are considered
- as totally unrelated by the JVM.
- </para>
-
- <para>The default initialization is very useful in environments
- where the exact entry point to the application depends on the
- runtime environment. For example, the same application can be
- used as a stand-alone application, as an applet, or as a servlet
- under the control of a web-server.
- </para>
-
- <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 <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>
-
- <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>
-
- </procedure>
-
- </sect1>
<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
-
- <computeroutput>
- export TOMCAT_OPTS="-Dlog4j.debug -Dlog4j.configuration=foobar.xml"
- </computeroutput>
-
- 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
- </computeroutput>
-
- 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>
-
- </sect2>
- </sect1>
-
- <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;
-
- 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>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>
-
- <init-param>
- <param-name>log4j-init-file</param-name>
- <param-value>WEB-INF/classes/log4j.lcf</param-value>
- </init-param>
-
- <emphasis role="bold"><load-on-startup>1</load-on-startup></emphasis>
- </servlet>
- </programlisting>
- </para>
-
- <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>
- </sect1>
-
- <sect1>
<title>SMTPAppender</title>
<para>Requires activation.jar, mail.jar. </para>
<para>Talk about triggering mechanism</para>
<para>Give an example</para>
</sect1>
-
<sect1>
- <title>DOMConfigurator</title>
- <para></para>
+ <title>AsyncAppender</title>
+ <para>Talk about EJB implications</para>
+ <para>Give an example</para>
</sect1>
-
+
<sect1>
<title>Filters</title>
<para></para>
@@ -616,7 +481,7 @@
</sect1>
<sect1>
- <title>Category Factories</title>
+ <title>Logger Factories</title>
<para></para>
</sect1>
1.10 +16 -8 jakarta-log4j/src/docbook/intro.xml
Index: intro.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/intro.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- intro.xml 2001/09/28 13:37:47 1.9
+++ intro.xml 2001/10/01 21:14:54 1.10
@@ -82,16 +82,24 @@
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>THIS PUBLICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
+ KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+ THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+ PARTICULAR PURPOSE, OR NON-INFRINGEMENT. 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>
+ <para>THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR
+ TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE
+ INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW
+ EDITIONS OF THE PUBLICATION. THE AUTHORS MAY MAKE IMPROVEMENTS
+ AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED
+ IN THIS PUBLICATION AT ANY TIME.
+ </para>
</sect1>
<!-- Section ----------------------------------------------------- -->
1.13 +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.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- manual.xml 2001/09/28 13:37:47 1.12
+++ manual.xml 2001/10/01 21:14:54 1.13
@@ -3,6 +3,7 @@
<!ENTITY intro SYSTEM "intro.xml">
<!ENTITY architecture SYSTEM "architecture.xml">
<!ENTITY conf SYSTEM "configuration.xml">
+<!ENTITY defaultInit SYSTEM "defaultInit.xml">
<!ENTITY wider SYSTEM "wider.xml">
<!ENTITY changes SYSTEM "changes.xml">
<!ENTITY faq SYSTEM "faq.xml">
@@ -35,6 +36,7 @@
&intro
&architecture
&conf
+ &defaultInit
&wider
&changes
&faq
1.1 jakarta-log4j/src/docbook/defaultInit.xml
Index: defaultInit.xml
===================================================================
<chapter id="defaultInit">
<title>Default Initialization Procedure</title>
<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 <classname>Logger</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
to remember that different classloaders may load distinct copies
of the same class. These copies of the same class are considered
as totally unrelated by the JVM.
</para>
<para>The default initialization is very useful in environments
where the exact entry point to the application depends on the
runtime environment. For example, the same application can be
used as a stand-alone application, as an applet, or as a servlet
under the control of a web-server.
</para>
<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,
Logger.class)</classname> which returns a URL. Note that the string
"log4j.properties" constitutes a malformed URL.
</para>
<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>
<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>
</procedure>
<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
<computeroutput>
export TOMCAT_OPTS="-Dlog4j.debug -Dlog4j.configuration=foobar.xml"
</computeroutput>
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
</computeroutput>
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>
</sect2>
</sect1>
<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;
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>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>
<init-param>
<param-name>log4j-init-file</param-name>
<param-value>WEB-INF/classes/log4j.lcf</param-value>
</init-param>
<emphasis role="bold"><load-on-startup>1</load-on-startup></emphasis>
</servlet>
</programlisting>
</para>
<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>
</chapter>
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: log4j-cvs-help@jakarta.apache.org