From 5a9f3399dbd59334b048887470aea26394d662a5 Mon Sep 17 00:00:00 2001
From: kkolinko <kkolinko@13f79535-47bb-0310-9956-ffa450edef68>
Date: Thu, 31 Mar 2011 10:43:22 +0000
Subject: [PATCH] Improve the logging documentation

git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1087247 13f79535-47bb-0310-9956-ffa450edef68
---
 java/org/apache/juli/AsyncFileHandler.java | 17 +++++++++++++
 java/org/apache/juli/FileHandler.java      | 38 ++++++++++++++++++++++++++++--
 webapps/docs/logging.xml                   | 24 +++++++++++++++----
 3 files changed, 73 insertions(+), 6 deletions(-)

diff --git a/java/org/apache/juli/AsyncFileHandler.java b/java/org/apache/juli/AsyncFileHandler.java
index 31895655f..c58050e43 100644
--- a/java/org/apache/juli/AsyncFileHandler.java
+++ b/java/org/apache/juli/AsyncFileHandler.java
@@ -20,6 +20,23 @@ import java.util.concurrent.LinkedBlockingDeque;
 import java.util.concurrent.TimeUnit;
 import java.util.logging.LogRecord;
 /**
+ * A {@link FileHandler} implementation that uses a queue of log entries.
+ *
+ * <p>Configuration properties are inherited from the {@link FileHandler}
+ * class. This class does not add its own configuration properties for the
+ * logging configuration, but relies on the following system properties
+ * instead:</p>
+ * 
+ * <ul>
+ *   <li><code>org.apache.juli.AsyncOverflowDropType</code>
+ *    Default value: <code>1</code></li>
+ *   <li><code>org.apache.juli.AsyncMaxRecordCount</code>
+ *    Default value: <code>10000</code></li>
+ *   <li><code>org.apache.juli.AsyncLoggerPollInterval</code>
+ *    Default value: <code>1000</code></li>
+ * </ul>
+ * 
+ * <p>See the System Properties page in the configuration reference of Tomcat.</p>
  * 
  * @author Filip Hanik
  *
diff --git a/java/org/apache/juli/FileHandler.java b/java/org/apache/juli/FileHandler.java
index cfae91b38..f337d22e1 100644
--- a/java/org/apache/juli/FileHandler.java
+++ b/java/org/apache/juli/FileHandler.java
@@ -39,8 +39,42 @@ import java.util.logging.SimpleFormatter;
 
 /**
  * Implementation of <b>Handler</b> that appends log messages to a file
- * named {prefix}.{date}.{suffix} in a configured directory, with an
- * optional preceding timestamp.
+ * named {prefix}{date}{suffix} in a configured directory.
+ *
+ * <p>The following configuration properties are available:</p>
+ * 
+ * <ul>
+ *   <li><code>directory</code> - The directory where to create the log file.
+ *    If the path is not absolute, it is relative to the current working
+ *    directory of the application. The Apache Tomcat configuration files usually
+ *    specify an absolute path for this property,
+ *    <code>${catalina.base}/logs</code> 
+ *    Default value: <code>logs</code></li>
+ *   <li><code>rotatable</code> - If <code>true</code>, the log file will be
+ *    rotated on the first write past midnight and the filename will be
+ *    <code>{prefix}{date}{suffix}</code>, where date is yyyy-MM-dd. If <code>false</code>,
+ *    the file will not be rotated and the filename will be <code>{prefix}{suffix}</code>.
+ *    Default value: <code>true</code></li>
+ *   <li><code>prefix</code> - The leading part of the log file name.
+ *    Default value: <code>juli.</code></li>
+ *   <li><code>suffix</code> - The trailing part of the log file name. Default value: <code>.log</code></li>
+ *   <li><code>bufferSize</code> - Configures buffering. The value of <code>0</code>
+ *    uses system default buffering (typically an 8K buffer will be used). A
+ *    value of <code>&lt;0</code> forces a writer flush upon each log write. A
+ *    value <code>&gt;0</code> uses a BufferedOutputStream with the defined
+ *    value but note that the system default buffering will also be
+ *    applied. Default value: <code>-1</code></li>
+ *   <li><code>encoding</code> - Character set used by the log file. Default value:
+ *    empty string, which means to use the system default character set.</li>
+ *   <li><code>level</code> - The level threshold for this Handler. See the
+ *    <code>java.util.logging.Level</code> class for the possible levels.
+ *    Default value: <code>ALL</code></li>
+ *   <li><code>filter</code> - The <code>java.util.logging.Filter</code>
+ *    implementation class name for this Handler. Default value: unset</li>
+ *   <li><code>formatter</code> - The <code>java.util.logging.Formatter</code>
+ *    implementation class name for this Handler. Default value:
+ *    <code>java.util.logging.SimpleFormatter</code></li>
+ * </ul>
  *
  * @version $Id$
  */
diff --git a/webapps/docs/logging.xml b/webapps/docs/logging.xml
index 75626efe3..67625806a 100644
--- a/webapps/docs/logging.xml
+++ b/webapps/docs/logging.xml
@@ -113,9 +113,7 @@
     </p>
 
     <p>
-      More details about Tomcat JULI may be found below and in Tomcat Javadoc
-      for the <a href="api/org/apache/juli/package-summary.html"><code>org.apache.juli</code></a>
-      package.
+      More details about Tomcat JULI may be found below.
     </p>
 
     </subsection>
@@ -371,6 +369,20 @@ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
       </source>
     </p>
 
+    <subsection name="References">
+      <p>See the following resources for additional information:</p>
+      <ul>
+        <li>Tomcat Javadoc for the
+          <a href="api/org/apache/juli/package-summary.html"><code>org.apache.juli</code></a>
+          package.
+        </li>
+        <li>Oracle Java 6 Javadoc for the
+          <a href="http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html"><code>java.util.logging</code></a>
+          package.
+        </li>
+      </ul>
+    </subsection>
+
   </section>
 
   <section name="Using Log4j">
@@ -459,7 +471,11 @@ log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/hos
             <code>output/extras/tomcat-juli.jar</code>.</li>
 
         <li>Place <code>output/extras/tomcat-juli-adapters.jar</code> in 
-            $CATALINA_HOME/lib.</li>
+            $CATALINA_HOME/lib.<br />
+            Note, that <code>tomcat-juli.jar</code> and
+            <code>tomcat-juli-adapters.jar</code> go into different
+            directories. While the first one goes into <code>bin</code>, this
+            one goes into <code>lib</code>.</li>
 
         <li>Delete <code>$CATALINA_BASE/conf/logging.properties</code> to
             prevent java.util.logging generating zero length log files.</li>
-- 
2.11.0