ceki 01/09/06 15:40:39
Modified: src/java/org/apache/log4j Category.java Hierarchy.java
Logger.java MDC.java PropertyConfigurator.java
src/java/org/apache/log4j/xml DOMConfigurator.java
src/sgml intro.sgml manual.sgml
Log:
- Added getLogger and getRootLogger static methods to Logger class.
- Javadoc changes.
- Docbook changes.
Revision Changes Path
1.50 +33 -8 jakarta-log4j/src/java/org/apache/log4j/Category.java
Index: Category.java
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/java/org/apache/log4j/Category.java,v
retrieving revision 1.49
retrieving revision 1.50
diff -u -r1.49 -r1.50
--- Category.java 2001/09/05 08:33:11 1.49
+++ Category.java 2001/09/06 22:40:39 1.50
@@ -44,12 +44,37 @@
/**
- This is the central class in the log4j package. One of the
- distintive features of log4j are hierarchical categories and their
- evaluation.
+ <font color="#AA2222"><b>This class has been deprecated and
+ replaced by the {@link Logger} <em>subclass</em>.</b></font> It
+ will be kept around to preserve backward compatibility until early
+ 2003.
+
+ <p><code>Logger</code> is a subclass of Category, i.e. it extends
+ Category. In other words, a logger <em>is</em> a category. Thus,
+ all operations that can be performed on a category can be performed
+ on a logger. Whenever log4j is asked to produce a Category object,
+ it will instead produce a Logger object. However, methods that
+ previously accepted cateogry objects still continue to accept
+ category objects.
+
+ <p>For example, the following are all legal and will work as expected.
+
+ <pre>
+ // Deprecated forms:
+ Category cat = Category.getInstance("foo.bar")
+ Logger logger = Logger.getInstance("foo.bar")
+ Category cat = Logger.getLogger("foo.bar")
+
+ // Preferred form for retrieving loggers:
+ Logger logger = Logger.getLogger("foo.bar")
+ </pre>
- <p>See the <a href="../../../../manual.html">user manual</a> for an
- introduction on this class.
+ <p>The first tree forms are deprecated and should be avoided.
+
+ <p><b>There is absolutely no need for new client code to use or
+ refer to the <code>Category</code> class.</b> Please avoid
+ referring to it.
+
@author Ceki Gülcü
@author Anders Kristensen */
@@ -596,7 +621,7 @@
it from the hierarchy. This is one of the central features of
log4j.
- @deprecated Please use {@link LogManager#getLogger(String)} instead.
+ @deprecated Please use {@link Logger#getLogger(String)} instead.
@param name The name of the category to retrieve. */
public
@@ -612,7 +637,7 @@
name of the category to retrieve. See {@link
#getInstance(String)} for more detailed information.
- @deprecated Please use {@link LogManager#getLogger(Class)} instead.
+ @deprecated Please use {@link Logger#getLogger(Class)} instead.
@since 1.0 */
public
@@ -698,7 +723,7 @@
Category.getInstance("root")} does not retrieve the root category
but a category just under root named "root".
- @deprecated Use {@link LogManager#getRootLogger()} instead.
+ @deprecated Use {@link Logger#getRootLogger()} instead.
*/
final
public
1.32 +49 -55 jakarta-log4j/src/java/org/apache/log4j/Hierarchy.java
Index: Hierarchy.java
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/java/org/apache/log4j/Hierarchy.java,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- Hierarchy.java 2001/09/05 06:45:28 1.31
+++ Hierarchy.java 2001/09/06 22:40:39 1.32
@@ -34,17 +34,16 @@
import org.apache.log4j.helpers.OptionConverter;
/**
- This class is specialized in retrieving categories by name and
- also maintaining the category hierarchy.
+ This class is specialized in retrieving loggers by name and also
+ maintaining the logger hierarchy.
- <p><em>The casual user should not have to deal with this class
- directly.</em> In fact, up until version 0.9.0, this class had
- default package access.
+ <p><em>The casual user does not have to deal with this class
+ directly.</em>
- <p>The structure of the category hierarchy is maintained by the
+ <p>The structure of the logger hierarchy is maintained by the
{@link #getLogger} method. The hierarchy is such that children link
to their parent but parents do not have any pointers to their
- children. Moreover, categories can be instantiated in any order, in
+ children. Moreover, loggers can be instantiated in any order, in
particular descendant before ancestor.
<p>In case a descendant is created before a particular ancestor,
@@ -71,7 +70,7 @@
boolean emittedNoResourceBundleWarning = false;
/**
- Create a new Category hierarchy.
+ Create a new logger hierarchy.
@param root The root of the new hierarchy.
@@ -106,9 +105,9 @@
}
/**
- This call will clear all category definitions from the internal
+ This call will clear all logger definitions from the internal
hashtable. Invoking this method will irrevocably mess up the
- category hierarchy.
+ logger hierarchy.
<p>You should <em>really</em> know what you are doing before
invoking this method.
@@ -124,7 +123,7 @@
void emitNoAppenderWarning(Category cat) {
// No appenders in hierarchy, warn user only once.
if(this.emittedNoAppenderWarning) {
- LogLog.error("No appenders could be found for category (" +
+ LogLog.error("No appenders could be found for logger (" +
cat.getName() + ").");
LogLog.error("Please initialize the log4j system properly.");
this.emittedNoAppenderWarning = true;
@@ -132,10 +131,10 @@
}
/**
- Check if the named category exists in the hierarchy. If so return
+ Check if the named logger exists in the hierarchy. If so return
its reference, otherwise returns <code>null</code>.
- @param name The name of the category to search for.
+ @param name The name of the logger to search for.
*/
public
@@ -168,23 +167,23 @@
/**
- Disable all logging requests of level <em>equal to or
- below</em> the level parameter <code>p</code>, for
- <em>all</em> categories in this hierarchy. Logging requests of
- higher level then <code>p</code> remain unaffected.
+ Disable all logging requests of level <em>equal to or below</em>
+ the level parameter <code>p</code>, for <em>all</em> loggers in
+ this hierarchy. Logging requests of higher level then
+ <code>p</code> remain unaffected.
<p>The "disable" family of methods are there for speed. They
allow printing methods such as debug, info, etc. to return
immediately after an integer comparison without walking the
- category hierarchy. In most modern computers an integer
- comparison is measured in nanoseconds where as a category walk is
- measured in units of microseconds.
+ logger hierarchy. In most modern computers an integer comparison
+ is measured in nanoseconds where as a logger walk is measured in
+ units of microseconds.
<p>Other configurators define alternate ways of overriding the
disable override flag. See {@link PropertyConfigurator} and
{@link org.apache.log4j.xml.DOMConfigurator}.
- @deprecated Please use the {@link #enable} familiy of methods instead.
+ @deprecated Please use the {@link #enable} family of methods instead.
@since 0.8.5 */
public
@@ -204,11 +203,11 @@
}
/**
- Disable all logging requests regardless of category and level.
+ Disable all logging requests regardless of logger and level.
This method is equivalent to calling {@link #disable} with the
argument {@link Level#FATAL}, the highest possible level.
- @deprecated Please use the {@link #enable} familiy of methods instead.
+ @deprecated Please use the {@link #enable} family of methods instead.
@since 0.8.5 */
public
@@ -218,13 +217,12 @@
/**
- Disable all logging requests of level DEBUG regardless of
- category. Invoking this method is equivalent to calling {@link
+ Disable all logging requests of level DEBUG regardless of the
+ logger. Invoking this method is equivalent to calling {@link
#disable} with the argument {@link Level#DEBUG}.
- @deprecated Please use the {@link #enable} familiy of methods instead.
-
- @since 0.8.5 */
+ @deprecated Please use the {@link #enable} family of methods instead.
+ */
public
void disableDebug() {
disable(Level.DEBUG);
@@ -233,13 +231,13 @@
/**
Disable all logging requests of level INFO and below
- regardless of category. Note that DEBUG messages are also
+ regardless of logger. Note that DEBUG messages are also
disabled.
<p>Invoking this method is equivalent to calling {@link
#disable(Level)} with the argument {@link Level#INFO}.
- @deprecated Please use the {@link #enable} familiy of methods instead.
+ @deprecated Please use the {@link #enable} family of methods instead.
@since 0.8.5 */
public
@@ -248,29 +246,26 @@
}
/**
- Undoes the effect of calling any of {@link #disable}, {@link
- #disableAll}, {@link #disableDebug} and {@link #disableInfo}
- methods. More precisely, invoking this method sets the Category
- class internal variable called <code>disable</code> to its
- default "off" value.
-
- @since 0.8.5 */
+ Equivalent to calling <code>enable(Level.ALL)</code>.
+
+ By default all levels are enabled.
+ */
public
void enableAll() {
enable(Level.ALL);
}
/**
- Enable logging for events with level p or higher.
+ Enable logging for logging requests with level <code>l</code> or
+ higher. By default all levels are enabled.
- @param p the minimum level for which events are sent to
- their appenders.
- @since 1.1.3 */
+ @param l The minimum level for which logging requests are sent to
+ their appenders. */
public
- void enable(Level p) {
- if(p != null) {
- enableInt = p.level;
- enable = p;
+ void enable(Level l) {
+ if(l != null) {
+ enableInt = l.level;
+ enable = l;
}
}
@@ -298,11 +293,10 @@
}
/**
- Returns a {@link Level} representation of the
- <code>enable</code> state.
+ Returns a {@link Level} representation of the <code>enable</code>
+ state.
- @since 1.2
- */
+ @since 1.2 */
public
Level getEnable() {
return enable;
@@ -336,16 +330,16 @@
}
/**
- Return a new category instance named as the first parameter using
+ Return a new logger instance named as the first parameter using
<code>factory</code>.
- <p>If a category of that name already exists, then it will be
- returned. Otherwise, a new category will be instantiated by the
+ <p>If a logger of that name already exists, then it will be
+ returned. Otherwise, a new logger will be instantiated by the
<code>factory</code> parameter and linked with its existing
ancestors as well as children.
- @param name The name of the category to retrieve.
- @param factory The factory that will make the new category instance.
+ @param name The name of the logger to retrieve.
+ @param factory The factory that will make the new logger instance.
*/
public
@@ -613,7 +607,7 @@
/**
We update the links for all the children that placed themselves
in the provision node 'pn'. The second argument 'cat' is a
- reference for the newly created Category, parent of all the
+ reference for the newly created Logger, parent of all the
children in 'pn'
We loop on all the children 'c' in 'pn':
1.5 +33 -5 jakarta-log4j/src/java/org/apache/log4j/Logger.java
Index: Logger.java
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/java/org/apache/log4j/Logger.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Logger.java 2001/09/04 18:44:47 1.4
+++ Logger.java 2001/09/06 22:40:39 1.5
@@ -29,19 +29,47 @@
/**
- This is the central class in the log4j package. One of the
- distintive features of log4j are hierarchical categories and their
- evaluation.
+ This is the central class in the log4j package. Most logging
+ operations, except configuration, are done through this class.
<p>See the <a href="../../../../manual.html">user manual</a> for an
introduction on this class.
- @author Ceki Gülcü
- @author Anders Kristensen */
+ @author Ceki Gülcü */
public class Logger extends Category {
protected
Logger(String name) {
super(name);
}
+
+ /**
+ Same as calling {@link LogManager#getLogger(String)}.
+ */
+ static
+ public
+ Logger getLogger(String name) {
+ return LogManager.getLogger(name);
+ }
+
+
+ /**
+ Same as calling {@link LogManager#getLogger(Class)}.
+ */
+ static
+ public
+ Logger getLogger(Class clazz) {
+ return LogManager.getLogger(clazz.getName());
+ }
+
+ /**
+ Same as calling {@link LogManager#getRootLogger()}.
+ */
+ public
+ static
+ Logger getRootLogger() {
+ return LogManager.getRootLogger();
+ }
+
+
}
1.9 +8 -8 jakarta-log4j/src/java/org/apache/log4j/MDC.java
Index: MDC.java
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/java/org/apache/log4j/MDC.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- MDC.java 2001/08/13 10:22:10 1.8
+++ MDC.java 2001/09/06 22:40:39 1.9
@@ -13,20 +13,20 @@
import org.apache.log4j.helpers.ThreadLocalMap;
/**
- The MDC class supercedes the {@link NDC} class. It provides
- <em>mapped diagnostic contexts</em>. A <em>Mapped Diagnostic
- Context</em>, or MDC in short, is an instrument for distinguishing
- interleaved log output from different sources. Log output is
- typically interleaved when a server handles multiple clients
- near-simultaneously.
+ The MDC class is similar to the {@link NDC} class except that it is
+ based on a map instead of a stack. It provides <em>mapped
+ diagnostic contexts</em>. A <em>Mapped Diagnostic Context</em>, or
+ MDC in short, is an instrument for distinguishing interleaved log
+ output from different sources. Log output is typically interleaved
+ when a server handles multiple clients near-simultaneously.
<p><b><em>The MDC is managed on a per thread basis</em></b>. A
child thread automatically inherits a <em>copy</em> of the mapped
diagnostic context of its parent.
<p>The MDC class requires JDK 1.2 or above. Under JDK 1.1 the MDC
- will always return empty values but others will not harm your
- application.
+ will always return empty values but otherwise will not affect or
+ harm your application.
@since 1.2
1.37 +3 -3
jakarta-log4j/src/java/org/apache/log4j/PropertyConfigurator.java
Index: PropertyConfigurator.java
===================================================================
RCS file:
/home/cvs/jakarta-log4j/src/java/org/apache/log4j/PropertyConfigurator.java,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -r1.36 -r1.37
--- PropertyConfigurator.java 2001/09/05 06:45:28 1.36
+++ PropertyConfigurator.java 2001/09/06 22:40:39 1.37
@@ -38,7 +38,7 @@
/**
Extends {@link BasicConfigurator} to provide configuration from an
- external file. See <b>{@link #doConfigure(String, Hierarchy)}</b> for the
+ external file. See <b>{@link #doConfigure(String, LoggerRepository)}</b> for the
expected format.
<p>It is sometimes useful to see how log4j is reading configuration
@@ -336,7 +336,7 @@
/**
Read configuration options from <code>properties</code>.
- See {@link #doConfigure(String, Hierarchy)} for the expected format.
+ See {@link #doConfigure(String, LoggerRepository)} for the expected format.
*/
static
public
@@ -383,7 +383,7 @@
/**
Read configuration options from <code>properties</code>.
- See {@link #doConfigure(String, Hierarchy)} for the expected format.
+ See {@link #doConfigure(String, LoggerRepository)} for the expected format.
*/
public
void doConfigure(Properties properties, LoggerRepository hierarchy) {
1.34 +2 -2 jakarta-log4j/src/java/org/apache/log4j/xml/DOMConfigurator.java
Index: DOMConfigurator.java
===================================================================
RCS file:
/home/cvs/jakarta-log4j/src/java/org/apache/log4j/xml/DOMConfigurator.java,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- DOMConfigurator.java 2001/09/05 06:45:29 1.33
+++ DOMConfigurator.java 2001/09/06 22:40:39 1.34
@@ -651,7 +651,7 @@
/**
- A static version of {@link #doConfigure(String, Hierarchy)}. */
+ A static version of {@link #doConfigure(String, LoggerRepository)}. */
static
public
void configure(String filename) throws FactoryConfigurationError {
@@ -659,7 +659,7 @@
}
/**
- A static version of {@link #doConfigure(URL, Hierarchy)}.
+ A static version of {@link #doConfigure(URL, LoggerRepository)}.
*/
static
public
1.2 +87 -12 jakarta-log4j/src/sgml/intro.sgml
Index: intro.sgml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/sgml/intro.sgml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- intro.sgml 2001/09/06 21:09:00 1.1
+++ intro.sgml 2001/09/06 22:40:39 1.2
@@ -13,7 +13,7 @@
<ulink url="http://www.opensource.org";>open source</ulink>
initiative. The latest log4j version, including full-source code,
class files and documentation can be found at <ulink
-url="http://jakarta.apache.org/log4j/";><b>http://jakarta.apache.org/log4j/</b></ulink>.
+url="http://jakarta.apache.org/log4j/";>http://jakarta.apache.org/log4j/</ulink>.
</para>
<para>Igor Poteryaev, an independent author, has ported log4j to the
@@ -29,18 +29,18 @@
multithreaded applications and distributed applications at large.
</para>
-<para>Experience indicated that logging was an important component of the
-development cycle. It offered several advantages. It could provide
-precise <em>context</em> about a run of the application. Once inserted
-into the code, the generation of logging output required no human
-intervention. Moreover, log output could be saved in persistent
-medium to be studied at a later time. In addition to its use in the
-development cycle, a sufficiently rich logging package could also be
-viewed as an auditing tool.
+<para>Experience indicated that logging was an important component of
+the development cycle. It offered several advantages. It could provide
+precise <emphasis>context</emphasis> about a run of the
+application. Once inserted into the code, the generation of logging
+output required no human intervention. Moreover, log output could be
+saved in persistent medium to be studied at a later time. In addition
+to its use in the development cycle, a sufficiently rich logging
+package could also be viewed as an auditing tool.
</para>
<para>As Brian W. Kernigan and Rob Pike put it in their truly excellent
-book <i>"The Practice of Programming"</i>
+book <emphasis>"The Practice of Programming"</emphasis>
<blockquote>
<literallayout>
As personal choice, we tend not to use debuggers beyond getting a
@@ -80,9 +80,10 @@
<para>Releases are available in two formats: <filename>zip<filename>
and <filename>tar.gz</filename>. After unpacking the distribution, you
should have the file
-<filename>$LOG4J_HOME/dist/lib/log4j-version.jar</filename> where
+<filename>$LOG4J_HOME/dist/lib/log4j-VERSION.jar</filename> where
<varname>$LOG4J_HOME</varname> is the directory where you unpacked the
-log4j distribution.
+log4j distribution and <varname>VERSION</varname> is the version of
+the log4j distibution you downloaded.
<para>To start using log4j simply add this jar file to your
<varname>CLASSPATH</varname>.</para>
@@ -91,5 +92,79 @@
<sect1>
<title>First run</title> <para></para>
+
+<para>After you have installed <filename>log4j-VERSION.jar</filename>
+in your <varname>CLASSPATH</varname>, we can try to write a small
+program that uses log4j.
+
+Please also see <xref linkend="faq-threadSafe">.
+
+<example>
+<title>First attempt</title>
+<programlisting>
+ package my.com;
+
+ import org.apache.log4j.Logger;
+
+ public class MyApp {
+ static final Logger logger = Logger.getLogger(MyApp.class);
+
+ static public void main(String[] args) {
+ logger.debug("Hello world.");
+ }
+ }
+</programlisting>
+</example>
+
+
+<example id="sample-catalog">
+ <title>Catalog Sample</title>
+ <programlistingco>
+ <areaspec>
+ <area coords="1" id="ex.catalogue.comment">
+ <area coords="5" id="ex.catalogue.definition">
+ <area coords="11" id="ex.catalogue.eof">
+ </areaspec>
+ <programlisting>
+-- Catalogues for the Conectiva S.A. Style --
+
+OVERRIDE YES
+
+PUBLIC "-//Conectiva SA//DTD books V1.0//EN" "/home/ldp/estilos/livros.dtd"
+
+DELEGATE "-//OASIS" "/home/ldp/SGML/dtds/catalog.dtd"
+
+DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
+
+-- EOF --
+ </programlisting>
+ <calloutlist>
+ <callout arearefs="ex.catalogue.comment">
+ <to> Comment. Comments begin with <quote>--</quote>
+ and follows to the end of the line. </to>
+ </callout>
+ <callout arearefs="ex.catalogue.definition">
+ <to> The public type association
+ <parameter class="option">"-//Conectiva SA//DTD books
V1.0//EN"</parameter>
+ with the file <filename>books.dtd</filename> on the directory
+ <filename class="directory">/home/ldp/estilos</filename>. </para>
+ </callout>
+ <callout arearefs="ex.catalogue.eof">
+ <para> Comment informing the end of the file. </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+</example>
+
+
+
+<computeroutput>
+aasdasd
+afasfd
+</computeroutput>
+
+
+</para>
+
</sect1>
</chapter>
1.3 +20 -8 jakarta-log4j/src/sgml/manual.sgml
Index: manual.sgml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/sgml/manual.sgml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- manual.sgml 2001/09/06 21:09:00 1.2
+++ manual.sgml 2001/09/06 22:40:39 1.3
@@ -127,15 +127,27 @@
<chapter>
<title>Frequently Asked Questions</title>
-<sect1>
-<title>Installation requirements</title>
-<para></para>
-</sect1>
+<qandaset>
-<sect1>
-<title>Exception</title>
-<para></para>
-</sect1>
+<qandaentry>
+<question>
+<para>What are the installation requirements for log4j?</para>
+</question>
+<answer>
+<para>Log4j requires JDK 1.1.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question id="faq-threadSafe">
+<para>Is log4j thread safe?</para>
+</question>
+<answer>
+<para>Yes it is.</para>
+</answer>
+</qandaentry>
+</qandaset>
+
</chapter>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
