[logback-dev] svn commit: r1584 - logback/trunk/logback-site/src/site/pages/manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Thu Sep 6 15:47:18 CEST 2007
Author: ceki
Date: Thu Sep 6 15:47:18 2007
New Revision: 1584
Modified:
logback/trunk/logback-site/src/site/pages/manual/appenders.html
Log:
ongoing work on documentation
Modified: logback/trunk/logback-site/src/site/pages/manual/appenders.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/appenders.html (original)
+++ logback/trunk/logback-site/src/site/pages/manual/appenders.html Thu Sep 6 15:47:18 2007
@@ -43,11 +43,11 @@
<h2>What is an Appender?</h2>
- <p>
- Logback delegates the task of writing a logging event to appenders.
- Appenders must implement the
- <a href="../xref/ch/qos/logback/core/Appender.html"><code>ch.qos.logback.core.Appender</code></a> interface.
- The salient methods of this interface are summarized below:
+ <p>Logback delegates the task of writing a logging event to
+ components called appenders. Appenders must implement the <a
+ href="../xref/ch/qos/logback/core/Appender.html"><code>ch.qos.logback.core.Appender</code></a>
+ interface. The salient methods of this interface are summarized
+ below:
</p>
<div class="source"><pre>package ch.qos.logback.core;
@@ -67,28 +67,35 @@
}</pre></div>
<p>
- Most of the methods in the <code>Appender</code> interface are made of setter
- and getter methods. A notable exception is the <code>doAppend()</code>
- method taking an Object instance as its only parameter.
- This method is perhaps the most important in the logback framework.
- It is responsible for outputting the logging events in a suitable format
- to the appropriate output device. Appenders are named entities.
- This ensures that they can be referenced by name, a quality confirmed
- to be especially significant in configuration scripts.
- An appender can contain multiple filters, thus the <code>Appender</code>
- interface extending the <code>FilterAttachable</code> interface.
- Filters are discussed in detail in a subsequent chapter.
+ Most of the methods in the <code>Appender</code> interface are
+ made of setter and getter methods. A notable exception is the
+ <code>doAppend()</code> method taking an object instance of type
+ <em>E</em> as its only parameter. The actual type of <em>E</em>
+ would vary depending on the logback module. Within the
+ logback-classic module <em>E</em> would be of type <a
+ href="../apidocs/ch/qos/logback/classic/spi/LoggingEvent.html">LoggingEvent</a>
+ and within the logback-access module it would be of type <a
+ href="../apidocs/ch/qos/logback/access/spi/AccessEvent.html">AccessEvent</a>.
+ The <code>doAppend()</code> method is perhaps the most important
+ in the logback framework. It is responsible for outputting the
+ logging events in a suitable format to the appropriate output
+ device. Appenders are named entities. This ensures that they can
+ be referenced by name, a quality confirmed to be especially
+ significant in configuration scripts. An appender can contain
+ multiple filters, thus the <code>Appender</code> interface
+ extending the <code>FilterAttachable</code> interface. Filters
+ are discussed in detail in a subsequent chapter.
</p>
<p>
- Appenders are ultimately responsible for outputting logging events.
- However, they may delegate the actual formatting of the event to a
- <code>Layout</code> object.
- Each layout is associated with one and only one appender, referred to
- as the containing appender. Some appenders have a built-in or fixed
- event format, such that they do not require a layout. For example, the
- <code>SocketAppender</code> simply serialize logging events before
- transmitting them over the wire.
+ Appenders are ultimately responsible for outputting logging
+ events. However, they may delegate the actual formatting of the
+ event to a <code>Layout</code> object. Each layout is associated
+ with one and only one appender, referred to as the owning
+ appender. Some appenders have a built-in or fixed event format,
+ such that they do not require a layout. For example, the
+ <code>SocketAppender</code> simply serializes logging events
+ before transmitting them over the wire.
</p>
<a name="AppenderBase"></a>
@@ -96,16 +103,17 @@
<p>
The <a href="../xref/ch/qos/logback/core/AppenderBase.html">
- <code>ch.qos.logback.core.AppenderBase</code></a> class is an abstract
- class implementing the <code>Appender</code> interface.
- It provides basic functionality shared by all appenders,
- such as methods for getting or setting their name, their started status,
- their layout and their filters.
- It is the super-class of all appenders shipped with logback.
- Although an abstract class, <code>AppenderBase</code> actually implements the
- <code>doAppend()</code> method in the <code>Append</code> interface.
- Perhaps the clearest way to discuss <code>AppenderBase</code> class is by
- presenting a bit of its actual source code.
+ <code>ch.qos.logback.core.AppenderBase</code></a> class is an
+ abstract class implementing the <code>Appender</code> interface.
+ It provides basic functionality shared by all appenders, such as
+ methods for getting or setting their name, their activation
+ status, their layout and their filters. It is the super-class of
+ all appenders shipped with logback. Although an abstract class,
+ <code>AppenderBase</code> actually implements the
+ <code>doAppend()</code> method in the <code>Append</code>
+ interface. Perhaps the clearest way to discuss
+ <code>AppenderBase</code> class is by presenting an excerpt of
+ actual source code.
</p>
<div class="source"><pre>public synchronized void doAppend(E eventObject) {
@@ -157,21 +165,24 @@
</p>
<p>
- The first statement of the <code>doAppend()</code> method, once the <code>try</code> block
- is reached, is to check whether the <code>started</code> field is true.
- If it is not, <code>doAppend()</code> will send a warning message and return.
- In other words, once stopped, it is impossible to write to a closed appender.
- <code>Appender</code> objects implement the <code>LifeCycle</code> interface,
- which implies that they implement <code>start()</code>, <code>stop()</code>
- and <code>isStarted()</code> methods. After setting all the options of an appender,
- Joran, logback's configuration framework, calls the <code>start()</code>
- method to signal the appender to bind or activate its options.
- Indeed, depending on the appender, certain options cannot be activated because
- of interferences with other options, or appenders can even not start at all if
- some options are missing.
- For example, since file creation depends on truncation mode,
- <code>FileAppender</code> cannot act on the value of its <code>File</code> option
- until the value of the Append option is also known for certain.
+ The first statement of the <code>doAppend()</code> method, once
+ the <code>try</code> block is reached, is to check whether the
+ <code>started</code> field is true. If it is not,
+ <code>doAppend()</code> will send a warning message and return.
+ In other words, once stopped, it is impossible to write to a
+ closed appender. <code>Appender</code> objects implement the
+ <code>LifeCycle</code> interface, which implies that they
+ implement <code>start()</code>, <code>stop()</code> and
+ <code>isStarted()</code> methods. After setting all the options of
+ an appender, Joran, logback's configuration framework, calls the
+ <code>start()</code> method to signal the appender to bind or
+ activate its options. Indeed, depending on the appender, certain
+ options cannot be activated because of interferences with other
+ options, or appenders can even not start at all if some options
+ are missing. For example, since file creation depends on
+ truncation mode, <code>FileAppender</code> cannot act on the value
+ of its <code>File</code> option until the value of the Append
+ option is also known for certain.
</p>
<p>
More information about the logback-dev
mailing list