From 2b81f34d2b9f4426fca29493259b3ad48c5068cb Mon Sep 17 00:00:00 2001
From: kkolinko <kkolinko@13f79535-47bb-0310-9956-ffa450edef68>
Date: Thu, 21 Jul 2011 10:52:46 +0000
Subject: [PATCH] =?utf8?q?Trivial=20improvements=20to=20access=20log=20val?=
 =?utf8?q?ve=20docs.=20Fix=20typos=20noted=20by=20Andr=C3=A9=20Warnier.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1149104 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/catalina/valves/AccessLogValve.java | 33 ++++++++++++++++++++--
 .../catalina/valves/ExtendedAccessLogValve.java    | 10 +++----
 webapps/docs/config/valve.xml                      | 26 ++++++++---------
 3 files changed, 48 insertions(+), 21 deletions(-)

diff --git a/java/org/apache/catalina/valves/AccessLogValve.java b/java/org/apache/catalina/valves/AccessLogValve.java
index 0c630729b..e7376492d 100644
--- a/java/org/apache/catalina/valves/AccessLogValve.java
+++ b/java/org/apache/catalina/valves/AccessLogValve.java
@@ -59,7 +59,8 @@ import org.apache.tomcat.util.buf.B2CConverter;
  * <p>Implementation of the <b>Valve</b> interface that generates a web server
  * access log with the detailed line contents matching a configurable pattern.
  * The syntax of the available patterns is similar to that supported by the
- * Apache <code>mod_log_config</code> module.  As an additional feature,
+ * <a href="http://httpd.apache.org/">Apache HTTP Server</a>
+ * <code>mod_log_config</code> module.  As an additional feature,
  * automatic rollover of log files when the date changes is also supported.</p>
  *
  * <p>Patterns for the logged message may include constant text or any of the
@@ -101,7 +102,9 @@ import org.apache.tomcat.util.buf.B2CConverter;
  * <p>
  * There is also support to write information from the cookie, incoming
  * header, the Session or something else in the ServletRequest.<br>
- * It is modeled after the apache syntax:
+ * It is modeled after the
+ * <a href="http://httpd.apache.org/">Apache HTTP Server</a> log configuration
+ * syntax:
  * <ul>
  * <li><code>%{xxx}i</code> for incoming headers
  * <li><code>%{xxx}o</code> for outgoing response headers
@@ -112,10 +115,34 @@ import org.apache.tomcat.util.buf.B2CConverter;
  * </p>
  *
  * <p>
+ * Log rotation can be on or off. This is dictated by the rotatable
+ * property.
+ * </p>
+ *
+ * <p>
+ * For UvNIX users, another field called <code>checkExists</code> is also
+ * available. If set to true, the log file's existence will be checked before
+ * each logging. This way an external log rotator can move the file
+ * somewhere and tomcat will start with a new file.
+ * </p>
+ *
+ * <p>
+ * For JMX junkies, a public method called </code>rotate</code> has
+ * been made available to allow you to tell this instance to move
+ * the existing log file to somewhere else and start writing a new log file.
+ * </p>
+ * 
+ * <p>
  * Conditional logging is also supported. This can be done with the
  * <code>condition</code> property.
  * If the value returned from ServletRequest.getAttribute(condition)
- * yields a non-null value. The logging will be skipped.
+ * yields a non-null value, the logging will be skipped.
+ * </p>
+ * 
+ * <p>
+ * For extended attributes coming from a getAttribute() call,
+ * it is you responsibility to ensure there are no newline or
+ * control characters.
  * </p>
  *
  * @author Craig R. McClanahan
diff --git a/java/org/apache/catalina/valves/ExtendedAccessLogValve.java b/java/org/apache/catalina/valves/ExtendedAccessLogValve.java
index 53a33fd3e..5d30bdb9e 100644
--- a/java/org/apache/catalina/valves/ExtendedAccessLogValve.java
+++ b/java/org/apache/catalina/valves/ExtendedAccessLogValve.java
@@ -74,14 +74,14 @@ import org.apache.tomcat.util.ExceptionUtils;
  *                             certain POST parameters.
  * </li>
  * <li>For any of the x-H(...) the following method will be called from the
- *                HttpServletRequestObject </li>
+ *                HttpServletRequest object </li>
  * <li><code>x-H(authType)</code>: getAuthType </li>
  * <li><code>x-H(characterEncoding)</code>: getCharacterEncoding </li>
  * <li><code>x-H(contentLength)</code>: getContentLength </li>
  * <li><code>x-H(locale)</code>:  getLocale</li>
  * <li><code>x-H(protocol)</code>: getProtocol </li>
  * <li><code>x-H(remoteUser)</code>:  getRemoteUser</li>
- * <li><code>x-H(requestedSessionId)</code>: getGequestedSessionId</li>
+ * <li><code>x-H(requestedSessionId)</code>: getRequestedSessionId</li>
  * <li><code>x-H(requestedSessionIdFromCookie)</code>:
  *                  isRequestedSessionIdFromCookie </li>
  * <li><code>x-H(requestedSessionIdValid)</code>:
@@ -98,7 +98,7 @@ import org.apache.tomcat.util.ExceptionUtils;
  * </p>
  *
  * <p>
- * For UvNIX users, another field called <code>checkExists</code>is also
+ * For UvNIX users, another field called <code>checkExists</code> is also
  * available. If set to true, the log file's existence will be checked before
  * each logging. This way an external log rotator can move the file
  * somewhere and tomcat will start with a new file.
@@ -107,14 +107,14 @@ import org.apache.tomcat.util.ExceptionUtils;
  * <p>
  * For JMX junkies, a public method called </code>rotate</code> has
  * been made available to allow you to tell this instance to move
- * the existing log file to somewhere else start writing a new log file.
+ * the existing log file to somewhere else and start writing a new log file.
  * </p>
  *
  * <p>
  * Conditional logging is also supported. This can be done with the
  * <code>condition</code> property.
  * If the value returned from ServletRequest.getAttribute(condition)
- * yields a non-null value. The logging will be skipped.
+ * yields a non-null value, the logging will be skipped.
  * </p>
  *
  * <p>
diff --git a/webapps/docs/config/valve.xml b/webapps/docs/config/valve.xml
index 0c55d8fce..4846782a6 100644
--- a/webapps/docs/config/valve.xml
+++ b/webapps/docs/config/valve.xml
@@ -133,12 +133,11 @@
 
       <attribute name="prefix" required="false">
         <p>The prefix added to the start of each log file's name.  If not
-        specified, the default value is "access_log.".  To specify no prefix,
-        use a zero-length string.</p>
+        specified, the default value is "access_log.".</p>
       </attribute>
 
       <attribute name="requestAttributesEnabled" required="false">
-        <p>Set to <code>true</code> to check for the existance of request
+        <p>Set to <code>true</code> to check for the existence of request
         attributes (typically set by the RemoteIpValve and similar) that should
         be used to override the values returned by the request for remote
         address, remote host, server port and protocol. If the attributes are
@@ -154,8 +153,8 @@
 
       <attribute name="suffix" required="false">
         <p>The suffix added to the end of each log file's name.  If not
-        specified, the default value is "".  To specify no suffix,
-        use a zero-length string.</p>
+        specified, the default value is "" (a zero-length string),
+        meaning that no suffix will be added.</p>
       </attribute>
 
       <attribute name="rotatable" required="false">
@@ -230,7 +229,9 @@
     There is also support to write information incoming or outgoing
     headers, cookies, session or request attributes and special
     timestamp formats.
-    It is modeled after the apache syntax:
+    It is modeled after the
+    <a href="http://httpd.apache.org/">Apache HTTP Server</a> log configuration
+    syntax:
     <ul>
     <li><b><code>%{xxx}i</code></b> for incoming headers</li>
     <li><b><code>%{xxx}o</code></b> for outgoing response headers</li>
@@ -324,12 +325,11 @@
 
       <attribute name="prefix" required="false">
         <p>The prefix added to the start of each log file's name.  If not
-        specified, the default value is "access_log.".  To specify no prefix,
-        use a zero-length string.</p>
+        specified, the default value is "access_log.".</p>
       </attribute>
 
       <attribute name="requestAttributesEnabled" required="false">
-        <p>Set to <code>true</code> to check for the existance of request
+        <p>Set to <code>true</code> to check for the existence of request
         attributes (typically set by the RemoteIpValve and similar) that should
         be used to override the values returned by the request for remote
         address, remote host, server port and protocol. If the attributes are
@@ -345,8 +345,8 @@
 
       <attribute name="suffix" required="false">
         <p>The suffix added to the end of each log file's name.  If not
-        specified, the default value is "".  To specify no suffix,
-        use a zero-length string.</p>
+        specified, the default value is "" (a zero-length string),
+        meaning that no suffix will be added.</p>
       </attribute>
 
       <attribute name="rotatable" required="false">
@@ -414,7 +414,7 @@
     </ul>
 
     <p>For any of the <code>x-H(XXX)</code> the following method will be called from the
-    HttpServletRequestObject:</p>
+    HttpServletRequest object:</p>
     <ul>
     <li><b><code>x-H(authType)</code></b>: getAuthType </li>
     <li><b><code>x-H(characterEncoding)</code></b>: getCharacterEncoding </li>
@@ -422,7 +422,7 @@
     <li><b><code>x-H(locale)</code></b>:  getLocale</li>
     <li><b><code>x-H(protocol)</code></b>: getProtocol </li>
     <li><b><code>x-H(remoteUser)</code></b>:  getRemoteUser</li>
-    <li><b><code>x-H(requestedSessionId)</code></b>: getGequestedSessionId</li>
+    <li><b><code>x-H(requestedSessionId)</code></b>: getRequestedSessionId</li>
     <li><b><code>x-H(requestedSessionIdFromCookie)</code></b>:
                      isRequestedSessionIdFromCookie </li>
     <li><b><code>x-H(requestedSessionIdValid)</code></b>:
-- 
2.11.0