svn commit: r1578180 - /logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml

[ma...@apache.org]

Author: mattsicker
Date: Sun Mar 16 23:26:03 2014
New Revision: 1578180

URL: http://svn.apache.org/r1578180
Log:
Update architecture manual page.

  - Added more cross-references.
  - Fixed some spacing issues.

Modified:
    logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml

Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml?rev=1578180&r1=1578179&r2=1578180&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/architecture.xml Sun Mar 16 23:26:03 2014
@@ -72,7 +72,7 @@
           is a parent of
           <code>"java.util"</code>
           and an
-          ancestor of<code>"java.util.Vector"</code>. This naming scheme
+          ancestor of <code>"java.util.Vector"</code>. This naming scheme
           should be familiar to most developers.
         </p>
 
@@ -87,7 +87,7 @@
             LogManager.getLogger
           </a>
           static method by passing the name of the desired Logger. Further information on the Logging
-          API can be found at<a href="../log4j-api/api.html">Log4j 2 API</a>.
+          API can be found in the <a href="../log4j-api/api.html">Log4j 2 API</a>.
         </p>
         <h4>LoggerContext</h4>
         <p>
@@ -119,14 +119,14 @@
         </p>
         <h5>Retrieving Loggers</h5>
         <p>
-          Calling the <code>getLogger</code> method with the same name will always return a reference to the exact 
-          same Logger object.
+          Calling the <code>LogManager.getLogger</code> method with the same name will always return a reference to the
+          exact same Logger object.
         </p>
 
         <p>For example, in
 <pre class="prettyprint">
-Logger x = Logger.getLogger("wombat");
-Logger y = Logger.getLogger("wombat");
+Logger x = LogManager.getLogger("wombat");
+Logger y = LogManager.getLogger("wombat");
 </pre>
           <code>x</code> and <code>y</code> refer to <em>exactly</em> the same Logger object.
         </p>
@@ -147,6 +147,11 @@ Logger y = Logger.getLogger("wombat");
           loggers as desired.
         </p>
 
+        <p>Since naming Loggers after their owning class is such a common idiom, the convenience method
+          <code>LogManager.getLogger()</code> is provided to automatically use the calling class's fully
+          qualified class name as the Logger name.
+        </p>
+
         <p>Nevertheless, naming loggers after the class where they are
           located seems to be the best strategy known so far.
         </p>
@@ -479,11 +484,11 @@ Logger y = Logger.getLogger("wombat");
           be applied before control is passed to any LoggerConfig, after control is passed to a LoggerConfig
           but before calling any Appenders, after control is passed to a LoggerConfig but before calling a
           specific Appender, and on each Appender. In a manner very similar to firewall filters,
-          each Filter can return one of three results, Accept, Deny or Neutral. A response of Accept means
-          that no other Filters should be called and the event should progress. A response of Deny means
-          the event should be immediately ignored and control should be returned to the caller. A response
-          of Neutral indicates the event should be passed to other Filters. If there are no other Filters the
-          event will be processed.
+          each Filter can return one of three results, <code>Accept</code>, <code>Deny</code> or <code>Neutral</code>.
+          A response of <code>Accept</code> means that no other Filters should be called and the event should progress.
+          A response of <code>Deny</code> means the event should be immediately ignored and control should be returned
+          to the caller. A response of <code>Neutral</code> indicates the event should be passed to other Filters. If
+          there are no other Filters the event will be processed.
         </p>
         <p>Although an event may be accepted by a Filter the event still might not be logged. This can happen
           when the event is accepted by the pre-LoggerConfig Filter but is then denied by a LoggerConfig
@@ -498,7 +503,9 @@ Logger y = Logger.getLogger("wombat");
           destination is called an
           <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html">Appender</a>.
           Currently, appenders exist for the console, files, remote socket servers, Apache Flume,
-          JMS, and remote UNIX Syslog daemons. More than one Appender can be attached to a Logger.
+          JMS, remote UNIX Syslog daemons, and various database APIs. See the section on
+          <a href="appenders.html">Appenders</a> for more details on the various types available.
+          More than one Appender can be attached to a Logger.
         </p>
         <p>An Appender can be added to a Logger by calling the
           <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html#addLoggerAppender(org.apache.logging.log4j.core.Logger, org.apache.logging.log4j.core.Appender)">addLoggerAppender</a>
@@ -617,6 +624,11 @@ Logger y = Logger.getLogger("wombat");
           request. The text after the '-' is the message of the statement.
         </p>
 
+        <p>Log4j comes with many different <a href="layouts.html">Layouts</a> for various use cases such as
+          JSON, XML, HTML, and Syslog (including the new RFC 5424 version). Other appenders such as the
+          database connectors fill in specified fields instead of a particular textual layout.
+        </p>
+
         <p>Just as importantly, log4j will render the content of the log
           message according to user specified criteria. For example, if you
           frequently need to log <code>Oranges</code>, an object type used in