[logback-dev] svn commit: r865 - in logback/trunk: logback-examples/src/main/java/chapter4 logback-examples/src/main/java/chapter4/conf logback-site/src/site/xdocTemplates/manual logback-skin/src/main/resources/css

noreply.seb at qos.ch noreply.seb at qos.ch
Fri Nov 3 16:42:34 CET 2006


Author: seb
Date: Fri Nov  3 16:42:34 2006
New Revision: 865

Modified:
   logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java
   logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes.java
   logback/trunk/logback-examples/src/main/java/chapter4/IO.java
   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
   logback/trunk/logback-skin/src/main/resources/css/site.css

Log:
on going work on chapter 4

Modified: logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java	(original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/ConfigurationTester.java	Fri Nov  3 16:42:34 2006
@@ -32,6 +32,7 @@
     try {
       JoranConfigurator configurator = new JoranConfigurator();
       configurator.setContext(lc);
+      lc.reset();
       configurator.doConfigure(args[0]);
     } catch (JoranException je) {
       je.printStackTrace();

Modified: logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes.java
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes.java	(original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes.java	Fri Nov  3 16:42:34 2006
@@ -19,8 +19,6 @@
 import ch.qos.logback.core.WriterAppender;
 import ch.qos.logback.core.layout.EchoLayout;
 
-
-
 public class ExitWoes {
 
   public static void main(String[] args) throws Exception {

Modified: logback/trunk/logback-examples/src/main/java/chapter4/IO.java
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/IO.java	(original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/IO.java	Fri Nov  3 16:42:34 2006
@@ -17,8 +17,6 @@
 import ch.qos.logback.core.FileAppender;
 import ch.qos.logback.core.layout.EchoLayout;
 
-
-
 public class IO extends Thread {
   static String msgLong = "ABCDEGHIJKLMNOPQRSTUVWXYZabcdeghijklmnopqrstuvwxyz1234567890";
   static String msgShort = "Hello";

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  3 16:42:34 2006
@@ -1,27 +1,22 @@
 <configuration>
 
-	<appender name="FILE"
-		class="ch.qos.logback.core.rolling.RollingFileAppender">
-		<rollingPolicy
-			class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
-			<param name="ActiveFileName" value="testFile.log" />
-			<param name="FileNamePattern" value="testFile.%i.log" />
-			<param name="MinIndex" value="1" />
-			<param name="MaxIndex" value="3" />
+	<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">
-			<param name="MaxFileSize" value="5MB" />
+			<MaxFileSize>5MB</MaxFileSize>
 		</triggeringPolicy>
 		<layout class="ch.qos.logback.classic.PatternLayout">
-			<param name="Pattern"
-				value="%-4relative [%thread] %-5level %class - %msg%n" />
+			<Pattern>%-4relative [%thread] %-5level %class - %msg%n</Pattern>
 		</layout>
 	</appender>
-
-
-
+	
 	<root>
 		<level value="debug" />
 		<appender-ref ref="FILE" />

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  3 16:42:34 2006
@@ -1,12 +1,12 @@
 <configuration>
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+   <File>logFile.log</File>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
-     <param name="ActiveFileName" value="outputFile.log" />
-     <param name="FileNamePattern" value="logFile.%d{yyyy-MM-dd}.log" />
+     <FileNamePattern>logFile.%d{yyyy-MM-dd}.log</FileNamePattern>
    </rollingPolicy>
 
    <layout class="ch.qos.logback.classic.PatternLayout">
-     <param name="pattern" value="%-4relative [%thread] %-5level %class - %msg%n" />
+     <Pattern>%-4relative [%thread] %-5level %class - %msg%n</Pattern>
    </layout>
  </appender> 
 

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 16:42:34 2006
@@ -36,8 +36,7 @@
 							Creative Commons
 							Attribution-NonCommercial-ShareAlike 2.5
 							License
-						</a>
-						.
+						</a>.
 						<!--/Creative Commons License-->
 					</p>
 				</td>
@@ -93,6 +92,7 @@
 		transmitting them over the wire.
 	</p>
 	
+	<a name="AppenderBase"/>
 	<h2>AppenderBase</h2>
 	
 	<p>
@@ -151,7 +151,12 @@
 	</p>
 	
 	<p>
-		EXPLAIN GUARD
+		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
+		that just called it, which would then call it again.
 	</p>
 	
 	<p>
@@ -202,7 +207,7 @@
 	that are dynamically inferred using JavaBeans introspection. </p>
 	
 	<h2>Logback Core</h2>
-	
+	<a name="WriterAppender" />
 	<h3>WriterAppender</h3>
 	
 	<p>
@@ -324,7 +329,7 @@
 	<p><b>include UML??</b>
 		Figure 4 2 illustrates the class diagram for WriterAppender and its subclasses
 	</p>
-	
+	<a name="ConsoleAppender" />
 	<h3>ConsoleAppender</h3>
 	
 	<p>
@@ -362,8 +367,8 @@
 			</td>
 		</tr>
 	</table>
-	
-	<h3>FileAppendery</h3>
+	<a name="FileAppender" />
+	<h3>FileAppender</h3>
 	
 	<p>
 		The <code>FileAppender</code>, a subclass of <code>WriterAppender</code>, 
@@ -455,6 +460,542 @@
 		of this file is also available. 
 	</p>
 	
+	<a name="RollingFileAppender" />
+	<h3>RollingFileAppender</h3>
+	
+	<p>
+		<code>RollingFileAppender</code> extends <code>FileAppender</code> by 
+		allowing rolling from a log file to another. For example,
+		<code>RollingFileAppender</code> can log to a <em>log.txt</em> file and, 
+		once a certain condition is met, change its logging target to another file.
+	</p>
+	<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
+		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.
+	</p>
+	
+	<p>
+		To be of any use, a <code>RollingFileAppender</code> must have
+		both a <code>RollingPolicy</code> and a <code>TriggeringPolicy</code>
+		set up. However, if its <code>RollingPolicy</code> also implements the
+		<code>TriggeringPolicy</code> interface, then only the former needs to be
+		set up.
+	</p>
+	
+	<p>Here are the available options for <code>RollingFileAppender</code>:</p>
+	
+	<table>
+			<tr>
+			<th>Option Name</th>
+			<th>Type</th>
+			<th>Description</th>
+		</tr>
+		<tr>
+			<td><b><span class="option">Append</span></b></td>
+			<td><code>boolean</code></td>
+			<td>See <code>FileAppender</code> options.</td>
+		</tr>	
+		<tr>
+			<td><b><span class="option">BufferedIO</span></b></td>
+			<td><code>boolean</code></td>
+			<td>See <code>FileAppender</code> options.</td>
+		</tr>		
+		<tr>
+			<td><b><span class="option">BufferSize</span></b></td>
+			<td><code>int</code></td>
+			<td>See <code>FileAppender</code> options.</td>
+		</tr>	
+		<tr>
+			<td><b><span class="option">Encoding</span></b></td>
+			<td><code>int</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>See <code>FileAppender</code> options.</td>
+		</tr>	
+		<tr>
+			<td><b><span class="option">ImmediateFlush</span></b></td>
+			<td><code>int</code></td>
+			<td>See <code>WriterAppender</code> options.</td>
+		</tr>	
+		<tr>
+			<td><b><span class="option">RollingPolicy</span></b></td>
+			<td><code>RollingPolicy</code></td>
+			<td>
+				This option is the component that will dictate 
+				<code>RollingFileAppender</code>'s behaviour when the rollover
+				occurs. See more information below.
+			</td>
+		</tr>	
+		<tr>
+			<td><b><span class="option">TriggeringPolicy</span></b></td>
+			<td><code>TriggeringPolicy</code></td>
+			<td>
+				This option is the component that will tell 
+				<code>RollingFileAppender</code> when to activate the rollover
+				procedure. See more information below.
+			</td>
+		</tr>	
+	</table>
+	
+	<h3>Rolling policies</h3>
+	<a name="FixedWindowRollingPolicy" />
+	<h4>FixedWindowRollingPolicy</h4>
+
+	<p>
+		When rolling over, <code>FixedWindowRollingPolicy</code>
+		renames files according to a fixed window algorithm as described below.
+	</p>
+	<p>
+		The <b>File</b>property, 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>
+		option represents the file name pattern for the archived (rolled over) log files. 
+		The <b>FileNamePattern</b> option, which is also required, must include 
+		an integer token, that is the string <em>%i</em>
+		somewhere within the pattern.
+	</p>
+	
+	<p>
+		Here are the available options for <code>FixedWindowRollingPolicy</code>
+	</p>
+	
+	<table>
+			<tr>
+			<th>Option Name</th>
+			<th>Type</th>
+			<th>Description</th>
+		</tr>
+		<tr>
+			<td><b><span class="option">FileNamePattern</span></b></td>
+			<td><code>String</code></td>
+			<td>
+				<p>
+					This option represents the pattern that will be followed by
+					the <code>FixedWindowRollingPolicy</code> when renaming the
+					log files. If must contain the string <em>%i</em>, which will
+					indicate the position where to insert the file's index.
+				</p>
+				<p>
+					For example, using <em>MyLogFile%i.log</em>, associated with
+					minimum and maximum values of <em>1</em> and <em>3</em> will produce 
+					files named <em>MyLogFile1.log</em>, <em>MyLogFile2.log</em> and
+					<em>MyLogFile3.log</em>.
+				</p>
+				<p>
+					File compression is also specified in the 
+					<span class="option">FileNamePattern</span> option. 
+					<em>MyLogFile%i.log.zip</em> will indicate to the
+					<code>FixedWindowRollingPolicy</code> that the archived file
+					must be compressed using the <em>zip</em> format. The <em>gz</em>
+					format is also supported.
+				</p>
+			</td>
+		</tr>	
+		<tr>
+			<td><b><span class="option">MaxIndex</span></b></td>
+			<td><code>int</code></td>
+			<td>
+				<p>
+					This option represents the maximum border of the window algorithm.
+				</p>
+			</td>
+		</tr>
+		<tr>
+			<td><b><span class="option">MinIndex</span></b></td>
+			<td><code>int</code></td>
+			<td>
+				<p>
+					This option represents the minimum border of the window algorithm.
+				</p>
+			</td>
+		</tr>
+	</table>
+
+	<p>
+		Given that this rollover algorithm requires as many file
+		renaming operations as the window size, large window sizes are
+		discouraged. The current implementation will automatically
+		reduce the window size to 12 when larger values are specified by
+		the user.
+	</p>
+
+	<p>
+		Here is an example of file handling by <code>FixedWindowRollingPolicy</code>.
+		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> 
+		option is set to <em>foo.log</em>.
+	</p>
+	
+	<table>
+		<tr>
+			<th>
+				Steps
+			</th>
+			<th>
+				Active file name
+			</th>
+			<th>
+				Archived file names
+			</th>
+			<th>Description</th>
+		</tr>
+		<tr>
+			<td>
+				0
+			</td>
+			<td>
+				foo.log
+			</td>
+			<td>
+				-
+			</td>
+			<td>
+				No rollover has happened yet, logback logs 
+				into the initial file.
+			</td>
+		</tr>		
+		<tr>
+			<td>
+				1
+			</td>
+			<td>
+				foo.log
+			</td>
+			<td>
+				foo1.log
+			</td>
+			<td>
+				First rollover. <em>foo.log</em> is renamed into <em>foo1.log</em> and
+				a new <em>foo.log</em> file is created and used for the output.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				2
+			</td>
+			<td>
+				foo.log
+			</td>
+			<td>
+				foo2.log, foo1.log
+			</td>
+			<td>
+				Second rollover. <em>foo.log</em> is renamed into <em>foo1.log</em> and
+				the old <em>foo1.log</em> is renamed into <em>foo2.log</em>.
+				Again, a new <em>foo.log</em> file is created and used for the output.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				3
+			</td>
+			<td>
+				foo.log
+			</td>
+			<td>
+				foo3.log, foo2.log, foo1.log
+			</td>
+			<td>
+				Third rollover. <em>foo.log</em> is renamed into <em>foo1.log</em> and
+				the old <em>foo1.log</em> is renamed into <em>foo2.log</em>. As well, the
+				old <em>foo2.log</em> is renamed into <em>foo3.log</em>.
+				A new <em>foo.log</em> file is created and used for the output.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				4
+			</td>
+			<td>
+				foo.log
+			</td>
+			<td>
+				foo3.log, foo2.log, foo1.log
+			</td>
+			<td>
+				At 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
+				for the time of 3 rollovers and being deleted afterwards.
+			</td>
+		</tr>
+	</table>
+	
+	<p>
+		Here is a sample configuration to use <code>RollingFileAppender</code>
+		and <code>FixedWindowRollingPolicy</code>.
+	</p>
+<div class="source"><pre>&lt;configuration>
+  &lt;appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+    &lt;File>testFile.log&lt;/File>
+    &lt;rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+      &lt;FileNamePattern>testFile.%i.log.zip&lt;/FileNamePattern>
+      &lt;MinIndex>1&lt;/MinIndex>
+      &lt;MaxIndex>3&lt;/MaxIndex>
+    &lt;/rollingPolicy>
+
+    &lt;triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+      &lt;MaxFileSize>5MB&lt;/MaxFileSize>
+    &lt;/triggeringPolicy>
+    &lt;layout class="ch.qos.logback.classic.PatternLayout">
+      &lt;Pattern>%-4relative [%thread] %-5level %class - %msg%n&lt;/Pattern>
+    &lt;/layout>
+  &lt;/appender>
+	
+  &lt;root>
+    &lt;level value="debug" />
+    &lt;appender-ref ref="FILE" />
+  &lt;/root>
+&lt;/configuration></pre></div>
+	
+	<a name="TimeBasedRollingPolicy" />
+	<h4>TimeBasedRollingPolicy</h4>
+	<p>
+		<code>TimeBasedRollingPolicy</code> is both easy to configure and quite powerful.
+		It allows the rollover to be made based on time conditions. It is possible to specify
+		that the rollover must occur each day, or month, for example.
+	</p>
+	<p>
+		<code>TimeBasedRollingPolicy</code>'s only option is the
+		<span class="option">FileNamePattern</span>.
+	</p>
+	
+	<p>
+		In order to use
+		<code>TimeBasedRollingPolicy</code>, the
+		<span class="option">FileNamePattern</span> option must be set. It basically 
+		specifies the name of the rolled log files. The 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 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 should
+		clarify the point.
+	</p>
+	<table>
+		<tr>
+			<th>
+				<span class="option">FileNamePattern</span>
+			</th>
+			<th>Roll-over schedule</th>
+			<th>Example</th>
+		</tr>
+		<tr>
+			<td>
+				<em>/wombat/folder/foo.%d</em>
+			</td>
+			<td>
+				Daily rollover (at midnight). Due to the omission of the
+				optional time and date pattern for the <em>%d</em> token
+				specifier, the default pattern of <em>yyyy-MM-dd</em> is
+				assumed, which corresponds to daily rollover.
+			</td>
+			<td>
+				During November 23rd, 2006, logging output will go to
+				the file <em>/wombat/foo.2006-11-23</em>. 
+				At midnight and for the rest of the 24th, logging
+				output will be directed to <em>/wombat/foo.2006-11-24</em>.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				<em>/wombat/foo.%d{yyyy-MM}.log</em>
+			</td>
+			<td>Rollover at the beginning of each month.</td>
+			<td>
+				During the month of October 2006, logging output will go
+				to <em>/wombat/foo.2006-10.log</em>. 
+				After midnight of October 31st and for the rest of
+				November, logging output will be directed to
+				<em>/wombat/foo.2006-11.log</em>.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				<em>/wombat/foo.%d{yyyy-ww}.log</em>
+			</td>
+			<td>Rollover at the first day of each week. Note that the first
+			day of the week depends on the locale.</td>
+			<td>
+				During the 23rd week of 2006, the file <em>/wombat/foo.2006-23.log</em> 
+				will contain the actual logging output. 
+				Logging for the 24th week of 2006 will be output to 
+				<em>/wombat/foo.2006-24.log</em> 
+				until it is rolled over at the beginning of the next week.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				<em>/wombat/foo.%d{yyyy-MM-dd-a}.log</em>
+			</td>
+			<td>Rollover at midnight and midday of each day.</td>
+			<td>
+				During the first 12 hours of November 3rd, 2006, the logging
+				will be output to <em>/wombat/foo.2006-11-03-AM.log</em>.
+				After noon, and until  midnight, the logging will be output to
+				<em>/wombat/foo.2006-11-03-PM.log</em>.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				<em>/wombat/foo.%d{yyyy-MM-dd_HH}.log</em>
+			</td>
+			<td>Rollover at the top of each hour.</td>
+			<td>
+				Between 11.00,001 and 11.59,999, on November 3rd, 2006, the logging
+				will be output to <em>/wombat/foo.2006-11-03_11.log</em>.
+				After that, and until  12.59,999, the logging will be output to
+				<em>/wombat/foo.2006-11-03_12.log</em>.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				<em>/wombat/foo.%d{yyyy-MM-dd_HH-mm}.log</em>
+			</td>
+			<td>Rollover at the beggining of every minute.</td>
+			<td>
+				Between 11.32,001 and 11.32,999, on November 3rd, 2006, the logging
+				will be output to <em>/wombat/foo.2006-11-03_11-32.log</em>.
+				After that, and until  12.33,999, the logging will be output to
+				<em>/wombat/foo.2006-11_12-33.log</em>.
+			</td>
+		</tr>
+	</table>
+	
+	<p>
+		Any characters in the pattern outside the ranges <em>['a'..'z']</em> and <em>['A'..'Z']</em> 
+		will be treated as quoted text. For instance, characters like <em>'.'</em>, <em>' '</em>, 
+		<em>'#'</em> and <em>'@'</em> will appear in the resulting time text even when they are not 
+		enclosed within single quotes. Nevertheless, we would recommend against 
+		using the colon <em>":"</em> character anywhere within the 
+		<span class="option">FileNamePattern</span> option. 
+		The text before the colon is interpreted as the protocol specification of a 
+		URL, which is most probably not what you intend. The slash <em>"/"</em> character, a 
+		common date field separator, must also be avoided. It is taken as a file 
+		separator causing the rollover operation to fail because the target file cannot 
+		be created. Although less common, the backslash character <em>"\"</em> is equally troublesome.
+	</p>
+
+	<p>
+		Just like <code>FixedWindowRollingPolicy</code>, <code>TimeBasedRollingPolicy</code> 
+		supports automatic file compression. 
+		This feature is enabled if the value of the <span class="option">FileNamePattern</span> option 
+		ends with <em>.gz</em> or <em>.zip</em>.
+	</p>
+	<table>
+	  <tr>
+	    <th><span class="option">FileNamePattern</span></th>
+	    <th>Rollover schedule</th>
+	    <th>Example</th>
+	  </tr>
+	  <tr>
+	    <td><em>/wombat/foo.%d.gz</em></td>
+	    <td>Daily rollover (at midnight) with automatic GZIP compression of the 
+	     arcived files.</td>
+	    <td>During November 23rd, 2004, logging output will go to 
+	      the file <em>/wombat/foo.2004-11-23</em>. However, at midnight that
+	      file will be compressed to become <em>/wombat/foo.2004-11-23.gz</em>.
+	      For the 24th of November, logging output will be directed to 
+	      <em>/wombat/folder/foo.2004-11-24</em> until its rolled over at the
+	      beginning of the next day.
+	    </td>
+	  </tr>
+	</table>
+	
+	<p>
+		As we have seen, the <span class="option">FileNamePattern</span> serves two purposes. First,
+		by studying the pattern, logback computes the requested rollover periodicity. Second,
+		it uses the pattern to custom each rolled files. It is entirely possible for two different
+		file name patterns to specify the same periodicity.
+		The date patterns <em>yyyy-MM</em> and <em>yyyy at MM</em> both specify monthly 
+		rollover periodicity, although the rolled files will carry different customizations.
+	</p>
+	
+	<p>
+		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>
+		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>.
+	</p>
+	
+	<p>
+		With <code>TimeBasedRollingPolicy</code>, it is possible to
+		decouple the location of the active log file and the archived log files
+	</p>
+	<p>
+		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>
+	<p>
+		By setting the <span class="option">File</span> option you can 
+		decouple the location of the active log file and the location 
+		of the archived log files. The actual logging will be done in the
+		file specified by the <span class="option">File</span> option. This way,
+		the active file name will never change. By not setting the
+		<span class="option">File</span> option, logback uses the 
+		<span class="option">FileNamePattern</span> to name the active file,
+		whose name will change each time a rollover occurs.
+	</p>
+	
+	<p>
+		For various efficiency reasons, rollovers are not time-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  
+		<em>yyyy-MM-dd</em> (daily rollover), the arrival of the first 
+		event after midnight will trigger rollover. If there are no logging events 
+		during, say 23 minutes and 47 seconds after midnight, 
+		then rollover will occur at 00:23'47 AM on March 9th and not at 0:00 AM. 
+		Thus, depending on the arrival rate of events, rollovers might be triggered 
+		with some latency.  However, regardless of the delay, the rollover algorithm 
+		is known to be correct, in the sense that all logging events generated 
+		during a certain period will be output in the correct file delimiting that period.
+	</p>
+	
+	<p>Here is a sample configuration of a <code>RollingFileAppender</code> which
+	uses a <code>TimeBasedRollingPolicy</code>
+	</p>
+	
+<div class="source"><pre>&lt;configuration>
+  &lt;appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+    &lt;File>logFile.log&lt;/File>
+    &lt;rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+      &lt;FileNamePattern>logFile.%d{yyyy-MM-dd}.log&lt;/FileNamePattern>
+    &lt;/rollingPolicy>
+
+    &lt;layout class="ch.qos.logback.classic.PatternLayout">
+      &lt;Pattern>%-4relative [%thread] %-5level %class - %msg%n&lt;/Pattern>
+    &lt;/layout>
+  &lt;/appender> 
+
+  &lt;root>
+    &lt;level value="debug" />
+    &lt;appender-ref ref="FILE" />
+  &lt;/root>
+&lt;/configuration></pre></div>
+	
+
+
+
+
+
+		<h3>Triggering policies</h3>
+	
+	
 	<h2>Logback Classic</h2>
 	
 	<h2>Logback Access</h2>

Modified: logback/trunk/logback-skin/src/main/resources/css/site.css
==============================================================================
--- logback/trunk/logback-skin/src/main/resources/css/site.css	(original)
+++ logback/trunk/logback-skin/src/main/resources/css/site.css	Fri Nov  3 16:42:34 2006
@@ -104,8 +104,8 @@
 	/*color: #900;*/
 	color: navy;
 	background-color: white;
-	font-weight: normal;
-	font-size: large;
+	font-weight: large;
+	font-size: normal;
 }
 
 h5 {



More information about the logback-dev mailing list