Repository: logging-log4j2
Updated Branches:
  refs/heads/master 59f34d768 -> 71b1f20f6


LOG4J2-1802: Convert event logging manual page to asciidoc


Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/7c855d1e
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/7c855d1e
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/7c855d1e

Branch: refs/heads/master
Commit: 7c855d1e336b35f2a7735e2e2b2edf6fa903036a
Parents: 59f34d7
Author: Matt Sicker <boa...@gmail.com>
Authored: Sun Apr 8 13:44:29 2018 -0500
Committer: Matt Sicker <boa...@gmail.com>
Committed: Sun Apr 8 13:44:29 2018 -0500

----------------------------------------------------------------------
 src/site/asciidoc/manual/eventlogging.adoc | 142 +++++++++++++++++++++++
 src/site/xdoc/manual/eventlogging.xml      | 145 ------------------------
 2 files changed, 142 insertions(+), 145 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7c855d1e/src/site/asciidoc/manual/eventlogging.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/eventlogging.adoc 
b/src/site/asciidoc/manual/eventlogging.adoc
new file mode 100644
index 0000000..c91f1f7
--- /dev/null
+++ b/src/site/asciidoc/manual/eventlogging.adoc
@@ -0,0 +1,142 @@
+////
+    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
+
+        https://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.
+////
+= Log4j 2 API
+Ralph Goers <rgo...@apache.org>
+
+[#EventLogging]
+== Event Logging
+
+The `EventLogger` class provides a simple mechanism 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.
+
+The recommended way of using the `EventLogger` in a typical 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 filter 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`.
+
+[source,java]
+----
+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 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() {
+    }
+}
+----
+
+Sample class that uses `EventLogger`.
+
+[source,java]
+----
+import org.apache.logging.log4j.StructuredDataMessage;
+import org.apache.logging.log4j.EventLogger;
+
+import java.util.Date;
+import java.util.UUID;
+
+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 StructuredDataMessage(confirm, null, 
"transfer");
+        msg.put("toAccount", toAccount);
+        msg.put("fromAccount", fromAccount);
+        msg.put("amount", amount);
+        EventLogger.logEvent(msg);
+        return confirm;
+    }
+}
+----
+
+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
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/StructuredDataLayout.html[`StructuredDataLayout`].

http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7c855d1e/src/site/xdoc/manual/eventlogging.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/eventlogging.xml 
b/src/site/xdoc/manual/eventlogging.xml
deleted file mode 100644
index 8573499..0000000
--- a/src/site/xdoc/manual/eventlogging.xml
+++ /dev/null
@@ -1,145 +0,0 @@
-<?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 xmlns="http://maven.apache.org/XDOC/2.0";
-          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
-          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 
http://maven.apache.org/xsd/xdoc-2.0.xsd";>
-    <properties>
-        <title>Log4j 2 API</title>
-        <author email="rgo...@apache.org">Ralph Goers</author>
-    </properties>
-
-    <body>
-        <section name="Log4j 2 API">
-          <a name="EventLogging"/>
-          <subsection name="Event Logging">
-            <p>
-              The EventLogger class provides a simple mechanism 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 typical 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 filter 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>
-
-            <pre class="prettyprint linenums">
-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 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() {
-    }
-}</pre>
-            <p>Sample class that uses EventLogger.</p>
-            <pre class="prettyprint linenums">
-import org.apache.logging.log4j.StructuredDataMessage;
-import org.apache.logging.log4j.EventLogger;
-
-import java.util.Date;
-import java.util.UUID;
-
-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 StructuredDataMessage(confirm, null, 
"transfer");
-        msg.put("toAccount", toAccount);
-        msg.put("fromAccount", fromAccount);
-        msg.put("amount", amount);
-        EventLogger.logEvent(msg);
-        return confirm;
-    }
-}</pre>
-            <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 class="javadoc" 
href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/StructuredDataLayout.html">StructuredDataLayout</a>.
-            </p>
-          </subsection>
-        </section>
-    </body>
-</document>

Reply via email to