Author: seb Date: Fri Nov 3 19:34:28 2006 New Revision: 866 Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml Log: on going work on chapter 4 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 3 19:34:28 2006 @@ -545,6 +545,32 @@ </table> <h3>Rolling policies</h3> + + <p><code>RollingPolicy</code> implementations are responsible for the + procedure of the rollover. They manage file renaming and sometimes deleting.</p> + + <p>The <code>RollingPolicy</code> interface is rather simple:</p> + +<div class="source"><pre>package ch.qos.logback.core.rolling; + +import ch.qos.logback.core.FileAppender; +import ch.qos.logback.core.spi.LifeCycle; + +public interface RollingPolicy extends LifeCycle { + + + public void rollover() throws RolloverFailure; + public String getNewActiveFileName(); + public void setParent(FileAppender appender); +}</pre></div> + + <p> + The <code>rollover</code> method proceeds to the file change, renaming or deletion. + The <code>getNewActiveFileName()</code> method is called to compute a new file name, with + respect to the configuration elements that were injected in the <code>RollingPolicy</code>. + Lastly, a <code>RollingPolicy</code> knows about its parent. + </p> + <a name="FixedWindowRollingPolicy" /> <h4>FixedWindowRollingPolicy</h4> @@ -738,11 +764,11 @@ <div class="source"><pre><configuration> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <File>testFile.log</File> - <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> + <b><rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> <FileNamePattern>testFile.%i.log.zip</FileNamePattern> <MinIndex>1</MinIndex> <MaxIndex>3</MaxIndex> - </rollingPolicy> + </rollingPolicy></b> <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> <MaxFileSize>5MB</MaxFileSize> @@ -973,9 +999,9 @@ <div class="source"><pre><configuration> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <File>logFile.log</File> - <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <b><rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <FileNamePattern>logFile.%d{yyyy-MM-dd}.log</FileNamePattern> - </rollingPolicy> + </rollingPolicy></b> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%-4relative [%thread] %-5level %class - %msg%n</Pattern> @@ -987,16 +1013,114 @@ <appender-ref ref="FILE" /> </root> </configuration></pre></div> + + <a name="TriggeringPolicy"/> + <h3>Triggering policies</h3> + + <p><code>TriggeringPolicy</code> implementations are responsible for instructing + the <code>RollingFileAppender</code> to proceed to the rollover.</p> + + <p>The <code>TriggeringPolicy</code> interface is pretty simple.</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 boolean isTriggeringEvent(final File file, final Object event); +}</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 + parameters, whether the rollover must occur or not, by + returning a boolean value. + </p> + + <a name="SizeBasedTriggeringPolicy" /> + <h4>SizeBasedTriggeringPolicy</h4> + + <p> + <code>SizeBasedTriggeringPolicy</code> + looks at size of the file being currently written to. If it + grows bigger 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> + <b>Althought values expressed in <em>GB</em> are possible, + we do not recommand setting the <span class="option">MaxFileSize</span> + option to a value bigger than XXX GB</b>. + </p> + <p> + Here is a sample configuration with a <code>RollingFileAppender</code> + using a <code>SizeBasedTriggeringPolicy</code>. + </p> + +<div class="source"><pre><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> + + <b><triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> + <MaxFileSize>5MB</MaxFileSize> + </triggeringPolicy></b> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%-4relative [%thread] %-5level %class - %msg%n</Pattern> + </layout> + </appender> + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </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> - <h3>Triggering policies</h3> - - - <h2>Logback Classic</h2> + + + + + + + + + <h2>Logback Classic</h2> <h2>Logback Access</h2>