logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgo...@apache.org
Subject svn commit: r1240834 - in /logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers: log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ src/site/ src/site/xdoc/manual/
Date Sun, 05 Feb 2012 21:50:05 GMT
Author: rgoers
Date: Sun Feb  5 21:50:04 2012
New Revision: 1240834

URL: http://svn.apache.org/viewvc?rev=1240834&view=rev
Log:
Finish documenting the API

Added:
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/eventlogging.xml
      - copied, changed from r1236171, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/flowtracing.xml
      - copied, changed from r1236171, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/markers.xml
      - copied, changed from r1236171, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml
Modified:
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ExtendedThrowablePatternConverter.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/PatternParser.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/messages.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ExtendedThrowablePatternConverter.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ExtendedThrowablePatternConverter.java?rev=1240834&r1=1240833&r2=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ExtendedThrowablePatternConverter.java (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ExtendedThrowablePatternConverter.java Sun Feb  5 21:50:04 2012
@@ -64,6 +64,10 @@ public final class ExtendedThrowablePatt
             }
             ThrowableProxy t = (ThrowableProxy) throwable;
             String trace = t.getExtendedStackTrace();
+            int len = toAppendTo.length();
+            if (len > 0 && !Character.isWhitespace(toAppendTo.charAt(len - 1))) {
+                toAppendTo.append(" ");
+            }
             if (lines > 0) {
                 StringBuilder sb = new StringBuilder();
                 String[] array = trace.split("\n");

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/PatternParser.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/PatternParser.java?rev=1240834&r1=1240833&r2=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/PatternParser.java (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/PatternParser.java Sun Feb  5 21:50:04 2012
@@ -414,7 +414,7 @@ public final class PatternParser {
             return null;
         }
 
-        Method[] methods = converterClass.getMethods();
+        Method[] methods = converterClass.getDeclaredMethods();
         Method newInstance = null;
         for (Method method : methods) {
             if (method.getName().equals("newInstance")) {

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.java?rev=1240834&r1=1240833&r2=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.java (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.java Sun Feb  5 21:50:04 2012
@@ -65,6 +65,10 @@ public final class RootThrowablePatternC
             }
             ThrowableProxy t = (ThrowableProxy) throwable;
             String trace = t.getRootCauseStackTrace();
+            int len = toAppendTo.length();
+            if (len > 0 && !Character.isWhitespace(toAppendTo.charAt(len - 1))) {
+                toAppendTo.append(" ");
+            }
             if (lines > 0) {
                 StringBuilder sb = new StringBuilder();
                 String[] array = trace.split("\n");

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.java?rev=1240834&r1=1240833&r2=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.java (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.java Sun Feb  5 21:50:04 2012
@@ -96,6 +96,10 @@ public class ThrowablePatternConverter e
         if (t != null) {
             StringWriter w = new StringWriter();
             t.printStackTrace(new PrintWriter(w));
+            int len = toAppendTo.length();
+            if (len > 0 && !Character.isWhitespace(toAppendTo.charAt(len - 1))) {
+                toAppendTo.append(" ");
+            }
             if (lines > 0) {
                 StringBuilder sb = new StringBuilder();
                 String[] array = w.toString().split("\n");

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml?rev=1240834&r1=1240833&r2=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml Sun Feb  5 21:50:04 2012
@@ -48,8 +48,9 @@
       <item name="Architecture" href="/manual/architecture.html"/>
       <item name="API" href="/manual/api.html" collapse="true">
         <item name="Overview" href="manual/api.html#Overview"/>
-        <item name="Markers" href="manual/api.html#Markers"/>
-        <item name="Event Logging" href="/manual/api.html#EventLogging"/>
+        <item name="Flow Tracing" href="manual/flowtracing.html"/>
+        <item name="Markers" href="manual/markers.html"/>
+        <item name="Event Logging" href="/manual/eventlogging.html"/>
         <item name="Messages" href="/manual/messages.html"/>
         <item name="ThreadContext" href="/manual/thread-context.html"/>
       </item>

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml?rev=1240834&r1=1240833&r2=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml Sun Feb  5 21:50:04 2012
@@ -73,15 +73,6 @@
               only occur when debug logging is enabled.
             </p>
           </subsection>
-          <a name="Markers"/>
-          <subsection name="Markers">
-
-          </subsection>
-          <a name="EventLogging"/>
-          <subsection name="EventLogging">
-
-          </subsection>
-
         </section>
     </body>
 </document>
\ No newline at end of file

Copied: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/eventlogging.xml (from r1236171, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/eventlogging.xml?p2=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/eventlogging.xml&p1=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml&r1=1236171&r2=1240834&rev=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/eventlogging.xml Sun Feb  5 21:50:04 2012
@@ -24,64 +24,118 @@
 
     <body>
         <section name="Log4j 2.0 API">
-          <a name="Overview"/>
-          <subsection name="Overview">
-            <p>
-              The Log4Jj 2.0 API provides the interface that applications should code to and provides the
-              adapter components required for implementers to create a logging implementation. Although Log4j 2
-              is broken up between an API and an implementation, the primary purpose of doing so was not to
-              allow multiple implementations, although that is certainly possible, but to clearly define
-              what classes and methods are safe to use in "normal" application code.
-            </p>
-            <h4>Hello World!</h4>
+          <a name="EventLogging"/>
+          <subsection name="Event Logging">
             <p>
-              No introduction would be complete without the customary Hello, World example. Here is ours. First,
-              a Logger with the name "HelloWorld" is obtained from the LogManager. Next, the logger is used to
-              write the "Hello, World!" message, however the message will be written only if the Logger is
-              configured to allow informational messages.
-            </p>
-            <source>    import org.apache.logging.log4j.LogManager;
-    import org.apache.logging.log4j.Logger;
+              The EventLogger class provides a simple mechansim for logging events that occur in an application.
+              While the EventLogger is useful as a way of initiating events that should be processed by an audit
+              Logging system, by itself it does not implement any of the features an audit logging system would require
+              such as guaranteed delivery.
+            </p>
+            <p>The recommended way of using the EventLogger in a typcial web application is to populate
+              the ThreadContext Map with data that is related to the entire lifespan of the request such as the user's
+              id, the user's ip address, the product name, etc. This can easily be done in a servlet fileter where
+              the ThreadContext Map can also be cleared at the end of the request. When an event that needs to be
+              recorded occurs a StructuredDataMessage should be created and populated.
+              Then call EventLogger.logEvent(msg) where msg is a reference to the StructuredDataMessage.</p>
+
+            <source>    import org.apache.logging.log4j.ThreadContext;
+    import org.apache.commons.lang.time.DateUtils;
+
+    import javax.servlet.Filter;
+    import javax.servlet.FilterConfig;
+    import javax.servlet.ServletException;
+    import javax.servlet.ServletRequest;
+    import javax.servlet.ServletResponse;
+    import javax.servlet.FilterChain;
+    import javax.servlet.http.HttpSession;
+    import javax.servlet.http.HttpServletRequest;
+    import javax.servlet.http.Cookie;
+    import javax.servlet.http.HttpServletResponse;
+    import java.io.IOException;
+    import java.util.TimeZone;
+
+    public class RequestFilter implements Filter {
+        private FilterConfig filterConfig;
+        private static String TZ_NAME = "timezoneOffset";
 
-    public class HelloWorld {
-        private static Logger logger = LogManager.getLogger("HelloWorld");
-        public static void main(String[] args) {
-            logger.info("Hello, World!");
+        public void init(FilterConfig filterConfig) throws ServletException {
+            this.filterConfig = filterConfig;
+        }
+
+        /**
+         * Sample filter that populates the MDC on every request.
+         */
+        public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)
+                throws IOException, ServletException {
+            HttpServletRequest request = (HttpServletRequest)servletRequest;
+            HttpServletResponse response = (HttpServletResponse)servletResponse;
+            ThreadContext.put("ipAddress", request.getRemoteAddr());
+            HttpSession session = request.getSession(false);
+            TimeZone timeZone = null;
+            if (session != null) {
+                // Something should set this after authentication completes
+                String loginId = (String)session.getAttribute("LoginId");
+                if (loginId != null) {
+                    ThreadContext.put("loginId", loginId);
+                }
+                // This assumes there is some javascript on the user's page to create the cookie.
+                if (session.getAttribute(TZ_NAME) == null) {
+                    if (request.getCookies() != null) {
+                        for (Cookie cookie : request.getCookies()) {
+                            if (TZ_NAME.equals(cookie.getName())) {
+                                int tzOffsetMinutes = Integer.parseInt(cookie.getValue());
+                                timeZone = TimeZone.getTimeZone("GMT");
+                                timeZone.setRawOffset((int)(tzOffsetMinutes * DateUtils.MILLIS_PER_MINUTE));
+                                request.getSession().setAttribute(TZ_NAME, tzOffsetMinutes);
+                                cookie.setMaxAge(0);
+                                response.addCookie(cookie);
+                            }
+                        }
+                    }
+                }
+            }
+            ThreadContext.put("hostname", servletRequest.getServerName());
+            ThreadContext.put("productName", filterConfig.getInitParameter("ProductName"));
+            Threadcontext.put("locale", servletRequest.getLocale().getDisplayName());
+            if (timeZone == null) {
+                timeZone = TimeZone.getDefault();
+            }
+            ThreadContext.put("timezone", timeZone.getDisplayName());
+            filterChain.doFilter(servletRequest, servletResponse);
+            ThreadContext.clear();
+        }
+
+        public void destroy() {
         }
     }</source>
-            <p>
-              The output from the call to logger.info() will vary significantly depending on the configuration
-              used. See the <a href="./configuration.html">Configuration</a> section for more details.
-            </p>
-            <h4>Parameter Substitution</h4>
-            <p>
-              Frequently the purpose of logging is to provide information about what is happening in the system,
-              which requires including information about the objects being manipulated. In Log4j 1.x this could
-              be accomplished by doing:
-            </p>
-            <source>    if (logger.isDebugEnabled()) {
-        logger.debug("Logging in user " + user.getName() + " with id " + user.getId());
-    }</source>
-            <p>
-              Doing this repeatedly has the effect of making the code feel like it is more about logging than the
-              actual task at hand. In addition, it results in the logging level being checked twice; once on the
-              call to isDebugEnabled and once on the debug method. A better alternative would be:
-            </p>
-            <source>    logger.debug("Logging in user {} with id {}", user.getName(), user.getId());</source>
-            <p>
-              With the code above the logging level will only be checked once and the String construction will
-              only occur when debug logging is enabled.
-            </p>
-          </subsection>
-          <a name="Markers"/>
-          <subsection name="Markers">
+            <p>Sample class that uses EventLogger.</p>
+            <source>    import org.apache.logging.log4j.StructuredDataMessage;
+    import org.apache.logging.log4j.EventLogger;
 
-          </subsection>
-          <a name="EventLogging"/>
-          <subsection name="EventLogging">
+    import java.util.Date;
+    import java.util.UUID;
 
-          </subsection>
+    public class MyApp {
 
+        public String doFundsTransfer(Account toAccount, Account fromAccount, long amount) {
+            toAccount.deposit(amount);
+            fromAccount.withdraw(amount);
+            String confirm = UUID.randomUUID().toString();
+            StructuredDataMessage msg = new StructureDataMessage(confirm, null, "transfer");
+            msg.put("toAccount", toAccount);
+            msg.put("fromAccount", fromAccount);
+            msg.put("amount", amount);
+            EventLogger.logEvent(data);
+            return confirm;
+        }
+    }</source>
+            <p>The EventLogger class uses a Logger named "EventLogger". EventLogger uses a logging level
+              of OFF as the default to indicate that it cannot be filtered. These events can be
+              formatted for printing using the
+              <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/layout/StructuredDataLayout.html">StructuredDataLayout</a>.
+            </p>
+          </subsection>
         </section>
     </body>
 </document>
\ No newline at end of file

Copied: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/flowtracing.xml (from r1236171, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/flowtracing.xml?p2=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/flowtracing.xml&p1=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml&r1=1236171&r2=1240834&rev=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/flowtracing.xml Sun Feb  5 21:50:04 2012
@@ -24,64 +24,219 @@
 
     <body>
         <section name="Log4j 2.0 API">
-          <a name="Overview"/>
-          <subsection name="Overview">
+          <a name="FlowTracing"/>
+          <subsection name="Flow Tracing">
             <p>
-              The Log4Jj 2.0 API provides the interface that applications should code to and provides the
-              adapter components required for implementers to create a logging implementation. Although Log4j 2
-              is broken up between an API and an implementation, the primary purpose of doing so was not to
-              allow multiple implementations, although that is certainly possible, but to clearly define
-              what classes and methods are safe to use in "normal" application code.
-            </p>
-            <h4>Hello World!</h4>
-            <p>
-              No introduction would be complete without the customary Hello, World example. Here is ours. First,
-              a Logger with the name "HelloWorld" is obtained from the LogManager. Next, the logger is used to
-              write the "Hello, World!" message, however the message will be written only if the Logger is
-              configured to allow informational messages.
+              The Logger class provides logging methods that are quite useful for following the
+              execution path of applications. These methods generate logging events that can be filtered
+              separately from other debug logging. Liberal use of these methods is encouraged as the output has
+              been found to
+              <ul>
+                <li>aid in problem diagnosis in development without requiring a debug session</li>
+                <li>aid in problem diagnosis in production where no debugging is possible</li>
+                <li>help educate new deveopers in learning the application.</li>
+              </ul>
             </p>
-            <source>    import org.apache.logging.log4j.LogManager;
-    import org.apache.logging.log4j.Logger;
-
-    public class HelloWorld {
-        private static Logger logger = LogManager.getLogger("HelloWorld");
-        public static void main(String[] args) {
-            logger.info("Hello, World!");
-        }
-    }</source>
             <p>
-              The output from the call to logger.info() will vary significantly depending on the configuration
-              used. See the <a href="./configuration.html">Configuration</a> section for more details.
+              The two most used methods are the entry() and exit() methods. entry() should be placed at the
+              beginning of methods, except perhaps ofr simple getters and setters. entry() can be called
+              passing from 0 to 4 parameters. Typically these will be parameters passed to the method.
+              The entry() method logs with a level of TRACE and uses a Marker with a name of "ENTER" which
+              is also a "FLOW" Marker.
             </p>
-            <h4>Parameter Substitution</h4>
             <p>
-              Frequently the purpose of logging is to provide information about what is happening in the system,
-              which requires including information about the objects being manipulated. In Log4j 1.x this could
-              be accomplished by doing:
+              The exit() method should be placed before any return statement or as the last statement of
+              methods without a return. exit() can be called with or without a parameter. Typically, methods
+              that return void will use exit() while methods that return an Object will use exit(Object obj).
+              The entry() method logs with a level of TRACE and uses a Marker with a name of "EXIT" which is
+              also a "FLOW" Marker.
             </p>
-            <source>    if (logger.isDebugEnabled()) {
-        logger.debug("Logging in user " + user.getName() + " with id " + user.getId());
-    }</source>
             <p>
-              Doing this repeatedly has the effect of making the code feel like it is more about logging than the
-              actual task at hand. In addition, it results in the logging level being checked twice; once on the
-              call to isDebugEnabled and once on the debug method. A better alternative would be:
+              The throwing() method can be used by an application when it is throwing an exception that is
+              unlikely to be handled, such as a RuntimeExcpetion. This will insure that proper diagnostics
+              are available if needed. The logging event generated will have a level of ERROR and will have
+              an associated Marker with a name of "THROWING" which is also an "EXCEPTION" Marker.
             </p>
-            <source>    logger.debug("Logging in user {} with id {}", user.getName(), user.getId());</source>
             <p>
-              With the code above the logging level will only be checked once and the String construction will
-              only occur when debug logging is enabled.
+              The catching() method can be used by an application when it catches an Exception that it is not
+              going to rethrow, either explicitely or attached to another Exception. The logging event generated
+              will have a level of ERROR and will have an associated Marker with a name of "CATCHING" which is
+              also an "EXCEPTION" Marker.
             </p>
-          </subsection>
-          <a name="Markers"/>
-          <subsection name="Markers">
+            <p>
+              The following example shows a simple application using these methods in a fairly typcial manner. The
+              throwing() is not present since no Exceptions are explicitely thrown and not handled.
+            </p>
+            <source>    package com.test;
 
-          </subsection>
-          <a name="EventLogging"/>
-          <subsection name="EventLogging">
+    import org.apache.logging.log4j.Logger;
+    import org.apache.logging.log4j.LogManager;
 
-          </subsection>
+    import java.util.Random;
+
+    public class TestService {
+        private Logger logger = LogManager.getLogger(TestService.class.getName());
+
+        private String[] messages = new String[] {
+            "Hello, World",
+            "Goodbye Cruel World",
+            "You had me at hello"
+        };
+        private Random rand = new Random(1);
+
+        public String retrieveMessage() {
+            logger.entry();
+
+            String testMsg = getMessage(getKey());
+
+            return logger.exit(testMsg);
+        }
 
+        public void exampleException() {
+            logger.entry();
+            try {
+                String msg = messages[messages.length];
+                logger.error("An exception should have been thrown");
+            } catch (Exception ex) {
+                logger.catching(ex);
+            }
+            logger.exit();
+        }
+
+        public String getMessage(int key) {
+            logger.entry(key);
+
+            String value = messages[key];
+
+            return logger.exit(value);
+        }
+
+        private int getKey() {
+            logger.entry();
+            int key = rand.nextInt(messages.length);
+            return logger.exit(key);
+        }
+    }</source>
+            <p>
+              This test application uses the preceding service to generate logging events.
+            </p>
+            <source>    package com.test;
+
+    public class App {
+
+        public static void main( String[] args ) {
+            TestService service = new TestService();
+            service.retrieveMessage();
+            service.retrieveMessage();
+            service.exampleException();
+        }
+    }</source>
+            <p>
+              The configuration below will cause all output to be routed to target/test.log. The pattern for
+              the FileAppender includes the class name, line number and method name. Including these
+              in the pattern are critical for the log to be of value.
+            </p>
+            <source><![CDATA[    <?xml version="1.0" encoding="UTF-8"?>
+    <configuration status="error">
+      <appenders>
+        <Console name="Console" target="SYSTEM_OUT">
+          <ThresholdFilter level="ERROR" onMatch="ACCEPT" onMismatch="DENY"/>
+          <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level %class{36} %L %M - %msg%xEx%n"/>
+        </Console>
+        <File name="log" fileName="target/test.log" append="false">
+          <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level %class{36} %L %M - %msg%xEx%n"/>
+        </File>
+      </appenders>
+      <loggers>
+        <root level="trace">
+          <appender-ref ref="log"/>
+        </root>
+      </loggers>
+    </configuration>]]></source>
+            <p>
+              Here is the output that results from the Java classes and configuration above.
+            </p>
+            <source>
+    19:08:07.056 TRACE com.test.TestService 19 retrieveMessage -  entry
+    19:08:07.060 TRACE com.test.TestService 46 getKey -  entry
+    19:08:07.060 TRACE com.test.TestService 48 getKey -  exit with (0)
+    19:08:07.060 TRACE com.test.TestService 38 getMessage -  entry parms(0)
+    19:08:07.060 TRACE com.test.TestService 42 getMessage -  exit with (Hello, World)
+    19:08:07.060 TRACE com.test.TestService 23 retrieveMessage -  exit with (Hello, World)
+    19:08:07.061 TRACE com.test.TestService 19 retrieveMessage -  entry
+    19:08:07.061 TRACE com.test.TestService 46 getKey -  entry
+    19:08:07.061 TRACE com.test.TestService 48 getKey -  exit with (1)
+    19:08:07.061 TRACE com.test.TestService 38 getMessage -  entry parms(1)
+    19:08:07.061 TRACE com.test.TestService 42 getMessage -  exit with (Goodbye Cruel World)
+    19:08:07.061 TRACE com.test.TestService 23 retrieveMessage -  exit with (Goodbye Cruel World)
+    19:08:07.062 TRACE com.test.TestService 27 exampleException -  entry
+    19:08:07.077 DEBUG com.test.TestService 32 exampleException - catching java.lang.ArrayIndexOutOfBoundsException: 3
+            at com.test.TestService.exampleException(TestService.java:29) [classes/:?]
+            at com.test.App.main(App.java:9) [classes/:?]
+            at com.test.AppTest.testApp(AppTest.java:15) [test-classes/:?]
+            at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29]
+            at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29]
+            at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29]
+            at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29]
+            at org.junit.internal.runners.TestMethodRunner.executeMethodBody(TestMethodRunner.java:99) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestMethodRunner.runUnprotected(TestMethodRunner.java:81) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestMethodRunner.runMethod(TestMethodRunner.java:75) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestMethodRunner.run(TestMethodRunner.java:45) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestClassMethodsRunner.invokeTestMethod(TestClassMethodsRunner.java:66) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestClassMethodsRunner.run(TestClassMethodsRunner.java:35) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestClassRunner$1.runUnprotected(TestClassRunner.java:42) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestClassRunner.run(TestClassRunner.java:52) [junit-4.3.1.jar:?]
+            at org.apache.maven.surefire.junit4.JUnit4TestSet.execute(JUnit4TestSet.java:35) [surefire-junit4-2.7.2.jar:2.7.2]
+            at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:115) [surefire-junit4-2.7.2.jar:2.7.2]
+            at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:97) [surefire-junit4-2.7.2.jar:2.7.2]
+            at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29]
+            at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29]
+            at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29]
+            at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29]
+            at org.apache.maven.surefire.booter.ProviderFactory$ClassLoaderProxy.invoke(ProviderFactory.java:103) [surefire-booter-2.7.2.jar:2.7.2]
+            at $Proxy0.invoke(Unknown Source) [?:?]
+            at org.apache.maven.surefire.booter.SurefireStarter.invokeProvider(SurefireStarter.java:150) [surefire-booter-2.7.2.jar:2.7.2]
+            at org.apache.maven.surefire.booter.SurefireStarter.runSuitesInProcess(SurefireStarter.java:91) [surefire-booter-2.7.2.jar:2.7.2]
+            at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:69) [surefire-booter-2.7.2.jar:2.7.2]
+    19:08:07.087 TRACE com.test.TestService 34 exampleException -  exit</source>
+            <p>
+              Simply changing the root logger level to DEBUG in the example above will reduce the output
+              considerably.
+            </p>
+            <source>
+    19:13:24.963 DEBUG com.test.TestService 32 exampleException - catching java.lang.ArrayIndexOutOfBoundsException: 3
+            at com.test.TestService.exampleException(TestService.java:29) [classes/:?]
+            at com.test.App.main(App.java:9) [classes/:?]
+            at com.test.AppTest.testApp(AppTest.java:15) [test-classes/:?]
+            at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29]
+            at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29]
+            at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29]
+            at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29]
+            at org.junit.internal.runners.TestMethodRunner.executeMethodBody(TestMethodRunner.java:99) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestMethodRunner.runUnprotected(TestMethodRunner.java:81) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestMethodRunner.runMethod(TestMethodRunner.java:75) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestMethodRunner.run(TestMethodRunner.java:45) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestClassMethodsRunner.invokeTestMethod(TestClassMethodsRunner.java:66) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestClassMethodsRunner.run(TestClassMethodsRunner.java:35) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestClassRunner$1.runUnprotected(TestClassRunner.java:42) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?]
+            at org.junit.internal.runners.TestClassRunner.run(TestClassRunner.java:52) [junit-4.3.1.jar:?]
+            at org.apache.maven.surefire.junit4.JUnit4TestSet.execute(JUnit4TestSet.java:35) [surefire-junit4-2.7.2.jar:2.7.2]
+            at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:115) [surefire-junit4-2.7.2.jar:2.7.2]
+            at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:97) [surefire-junit4-2.7.2.jar:2.7.2]
+            at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29]
+            at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29]
+            at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29]
+            at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29]
+            at org.apache.maven.surefire.booter.ProviderFactory$ClassLoaderProxy.invoke(ProviderFactory.java:103) [surefire-booter-2.7.2.jar:2.7.2]
+            at $Proxy0.invoke(Unknown Source) [?:?]
+            at org.apache.maven.surefire.booter.SurefireStarter.invokeProvider(SurefireStarter.java:150) [surefire-booter-2.7.2.jar:2.7.2]
+            at org.apache.maven.surefire.booter.SurefireStarter.runSuitesInProcess(SurefireStarter.java:91) [surefire-booter-2.7.2.jar:2.7.2]
+            at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:69) [surefire-booter-2.7.2.jar:2.7.2]</source>
+          </subsection>
         </section>
     </body>
 </document>
\ No newline at end of file

Copied: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/markers.xml (from r1236171, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/markers.xml?p2=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/markers.xml&p1=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml&r1=1236171&r2=1240834&rev=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/markers.xml Sun Feb  5 21:50:04 2012
@@ -24,64 +24,74 @@
 
     <body>
         <section name="Log4j 2.0 API">
-          <a name="Overview"/>
-          <subsection name="Overview">
-            <p>
-              The Log4Jj 2.0 API provides the interface that applications should code to and provides the
-              adapter components required for implementers to create a logging implementation. Although Log4j 2
-              is broken up between an API and an implementation, the primary purpose of doing so was not to
-              allow multiple implementations, although that is certainly possible, but to clearly define
-              what classes and methods are safe to use in "normal" application code.
-            </p>
-            <h4>Hello World!</h4>
+          <a name="Markers"/>
+          <subsection name="Markers">
             <p>
-              No introduction would be complete without the customary Hello, World example. Here is ours. First,
-              a Logger with the name "HelloWorld" is obtained from the LogManager. Next, the logger is used to
-              write the "Hello, World!" message, however the message will be written only if the Logger is
-              configured to allow informational messages.
-            </p>
-            <source>    import org.apache.logging.log4j.LogManager;
-    import org.apache.logging.log4j.Logger;
+              One of the primary purpose of a logging framework is to provide the means to generate debugging and
+              diagnostic information only when it is needed, and to allow filtering of that information so that it
+              does not overwhelm the system or the individuals who need to make use of it. As an example, an
+              application desires to log its entry, exit and other operations separately from SQL statements
+              being executed, and wishes to be able to log queries separate from updates. One way to accomplish
+              this is shown below:
+            </p>
+            <source><![CDATA[    import org.apache.logging.log4j.Logger;
+    import org.apache.logging.log4j.LogManager;
+    import java.util.Map;
+
+    public class MyApp {
+
+        private Logger logger = LogManager.getLogger(MyApp.class.getName());
+        private static final Marker SQL_MARKER = MarkerManager.getMarker("SQL");
+        private static final Marker UPDATE_MARKER = MarkerManager.getMarker("SQL_UPDATE", SQL_MARKER);
+        private static final Marker QUERY_MARKER = MarkerManager.getMarker("SQL_QUERY", SQL_MARKER);
 
-    public class HelloWorld {
-        private static Logger logger = LogManager.getLogger("HelloWorld");
-        public static void main(String[] args) {
-            logger.info("Hello, World!");
+        public String doQuery(String table) {
+            logger.entry(param);
+
+            logger.debug(QUERY_MARKER, "SELECT * FROM {}", table);
+
+            return logger.exit();
         }
-    }</source>
-            <p>
-              The output from the call to logger.info() will vary significantly depending on the configuration
-              used. See the <a href="./configuration.html">Configuration</a> section for more details.
-            </p>
-            <h4>Parameter Substitution</h4>
-            <p>
-              Frequently the purpose of logging is to provide information about what is happening in the system,
-              which requires including information about the objects being manipulated. In Log4j 1.x this could
-              be accomplished by doing:
-            </p>
-            <source>    if (logger.isDebugEnabled()) {
-        logger.debug("Logging in user " + user.getName() + " with id " + user.getId());
-    }</source>
+
+        public String doUpdate(String table, Map<String, String> params) {
+            logger.entry(param);
+
+            if (logger.isDebugEnabled()) {
+              logger.debug(UPDATE_MARKER, "UPDATE {} SET {}", table, formatCols);
+
+            return logger.exit();
+        }
+
+        private String formatCols(Map<String, String> cols) {
+            StringBuilder sb = new StringBuilder();
+            boolean first = true;
+            for (Map.Entry<String, String> entry : cols.entrySet()) {
+                if (!first) {
+                    sb.append(", ");
+                }
+                sb.append(entry.getKey()).append("=").append(entry.getValue());
+                first = false;
+            }
+            return sb.toString();
+        }
+    }]]></source>
             <p>
-              Doing this repeatedly has the effect of making the code feel like it is more about logging than the
-              actual task at hand. In addition, it results in the logging level being checked twice; once on the
-              call to isDebugEnabled and once on the debug method. A better alternative would be:
+              In the example above it is now possible to add MarkerFilters to only allow SQL update operations
+              to be logged, all SQL updates to be logged or to log everything in MyApp.
             </p>
-            <source>    logger.debug("Logging in user {} with id {}", user.getName(), user.getId());</source>
             <p>
-              With the code above the logging level will only be checked once and the String construction will
-              only occur when debug logging is enabled.
+              Some important rules about Markers must be considered when using them.
+              <ol>
+                <li>Markers must be unique. They are permanently registered by name so care should be taken
+                  to insure that Markers used in your application are distinct from those in the application's
+                  dependencies, unless that is what is desired.</li>
+                <li>Like many objects in Log4J2, Markers are immutable. If a marker has a parent, the parent
+                  must be named when the Marker is created and the parent cannot be changed after creation.</li>
+                <li>Markers only have a single parent. Markers can, however, have many children that reference
+                  them.</li>
+              </ol>
             </p>
           </subsection>
-          <a name="Markers"/>
-          <subsection name="Markers">
-
-          </subsection>
-          <a name="EventLogging"/>
-          <subsection name="EventLogging">
-
-          </subsection>
-
         </section>
     </body>
 </document>
\ No newline at end of file

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/messages.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/messages.xml?rev=1240834&r1=1240833&r2=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/messages.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/messages.xml Sun Feb  5 21:50:04 2012
@@ -23,9 +23,9 @@
   </properties>
 
   <body>
-    <section name="Log4j 2.0 API Messages">
-      <a name="Introduction"/>
-      <subsection name="Introduction">
+    <section name="Log4j 2.0 API">
+      <a name="Messages"/>
+      <subsection name="Messages">
         <p>
           Although Log4j 2 provides Logger methods that accept Strings and Objects, all of these are ulitmately
           captured in Message objects that are then associated with the log event. Applications are free to
@@ -66,10 +66,110 @@
           are encountered. With Messages the Layout has the option of delegating the formatting to the Message or
           performing its formatting based on the type of Message encountered.
         </p>
+        <p>
+          Borrowing from the earlier example illustrating Markers to identify SQL statements being logged, Messages
+          can also be leveraged. First, the Message is defined.
+        </p>
+        <source><![CDATA[
 
-      </subsection>
+  public class SQLMessage implements Message {
+      public enum SQLType {
+          UPDATE,
+          QUERY
+      };
+
+      prviate final SQLType type;
+      private final String table;
+      private final Map<String, String> cols;
+
+      public SQLMessage(SQLType type, String table) {
+          this(type, table, null);
+      }
+
+      public SQLMessage(SQLType type, String table, Map<String, String> cols) {
+          this.type = type;
+          this.table = table;
+          this.cols = cols;
+      }
+
+      public String getFormattedMessage() {
+          switch (type) {
+              case UPDATE:
+                return createUpdateString();
+                break;
+              case QUERY:
+                return createQueryString();
+                break;
+              default;
+          }
+      }
+
+      public String getMessageFormat() {
+          return type + " " + table;
+      }
+
+      public Object getParameters() {
+          return cols;
+      }
+
+      private String createUpdateString() {
+      }
+
+      private String createQueryString() {
+      }
+
+      private String formatCols(Map<String, String> cols) {
+          StringBuilder sb = new StringBuilder();
+          boolean first = true;
+          for (Map.Entry<String, String> entry : cols.entrySet()) {
+              if (!first) {
+                  sb.append(", ");
+              }
+              sb.append(entry.getKey()).append("=").append(entry.getValue());
+              first = false;
+          }
+          return sb.toString();
+      }
+  }]]></source>
+      <p>
+        Next we can use the message in our application.
+      </p>
+        <source><![CDATA[    import org.apache.logging.log4j.Logger;
+    import org.apache.logging.log4j.LogManager;
+    import java.util.Map;
+
+    public class MyApp {
+
+        private Logger logger = LogManager.getLogger(MyApp.class.getName());
+        private static final Marker SQL_MARKER = MarkerManager.getMarker("SQL");
+        private static final Marker UPDATE_MARKER = MarkerManager.getMarker("SQL_UPDATE", SQL_MARKER);
+        private static final Marker QUERY_MARKER = MarkerManager.getMarker("SQL_QUERY", SQL_MARKER);
+
+        public String doQuery(String table) {
+            logger.entry(param);
+
+            logger.debug(QUERY_MARKER, new SQLMessage(SQLMessage.SQLType.QUERY, table);
+
+            return logger.exit();
+        }
+
+        public String doUpdate(String table, Map<String, String> params) {
+            logger.entry(param);
+
+            logger.debug(UPDATE_MARKER, new SQLMessage(SQLMessage.SQLType.UPDATE, table, parmas);
+
+            return logger.exit();
+        }
+    }]]></source>
+        <p>
+          Notice that in contrast to the prior version of this example, the logger.debug in doUpdate no longer
+          needs to be wrapped in an isDebugEnabled call as creation of the SQLMessage is on the same order of
+          magnitude of performing that check. Furthermore, all the formatting of the SQL columns is now hidden
+          in the SQLMessage instead of having to take place in the business logic. Finally, if desired, Filters
+          and/or Layouts can be written to take special action when an SQLMessage is encountered.
+        </p>
       <a name="FormattedMessage"/>
-      <subsection name="FormattedMessage">
+      <h4>FormattedMessage</h4>
         <p>
           A FormattedMessage will have setFormat and getFormat methods. The setFormat method may be called by a
           Layout to provide advice on how the Message should be formatted. If the Message doesn't recognize the
@@ -77,9 +177,8 @@
           StructuredDataMessage which accepts a format String of "XML" which will cause it to format the event data
           as XML instead of the RFC 5424 format.
         </p>
-      </subsection>
       <a name="LocalizedMessage"/>
-      <subsection name="LocalizedMessage">
+      <h4>LocalizedMessage</h4>
         <p>
           <a href="../log4j2-api/apidocs/org/apache/logging/log4j/message/LocalizedMessage.html">LocalizedMessage</a>
           is provided primarily to provide compatibility with Log4j 1.x. Generally,
@@ -91,60 +190,52 @@
           LocalizedMessage will attempt to locate a bundle with the name of the Logger used to log the event. The
           parameters to the Message will be incorporated into the Message whereever the "{}" placeholders occur.
         </p>
-      </subsection>
       <a name="LoggerNameAwareMessage"/>
-      <subsection name="LoggerNameAwareMessage">
+      <h4>LoggerNameAwareMessage</h4>
         <p>
           LoggerNameAwareMessage is an interface with a setLoggerName method. This method will be called during
           event construction so that the Message has the name of the Logger used to log the event when the
           message is being formatted.
         </p>
-      </subsection>
       <a name="MapMessage"/>
-      <subsection name="MapMessage">
+      <h4>MapMessage</h4>
         <p>
           A MapMessage contains a Map of String keys and values. MapMessage implements FormattedMessage and accepts
           a format specifier of "XML", in which case the Map will be formatted as XML. Otherwise, the Map will be
           formatted as "key1=value1 key2=value2...".
         </p>
-      </subsection>
       <a name="ObjectMessage"/>
-      <subsection name="ObjectMessage">
+      <h4>ObjectMessage</h4>
         <p>
           Formats an Object by calling its toString method.
         </p>
-      </subsection>
       <a name="ParameterizedMessage"/>
-      <subsection name="ParameterizedMessage">
+      <h4>ParameterizedMessage</h4>
         <p>
           <a href="../log4j2-api/apidocs/org/apache/logging/log4j/message/ParameterizedMessage.html">ParameterizedMessage</a>
           handles messages that contain "{}" in the format to represent replaceable tokens and the replacement
           parameters.
         </p>
-      </subsection>
       <a name="SimpleMessage"/>
-      <subsection name="SimpleMessage">
+      <h4>SimpleMessage</h4>
         <p>
           SimpleMessage contains a String that requires no formatting.
         </p>
-      </subsection>
       <a name="StructuredDataMessage"/>
-      <subsection name="StructuredDataMessage">
+      <h4>StructuredDataMessage</h4>
         <p>
           <a href="../log4j2-api/apidocs/org/apache/logging/log4j/message/StructuredDataMessage.html">StructuredDataMessage</a>
           allows applications to add items to a Map as well as set the id to allow a message to be formatted as a
           Structured Data element in accordance with <a href="http://tools.ietf.org/html/rfc5424">RFC 5424</a>.
         </p>
-      </subsection>
       <a name="ThreadDumpMessage"/>
-      <subsection name="ThreadDumpMessage">
+      <h4>ThreadDumpMessage</h4>
         <p>
           A ThreadDumpMessage, if logged, will generate stack traces for all threads. If running on Java 6+ the
           stack traces will include any locks that are held.
         </p>
-      </subsection>
       <a name="TimestampMessage"/>
-      <subsection name="TimestampMessage">
+      <h4>TimestampMessage</h4>
         <p>
           A TimestampMessage will provide a getTimestamp method that is called during event construction. The
           timestamp in the Message will be used in lieu of the current timestamp.

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml?rev=1240834&r1=1240833&r2=1240834&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/thread-context.xml Sun Feb  5 21:50:04 2012
@@ -23,8 +23,9 @@
     </properties>
 
     <body>
-      <section name="Thread Context">
-        <subsection name="Introduction">
+      <section name="Log4j 2.0 API">
+        <subsection name="Thread Context">
+          <h4>Introduction</h4>
           <p>Log4j introduced the concept of the Mapped Diagnostic Context or MDC. It has been documented and
             discussed in numerous places including
             <a href="http://veerasundar.com/blog/2009/10/log4j-mdc-mapped-diagnostic-context-what-and-why/">Log4j MDC: What and Why</a> and
@@ -40,8 +41,7 @@
             NDC. Although these are frequently used for purposes other than diagnosing problems, they are still
             frequently referred to as the MDC and NDC in Log4j 2 since they are already well known by those acronyms.
           </p>
-        </subsection>
-        <subsection name="Fish Tagging">
+          <h4>Fish Tagging</h4>
           <p>Most real-world systems have to deal with multiple clients simultaneously. In a typical multithreaded
             implementation of such asystem, different threads will handle different clients. Logging is
             especially well suited to trace and debug complex distributed applications. A common approach to
@@ -109,8 +109,7 @@
             <a href="../log4j2-api/apidocs/org/apache/logging/log4j/ThreadContext.html">ThreadContext</a>
             class are static.
           </p>
-        </subsection>
-        <subsection name="Including the ThreadContext when writing logs">
+          <h4>Including the ThreadContext when writing logs</h4>
           <p>
             The PatternLayout provides mechanisms to print the contents of the ThreadContext Map and Stack. Using
             %X by itself will cause the full contents of the Map to be included while %X{key} will cause the value



Mime
View raw message