ceki 01/09/20 15:19:07
Modified: src/docbook configuration.xml faq.xml glossary.xml
manual.xml
Added: src/docbook trouble.xml
Log:
Added/merged the trouble shooting guide to docbook manual.
Revision Changes Path
1.5 +4 -0 jakarta-log4j/src/docbook/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/configuration.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- configuration.xml 2001/09/18 22:03:15 1.4
+++ configuration.xml 2001/09/20 22:19:07 1.5
@@ -2,6 +2,10 @@
<title>Configuration</title>
+ <para>
+ disabling from configuration files, duplicates in log
+ </para>
+
<para>Inserting log requests into the application code requires a
fair amount of planning and effort. Observation shows that
approximately 4 percent of code is dedicated to
1.3 +1 -1 jakarta-log4j/src/docbook/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/faq.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- faq.xml 2001/09/19 22:09:10 1.2
+++ faq.xml 2001/09/20 22:19:07 1.3
@@ -1,4 +1,4 @@
- <chapter>
+ <chapter id="faq">
<title>Frequently Asked Questions</title>
<qandaset>
1.4 +1 -1 jakarta-log4j/src/docbook/glossary.xml
Index: glossary.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/glossary.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- glossary.xml 2001/09/19 22:09:10 1.3
+++ glossary.xml 2001/09/20 22:19:07 1.4
@@ -27,7 +27,7 @@
<para>The logging API introduced in JDK 1.4. It is the result of
the <ulink
url="http://jcp.org/aboutJava/communityprocess/review/jsr047/index.html";>JSR47</ulink>
- effort.
+ effort.
</para>
</glossdef>
1.9 +2 -1 jakarta-log4j/src/docbook/manual.xml
Index: manual.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/manual.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- manual.xml 2001/09/10 22:20:29 1.8
+++ manual.xml 2001/09/20 22:19:07 1.9
@@ -5,6 +5,7 @@
<!ENTITY conf SYSTEM "configuration.xml">
<!ENTITY faq SYSTEM "faq.xml">
<!ENTITY glo SYSTEM "glossary.xml">
+<!ENTITY trouble SYSTEM "trouble.xml">
]>
<book lang="en">
@@ -38,8 +39,8 @@
&architecture
&conf
&faq
+ &trouble
&glo
-
</book>
1.1 jakarta-log4j/src/docbook/trouble.xml
Index: trouble.xml
===================================================================
<chapter id="troubleShooting">
<title>Trouble Shooting Guide</title>
<para>
This chapter contains a list of commonly encountered problems
when using log4j.
</para>
<qandaset>
<qandaentry>
<question>
<para>Log4j tells me to initialize properly.</para>
</question>
<answer>
<para>
Logging output is written to a target by using an appender. If no
appenders are attached to a category nor to any of its ancestors, you
will get the following message when trying to log:
</para>
<screen>
log4j: No appenders could be found for category (some.category.name).
log4j: Please initialize the log4j system properly.
</screen>
<para><emphasis>Log4j does not have a default logging
target.</emphasis> It is the user's responsibility to
ensure that all categories can inherit an appender.
This can be easily achieved by attaching an appender to
the root category.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Duplicates in log4j output.</para>
</question>
<answer>
<para>The reason for observing duplicates in log4j output is
either due to having added the same appender multiple
times to the same logger (typically root) or having
added the same appender to different categories ignoring
the fact that appenders are inherited cumulatively.
</para>
<para>Log4j does not eliminate appender duplicates. In other
words, if you add the same appender to a logger
<emphasis>n</emphasis> times, that appender will be
invoked <emphasis>n</emphasis> times to append to its
target.
</para>
<para>A slightly different cause is adding different
appenders all sharing the same underlying output target to
some logger. In the most common occurrence of this
phenomenon, the BasicConfigurator.configure() method is
invoked multiple times. Each time it is invoked, this
method adds an appender with a
<function>System.out</function> target to the root
logger.</para>
<para>One other common mistake is to forget that appenders
are inherited cumulatively from the hierarchy. For
example, if you add an appender, say
<function>A</function>, to the root logger, all other
categories will inherit <function>A</function> as an
appender. Thus, if you add <function>A</function> to a
logger, say <function>L</function>, then an enabled
statement of logger <function>L</function>, will print to
<function>A</function> twice, once because
<function>A</function> is in root and once because it is
in <function>L</function>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Caller location information is printed as a "?"
character.</para>
</question>
<answer>
<para>Location information is extracted automatically by the
PatternLayout conversion patterns %C, %F, %M and
%L. However, some just-in-time (JIT) compilers make it
impossible to extract location information. It is also
possible that the compiler that generated the byte code
may have omitted the LineNumber table as is done by -O
option of javac and jikes.
</para>
<para>You can remedy this problem by disabling the JIT compiler and by
compiling the code without the -O option.
</para>
<para>Wrappers or subclasses of Logger constiture a special
case.</para>
<para>Wrappers or subclasses of <function>Logger</function>
need supply their fully qualified class name to the
<function>Logger.log</function> method or to
<function>Logger.forcedLog</function> methods so that the
caller location information can be extracted correctly.
</para>
<para>This approach will work correctly in all cases except
if the class invoking the extended logger instance has the
same prefix as the extended logger class. For example,
calling an instance of
<function>com.foo.BarLogger</function> from the
<function>com.foo.BarLoggerTest</function> class will not
yield the correct caller information. To circumvent this
"bug", either perform the tests from a class with a
different name or add a dot to the fully qualified name of
the extending class that you supply to
<function>Loggerlog</function> to
<function>Logger.forcedLog</function> methods. For the
<function>com.foo.BarLogger</function> example, supply the
string <function>"com.foo.BarLogger."</function>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<function>ClassCastException</function> when instantiating
<function>Logger</function> subclasses.
</question>
<answer>
<para>This exception is thrown because log4j does not
support homonyms. For example, the following will
systematically throw a <function>ClassCastException</function>
<programlisting>
Logger c1 = Logger.getLogger("bad");
MyLogger c2 = (MyLogger) MyLogger.getLogger("bad");
</programlisting>
where <function>MyLogger</function> is a subclass of
<function>Logger</function>. The problem occurs because the
second <function>getInstance</function> invocation will retrieve
the Logger created in the fist invocation. This instance
is a <function>Logger</function> object and cannot be cast to
<function>MyLogger</function>. </para>
<para>By default, the <function>PropertyConfigurator</function> will
create and configure <function>org.apache.log4j.Logger</function>
objects. Thus, if you try to instantiate a Logger subclass
for an already existing logger, and try to cast it to the
subclass type, you will systematically get a
<function>ClassCastException</function>.</para>
<para>To address this problem, the
<function>PropertyConfigurator</function> admits the
<function>log4j.loggerFactory</function> key. The value of this
key will be used as the factory to invoke when
instantiating Logger objects.</para>
<para>The <function>DOMConfigurator</function> has a finer grain
method for setting the class of the logger object to
instantiate.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
</question>
<answer>
</answer>
</qandaentry>
</qandaset>
</chapter>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
