Mailing-List: contact commits-help@logging.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@logging.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: svn commit: r1235721 - in
 /logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers: log4j2-api/
 log4j2-api/src/main/java/org/apache/logging/log4j/message/
 log4j2-api/src/site/xdoc/
 log4j2-api/src/test/java/org/apache/logging/log4j/message/ log4j2-core/sr...
Date: Wed, 25 Jan 2012 12:13:24 -0000
To: commits@logging.apache.org
From: rgoers@apache.org
Message-Id: <20120125121325.23FBC238899C@eris.apache.org>

Author: rgoers
Date: Wed Jan 25 12:13:24 2012
New Revision: 1235721

URL: http://svn.apache.org/viewvc?rev=1235721&view=rev
Log:
Start on API documentation

Added:
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/appender/db/
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml
      - copied, changed from r1226512, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/site/xdoc/api.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/messages.xml
Removed:
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/message/DeferredMessage.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/site/xdoc/api.xml
Modified:
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/pom.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/test/java/org/apache/logging/log4j/message/MapMessageTest.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/jmx.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/layouts.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/logsep.xml

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/pom.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/pom.xml?rev=1235721&r1=1235720&r2=1235721&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/pom.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/pom.xml Wed Jan 25 12:13:24 2012
@@ -33,6 +33,12 @@
   </properties>
   <dependencies>
     <dependency>
+      <groupId>commons-httpclient</groupId>
+      <artifactId>commons-httpclient</artifactId>
+      <version>3.1</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
       <version>4.3.1</version>

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java?rev=1235721&r1=1235720&r2=1235721&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/message/MapMessage.java Wed Jan 25 12:13:24 2012
@@ -16,6 +16,10 @@
  */
 package org.apache.logging.log4j.message;
 
+import javax.xml.stream.XMLOutputFactory;
+import javax.xml.stream.XMLStreamException;
+import javax.xml.stream.XMLStreamWriter;
+import java.io.ByteArrayOutputStream;
 import java.io.Serializable;
 import java.util.Collections;
 import java.util.HashMap;
@@ -149,7 +153,7 @@ public class MapMessage implements Forma
      * @return The formatted String.
      */
     public String asString() {
-        return asString("");
+        return asString(format == null ? "" : format);
     }
 
     /**
@@ -169,7 +173,12 @@ public class MapMessage implements Forma
     }
 
     public void asXML(StringBuilder sb) {
-
+        sb.append("<Map>\n");
+        SortedMap<String, String> sorted = new TreeMap<String, String>(data);
+        for (Map.Entry<String, String> entry : sorted.entrySet()) {
+            sb.append("  <Entry key=").append(entry.getKey()).append(">").append(entry.getValue()).append("</Entry>\n");
+        }
+        sb.append("</Map>");
     }
 
     /**

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/test/java/org/apache/logging/log4j/message/MapMessageTest.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/test/java/org/apache/logging/log4j/message/MapMessageTest.java?rev=1235721&r1=1235720&r2=1235721&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/test/java/org/apache/logging/log4j/message/MapMessageTest.java (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/test/java/org/apache/logging/log4j/message/MapMessageTest.java Wed Jan 25 12:13:24 2012
@@ -35,4 +35,18 @@ public class MapMessageTest {
         String expected = "message=\"Test message {}\" project=\"Log4j\"";
         assertEquals(expected, result);
     }
+
+    @Test
+    public void testXML() {
+        String testMsg = "Test message {}";
+        MapMessage msg = new MapMessage();
+        msg.setFormat("XML");
+        msg.put("message", testMsg);
+        msg.put("project", "Log4j");
+        String result = msg.getFormattedMessage();
+        String expected = "<Map>\n  <Entry key=message>Test message {}</Entry>\n" +
+            "  <Entry key=project>Log4j</Entry>\n" +
+            "</Map>";
+        assertEquals(expected, result);
+    }
 }

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=1235721&r1=1235720&r2=1235721&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 Wed Jan 25 12:13:24 2012
@@ -39,7 +39,6 @@
   <body>
     <menu name="Apache Log4jâ¢ 2" inherit="top">
       <item name="About" href="/index.html"/>
-      <item name="Log4j2 API" href="log4j2-api/api.html"/>
       <item name="Download" href="/download.html"/>
       <item name="Build and Install" href="/build.html"/>
       <item name="Changelog" href="/changelog.html"/>
@@ -47,6 +46,13 @@
     <menu name="Manual" inherit="top">
       <item name="Introduction" href="/manual/index.html"/>
       <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="Messages" href="/manual/messages.html"/>
+        <item name="ThreadContext" href="/manual/thread-context.html"/>
+      </item>
       <item name="Configuration" href="/manual/configuration.html" collapse="true">
         <item name="Automatic Configuration" href="/manual/configuration.html#AutomaticConfiguration"/>
         <item name="Additivity" href="/manual/configuration.html#Additivity"/>
@@ -103,7 +109,6 @@
         <item name="Threshold" href="/manual/filters.html#ThresholdFilter"/>
         <item name="Time" href="/manual/filters.html#TimeFilter"/>
       </item>
-      <item name="ThreadContext" href="/manual/thread-context.html"/>
       <item name="JMX" href="/manual/jmx.html"/>
       <item name="Logging Separation" href="/manual/logsep.html"/>
       <item name="Extending Log4j" href="/manual/extending.html" collapse="true">

Copied: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml (from r1226512, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/site/xdoc/api.xml)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml?p2=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml&p1=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/site/xdoc/api.xml&r1=1226512&r2=1235721&rev=1235721&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/site/xdoc/api.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml Wed Jan 25 12:13:24 2012
@@ -24,19 +24,22 @@
 
     <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.
             </p>
+          </subsection>
+          <a name="Markers"/>
+          <subsection name="Markers">
 
-        </section>
+          </subsection>
+          <a name="EventLogging"/>
+          <subsection name="EventLogging">
 
-        <section name="Requirements">
-           <p>
-             The Log4j 2.0 API requires at least Java 5.
-          </p>
-        </section>
+          </subsection>
 
+        </section>
     </body>
 </document>
\ No newline at end of file

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/jmx.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/jmx.xml?rev=1235721&r1=1235720&r2=1235721&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/jmx.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/jmx.xml Wed Jan 25 12:13:24 2012
@@ -18,13 +18,15 @@
 
 <document>
     <properties>
-        <title>Overview</title>
+        <title>JMX</title>
         <author email="rgoers@apache.org">Ralph Goers</author>
     </properties>
 
     <body>
       <section name="JMX">
-
+        <p>
+          JMX support is incomplete at this time. Patches are welcome!
+        </p>
       </section>
     </body>
 </document>
\ No newline at end of file

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/layouts.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/layouts.xml?rev=1235721&r1=1235720&r2=1235721&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/layouts.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/layouts.xml Wed Jan 25 12:13:24 2012
@@ -586,7 +586,7 @@
         <subsection name="RFC5424Layout">
           <p>
             As the name implies, the RFC5424Layout formats LogEvents in accordance with
-            <a href="">RFC 5424</a>, the enhanced Syslog specification. Although the specification
+            <a href="http://tools.ietf.org/html/rfc5424">RFC 5424</a>, the enhanced Syslog specification. Although the specification
             is primarily directed at sending messages via Syslog, this format is quite useful for
             other purposes since items are passed in the message as self-describing key/value pairs.
           </p>

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/logsep.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/logsep.xml?rev=1235721&r1=1235720&r2=1235721&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/logsep.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/logsep.xml Wed Jan 25 12:13:24 2012
@@ -18,7 +18,7 @@
 
 <document>
     <properties>
-        <title>Overview</title>
+        <title>Logging Separation</title>
         <author email="rgoers@apache.org">Ralph Goers</author>
     </properties>
 

Added: 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=1235721&view=auto
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/messages.xml (added)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/messages.xml Wed Jan 25 12:13:24 2012
@@ -0,0 +1,155 @@
+<?xml version="1.0"?>
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+<document>
+  <properties>
+    <title>Log4J 2.0 API Messages</title>
+    <author email="rgoers@apache.org">Ralph Goers</author>
+  </properties>
+
+  <body>
+    <section name="Log4j 2.0 API Messages">
+      <a name="Introduction"/>
+      <subsection name="Introduction">
+        <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
+          construct Messages of their own and pass them to the Logger. Although it may seem more expensive than
+          passing the message format and parameters directly to the event, testing has shown that with modern
+          JVMs the cost of creating and destroying events is minor, especially when complex tasks are encapsulated
+          in the Message instead of the application. In addition, when using the methods that accept Strings and
+          parameters, the underlying Message object will only be created if any configured global filters
+          or the Logger's log level allow the message to be processed.
+        </p>
+        <p>
+          Consider an application that has a Map object containing {"Name" = "John Doe", "Address" = "123 Main
+          St.",
+          "Phone" = "(999) 555-1212"} and a User object that has a getId method that returns "jdoe". The developer
+          would like to add an informational message that returns "User John Doe has logged in using id jdoe". The
+          way this could be accomplished is by doing:
+        </p>
+        <pre>
+          logger.info("User {} has logged in using id {}, map.get("Name"), user.getId());
+        </pre>
+        <p>
+          While there is nothing inherently wrong with this, as the complexity of the objects and desired output
+          increases this technique becomes harder to use. As an alternative, using Messages allows:
+        </p>
+        <pre>
+          logger.info(new LoggedInMessage(map, user));
+        </pre>
+        <p>
+          In this alternative the formatting is delegated to the LoggedInMessage object's getFormattedMessage
+          method.
+          Although in this alternative a new object is created, none of the methods on the objects passed to the
+          LoggedInMessage are invoked until the LoggedInMessage is formatted. This is especially useful when an
+          Object's toString method does not produce the information you would like to appear in the log.
+        </p>
+        <p>
+          Another advantage to Messages is that they simplify writing Layouts. In other logging frameworks the
+          Layout must loop through the parameters individually and determine what to do based on what objects
+          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>
+
+      </subsection>
+      <a name="FormattedMessage"/>
+      <subsection name="FormattedMessage">
+        <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
+          format name it will simply format the data using its default format. An example of this is the
+          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">
+        <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,
+          the best approach to localization is to have the client UI render the events in the client's locale.
+        </p>
+        <p>
+          LocalizedMessage extends a ParameterizedMessage by incorporating a ResourceBundle and allowing
+          the message pattern parameter to be the key to the message pattern in the bundle. If no bundle is specified,
+          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">
+        <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">
+        <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">
+        <p>
+          Formats an Object by calling its toString method.
+        </p>
+      </subsection>
+      <a name="ParameterizedMessage"/>
+      <subsection name="ParameterizedMessage">
+        <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">
+        <p>
+          SimpleMessage contains a String that requires no formatting.
+        </p>
+      </subsection>
+      <a name="StructuredDataMessage"/>
+      <subsection name="StructuredDataMessage">
+        <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">
+        <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">
+        <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.
+        </p>
+      </subsection>
+    </section>
+  </body>
+</document>
\ No newline at end of file