Author: seb
Date: Fri Nov 10 15:58:25 2006
New Revision: 893
Added:
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingFixedWindow.xml
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml
Modified:
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingTimeBased.xml
logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
Log:
on going work
Added:
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingFixedWindow.xml
==============================================================================
--- (empty file)
+++
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingFixedWindow.xml
Fri Nov 10 15:58:25 2006
@@ -0,0 +1,22 @@
+<configuration>
+ <appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
+ <File>testFile.log</File>
+ <rollingPolicy
class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+ <FileNamePattern>testFile.%i.log.zip</FileNamePattern>
+ <MinIndex>1</MinIndex>
+ <MaxIndex>3</MaxIndex>
+ </rollingPolicy>
+
+ <triggeringPolicy
class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+ <MaxFileSize>5MB</MaxFileSize>
+ </triggeringPolicy>
+ <layout class="ch.qos.logback.classic.PatternLayout">
+ <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern>
+ </layout>
+ </appender>
+
+ <root>
+ <level value="debug" />
+ <appender-ref ref="FILE" />
+ </root>
+</configuration>
\ No newline at end of file
Modified:
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml
==============================================================================
---
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml
(original)
+++
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml
Fri Nov 10 15:58:25 2006
@@ -13,7 +13,7 @@
<MaxFileSize>5MB</MaxFileSize>
</triggeringPolicy>
<layout class="ch.qos.logback.classic.PatternLayout">
- <Pattern>%-4relative [%thread] %-5level %class -
%msg%n</Pattern>
+ <Pattern>%-4relative [%thread] %-5level %logger{35} -
%msg%n</Pattern>
</layout>
</appender>
Modified:
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingTimeBased.xml
==============================================================================
---
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingTimeBased.xml
(original)
+++
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-RollingTimeBased.xml
Fri Nov 10 15:58:25 2006
@@ -6,7 +6,7 @@
</rollingPolicy>
<layout class="ch.qos.logback.classic.PatternLayout">
- <Pattern>%-4relative [%thread] %-5level %class - %msg%n</Pattern>
+ <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern>
</layout>
</appender>
Added:
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml
==============================================================================
--- (empty file)
+++
logback/trunk/logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml
Fri Nov 10 15:58:25 2006
@@ -0,0 +1,20 @@
+<configuration>
+
+ <appender name="FILE" class="ch.qos.logback.core.FileAppender">
+ <File>testFile.log</File>
+ <Append>true</Append>
+ <Encoding>UTF-8</Encoding>
+ <BufferedIO>false</BufferedIO>
+ <ImmediateFlush>true</ImmediateFlush>
+
+ <layout class="ch.qos.logback.classic.PatternLayout">
+ <Pattern>%-4relative [%thread] %-5level %logger{35} -
%msg%n</Pattern>
+ </layout>
+ </appender>
+
+ <root>
+ <level value="debug" />
+ <appender-ref ref="FILE" />
+ </root>
+</configuration>
+
Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
(original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
Fri Nov 10 15:58:25 2006
@@ -14,7 +14,6 @@
Authors: Ceki Gülcü, Sébastien Pennec
</div>
-
<table>
<tr>
<td valign="top" align="top">
@@ -104,13 +103,10 @@
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, AppenderBase actually implements
the
+ 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 AppenderBase class is by
+ Perhaps the clearest way to discuss <code>AppenderBase</code>
class is by
presenting a bit of its actual source code.
- <code>AppenderBase</code>'s complete source code is also
- <a href="../xref/ch/qos/logback/core/AppenderBase.html">
- available for viewing</a>.
</p>
<div class="source"><pre>public synchronized void doAppend(Object eventObject)
{
@@ -155,30 +151,28 @@
<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. Why could it call
itself, you might ask? Well,
- just imagine that a logback component, called somewhere beyond
the <code>append()</code>
- method, might want to log something. Its call could be directed
to the very same appender
+ 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.
+ 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> object implement the
<code>LifeCycle</code> interface,
+ <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 this method to
signal the appender
- to bind or activate its options.
+ 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.
- Sub-classes of <code>AppenderBase</code> are required to set
the boolean variable
- <code>started</code> to false when their <code>stop()</code>
method is invoked.
</p>
<p>
@@ -192,8 +186,8 @@
<p>
The next <code>if</code> statement checks the result
of the attached <code>Filter</code> objects.
- Depending on the decision made by the filters
- in the filter chain, events can be denied or alternatively
accepted.
+ 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>
@@ -242,7 +236,8 @@
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 null such
+ By default, the <span
class="option">Encoding</span> option is
+ <code>null</code> such
that the platform's default encoding is used.
</td>
</tr>
@@ -315,7 +310,8 @@
running <code>ExitWoes1</code> will not produce any output in
the file
<em>exitWoes1.log</em>
because the Java VM does not flush output streams when it
exits.
- Calling the <code>reset()</code> method of a
<code>LoggerContext</code> ensures that all
+ Calling the <code>shutdownAndReset()</code> method of a
<code>LoggerContext</code>
+ ensures that all
appenders in the hierarchy are closed and their buffers are
flushed. The
<code>ExitWoes2</code> class uses this statement and outputs a
logging
request. <b>DOES NOT WORK ??</b>
@@ -368,6 +364,34 @@
</td>
</tr>
</table>
+
+ <p>
+ Here is a sample configuration that uses
<code>ConsoleAppender</code>.
+ </p>
+
+<em>Example 4.2: ConsoleAppender configuration
(logback-examples/src/main/java/chapter4/conf/logback-Console.xml)</em>
+<div class="source"><pre><configuration>
+
+ <b><appender name="STDOUT"
+ class="ch.qos.logback.core.ConsoleAppender">
+ <layout class="ch.qos.logback.classic.PatternLayout">
+ <Pattern>%-4relative [%thread] %-5level - %msg %n</Pattern>
+ </layout>
+ </appender></b>
+
+ <root>
+ <level value="debug" />
+ <appender-ref ref="STDOUT" />
+ </root>
+</configuration></pre></div>
+
+ <p>
+ To run this example, use the provided
<code>ConfigurationTester</code> by
+ issuing the following command, once in the
<em>logback-examples/target/classes</em>:
+ </p>
+
+<div class="source"><pre>java chapter4.ConfigurationTester
chapter4/conf/logback-Console.xml</pre></div>
+
<a name="FileAppender" />
<h3>FileAppender</h3>
@@ -439,6 +463,13 @@
The <span class="option">File</span> option has
no default value.
</td>
</tr>
+ <tr>
+ <td><b><span
class="option">ImmediateFlush</span></b></td>
+ <td><code>boolean</code></td>
+ <td>
+ See <code>WriterAppender</code> options.
+ </td>
+ </tr>
</table>
<p>
@@ -456,12 +487,44 @@
I/O buffering (<span
class="option">ImmediateFlush</span>=false).
Performance varies somewhat depending on the host machine as
well as JDK version.
Throughput measurements are based on the
<code>chapter4.IO</code> application.
- Please refer to the file
<em>logback-examples/src/main/java/chapter4/IO.java</em>
+ Please refer to <a href="../xref/chapter4/IO.html">
+ <em>logback-examples/src/main/java/chapter4/IO.java</em></a>
for actual source code.
- <a href="../xref/chapter4/IO.html">Online viewing</a>
- of this file is also available.
</p>
+ <p>
+ Configuring <code>FileAppender</code> can be done the following
way:
+ </p>
+
+<em>Example 4.3: FileAppender configuration
(logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml)</em>
+<div class="source"><pre><configuration>
+
+ <b><appender name="FILE" class="ch.qos.logback.core.FileAppender">
+ <File>testFile.log</File>
+ <Append>true</Append>
+ <Encoding>UTF-8</Encoding>
+ <BufferedIO>false</BufferedIO>
+ <ImmediateFlush>true</ImmediateFlush>
+
+ <layout class="ch.qos.logback.classic.PatternLayout">
+ <Pattern>%-4relative [%thread] %-5level %logger{35}
- %msg%n</Pattern>
+ </layout>
+ </appender></b>
+
+ <root>
+ <level value="debug" />
+ <appender-ref ref="FILE" />
+ </root>
+</configuration></pre></div>
+
+ <p>
+ To run this example, use the provided
<code>ConfigurationTester</code> by
+ issuing the following command, once in the
<em>logback-examples/target/classes</em>:
+ </p>
+
+<div class="source"><pre>java chapter4.ConfigurationTester
chapter4/conf/logback-fileAppender.xml</pre></div>
+
+
<a name="RollingFileAppender" />
<h3>RollingFileAppender</h3>
@@ -475,7 +538,7 @@
<p>
There are two important logback componenents that interact with
<code>RollingFileAppender</code>. First,
<code>RollingPolicy</code>
- implementation define the procedure that will be followed when
+ implementations define the procedure that will be followed when
the rollover happens. The second componenent is
<code>TriggeringPolicy</code> implementations that are used
to check wether the rollover must happen or not at a given time.
@@ -514,17 +577,17 @@
</tr>
<tr>
<td><b><span class="option">Encoding</span></b></td>
- <td><code>int</code></td>
+ <td><code>String</code></td>
<td>See <code>WriterAppender</code> options.</td>
</tr>
<tr>
<td><b><span class="option">File</span></b></td>
- <td><code>int</code></td>
+ <td><code>String</code></td>
<td>See <code>FileAppender</code> options.</td>
</tr>
<tr>
<td><b><span
class="option">ImmediateFlush</span></b></td>
- <td><code>int</code></td>
+ <td><code>boolean</code></td>
<td>See <code>WriterAppender</code> options.</td>
</tr>
<tr>
@@ -562,8 +625,7 @@
public interface RollingPolicy extends LifeCycle {
-
- public void rollover() throws RolloverFailure;
+ <b>public void rollover() throws RolloverFailure;</b>
public String getNewActiveFileName();
public void setParent(FileAppender appender);
}</pre></div>
@@ -584,11 +646,11 @@
renames files according to a fixed window algorithm as
described below.
</p>
<p>
- The <b>File</b> property, which is configured in the
+ The <span class="option">File</span>> option, which is
configured in the
<code>FileAppender</code> element, is required. It represents
the name of the file
- where current logging output will be written. The
<b>FileNamePattern</b>
+ where current logging output will be written. The <span
class="option">FileNamePattern</span>
option represents the file name pattern for the archived
(rolled over) log files.
- The <b>FileNamePattern</b> option, which is also required, must
include
+ The <span class="option">FileNamePattern</span> option, which
is also required, must include
an integer token, that is the string <em>%i</em>
somewhere within the pattern.
</p>
@@ -662,7 +724,7 @@
We suppose that the <span class="option">MinIndex</span> is set
to <em>1</em> and
<span class="option">MaxIndex</span> is set to <em>3</em>. The
<span class="option">FileNamePattern</span> option is set to
<em>foo%i.log</em>, and
- the <code>FileAppender</code>'s <span
class="option">FileNamePattern</span>
+ the <span class="option">FileNamePattern</span>
option is set to <em>foo.log</em>.
</p>
@@ -753,7 +815,7 @@
foo3.log, foo2.log, foo1.log
</td>
<td>
- At the fourth rollover, the old
<em>foo3.log</em> file is deleted. The files
+ From the fourth rollover, the old
<em>foo3.log</em> file is deleted. The files
are all renamed with an increment to their
index, and a new <em>foo.log</em>
file is created and used for the output.
From this moment on, there will always be 4 log
files available, each being present
@@ -766,6 +828,9 @@
Here is a sample configuration to use
<code>RollingFileAppender</code>
and <code>FixedWindowRollingPolicy</code>.
</p>
+
+<em>Example 4.4: Sample configuration of a <code>RollingFileAppender</code>
using a
+<code>FixedWindowRollingPolicy</code>
(logback-examples/src/main/java/chapter4/conf/logback-RollingFixedWindow.xml)</em>
<div class="source"><pre><configuration>
<appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<File>testFile.log</File>
@@ -779,7 +844,7 @@
<MaxFileSize>5MB</MaxFileSize>
</triggeringPolicy>
<layout class="ch.qos.logback.classic.PatternLayout">
- <Pattern>%-4relative [%thread] %-5level %class - %msg%n</Pattern>
+ <Pattern>%-4relative [%thread] %-5level %logger{35} -
%msg%n</Pattern>
</layout>
</appender>
@@ -958,7 +1023,7 @@
Given the use of the <span
class="option">FileNamePattern</span>, we see that the
<code>TimeBasedRollingPolicy</code> is responsible for the
rollover as well as for
the triggering of said rollover. Therefore,
<code>TimeBasedTriggeringPolicy</code>
- implements <code>RollingPolicy</code> as well as
<code>TriggeringPolicy</code>
+ implements both <code>RollingPolicy</code> and
<code>TriggeringPolicy</code>
interfaces. A <code>RollingFileAppender</code> that uses
<code>TimeBasedRollingPolicy</code> can be started and used
correctly even
if its configuration does not contain any reference to a
<code>TriggeringPolicy</code>.
@@ -1002,6 +1067,8 @@
uses a <code>TimeBasedRollingPolicy</code>
</p>
+<em>Example 4.5: Sample configuration of a <code>RollingFileAppender</code>
using a
+<code>TimeBasedRollingPolicy</code>
(logback-examples/src/main/java/chapter4/conf/logback-RollingTimeBased.xml)</em>
<div class="source"><pre><configuration>
<appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<File>logFile.log</File>
@@ -1010,7 +1077,7 @@
</rollingPolicy></b>
<layout class="ch.qos.logback.classic.PatternLayout">
- <Pattern>%-4relative [%thread] %-5level %class - %msg%n</Pattern>
+ <Pattern>%-4relative [%thread] %-5level %logger{35} -
%msg%n</Pattern>
</layout>
</appender>
@@ -1036,14 +1103,14 @@
public interface TriggeringPolicy extends LifeCycle {
- public boolean isTriggeringEvent(final File file, final Object event);
+ <b>public boolean isTriggeringEvent(final File file, final Object event);</b>
}</pre></div>
<p>
The
<code>isTriggeringEvent()</code>
method takes the active file, and the currently
processed
- logging event. It's implementation decied, based on
these
+ logging event. It's implementation decides, based on
these
parameters, whether the rollover must occur or not, by
returning a boolean value.
</p>
@@ -1082,6 +1149,8 @@
using a <code>SizeBasedTriggeringPolicy</code>.
</p>
+<em>Example 4.6: Sample configuration of a <code>RollingFileAppender</code>
using a
+<code>SizeBasedTriggeringPolicy</code>
(logback-examples/src/main/java/chapter4/conf/logback-RollingSizeBased.xml)</em>
<div class="source"><pre><configuration>
<appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<File>testFile.log</File>
@@ -1095,7 +1164,7 @@
<MaxFileSize>5MB</MaxFileSize>
</triggeringPolicy></b>
<layout class="ch.qos.logback.classic.PatternLayout">
- <Pattern>%-4relative [%thread] %-5level %class - %msg%n</Pattern>
+ <Pattern>%-4relative [%thread] %-5level %logger{35} -
%msg%n</Pattern>
</layout>
</appender>
@@ -1121,14 +1190,9 @@
with a <code>Level</code> of <em>ERROR</em> or more is
issued.
</p>
-
-
<a name="Classic"/>
<h2>Logback Classic</h2>
-
- <p><b>Keep this??</b>While logging event are declared as
<code>Object</code> in logback core,
- they are instances of the <code>LoggingEvent</code> class in
logback classic.</p>
-
+
<a name="SocketAppender" />
<h3>SockerAppender</h3>
@@ -1181,7 +1245,7 @@
pipe which may be lost. This is a common problem on
Windows based systems.
To avoid lost data, it is usually sufficient to
<code>close()</code> the
<code>SocketAppender</code> either explicitly or by
calling the
- <code>LoggerContext</code>'s <code>reset()</code>
method before exiting the application.
+ <code>LoggerContext</code>'s
<code>shutdownAndReset()</code> method before exiting the application.
</p>
<p>
@@ -1300,7 +1364,7 @@
and attaches it to the root logger.
</p>
- <em>Example 4.2: SocketAppender configuration
(logback-examples/src/main/java/chapter4/socket/client1.xml)</em>
+ <em>Example 4.7: SocketAppender configuration
(logback-examples/src/main/java/chapter4/socket/client1.xml)</em>
<div class="source"><pre><configuration>
<appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender">
@@ -1499,7 +1563,7 @@
Here is a sample configuration file you can supply to
chapter4.mail.Email:
</p>
-<em>Example 4.3: A sample <code>SMTPAppender</code> configuration
(logback-examples/src/main/java/chapter4/mail/mail1.xml)</em>
+<em>Example 4.8: A sample <code>SMTPAppender</code> configuration
(logback-examples/src/main/java/chapter4/mail/mail1.xml)</em>
<div class="source"><pre><configuration>
<appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
@@ -1584,7 +1648,7 @@
every 1024th event triggers an email message.
</p>
-<em>Example 4.4: A <code>TriggeringPolicy</code> implementation
+<em>Example 4.9: A <code>TriggeringPolicy</code> implementation
that triggers every 1024th event (<a
href="../xref/chapter4/mail/CounterBasedTP.html">logback-examples/src/main/java/chapter4/mail/CounterBasedTP.java</a>)</em>
<div class="source"><pre>package chapter4.mail;
@@ -1624,7 +1688,7 @@
as its triggering event evaluator.
</p>
-<em>Example 4.5: <code>SMTPAppender</code> with custom
+<em>Example 4.10: <code>SMTPAppender</code> with custom
<code>TriggeringPolicy</code> and buffer size
(logback-examples/src/main/java/chapter4/mail/mail3.xml)</em>
<div class="source"><pre><configuration>
@@ -1919,7 +1983,7 @@
The following configuration file is what one would need.
</p>
-<em>Example 4.6: <code>DBAppender</code> configuration
(logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml)</em>
+<em>Example 4.11: <code>DBAppender</code> configuration
(logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml)</em>
<div class="source"><pre><configuration>
<b><appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
@@ -1998,7 +2062,7 @@
<code>javax.sql.DataSource</code>.
</p>
-<em>Example 4.7: <code>DBAppender</code> configuration
(logback-examples/src/main/java/chapter4/db/append-with-datasource.xml)</em>
+<em>Example 4.12: <code>DBAppender</code> configuration
(logback-examples/src/main/java/chapter4/db/append-with-datasource.xml)</em>
<div class="source"><pre><configuration>
<appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
@@ -2112,7 +2176,7 @@
configuration file, logging events are sent to a MySQL
database,
without any pooling.
</p>
-<em>Example 4.8: <code>DBAppender</code> configuration without pooling
(logback-examples/src/main/java/chapter4/db/append-toMySQL-with-datasource.xml)</em>
+<em>Example 4.13: <code>DBAppender</code> configuration without pooling
(logback-examples/src/main/java/chapter4/db/append-toMySQL-with-datasource.xml)</em>
<div class="source"><pre><configuration>
<appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
@@ -2155,7 +2219,7 @@
in the classpath.
</p>
-<em>Example 4.8: <code>DBAppender</code> configuration with pooling
(logback-examples/src/main/java/chapter4/db/append-toMySQL-with-datasource-and-pooling.xml)</em>
+<em>Example 4.14: <code>DBAppender</code> configuration with pooling
(logback-examples/src/main/java/chapter4/db/append-toMySQL-with-datasource-and-pooling.xml)</em>
<div class="source"><pre><configuration>
<appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
@@ -2298,6 +2362,7 @@
Here is a sample configuration using a
<code>SyslogAppender</code>.
</p>
+<em>Example 4.15: <code>SyslogAppender</code> configuration
(logback-examples/src/main/java/chapter4/conf/logback-syslog.xml)</em>
<div class="source"><pre><configuration>
<appender name="SYSLOG"
_______________________________________________
logback-dev mailing list
[email protected]
http://qos.ch/mailman/listinfo/logback-dev
