[logback-dev] svn commit: r1589 - in logback/trunk: . logback-access logback-classic logback-core logback-examples logback-examples/lib logback-site logback-site/src/site/pages logback-site/src/site/pages/manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Tue Sep 11 21:01:06 CEST 2007
Author: ceki
Date: Tue Sep 11 21:01:05 2007
New Revision: 1589
Added:
logback/trunk/logback-examples/lib/slf4j-api-1.4.3.jar (contents, props changed)
Removed:
logback/trunk/logback-examples/lib/slf4j-api-1.4.0.jar
Modified:
logback/trunk/logback-access/pom.xml
logback/trunk/logback-classic/pom.xml
logback/trunk/logback-core/pom.xml
logback/trunk/logback-examples/pom.xml
logback/trunk/logback-site/pom.xml
logback/trunk/logback-site/src/site/pages/index.html
logback/trunk/logback-site/src/site/pages/manual/appenders.html
logback/trunk/pom.xml
Log:
- starting work on 0.9.9
- updates to documentation
- replaced slf4j-api-1.4.0.jar with slf4j-api-1.4.3.jar
Modified: logback/trunk/logback-access/pom.xml
==============================================================================
--- logback/trunk/logback-access/pom.xml (original)
+++ logback/trunk/logback-access/pom.xml Tue Sep 11 21:01:05 2007
@@ -3,7 +3,7 @@
<parent>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-parent</artifactId>
- <version>0.9.8</version>
+ <version>0.9.9-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
Modified: logback/trunk/logback-classic/pom.xml
==============================================================================
--- logback/trunk/logback-classic/pom.xml (original)
+++ logback/trunk/logback-classic/pom.xml Tue Sep 11 21:01:05 2007
@@ -5,7 +5,7 @@
<parent>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-parent</artifactId>
- <version>0.9.8</version>
+ <version>0.9.9-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
Modified: logback/trunk/logback-core/pom.xml
==============================================================================
--- logback/trunk/logback-core/pom.xml (original)
+++ logback/trunk/logback-core/pom.xml Tue Sep 11 21:01:05 2007
@@ -5,7 +5,7 @@
<parent>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-parent</artifactId>
- <version>0.9.8</version>
+ <version>0.9.9-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
Added: logback/trunk/logback-examples/lib/slf4j-api-1.4.3.jar
==============================================================================
Binary file. No diff available.
Modified: logback/trunk/logback-examples/pom.xml
==============================================================================
--- logback/trunk/logback-examples/pom.xml (original)
+++ logback/trunk/logback-examples/pom.xml Tue Sep 11 21:01:05 2007
@@ -3,7 +3,7 @@
<parent>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-parent</artifactId>
- <version>0.9.8</version>
+ <version>0.9.9-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
Modified: logback/trunk/logback-site/pom.xml
==============================================================================
--- logback/trunk/logback-site/pom.xml (original)
+++ logback/trunk/logback-site/pom.xml Tue Sep 11 21:01:05 2007
@@ -3,7 +3,7 @@
<parent>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-parent</artifactId>
- <version>0.9.8</version>
+ <version>0.9.9-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
Modified: logback/trunk/logback-site/src/site/pages/index.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/index.html (original)
+++ logback/trunk/logback-site/src/site/pages/index.html Tue Sep 11 21:01:05 2007
@@ -44,8 +44,8 @@
<p>The logback-access module integrates with Servlet containers,
such as Tomcat and Jetty, to provide HTTP-access log
- functionality. Note that you can easily build your own modules on
- top of the Core module.
+ functionality. Note that you could easily build your own module
+ on top of logback-core.
</p>
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 Tue Sep 11 21:01:05 2007
@@ -66,54 +66,52 @@
}</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 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 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>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.
+ </p>
+
+ <p>Appenders are named entities. This ensures that they can be
+ referenced by name, a quality confirmed to be instrumental in
+ configuration scripts. The <code>Appender</code> interface extends
+ the <code>FilterAttachable</code> interface. It follows that one or
+ more filters can be attaqched to an appender instance. 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 owning
+ appender. Some appenders have a built-in or fixed event
+ format. Consequently, they do not require nor have a layout. For
+ example, the <code>SocketAppender</code> simply serializes logging
+ events before transmitting them over the wire.
</p>
<a name="AppenderBase"></a>
<h2>AppenderBase</h2>
- <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 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>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 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) {
@@ -146,139 +144,143 @@
}
}</pre></div>
- <p>
- This implementation of the <code>doAppend()</code> method is synchronized.
- It follows that logging to the same appender from different
- threads is safe. While a thread, say <em>T</em>, is executing the <code>doAppend()</code>
- method, subsequent calls by other threads are queued until <em>T</em>
- leaves the <code>doAppend()</code> method, ensuring
- <em>T</em>'s exclusive access to the appender.
- </p>
-
- <p>
- The first thing the <code>doAppend()</code> method does is to set the
- <code>guard</code> variable to <code>true</code>. This ensures that the method will not
- call itself and create an infinite loop. Just imagine that a component, called somewhere
- beyond the <code>append()</code>
- method, wants to log something. Its call could be directed to the very same appender
- that just called it, which would then call it again.
- </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.
- </p>
-
- <p>
- If a warning message is sent due to incorrect calls to the
- <code>doAppend()</code> method, logback's powerful
- <code>Status</code> error reporting system is used. In case
- several incorrect calls on <code>doAppend()</code> are issued,
- <code>AppenderBase</code> does not send an unlimited number of
- warnings. Once a certain limit is reached, the
- <code>AppenderBase</code> instance stops its warnings.
- </p>
-
- <p>
- The next <code>if</code> statement checks the result of the
- attached <code>Filter</code> objects. Depending on the decision
- resulting from the filter chain, events can be denied or
- alternatively accepted. In the absence of a decision by the
- filter chain, events are accepted by default.
- </p>
-
- <p>
- Lastly, the <code>doAppend()</code> method invoke the derived
- classes' implementation of the <code>append()</code> method, which
- does the actual work of appending the event to the appropriate
- device.
- </p>
-
- <p>In appenders, the term option or property is reserved for named
- attributes that are dynamically inferred using JavaBeans
- introspection. </p>
-
- <h2>Logback Core</h2>
-
- <p>
- Core is logback's central module. It offers functionnalities that
- are available to any other module based on logback core. The
- <code>Appender</code> classes contained in the core module are can
- be used by any module without any customization.
- </p>
-
+ <p>This implementation of the <code>doAppend()</code> method is
+ synchronized. It follows that logging to the same appender from
+ different threads is safe. While a thread, say <em>T</em>, is
+ executing the <code>doAppend()</code> method, subsequent calls by
+ other threads are queued until <em>T</em> leaves the
+ <code>doAppend()</code> method, ensuring <em>T</em>'s exclusive
+ access to the appender.
+ </p>
+
+ <p>The first thing the <code>doAppend()</code> method does is to
+ check whether the guard is set to true. If it is, it immediately
+ exits. If the guard is not set, it is set to true at the next
+ statement. The guard ensures that the <code>doAppend()</code> method
+ will not recursively call itself. Just imagine that a component,
+ called somewhere beyond the <code>append()</code> method, wants to
+ log something. Its call could be directed to the very same appender
+ that just called it.
+ </p>
+
+ <p>In the following statement we 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 an appender is closed, it is impossible to write
+ to it. <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 activate its
+ options. Depending on its kind, an appender may fail to start if
+ certain options are missing or because of interferences between
+ various options. For example, given that 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 with certainty. The explicit activation step ensures
+ that an appender acts on its options <em>after</em> their values
+ become known.
+ </p>
+
+ <p>If the appender could not be started or if it has been stopped, a
+ warning message will be issued through logback's internal status
+ management system. After several attempts, in order to avoid
+ flooding the internal status system with copies of the same warning
+ message, the <code>doAppend()</code> method will stop issuing these
+ warnings.
+ </p>
+
+ <p>The next <code>if</code> statement checks the result of the
+ attached filters. Depending on the decision resulting from the
+ filter chain, events can be denied or alternatively accepted. In
+ the absence of a decision by the filter chain, events are accepted
+ by default.
+ </p>
+
+ <p>The <code>doAppend()</code> method then invokes the derived
+ classes' implementation of the <code>append()</code> method. This
+ method does the actual work of appending the event to the
+ appropriate device.
+ </p>
+
+ <p>Finally, the guard is released so as to allow a subsequent
+ invocation of the <code>doAppend()</code> method.
+ </p>
+
+ <p>For the remainder of this manual, we reserve the term "option" or
+ alternatively "property" for any attribute that is inferred
+ dynamically using JavaBeans introspection through setter and getter
+ methods. </p>
+
+ <h2>Logback-core</h2>
+
+ <p>Logback-core lays the foundation upon which the other logback
+ modules are built. In general, the components in logback-core
+ require some, albeit minimal, amount of customisation. However, in
+ the next few sections, we describe several appenders which are ready
+ for use out of the box.
+ </p>
+
+
<a name="WriterAppender"></a>
<h3>WriterAppender</h3>
<p><a
- href="../xref/ch/qos/logback/core/WriterAppender.html"><code>WriterAppender</code></a>
- appends events to a <code>java.io.Writer</code>. This class
- provides basic services that other appenders build upon. Users do
- not usually instantiate <code>WriterAppender</code> objects
- directly. Since <code>java.io.Writer</code> type cannot be mapped
- to a string, there is no way to specify the target
- <code>Writer</code> object in a configuration script. Simply put,
- you cannot configure a <code>WriterAppender</code> from a script.
- However, this does not mean that <code>WriterAppender</code> lacks
- configurable options. These options are described next.
- </p>
-
- <table class="bodyTable">
- <tr class="a">
- <th>Option Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- <tr class="a">
- <td><b><span class="option">Encoding</span></b></td>
- <td><code>String</code></td>
- <td>
- The encoding specifies the method of conversion between 16-bit Unicode
- characters into raw 8-bit bytes. This appender will use the local platform's
- default encoding unless you specify otherwise using the
- <span class="option">Encoding</span> option.
- According to the <code>java.lang</code> package documentation, acceptable values
- are dependent on the VM implementation although all implementations are
- required to support at least the following encodings:
- <em>US-ASCII</em>, <em>ISO-8859-1</em>, <em>UTF-8</em>, <em>UTF-16BE</em>,
- <em>UTF-16LE</em> and <em>UTF-16</em>.
- By default, the <span class="option">Encoding</span> option is
- <code>null</code> such
- that the platform's default encoding is used.
+ href="../xref/ch/qos/logback/core/WriterAppender.html"><code>WriterAppender</code></a>
+ appends events to a <code>java.io.Writer</code>. This class
+ provides basic services that other appenders build upon. Users do
+ not usually instantiate <code>WriterAppender</code> objects
+ directly. Since <code>java.io.Writer</code> type cannot be mapped
+ to a string, as there is no way to specify the target
+ <code>Writer</code> object in a configuration script. Simply put,
+ you cannot configure a <code>WriterAppender</code> from a script.
+ However, this does not mean that <code>WriterAppender</code> lacks
+ configurable options. These options are described next.
+ </p>
+
+ <table class="bodyTable">
+ <tr class="a">
+ <th>Option Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+
+ <tr class="a">
+ <td><b><span class="option">Encoding</span></b></td>
+ <td><code>String</code></td>
+
+ <td>The encoding specifies the method of conversion between
+ Java's internal 16-bit Unicode representation of characters into
+ raw 8-bit bytes. This appender will use the local platform's
+ default encoding unless you say otherwise by specifying an <span
+ class="option">Encoding</span> value. According to the
+ <code>java.lang</code> package documentation, acceptable values
+ are dependent on the VM implementation although all
+ implementations are required to support at least the following
+ encodings: <em>US-ASCII</em>, <em>ISO-8859-1</em>,
+ <em>UTF-8</em>, <em>UTF-16BE</em>, <em>UTF-16LE</em> and
+ <em>UTF-16</em>. As mentioned previously, by default, the <span
+ class="option">Encoding</span> option is <code>null</code> such
+ that the platform's default encoding is used.
</td>
</tr>
<tr class="b">
<td><b><span class="option">ImmediateFlush</span></b></td>
<td><code>boolean</code></td>
- <td>
- If set to true, each write of a logging event is followed by a
- flush operation on the underlying <code>Writer</code>
- object. Conversely, if the option is set to false, each write
- will not be followed by a flush. In general, skipping the
- flush operation improves logging throughput by roughly 15%.
- The downside is that if the application exits abruptly, the
- unwritten characters buffered inside the <code>Writer</code>
- might be lost. This can be particularly troublesome as those
- unwritten characters may contain crucial information needed in
- identifying the reasons behind a crash. By default, the <span
- class="option">ImmediateFlush</span> option is set to true.
+ <td>If the <span class="option">ImmediateFlush</span> option is
+ set to true, then each write of a logging event will be followed
+ by a flush operation on the underlying <code>Writer</code>
+ object. Conversely, if the option is set to false, each write
+ will not be followed by a flush. In general, skipping the flush
+ operation improves logging throughput by roughly 15%. The
+ downside is that if the application exits abruptly, the
+ unwritten characters buffered inside the <code>Writer</code>
+ might be lost. This can be particularly troublesome as those
+ unwritten characters may contain crucial information needed in
+ identifying the reasons behind a crash. By default, the <span
+ class="option">ImmediateFlush</span> option is set to true.
</td>
</tr>
Modified: logback/trunk/pom.xml
==============================================================================
--- logback/trunk/pom.xml (original)
+++ logback/trunk/pom.xml Tue Sep 11 21:01:05 2007
@@ -5,7 +5,7 @@
<groupId>ch.qos.logback</groupId>
<artifactId>logback-parent</artifactId>
- <version>0.9.8</version>
+ <version>0.9.9-SNAPSHOT</version>
<packaging>pom</packaging>
<name>Logback-Parent</name>
More information about the logback-dev
mailing list