ceki 2004/11/24 05:56:32
Modified: src/java/org/apache/log4j/rolling
TimeBasedRollingPolicy.java
Log:
Javadoc enhancements
Revision Changes Path
1.13 +74 -21
logging-log4j/src/java/org/apache/log4j/rolling/TimeBasedRollingPolicy.java
Index: TimeBasedRollingPolicy.java
===================================================================
RCS file:
/home/cvs/logging-log4j/src/java/org/apache/log4j/rolling/TimeBasedRollingPolicy.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- TimeBasedRollingPolicy.java 23 Nov 2004 20:42:36 -0000 1.12
+++ TimeBasedRollingPolicy.java 24 Nov 2004 13:56:32 -0000 1.13
@@ -28,17 +28,16 @@
/**
* <code>TimeBasedRollingPolicy</code> is both easy to configure yet quite
- * powerful. It <em>requires</em> the user to set just one option, namely
the
- * <b>FileNamePattern</b> option.
+ * powerful.
*
- * <p>The <b>FileNamePattern</b> option basically specifies the name of the
- * rolled log files. In addition to the name of the file, the FileNamePattern
- * must contain a reference to a [EMAIL PROTECTED] DateTokenConverter} which
is specified
- * by the <code>%d</code> conversion specifier. Moreover, the
<code>%d</code>
- * conversion specifier may contain a date and time pattern as admitted by
- * the [EMAIL PROTECTED] java.text.SimpleDateFormat} class. If the date and
time
- * pattern is ommitted, then the default pattern of "yyyy-MM-dd" is assumed.
- * The following examples should clarify the point.
+ * <p>In order to use <code>TimeBasedRollingPolicy</code>, the
+ * <b>FileNamePattern</b> option must be set. It basically specifies the
name of the
+ * rolled log files. The value <code>FileNamePattern</code> should consist
of
+ * the name of the file, plus a suitably placed <code>%d</code> conversion
+ * specifier. The <code>%d</code> conversion specifier may contain a date
and
+ * time pattern as specified by the [EMAIL PROTECTED]
java.text.SimpleDateFormat} class. If
+ * the date and time pattern is ommitted, then the default pattern of
+ * "yyyy-MM-dd" is assumed. The following examples should clarify the point.
*
* <p>
* <table cellspacing="5px" border="1">
@@ -48,25 +47,79 @@
* <th>Example</th>
* </tr>
* <tr>
- * <td nowrap="true"><code>/some/folder/foo.log.%d</code></td>
- * <td>Daily rollover (at midnight).The %d token converter without the
optional time and date pattern
- * implies daily rollover.
+ * <td nowrap="true"><code>/wombat/folder/foo.%d</code></td>
+ * <td>Daily rollover (at midnight). Due to the omission of the
optional
+ * time and date pattern for the %d token specifier, the default
pattern
+ * of "yyyy-MM-dd" is assumed, which corresponds to daily rollover.
* </td>
* <td>During November 23rd, 2004, logging output will go to
- * <code>/some/folder/foo.2004-11-23</code>. At midnight and during
+ * the file <code>/wombat/foo.2004-11-23</code>. At midnight and for
* the rest of the 24th, logging output will be directed to
- * <code>/some/folder/foo.2004-11-24</code> until the start of the
- * next day.
+ * <code>/wombat/foo.2004-11-24</code>.
* </td>
* </tr>
* <tr>
- * <td nowrap="true"><code>/some/folder/foo.%d{yyyy-MM}.log</code></td>
+ * <td nowrap="true"><code>/wombat/foo.%d{yyyy-MM}.log</code></td>
* <td>Rollover at the beginning of each month.</td>
* <td>During the month of October 2004, logging output will go to
- * <code>/some/folder/foo.2004-10.log</code>. After midnight of October
31st
- * and during the rest of November, logging output will be directed to
- * <code>/some/folder/foo.2004-11.log</code> untill the beginning of
- * the next month.
+ * <code>/wombat/foo.2004-10.log</code>. After midnight of October 31st
+ * and for the rest of November, logging output will be directed to
+ * <code>/wombat/foo.2004-11.log</code>.
+ * </td>
+ * </tr>
+ * </table>
+ * <h2>Automatic file compression</h2>
+ * <code>TimeBasedRollingPolicy</code> supports automatic file compression.
+ * This feature is enabled if the value of the <b>FileNamePattern</b> option
+ * ends with <code>.gz</code> or <code>.zip</code>.
+ * <p>
+ * <table cellspacing="5px" border="1">
+ * <tr>
+ * <th><code>FileNamePattern</code> value</th>
+ * <th>Rollover schedule</th>
+ * <th>Example</th>
+ * </tr>
+ * <tr>
+ * <td nowrap="true"><code>/wombat/foo.%d.gz</code></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 <code>/wombat/foo.2004-11-23</code>. However, at midnight
that
+ * file will be compressed to become
<code>/wombat/foo.2004-11-23.gz</code>.
+ * For the 24th of November, logging output will be directed to
+ * <code>/some/folder/foo.2004-11-24</code> until its rolled over at
the
+ * beginning of the next day.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <h2>Decoupling the location of the active log file and the archived
files</h2>
+ * <p>The <em>active file</em> is defined as the log file for the current
period
+ * whereas <em>archived files</em> are thos files which have been rolled over
+ * in previous periods.
+ *
+ * <p>By setting the <b>ActiveFileName</b> option you can decouple the
location
+ * of the active log file and the location of the archived log files.
+ * <p>
+ * * <table cellspacing="5px" border="1">
+ * <tr>
+ * <th><code>FileNamePattern</code> value</th>
+ * <th>ActiveFileName</th>
+ * <th>Rollover schedule</th>
+ * <th>Example</th>
+ * </tr>
+ * <tr>
+ * <td nowrap="true"><code>/wombat/foo.log.%d</code></td>
+ * <td nowrap="true"><code>/wombat/foo.log</code></td>
+ * <td>Daily rollover.</td>
+ *
+ * <td>During November 23rd, 2004, logging output will go to
+ * the file <code>/wombat/foo.log</code>. However, at midnight that
file
+ * will archived as <code>/wombat/foo.log.2004-11-23</code>. For the
24th
+ * of November, logging output will be directed to
+ * <code>/wombat/folder/foo.log</code> until its archived as
+ * <code>/wombat/foo.log.2004-11-24</code> at the beginning of the
next
+ * day.
* </td>
* </tr>
* </table>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
