logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgo...@apache.org
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 GMT
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



Mime
View raw message