[logback-dev] svn commit: r1654 - logback/trunk/logback-site/src/site/pages/manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Wed Mar 19 22:07:35 CET 2008
Author: ceki
Date: Wed Mar 19 22:07:35 2008
New Revision: 1654
Modified:
logback/trunk/logback-site/src/site/pages/manual/appenders.html
Log:
- ongoing work on the appenders chapter
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 Wed Mar 19 22:07:35 2008
@@ -857,7 +857,7 @@
<a href="../xref/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html">
<code>TimeBasedRollingPolicy</code></a> is probably the most
popular rolling polciy. It allows defines a rollover policy based
- on time, say by day or month.
+ on time, say by day or by month.
</p>
<p><code>TimeBasedRollingPolicy</code>'s has only one mandatory
@@ -868,10 +868,10 @@
name of the rolled (archived) log files. Its value <span
class="option">FileNamePattern</span> should consist of the name of
the file, plus a suitably placed <em>%d</em> conversion specifier.
- The <em>%d</em> conversion specifier may contain a date and time
+ The <em>%d</em> conversion specifier may contain a date-and-time
pattern as specified by the <code>java.text.SimpleDateFormat</code>
- class. If the date and time pattern is omitted, then the default
- pattern of <em>yyyy-MM-dd</em> is assumed. The following examples
+ class. If the date-and-time pattern is omitted, then the default
+ pattern <em>yyyy-MM-dd</em> is assumed. The following examples
should clarify the point.
</p>
@@ -1005,30 +1005,19 @@
</table>
<p>The <span class="option">FileNamePattern</span> serves a dual
- purposes. First, by studying the pattern, logback computes the
- requested rollover periodicity. Second, it computes each file's
- name. It is entirely possible for two different patterns to specify
- the same periodicity. The (date) patterns <em>yyyy-MM</em> and
+ purpose. First, by studying the pattern, logback computes the
+ requested rollover periodicity. Second, it computes each archived
+ file's name. Note that it is possible for two different patterns to
+ specify the same periodicity. The patterns <em>yyyy-MM</em> and
<em>yyyy at MM</em> both specify monthly rollover, although the
resulting archive files will carry different names.
</p>
-
- <p>Thus, <code>TimeBasedRollingPolicy</code> caries a responsiblity
- for rollover as well as for the triggering of said rollover. Put
- differently, <code>TimeBasedTriggeringPolicy</code> implements both
- <code>RollingPolicy</code> and <code>TriggeringPolicy</code>
- interfaces. A <code>RollingFileAppender</code> owning a child
- <code>TimeBasedRollingPolicy</code> can be started and used
- correctly even if its does not contain a reference to a
- <code>TriggeringPolicy</code>.
- </p>
-
- <p>As with <code>FixedWindowRollingPolicy</code>,
- <code>TimeBasedRollingPolicy</code> decouples the location of the
- active log file and the archived log files. The <span
- class="option">File</span> option defines the log file for the
- current period whereas <em>archived files</em> are those files which
- have been rolled over in previous periods.
+
+ <p>Thus, <code>TimeBasedRollingPolicy</code> assumes the
+ responsiblity for rollover as well as for the triggering of said
+ rollover. Indeed, <code>TimeBasedTriggeringPolicy</code> implements
+ both <code>RollingPolicy</code> and <code>TriggeringPolicy</code>
+ interfaces.
</p>
<p>By setting the <span class="option">File</span> option you can
@@ -1042,6 +1031,7 @@
class="option">FileNamePattern</span>.
</p>
+
<p>For various reasons, rollovers are not clock-driven but depend on
the arrival of logging events. For example, on 8th of March 2002,
assuming the <span class="option">FileNamePattern</span> is set to
@@ -1056,9 +1046,9 @@
output in the correct file delimiting that period.
</p>
- <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -->
- <p>Here is a sample configuration of a <code>RollingFileAppender</code> which
- uses a <code>TimeBasedRollingPolicy</code>
+ <p>Here is a sample configuration for
+ <code>RollingFileAppender</code> in conjuction with a
+ <code>TimeBasedRollingPolicy</code>.
</p>
<em>Example 4.5: Sample configuration of a <code>RollingFileAppender</code> using a
@@ -1084,63 +1074,59 @@
<a name="TriggeringPolicy"></a>
<h3>Triggering policies</h3>
- <p><a href="../xref/ch/qos/logback/core/rolling/TriggeringPolicy.html"><code>TriggeringPolicy</code></a>
- implementations are responsible for instructing
- the <code>RollingFileAppender</code> to rollover.</p>
+ <p><a
+ href="../xref/ch/qos/logback/core/rolling/TriggeringPolicy.html"><code>TriggeringPolicy</code></a>
+ implementations are responsible for instructing the
+ <code>RollingFileAppender</code> to rollover.</p>
- <p>The <code>TriggeringPolicy</code> interface is pretty simple.</p>
+ <p>The <code>TriggeringPolicy</code> interface contains only one
+ method.</p>
<div class="source"><pre>package ch.qos.logback.core.rolling;
import java.io.File;
import ch.qos.logback.core.spi.LifeCycle;
-public interface TriggeringPolicy extends LifeCycle {
+public interface TriggeringPolicy<E> extends LifeCycle {
- <b>public boolean isTriggeringEvent(final File activeFile, final Object event);</b>
+ <b>public boolean isTriggeringEvent(final File activeFile, final <E> event);</b>
}</pre></div>
<p>
- The
- <code>isTriggeringEvent()</code>
- method takes the active file, and the currently processed
- logging event. It's implementation decides, based on these
- parameters, whether the rollover must occur or not, by
- returning a boolean value.
+ The <code>isTriggeringEvent()</code> method takes as parameters
+ the active file, and the logging event currently being
+ processed. The concrete implementation determines whether the
+ rollover should occur or not, based on the said parameters.
</p>
<a name="SizeBasedTriggeringPolicy"></a>
<h4>SizeBasedTriggeringPolicy</h4>
- <p>
- <a href="../xref/ch/qos/logback/core/rolling/SizeBasedTriggeringPolicy.html">
- <code>SizeBasedTriggeringPolicy</code></a>
- looks at size of the file being currently written to. If it
- grows larger than the specified size, the
- <code>FileAppender</code> using the
- <code>SizeBasedTriggeringPolicy</code>
- will proceed to the rollover of the current file and log to
- a new one.
- </p>
-
- <p>
- This <code>TriggeringPolicy</code>
- only accepts one parameter, that is the
- <span class="option">MaxFileSize</span>
- option. This option's default value is 10 MB.
- </p>
-
- <p>
- The <span class="option">MaxFileSize</span>
- option can be specified in a simple and easy way, by
- specifying the unit that should be used. One can enter any
- numeric value, with three possible units, namely <em>KB</em>,
- <em>MB</em> and <em>GB</em>. Consequently, values like
- <em>5MB</em>, <em>500KB</em> or <em>2GB</em> are all valid.
- </p>
- <p>
- Here is a sample configuration with a <code>RollingFileAppender</code>
- using a <code>SizeBasedTriggeringPolicy</code>.
+ <p><a
+ href="../xref/ch/qos/logback/core/rolling/SizeBasedTriggeringPolicy.html">
+ <code>SizeBasedTriggeringPolicy</code></a> looks at size of the
+ currently active file. If it grows larger than the specified size,
+ the <code>FileAppender</code> using the
+ <code>SizeBasedTriggeringPolicy</code> will proceed to the
+ rollover of the existing active file and create a new one.
+ </p>
+
+ <p>This <code>TriggeringPolicy</code> accepts only one parameter,
+ namely <span class="option">MaxFileSize</span>, with a default
+ value of 10 MB.
+ </p>
+
+ <p>The <span class="option">MaxFileSize</span> option can be
+ specified in bytes, kilobytes, megabytes or gigabytes by suffixing
+ a numeric value with <em>KB</em>, <em>MB</em> and respectively
+ <em>GB</em>. For example, <em>5000000</em>, <em>5000KB</em>,
+ <em>5MB</em> and <em>2GB</em> are all valid values, with the first
+ three being also equivalent.
+ </p>
+
+ <p>Here is a sample configuration with a
+ <code>RollingFileAppender</code> in conjuction with
+ <code>SizeBasedTriggeringPolicy</code>.
</p>
<em>Example 4.6: Sample configuration of a <code>RollingFileAppender</code> using a
@@ -1168,28 +1154,17 @@
</root>
</configuration></pre></div>
- <p>
- <code>TriggeringPolicy</code> implementations do not only serve with
- <code>RollingFileAppender</code> objects. They can also be used to tell
- <code>SMTPAppender</code>, which will be covered soon, when to send an email
- containing the last logging events.
- </p>
-
- <p>
- In that case, the <code>isTriggeringEvent()</code> method takes <em>null</em>
- as its first parameter (of type <code>File</code>) and takes the logging event
- as its second parameter. It is based on that last element that the decision is
- made to send the email or not. By default, a <code>TriggeringPolicy</code> is
- included with <code>SMTPAppender</code> that triggers the mail each time an event
- with a <code>Level</code> of <em>ERROR</em> or more is issued.
- </p>
-
+
+ <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXx -->
<a name="Classic"></a>
<h2>Logback Classic</h2>
-
-
- <p>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>
+
+
+ <p>While logging events are generic in logback-core, within
+ logback-classic they are always instances of
+ <code>LoggingEvent</code>.
+
+ </p>
<a name="SocketAppender"></a>
<h3>SocketAppender</h3>
More information about the logback-dev
mailing list