You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ma...@apache.org on 2018/04/08 21:03:42 UTC
[1/7] logging-log4j2 git commit: LOG4J2-1802: Convert webapps manual
page to asciidoc
Repository: logging-log4j2
Updated Branches:
refs/heads/master d7f2fd7d4 -> db18f5ada
LOG4J2-1802: Convert webapps 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/db18f5ad
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/db18f5ad
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/db18f5ad
Branch: refs/heads/master
Commit: db18f5ada1c2141a1d9531b0186855dcbd66991e
Parents: fa0135e
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 16:03:25 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 16:03:36 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/webapp.adoc | 486 ++++++++++++++++++++++++++++++
src/site/xdoc/manual/webapp.xml | 451 ---------------------------
2 files changed, 486 insertions(+), 451 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/db18f5ad/src/site/asciidoc/manual/webapp.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/webapp.adoc b/src/site/asciidoc/manual/webapp.adoc
new file mode 100644
index 0000000..8a864d5
--- /dev/null
+++ b/src/site/asciidoc/manual/webapp.adoc
@@ -0,0 +1,486 @@
+////
+ 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.
+////
+= Web Applications
+Nick Williams <ni...@apache.org>; Matt Sicker <ma...@apache.org>
+
+== Using Log4j 2 in Web Applications
+
+You must take particular care when using Log4j or any other logging
+framework within a Java EE web application. It's important for logging
+resources to be properly cleaned up (database connections closed, files
+closed, etc.) when the container shuts down or the web application is
+undeployed. Because of the nature of class loaders within web
+applications, Log4j resources cannot be cleaned up through normal means.
+Log4j must be "started" when the web application deploys and "shut down"
+when the web application undeploys. How this works varies depending on
+whether your application is a link:#Servlet-3.0[Servlet 3.0 or newer] or
+link:#Servlet-2.5[Servlet 2.5] web application.
+
+In either case, you'll need to add the `log4j-web` module to your
+deployment as detailed in the link:../maven-artifacts.html[Maven, Ivy,
+and Gradle Artifacts] manual page.
+
+NOTE: To avoid problems the Log4j shutdown hook will automatically be
+disabled when the log4j-web jar is included.
+
+[#Configuration]
+== Configuration
+
+Log4j allows the configuration file to be specified in web.xml using the
+`log4jConfiguration` context parameter. Log4j will search for
+configuration files by:
+
+1. If a location is provided it will be searched for as a servlet
+context resource. For example, if `log4jConfiguration` contains
+"logging.xml" then Log4j will look for a file with that name in the root
+directory of the web application.
+2. If no location is defined Log4j will search for a file that starts
+with "log4j2" in the WEB-INF directory. If more than one file is found,
+and if a file that starts with "log4j2-name" is present, where name is
+the name of the web application, then it will be used. Otherwise the
+first file will be used.
+3. The "normal" search sequence using the classpath and file URLs will
+be used to locate the configuration file.
+
+[#Servlet-3.0]
+== Servlet 3.0 and Newer Web Applications
+
+A Servlet 3.0 or newer web application is any `<web-app>` whose
+`version` attribute has a value of "3.0" or higher. Of course, the
+application must also be running in a compatible web container. Some
+examples are: Tomcat 7.0 and higher, GlassFish 3.0 and higher, JBoss 7.0
+and higher, Oracle WebLogic 12c and higher, and IBM WebSphere 8.0 and
+higher.
+
+=== The Short Story
+
+Log4j 2 "just works" in Servlet 3.0 and newer web applications. It is
+capable of automatically starting when the application deploys and
+shutting down when the application undeploys. Thanks to the
+https://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html[`ServletContainerInitializer`]
+API added to Servlet 3.0, the relevant `Filter` and
+`ServletContextListener` classes can be registered dynamically on web
+application startup.
+
+NOTE: For performance reasons, containers often ignore
+certain JARs known not to contain TLDs or `ServletContainerInitializer`
+and do not scan them for web-fragments and initializers. Importantly,
+Tomcat 7 <7.0.43 ignores all JAR files named log4j*.jar, which prevents
+this feature from working. This has been fixed in Tomcat 7.0.43, Tomcat
+8, and later. In Tomcat 7 <7.0.43 you will need to change
+`catalina.properties` and remove "log4j*.jar" from the `jarsToSkip`
+property. You may need to do something similar on other containers if
+they skip scanning Log4j JAR files.
+
+=== The Long Story
+
+The Log4j 2 Web JAR file is a web-fragment configured to order before
+any other web fragments in your application. It contains a
+`ServletContainerInitializer`
+(link:../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContainerInitializer.html[`Log4jServletContainerInitializer`])
+that the container automatically discovers and initializes. This adds
+the
+link:../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html[`Log4jServletContextListener`]
+and
+link:../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html[`Log4jServletFilter`]
+to the `ServletContext`. These classes properly initialize and
+deinitialize the Log4j configuration.
+
+For some users, automatically starting Log4j is problematic or
+undesirable. You can easily disable this feature using the
+`isLog4jAutoInitializationDisabled` context parameter. Simply add it to
+your deployment descriptor with the value "true" to disable
+auto-initialization. You _must_ define the context parameter in
+`web.xml`. If you set in programmatically, it will be too late for Log4j
+to detect the setting.
+
+[source,xml]
+----
+<context-param>
+ <param-name>isLog4jAutoInitializationDisabled</param-name>
+ <param-value>true</param-value>
+</context-param>
+----
+
+Once you disable auto-initialization, you must initialize Log4j as you
+would a link:#Servlet-2.5[Servlet 2.5 web application]. You must do so
+in a way that this initialization happens before any other application
+code (such as Spring Framework startup code) executes.
+
+You can customize the behavior of the listener and filter using the
+`log4jContextName`, `log4jConfiguration`, and/or
+`isLog4jContextSelectorNamed` context parameters. Read more about this
+in the link:#ContextParams[Context Parameters] section below. You _must
+not_ manually configure the `Log4jServletContextListener` or
+`Log4jServletFilter` in your deployment descriptor (`web.xml`) or in
+another initializer or listener in a Servlet 3.0 or newer application
+_unless you disable auto-initialization_ with
+`isLog4jAutoInitializationDisabled`. Doing so will result in startup
+errors and unspecified erroneous behavior.
+
+[#Servlet-2.5]
+== Servlet 2.5 Web Applications
+
+A Servlet 2.5 web application is any `<web-app>` whose `version`
+attribute has a value of "2.5." The `version` attribute is the only
+thing that matters; even if the web application is running in a Servlet
+3.0 or newer container, it is a Servlet 2.5 web application if the
+`version` attribute is "2.5." Note that Log4j 2 does not support Servlet
+2.4 and older web applications.
+
+If you are using Log4j in a Servlet 2.5 web application, or if you have
+disabled auto-initialization with the
+`isLog4jAutoInitializationDisabled` context parameter, you _must_
+configure the
+link:../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html[`Log4jServletContextListener`]
+and
+link:../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html[`Log4jServletFilter`]
+in the deployment descriptor or programmatically. The filter should
+match all requests of any type. The listener should be the very first
+listener defined in your application, and the filter should be the very
+first filter defined and mapped in your application. This is easily
+accomplished using the following `web.xml` code:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.apache.logging.log4j.web.Log4jServletContextListener</listener-class>
+</listener>
+
+<filter>
+ <filter-name>log4jServletFilter</filter-name>
+ <filter-class>org.apache.logging.log4j.web.Log4jServletFilter</filter-class>
+</filter>
+<filter-mapping>
+ <filter-name>log4jServletFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ <dispatcher>REQUEST</dispatcher>
+ <dispatcher>FORWARD</dispatcher>
+ <dispatcher>INCLUDE</dispatcher>
+ <dispatcher>ERROR</dispatcher>
+ <dispatcher>ASYNC</dispatcher><!-- Servlet 3.0 w/ disabled auto-initialization only; not supported in 2.5 -->
+</filter-mapping>
+----
+
+You can customize the behavior of the listener and filter using the
+`log4jContextName`, `log4jConfiguration`, and/or
+`isLog4jContextSelectorNamed` context parameters. Read more about this
+in the link:#ContextParams[Context Parameters] section below.
+
+[#ContextParams]
+== Context Parameters
+
+By default, Log4j 2 uses the `ServletContext`'s
+https://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getServletContextName()[context
+name] as the `LoggerContext` name and uses the standard pattern for
+locating the Log4j configuration file. There are three context
+parameters that you can use to control this behavior. The first,
+`isLog4jContextSelectorNamed`, specifies whether the context should be
+selected using the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/selector/JndiContextSelector.html[`JndiContextSelector`].
+If `isLog4jContextSelectorNamed` is not specified or is anything other
+than `true`, it is assumed to be `false`.
+
+If `isLog4jContextSelectorNamed` is `true`, `log4jContextName` must be
+specified or `display-name` must be specified in `web.xml`; otherwise,
+the application will fail to start with an exception.
+`log4jConfiguration` _should_ also be specified in this case, and must
+be a valid URI for the configuration file; however, this parameter is
+not required.
+
+If `isLog4jContextSelectorNamed` is not `true`, `log4jConfiguration` may
+optionally be specified and must be a valid URI or path to a
+configuration file or start with "classpath:" to denote a configuration
+file that can be found on the classpath. Without this parameter, Log4j
+will use the standard mechanisms for locating the configuration file.
+
+When specifying these context parameters, you must specify them in the
+deployment descriptor (`web.xml`) even in a Servlet 3.0 or never
+application. If you add them to the `ServletContext` within a listener,
+Log4j will initialize before the context parameters are available and
+they will have no effect. Here are some sample uses of these context
+parameters.
+
+=== Set the Logging Context Name to "myApplication"
+
+[source,xml]
+----
+<context-param>
+ <param-name>log4jContextName</param-name>
+ <param-value>myApplication</param-value>
+</context-param>
+----
+
+=== Set the Configuration Path/File/URI to "/etc/myApp/myLogging.xml"
+
+[source,xml]
+----
+<context-param>
+ <param-name>log4jConfiguration</param-name>
+ <param-value>file:///etc/myApp/myLogging.xml</param-value>
+</context-param>
+----
+
+=== Use the `JndiContextSelector`
+
+[source,xml]
+----
+<context-param>
+ <param-name>isLog4jContextSelectorNamed</param-name>
+ <param-value>true</param-value>
+</context-param>
+<context-param>
+ <param-name>log4jContextName</param-name>
+ <param-value>appWithJndiSelector</param-value>
+</context-param>
+<context-param>
+ <param-name>log4jConfiguration</param-name>
+ <param-value>file:///D:/conf/myLogging.xml</param-value>
+</context-param>
+----
+
+Note that in this case you must also set the "Log4jContextSelector"
+system property to
+"org.apache.logging.log4j.core.selector.JndiContextSelector".
+
+[#WebLookup]
+== Using Web Application Information During the Configuration
+
+You may want to use information about the web application during
+configuration. For example, you could embed the web application's
+context path in the name of a Rolling File Appender. See WebLookup in
+link:./lookups.html#WebLookup[Lookups] for more information.
+
+[#JspLogging]
+== JavaServer Pages Logging
+
+You may use Log4j 2 within JSPs just as you would within any other Java
+code. Simple obtain a `Logger` and call its methods to log events.
+However, this requires you to use Java code within your JSPs, and some
+development teams rightly are not comfortable with doing this. If you
+have a dedicated user interface development team that is not familiar
+with using Java, you may even have Java code disabled in your JSPs.
+
+For this reason, Log4j 2 provides a JSP Tag Library that enables you to
+log events without using any Java code. To read more about using this
+tag library, link:../log4j-taglib/index.html[read the Log4j Tag Library
+documentation.]
+
+NOTE: As noted above, containers often ignore certain
+JARs known not to contain TLDs and do not scan them for TLD files.
+Importantly, Tomcat 7 <7.0.43 ignores all JAR files named log4j*.jar,
+which prevents the JSP tag library from being automatically discovered.
+This does not affect Tomcat 6.x and has been fixed in Tomcat 7.0.43,
+Tomcat 8, and later. In Tomcat 7 <7.0.43 you will need to change
+`catalina.properties` and remove "log4j*.jar" from the `jarsToSkip`
+property. You may need to do something similar on other containers if
+they skip scanning Log4j JAR files.
+
+[#Async]
+== Asynchronous Requests and Threads
+
+The handling of asynchronous requests is tricky, and regardless of
+Servlet container version or configuration Log4j cannot handle
+everything automatically. When standard requests, forwards, includes,
+and error resources are processed, the `Log4jServletFilter` binds the
+`LoggerContext` to the thread handling the request. After request
+processing completes, the filter unbinds the `LoggerContext` from the
+thread.
+
+Similarly, when an internal request is dispatched using a
+`javax.servlet.AsyncContext`, the `Log4jServletFilter` also binds the
+`LoggerContext` to the thread handling the request and unbinds it when
+request processing completes. However, this only happens for requests
+_dispatched_ through the `AsyncContext`. There are other asynchronous
+activities that can take place other than internal dispatched requests.
+
+For example, after starting an `AsyncContext` you could start up a
+separate thread to process the request in the background, possibly
+writing the response with the `ServletOutputStream`. Filters cannot
+intercept the execution of this thread. Filters also cannot intercept
+threads that you start in the background during non-asynchronous
+requests. This is true whether you use a brand new thread or a thread
+borrowed from a thread pool. So what can you do for these special
+threads?
+
+You may not need to do anything. If you didn't use the
+`isLog4jContextSelectorNamed` context parameter, there is no need to
+bind the `LoggerContext` to the thread. Log4j can safely locate the
+`LoggerContext` on its own. In these cases, the filter provides only
+very modest performance gains, and only when creating new `Logger` instances.
+However, if you _did_ specify the `isLog4jContextSelectorNamed` context
+parameter with the value "true", you will need to manually bind the
+`LoggerContext` to asynchronous threads. Otherwise, Log4j will not be
+able to locate it.
+
+Thankfully, Log4j provides a simple mechanism for binding the
+`LoggerContext` to asynchronous threads in these special circumstances.
+The simplest way to do this is to wrap the `Runnable` instance that is
+passed to the `AsyncContext.start()` method.
+
+[source,java]
+----
+import java.io.IOException;
+import javax.servlet.AsyncContext;
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.web.WebLoggerContextUtils;
+
+public class TestAsyncServlet extends HttpServlet {
+
+ @Override
+ protected void doGet(final HttpServletRequest req, final HttpServletResponse resp) throws ServletException, IOException {
+ final AsyncContext asyncContext = req.startAsync();
+ asyncContext.start(WebLoggerContextUtils.wrapExecutionContext(this.getServletContext(), new Runnable() {
+ @Override
+ public void run() {
+ final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
+ logger.info("Hello, servlet!");
+ }
+ }));
+ }
+
+ @Override
+ protected void doPost(final HttpServletRequest req, final HttpServletResponse resp) throws ServletException, IOException {
+ final AsyncContext asyncContext = req.startAsync();
+ asyncContext.start(new Runnable() {
+ @Override
+ public void run() {
+ final Log4jWebSupport webSupport =
+ WebLoggerContextUtils.getWebLifeCycle(TestAsyncServlet.this.getServletContext());
+ webSupport.setLoggerContext();
+ // do stuff
+ webSupport.clearLoggerContext();
+ }
+ });
+ }
+}
+----
+
+This can be slightly more convenient when using Java 1.8 and lambda
+functions as demonstrated below.
+
+[source,java]
+----
+import java.io.IOException;
+import javax.servlet.AsyncContext;
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.web.WebLoggerContextUtils;
+
+public class TestAsyncServlet extends HttpServlet {
+ @Override
+ protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
+ final AsyncContext asyncContext = req.startAsync();
+ asyncContext.start(WebLoggerContextUtils.wrapExecutionContext(this.getServletContext(), () -> {
+ final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
+ logger.info("Hello, servlet!");
+ }));
+ }
+}
+----
+
+Alternatively, you can obtain the
+link:../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jWebLifeCycle.html[`Log4jWebLifeCycle`]
+instance from the `ServletContext` attributes, call its
+`setLoggerContext` method as the very first line of code in your
+asynchronous thread, and call its `clearLoggerContext` method as the
+very last line of code in your asynchronous thread. The following code
+demonstrates this. It uses the container thread pool to execute
+asynchronous request processing, passing an anonymous inner `Runnable`
+to the `start` method.
+
+[source,java]
+----
+import java.io.IOException;
+import javax.servlet.AsyncContext;
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.web.Log4jWebLifeCycle;
+import org.apache.logging.log4j.web.WebLoggerContextUtils;
+
+public class TestAsyncServlet extends HttpServlet {
+ @Override
+ protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
+ final AsyncContext asyncContext = req.startAsync();
+ asyncContext.start(new Runnable() {
+ @Override
+ public void run() {
+ final Log4jWebLifeCycle webLifeCycle =
+ WebLoggerContextUtils.getWebLifeCycle(TestAsyncServlet.this.getServletContext());
+ webLifeCycle.setLoggerContext();
+ try {
+ final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
+ logger.info("Hello, servlet!");
+ } finally {
+ webLifeCycle.clearLoggerContext();
+ }
+ }
+ });
+ }
+}
+----
+
+Note that you _must_ call `clearLoggerContext` once your thread is
+finished processing. Failing to do so will result in memory leaks. If
+using a thread pool, it can even disrupt the logging of other web
+applications in your container. For that reason, the example here shows
+clearing the context in a `finally` block, which will always execute.
+
+== Using the Servlet Appender
+
+Log4j provides a Servlet Appender that uses the servlet context as the
+log target. For example:
+
+[source,xml]
+----
+<Configuration status="WARN" name="ServletTest">
+
+ <Appenders>
+ <Servlet name="Servlet">
+ <PatternLayout pattern="%m%n%ex{none}"/>
+ </Servlet>
+ </Appenders>
+
+ <Loggers>
+ <Root level="debug">
+ <AppenderRef ref="Servlet"/>
+ </Root>
+ </Loggers>
+
+</Configuration>
+----
+
+To avoid double logging of exceptions to the servlet context, you must
+use `%ex{none}` in your `PatternLayout` as shown in the example. The
+exception will be omitted from the message text but it is passed to the
+servlet context as the actual `Throwable` object.
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/db18f5ad/src/site/xdoc/manual/webapp.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/webapp.xml b/src/site/xdoc/manual/webapp.xml
deleted file mode 100644
index ade3236..0000000
--- a/src/site/xdoc/manual/webapp.xml
+++ /dev/null
@@ -1,451 +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 Web Applications</title>
- <author email="nickwilliams@apache.org">Nick Williams</author>
- <author email="mattsicker@apache.org">Matt Sicker</author>
- </properties>
-
- <body>
- <section name="Using Log4j 2 in Web Applications">
- <p>
- You must take particular care when using Log4j or any other logging framework within a Java EE web application.
- It's important for logging resources to be properly cleaned up (database connections closed, files closed, etc.)
- when the container shuts down or the web application is undeployed. Because of the nature of class loaders
- within web applications, Log4j resources cannot be cleaned up through normal means. Log4j must be "started" when
- the web application deploys and "shut down" when the web application undeploys. How this works varies depending
- on whether your application is a <a href="#Servlet-3.0">Servlet 3.0 or newer</a> or
- <a href="#Servlet-2.5">Servlet 2.5</a> web application.
- </p>
- <p>
- In either case, you'll need to add the <code>log4j-web</code> module to your deployment as detailed in the
- <a href="../maven-artifacts.html">Maven, Ivy, and Gradle Artifacts</a> manual page.
- </p>
- <p class="big-red">
- <i class="icon-exclamation-sign"/>
- To avoid problems the Log4j shutdown hook will automatically be disabled when the log4j-web jar is included.
- </p>
- <a name="Configuration"/>
- <subsection name="Configuration">
- <p>
- Log4j allows the configuration file to be specified in web.xml using the <code>log4jConfiguration</code>
- context parameter. Log4j will search for configuration files by:
- </p>
- <ol>
- <li>
- If a location is provided it will be searched for as a servlet context resource. For example, if
- <code>log4jConfiguration</code> contains "logging.xml" then Log4j will look for a file with that
- name in the root directory of the web application.
- </li>
- <li>
- If no location is defined Log4j will search for a file that starts with "log4j2" in the WEB-INF directory.
- If more than one file is found, and if a file that starts with "log4j2-<var>name</var>" is present, where
- <var>name</var> is the name of the web application, then it will be used. Otherwise the first file will be
- used.
- </li>
- <li>
- The "normal" search sequence using the classpath and file URLs will be used to locate the configuration file.
- </li>
- </ol>
- </subsection>
- <subsection name="Servlet 3.0 and Newer Web Applications">
- <a name="Servlet-3.0" />
- <p>
- A Servlet 3.0 or newer web application is any <code><web-app></code> whose <code>version</code>
- attribute has a value of "3.0" or higher. Of course, the application must also be running in a compatible
- web container. Some examples are: Tomcat 7.0 and higher, GlassFish 3.0 and higher, JBoss 7.0 and higher,
- Oracle WebLogic 12c and higher, and IBM WebSphere 8.0 and higher.
- </p>
- <h4>The Short Story</h4>
- <p>
- Log4j 2 "just works" in Servlet 3.0 and newer web applications. It is capable of automatically starting when
- the application deploys and shutting down when the application undeploys. Thanks to the
- <a class="javadoc" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html">ServletContainerInitializer</a>
- API added to Servlet 3.0, the relevant <code>Filter</code> and <code>ServletContextListener</code> classes
- can be registered dynamically on web application startup.
- </p>
- <p>
- <strong class="text-warning"><i class="icon-exclamation-sign"/> Important Note!</strong>
- For performance reasons, containers often ignore certain JARs known not to
- contain TLDs or <code>ServletContainerInitializer</code>s and do not scan them for web-fragments and
- initializers. Importantly, Tomcat 7 <7.0.43 ignores all JAR files named log4j*.jar, which prevents this
- feature from working. This has been fixed in Tomcat 7.0.43, Tomcat 8, and later. In Tomcat 7 <7.0.43 you
- will need to change <code>catalina.properties</code> and remove "log4j*.jar" from the <code>jarsToSkip</code>
- property. You may need to do something similar on other containers if they skip scanning Log4j JAR files.
- </p>
- <h4>The Long Story</h4>
- <p>
- The Log4j 2 Web JAR file is a web-fragment configured to order before any other web fragments in your
- application. It contains a <code>ServletContainerInitializer</code>
- (<a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContainerInitializer.html"
- >Log4jServletContainerInitializer</a>) that the container automatically discovers and initializes. This adds
- the <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html"
- >Log4jServletContextListener</a> and
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html"
- >Log4jServletFilter</a> to the <code>ServletContext</code>. These classes properly initialize
- and deinitialize the Log4j configuration.
- </p>
- <p>
- For some users, automatically starting Log4j is problematic or undesirable. You can easily disable this
- feature using the <code>isLog4jAutoInitializationDisabled</code> context parameter. Simply add it to your
- deployment descriptor with the value "true" to disable auto-initialization. You <em>must</em> define the
- context parameter in <code>web.xml</code>. If you set in programmatically, it will be too late for Log4j
- to detect the setting.
- </p>
- <pre class="prettyprint linenums"><![CDATA[ <context-param>
- <param-name>isLog4jAutoInitializationDisabled</param-name>
- <param-value>true</param-value>
- </context-param>]]></pre>
- <p>
- Once you disable auto-initialization, you must initialize Log4j as you would a
- <a href="#Servlet-2.5">Servlet 2.5 web application</a>. You must do so in a way that this initialization
- happens before any other application code (such as Spring Framework startup code) executes.
- </p>
- <p>
- You can customize the behavior of the listener and filter using the <code>log4jContextName</code>,
- <code>log4jConfiguration</code>, and/or <code>isLog4jContextSelectorNamed</code> context parameters. Read more
- about this in the <a href="#ContextParams">Context Parameters</a> section below. You <em>must not</em>
- manually configure the <code>Log4jServletContextListener</code> or <code>Log4jServletFilter</code> in your
- deployment descriptor (<code>web.xml</code>) or in another initializer or listener in a Servlet 3.0 or newer
- application <em>unless you disable auto-initialization</em> with
- <code>isLog4jAutoInitializationDisabled</code>. Doing so will result in startup errors and unspecified
- erroneous behavior.
- </p>
- </subsection>
- <subsection name="Servlet 2.5 Web Applications">
- <a name="Servlet-2.5" />
- <p>
- A Servlet 2.5 web application is any <code><web-app></code> whose <code>version</code> attribute has a
- value of "2.5." The <code>version</code> attribute is the only thing that matters; even if the web application
- is running in a Servlet 3.0 or newer container, it is a Servlet 2.5 web application if the
- <code>version</code> attribute is "2.5." Note that Log4j 2 does not support Servlet 2.4 and older web
- applications.
- </p>
- <p>
- If you are using Log4j in a Servlet 2.5 web application, or if you have disabled auto-initialization with
- the <code>isLog4jAutoInitializationDisabled</code> context parameter, you <em>must</em> configure the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletContextListener.html"
- >Log4jServletContextListener</a> and
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jServletFilter.html"
- >Log4jServletFilter</a> in the deployment descriptor or programmatically. The filter should match all
- requests of any type. The listener should be the very first listener defined in your application, and the
- filter should be the very first filter defined and mapped in your application. This is easily accomplished
- using the following <code>web.xml</code> code:
- </p>
- <pre class="prettyprint linenums"><![CDATA[ <listener>
- <listener-class>org.apache.logging.log4j.web.Log4jServletContextListener</listener-class>
- </listener>
-
- <filter>
- <filter-name>log4jServletFilter</filter-name>
- <filter-class>org.apache.logging.log4j.web.Log4jServletFilter</filter-class>
- </filter>
- <filter-mapping>
- <filter-name>log4jServletFilter</filter-name>
- <url-pattern>/*</url-pattern>
- <dispatcher>REQUEST</dispatcher>
- <dispatcher>FORWARD</dispatcher>
- <dispatcher>INCLUDE</dispatcher>
- <dispatcher>ERROR</dispatcher>
- <dispatcher>ASYNC</dispatcher><!-- Servlet 3.0 w/ disabled auto-initialization only; not supported in 2.5 -->
- </filter-mapping>]]></pre>
- <p>
- You can customize the behavior of the listener and filter using the <code>log4jContextName</code>,
- <code>log4jConfiguration</code>, and/or <code>isLog4jContextSelectorNamed</code> context parameters. Read more
- about this in the <a href="#ContextParams">Context Parameters</a> section below.
- </p>
- </subsection>
- <subsection name="Context Parameters">
- <a name="ContextParams" />
- <p>
- By default, Log4j 2 uses the <code>ServletContext</code>'s
- <a href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getServletContextName()">context name</a>
- as the <code>LoggerContext</code> name and uses the standard pattern for locating the Log4j configuration
- file. There are three context parameters that you can use to control this behavior. The first,
- <code>isLog4jContextSelectorNamed</code>, specifies whether the context should be selected using the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/JndiContextSelector.html"
- >JndiContextSelector</a>. If <code>isLog4jContextSelectorNamed</code> is not specified or is anything other
- than <code>true</code>, it is assumed to be <code>false</code>.
- </p>
- <p>
- If <code>isLog4jContextSelectorNamed</code> is <code>true</code>, <code>log4jContextName</code> must be
- specified or <code>display-name</code> must be specified in <code>web.xml</code>; otherwise, the application
- will fail to start with an exception. <code>log4jConfiguration</code>
- <em>should</em> also be specified in this case, and must be a valid URI for the configuration file; however,
- this parameter is not required.
- </p>
- <p>
- If <code>isLog4jContextSelectorNamed</code> is not <code>true</code>, <code>log4jConfiguration</code> may
- optionally be specified and must be a valid URI or path to a configuration file or start with "classpath:" to
- denote a configuration file that can be found on the classpath. Without this parameter, Log4j will use the
- standard mechanisms for locating the configuration file.
- </p>
- <p>
- When specifying these context parameters, you must specify them in the deployment descriptor
- (<code>web.xml</code>) even in a Servlet 3.0 or never application. If you add them to the
- <code>ServletContext</code> within a listener, Log4j will initialize before the context parameters are
- available and they will have no effect. Here are some sample uses of these context parameters.
- </p>
- <h4>Set the Logging Context Name to "myApplication"</h4>
- <pre class="prettyprint linenums"><![CDATA[ <context-param>
- <param-name>log4jContextName</param-name>
- <param-value>myApplication</param-value>
- </context-param>]]></pre>
- <h4>Set the Configuration Path/File/URI to "/etc/myApp/myLogging.xml"</h4>
- <pre class="prettyprint linenums"><![CDATA[ <context-param>
- <param-name>log4jConfiguration</param-name>
- <param-value>file:///etc/myApp/myLogging.xml</param-value>
- </context-param>]]></pre>
- <h4>Use the <code>JndiContextSelector</code></h4>
- <pre class="prettyprint linenums"><![CDATA[ <context-param>
- <param-name>isLog4jContextSelectorNamed</param-name>
- <param-value>true</param-value>
- </context-param>
- <context-param>
- <param-name>log4jContextName</param-name>
- <param-value>appWithJndiSelector</param-value>
- </context-param>
- <context-param>
- <param-name>log4jConfiguration</param-name>
- <param-value>file:///D:/conf/myLogging.xml</param-value>
- </context-param>]]></pre>
- <p>
- Note that in this case you must also set the "Log4jContextSelector" system property to
- "<kbd>org.apache.logging.log4j.core.selector.JndiContextSelector</kbd>".
- </p>
- </subsection>
- <subsection name="Using Web Application Information During the Configuration">
- <a name="WebLookup" />
- <p>
- You may want to use information about the web application during configuration. For example, you could embed
- the web application's context path in the name of a Rolling File Appender. See WebLookup in
- <a href="./lookups.html#WebLookup">Lookups</a> for more information.
- </p>
- </subsection>
- <subsection name="JavaServer Pages Logging">
- <a name="JspLogging" />
- <p>
- You may use Log4j 2 within JSPs just as you would within any other Java code. Simple obtain a
- <code>Logger</code> and call its methods to log events. However, this requires you to use Java code within
- your JSPs, and some development teams rightly are not comfortable with doing this. If you have a dedicated
- user interface development team that is not familiar with using Java, you may even have Java code disabled in
- your JSPs.
- </p>
- <p>
- For this reason, Log4j 2 provides a JSP Tag Library that enables you to log events without using any Java
- code. To read more about using this tag library, <a href="../log4j-taglib/index.html">read the Log4j Tag
- Library documentation.</a>
- </p>
- <p>
- <strong class="text-warning"><i class="icon-exclamation-sign"/> Important Note!</strong>
- As noted above, containers often ignore certain JARs known not to
- contain TLDs and do not scan them for TLD files. Importantly, Tomcat 7 <7.0.43 ignores all JAR files named
- log4j*.jar, which prevents the JSP tag library from being automatically discovered. This does not affect
- Tomcat 6.x and has been fixed in Tomcat 7.0.43, Tomcat 8, and later. In Tomcat 7 <7.0.43 you
- will need to change <code>catalina.properties</code> and remove "log4j*.jar" from the <code>jarsToSkip</code>
- property. You may need to do something similar on other containers if they skip scanning Log4j JAR files.
- </p>
- </subsection>
- <subsection name="Asynchronous Requests and Threads">
- <a name="Async" />
- <p>
- The handling of asynchronous requests is tricky, and regardless of Servlet container version or configuration
- Log4j cannot handle everything automatically. When standard requests, forwards, includes, and error resources
- are processed, the <code>Log4jServletFilter</code> binds the <code>LoggerContext</code> to the thread handling
- the request. After request processing completes, the filter unbinds the <code>LoggerContext</code> from the
- thread.
- </p>
- <p>
- Similarly, when an internal request is dispatched using a <code>javax.servlet.AsyncContext</code>, the
- <code>Log4jServletFilter</code> also binds the <code>LoggerContext</code> to the thread handling the request
- and unbinds it when request processing completes. However, this only happens for requests <em>dispatched</em>
- through the <code>AsyncContext</code>. There are other asynchronous activities that can take place other than
- internal dispatched requests.
- </p>
- <p>
- For example, after starting an <code>AsyncContext</code> you could start up a separate thread to process the
- request in the background, possibly writing the response with the <code>ServletOutputStream</code>. Filters
- cannot intercept the execution of this thread. Filters also cannot intercept threads that you start in
- the background during non-asynchronous requests. This is true whether you use a brand new thread or a thread
- borrowed from a thread pool. So what can you do for these special threads?
- </p>
- <p>
- You may not need to do anything. If you didn't use the <code>isLog4jContextSelectorNamed</code> context
- parameter, there is no need to bind the <code>LoggerContext</code> to the thread. Log4j can safely locate the
- <code>LoggerContext</code> on its own. In these cases, the filter provides only very modest performance
- gains, and only when creating new <code>Logger</code>s. However, if you <em>did</em> specify the
- <code>isLog4jContextSelectorNamed</code> context parameter with the value "true", you will need to manually
- bind the <code>LoggerContext</code> to asynchronous threads. Otherwise, Log4j will not be able to locate it.
- </p>
- <p>
- Thankfully, Log4j provides a simple mechanism for binding the <code>LoggerContext</code> to asynchronous
- threads in these special circumstances. The simplest way to do this is to wrap the <code>Runnable</code>
- instance that is passed to the <code>AsyncContext.start()</code> method.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-import java.io.IOException;
-import javax.servlet.AsyncContext;
-import javax.servlet.ServletException;
-import javax.servlet.http.HttpServlet;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.web.WebLoggerContextUtils;
-
-public class TestAsyncServlet extends HttpServlet {
-
- @Override
- protected void doGet(final HttpServletRequest req, final HttpServletResponse resp) throws ServletException, IOException {
- final AsyncContext asyncContext = req.startAsync();
- asyncContext.start(WebLoggerContextUtils.wrapExecutionContext(this.getServletContext(), new Runnable() {
- @Override
- public void run() {
- final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
- logger.info("Hello, servlet!");
- }
- }));
- }
-
- @Override
- protected void doPost(final HttpServletRequest req, final HttpServletResponse resp) throws ServletException, IOException {
- final AsyncContext asyncContext = req.startAsync();
- asyncContext.start(new Runnable() {
- @Override
- public void run() {
- final Log4jWebSupport webSupport =
- WebLoggerContextUtils.getWebLifeCycle(TestAsyncServlet.this.getServletContext());
- webSupport.setLoggerContext();
- // do stuff
- webSupport.clearLoggerContext();
- }
- });
- }
-}
- ]]></pre>
- <p>
- This can be slightly more convenient when using Java 1.8 and lambda functions as demonstrated below.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-import java.io.IOException;
-import javax.servlet.AsyncContext;
-import javax.servlet.ServletException;
-import javax.servlet.http.HttpServlet;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.web.WebLoggerContextUtils;
-
-public class TestAsyncServlet extends HttpServlet {
- @Override
- protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
- final AsyncContext asyncContext = req.startAsync();
- asyncContext.start(WebLoggerContextUtils.wrapExecutionContext(this.getServletContext(), () -> {
- final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
- logger.info("Hello, servlet!");
- }));
- }
-}
- ]]></pre>
- <p>
- Alternatively, you can obtain the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/web/Log4jWebLifeCycle.html">Log4jWebLifeCycle</a>
- instance from the <code>ServletContext</code> attributes, call its <code>setLoggerContext</code> method as
- the very first line of code in your asynchronous thread, and call its <code>clearLoggerContext</code> method
- as the very last line of code in your asynchronous thread. The following code demonstrates this. It uses the
- container thread pool to execute asynchronous request processing, passing an anonymous inner
- <code>Runnable</code> to the <code>start</code> method.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-import java.io.IOException;
-import javax.servlet.AsyncContext;
-import javax.servlet.ServletException;
-import javax.servlet.http.HttpServlet;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.web.Log4jWebLifeCycle;
-import org.apache.logging.log4j.web.WebLoggerContextUtils;
-
-public class TestAsyncServlet extends HttpServlet {
- @Override
- protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
- final AsyncContext asyncContext = req.startAsync();
- asyncContext.start(new Runnable() {
- @Override
- public void run() {
- final Log4jWebLifeCycle webLifeCycle =
- WebLoggerContextUtils.getWebLifeCycle(TestAsyncServlet.this.getServletContext());
- webLifeCycle.setLoggerContext();
- try {
- final Logger logger = LogManager.getLogger(TestAsyncServlet.class);
- logger.info("Hello, servlet!");
- } finally {
- webLifeCycle.clearLoggerContext();
- }
- }
- });
- }
-}
- ]]></pre>
- <p>
- Note that you <em>must</em> call <code>clearLoggerContext</code> once your thread is finished
- processing. Failing to do so will result in memory leaks. If using a thread pool, it can even disrupt the
- logging of other web applications in your container. For that reason, the example here shows clearing the
- context in a <code>finally</code> block, which will always execute.
- </p>
- </subsection>
- <subsection name="Using the Servlet Appender">
- <p>
- Log4j provides a Servlet Appender that uses the servlet context as the log target. For example:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<Configuration status="WARN" name="ServletTest">
-
- <Appenders>
- <Servlet name="Servlet">
- <PatternLayout pattern="%m%n%ex{none}"/>
- </Servlet>
- </Appenders>
-
- <Loggers>
- <Root level="debug">
- <AppenderRef ref="Servlet"/>
- </Root>
- </Loggers>
-
-</Configuration>]]></pre>
- <p>
- To avoid double logging of exceptions to the servlet context, you must use <code>%ex{none}</code> in your
- <code>PatternLayout</code> as shown in the example. The exception will be omitted from the message text but
- it is passed to the servlet context as the actual Throwable object.
- </p>
- </subsection>
- </section>
- </body>
-
-</document>
[2/7] logging-log4j2 git commit: LOG4J2-1802: Convert extending Log4j
manual page to asciidoc
Posted by ma...@apache.org.
LOG4J2-1802: Convert extending Log4j manual page to asciidoc
Also has some documentation fixes
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/7b4493f2
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/7b4493f2
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/7b4493f2
Branch: refs/heads/master
Commit: 7b4493f2205b997741b0a3b06eca214dcbeee459
Parents: 77a3712
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 15:46:28 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 16:03:36 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/extending.adoc | 624 +++++++++++++++++++++++++++
src/site/xdoc/manual/extending.xml | 565 ------------------------
2 files changed, 624 insertions(+), 565 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7b4493f2/src/site/asciidoc/manual/extending.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/extending.adoc b/src/site/asciidoc/manual/extending.adoc
new file mode 100644
index 0000000..db5a6f9
--- /dev/null
+++ b/src/site/asciidoc/manual/extending.adoc
@@ -0,0 +1,624 @@
+////
+ 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.
+////
+= Extending Log4j 2
+Ralph Goers <rg...@apache.org>
+
+Log4j 2 provides numerous ways that it can be manipulated and extended.
+This section includes an overview of the various ways that are directly
+supported by the Log4j 2 implementation.
+
+[#LoggerContextFactory]
+== LoggerContextFactory
+
+The `LoggerContextFactory` binds the Log4j API to its implementation.
+The Log4j `LogManager` locates a `LoggerContextFactory` by using
+java.util.ServiceLoader to locate all instances of
+`org.apache.logging.log4j.spi.Provider`. Each implementation must
+provide a class that extends`org.apache.logging.log4j.spi.Provider` and
+should have a no-arg constructor that delegates to Provider's
+constructor passing the Priority, the API versions it is compatible
+with, and the class that implements
+`org.apache.logging.log4j.spi.LoggerContextFactory`. Log4j will compare
+the current API version and if it is compatible the implementation will
+be added to the list of providers. The API version in
+`org.apache.logging.log4j.LogManager` is only changed when a feature is
+added to the API that implementations need to be aware of. If more than
+one valid implementation is located the value for the Priority will be
+used to identify the factory with the highest priority. Finally, the
+class that implements
+`org.apache.logging.log4j.spi.LoggerContextFactory` will be instantiated
+and bound to the LogManager. In Log4j 2 this is provided by
+`Log4jContextFactory`.
+
+Applications may change the LoggerContextFactory that will be used by
+
+1. Create a binding to the logging implementation.
+.. Implement a new `LoggerContextFactory`.
+.. Implement a class that extends `org.apache.logging.spi.Provider.`
+with a no-arg constructor that calls super-class's constructor with the
+Priority, the API version(s), `LoggerContextFactory` class, and
+optionally, a `ThreadContextMap` implementation class.
+.. Create a `META-INF/services/org.apache.logging.spi.Provider` file
+that contains the name of the class that implements
+`org.apache.logging.spi.Provider`.
+2. Setting the system property log4j2.loggerContextFactory to the name
+of the `LoggerContextFactory` class to use.
+3. Setting the property "log4j2.loggerContextFactory" in a properties
+file named "log4j2.LogManager.properties" to the name of the
+LoggerContextFactory class to use. The properties file must be on the
+classpath.
+
+[#ContextSelector]
+== ContextSelector
+
+ContextSelectors are called by the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/impl/Log4jContextFactory.html[Log4j
+LoggerContext factory]. They perform the actual work of locating or
+creating a LoggerContext, which is the anchor for Loggers and their
+configuration. ContextSelectors are free to implement any mechanism they
+desire to manage LoggerContexts. The default Log4jContextFactory checks
+for the presence of a System Property named "Log4jContextSelector". If
+found, the property is expected to contain the name of the Class that
+implements the ContextSelector to be used.
+
+Log4j provides five ContextSelectors:
+
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/selector/BasicContextSelector.html[`BasicContextSelector`]::
+ Uses either a LoggerContext that has been stored in a ThreadLocal or a
+ common LoggerContext.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.html[`ClassLoaderContextSelector`]::
+ Associates LoggerContexts with the ClassLoader that created the caller
+ of the getLogger call. This is the default ContextSelector.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/selector/JndiContextSelector.html[`JndiContextSelector`]::
+ Locates the LoggerContext by querying JNDI.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector.html[`AsyncLoggerContextSelector`]::
+ Creates a LoggerContext that ensures that all loggers are
+ AsyncLoggers.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/osgi/BundleContextSelector.html[`BundleContextSelector`]::
+ Associates LoggerContexts with the ClassLoader of the bundle that
+ created the caller of the getLogger call. This is enabled by default
+ in OSGi environments.
+
+[#ConfigurationFactory]
+== ConfigurationFactory
+
+Modifying the way in which logging can be configured is usually one of
+the areas with the most interest. The primary method for doing that is
+by implementing or extending a
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/ConfigurationFactory.html[`ConfigurationFactory`].
+Log4j provides two ways of adding new ConfigurationFactories. The first
+is by defining the system property named "log4j.configurationFactory" to
+the name of the class that should be searched first for a configuration.
+The second method is by defining the `ConfigurationFactory` as a `Plugin`.
+
+All the ConfigurationFactories are then processed in order. Each factory
+is called on its `getSupportedTypes` method to determine the file
+extensions it supports. If a configuration file is located with one of
+the specified file extensions then control is passed to that
+`ConfigurationFactory` to load the configuration and create the
+`Configuration` object.
+
+Most `Configuration` extend the `BaseConfiguration` class. This class
+expects that the subclass will process the configuration file and create
+a hierarchy of `Node` objects. Each `Node` is fairly simple in that it
+consists of the name of the node, the name/value pairs associated with
+the node, The `PluginType` of the node and a List of all of its child
+Nodes. `BaseConfiguration` will then be passed the `Node` tree and
+instantiate the configuration objects from that.
+
+[source,java]
+----
+@Plugin(name = "XMLConfigurationFactory", category = "ConfigurationFactory")
+@Order(5)
+public class XMLConfigurationFactory extends ConfigurationFactory {
+
+ /**
+ * Valid file extensions for XML files.
+ */
+ public static final String[] SUFFIXES = new String[] {".xml", "*"};
+
+ /**
+ * Returns the Configuration.
+ * @param loggerContext The logger context.
+ * @param source The InputSource.
+ * @return The Configuration.
+ */
+ @Override
+ public Configuration getConfiguration(final LoggerContext loggerContext, final ConfigurationSource source) {
+ return new XmlConfiguration(loggerContext, source);
+ }
+
+ /**
+ * Returns the file suffixes for XML files.
+ * @return An array of File extensions.
+ */
+ public String[] getSupportedTypes() {
+ return SUFFIXES;
+ }
+}
+----
+
+[#LoggerConfig]
+== LoggerConfig
+
+`LoggerConfig` objects are where Loggers created by applications tie into
+the configuration. The Log4j implementation requires that all
+LoggerConfigs be based on the LoggerConfig class, so applications
+wishing to make changes must do so by extending the `LoggerConfig` class.
+To declare the new `LoggerConfig`, declare it as a Plugin of type "Core"
+and providing the name that applications should specify as the element
+name in the configuration. The `LoggerConfig` should also define a
+PluginFactory that will create an instance of the `LoggerConfig`.
+
+The following example shows how the root `LoggerConfig` simply extends a
+generic `LoggerConfig`.
+
+[source,java]
+----
+@Plugin(name = "root", category = "Core", printObject = true)
+public static class RootLogger extends LoggerConfig {
+
+ @PluginFactory
+ public static LoggerConfig createLogger(@PluginAttribute(value = "additivity", defaultBooleanValue = true) boolean additivity,
+ @PluginAttribute(value = "level", defaultStringValue = "ERROR") Level level,
+ @PluginElement("AppenderRef") AppenderRef[] refs,
+ @PluginElement("Filters") Filter filter) {
+ List<AppenderRef> appenderRefs = Arrays.asList(refs);
+ return new LoggerConfig(LogManager.ROOT_LOGGER_NAME, appenderRefs, filter, level, additivity);
+ }
+}
+----
+
+[#LogEventFactory]
+== LogEventFactory
+
+A `LogEventFactory` is used to generate LogEvents. Applications may
+replace the standard `LogEventFactory` by setting the value of the system
+property `log4j2.logEventFactory` to the name of the custom `LogEventFactory`
+class.
+
+Note: When log4j is configured to have link:async.html#AllAsync[all
+loggers asynchronous], log events are pre-allocated in a ring buffer and
+the `LogEventFactory` is not used.
+
+[#MessageFactory]
+== MessageFactory
+
+A `MessageFactory` is used to generate `Message` objects. Applications may
+replace the standard `ParameterizedMessageFactory` (or
+`ReusableMessageFactory` in garbage-free mode) by setting the value of the
+system property `log4j2.messageFactory` to the name of the custom
+`MessageFactory` class.
+
+Flow messages for the `Logger.entry()` and `Logger.exit()` methods have
+a separate `FlowMessageFactory`. Applications may replace the
+`DefaultFlowMessageFactory` by setting the value of the system property
+`log4j2.flowMessageFactory` to the name of the custom `FlowMessageFactory`
+class.
+
+[#Lookups]
+== Lookups
+
+Lookups are the means in which parameter substitution is performed.
+During Configuration initialization an "Interpolator" is created that
+locates all the Lookups and registers them for use when a variable needs
+to be resolved. The interpolator matches the "prefix" portion of the
+variable name to a registered Lookup and passes control to it to resolve
+the variable.
+
+A Lookup must be declared using a `@Plugin` annotation with a `type` of
+"Lookup". The `name` specified on the `@Plugin` annotation will be used to
+match the prefix. Unlike other Plugins, Lookups do not use a
+`@PluginFactory`. Instead, they are required to provide a constructor that
+accepts no arguments. The example below shows a Lookup that will return
+the value of a System Property.
+
+The provided Lookups are documented here: link:./lookups.html[Lookups]
+
+[source,java]
+----
+@Plugin(name = "sys", category = "Lookup")
+public class SystemPropertiesLookup implements StrLookup {
+
+ /**
+ * Lookup the value for the key.
+ * @param key the key to be looked up, may be null
+ * @return The value for the key.
+ */
+ public String lookup(String key) {
+ return System.getProperty(key);
+ }
+
+ /**
+ * Lookup the value for the key using the data in the LogEvent.
+ * @param event The current LogEvent.
+ * @param key the key to be looked up, may be null
+ * @return The value associated with the key.
+ */
+ public String lookup(LogEvent event, String key) {
+ return System.getProperty(key);
+ }
+}
+----
+
+[#Filters]
+== Filters
+
+As might be expected, Filters are the used to reject or accept log
+events as they pass through the logging system. A Filter is declared
+using a `@Plugin` annotation of `type` "Core" and an `elementType` of "filter".
+The `name` attribute on the Plugin annotation is used to specify the name
+of the element users should use to enable the Filter. Specifying the
+`printObject` attribute with a value of "true" indicates that a call to
+`toString` will format the arguments to the filter as the configuration is
+being processed. The Filter must also specify a `@PluginFactory` method
+or `@PluginFactoryBuilder` builder class and method
+that will be called to create the Filter
+
+The example below shows a Filter used to reject LogEvents based upon
+their logging level. Notice the typical pattern where all the filter
+methods resolve to a single filter method.
+
+[source,java]
+----
+@Plugin(name = "ThresholdFilter", category = "Core", elementType = "filter", printObject = true)
+public final class ThresholdFilter extends AbstractFilter {
+
+ private final Level level;
+
+ private ThresholdFilter(Level level, Result onMatch, Result onMismatch) {
+ super(onMatch, onMismatch);
+ this.level = level;
+ }
+
+ public Result filter(Logger logger, Level level, Marker marker, String msg, Object[] params) {
+ return filter(level);
+ }
+
+ public Result filter(Logger logger, Level level, Marker marker, Object msg, Throwable t) {
+ return filter(level);
+ }
+
+ public Result filter(Logger logger, Level level, Marker marker, Message msg, Throwable t) {
+ return filter(level);
+ }
+
+ @Override
+ public Result filter(LogEvent event) {
+ return filter(event.getLevel());
+ }
+
+ private Result filter(Level level) {
+ return level.isAtLeastAsSpecificAs(this.level) ? onMatch : onMismatch;
+ }
+
+ @Override
+ public String toString() {
+ return level.toString();
+ }
+
+ /**
+ * Create a ThresholdFilter.
+ * @param loggerLevel The log Level.
+ * @param match The action to take on a match.
+ * @param mismatch The action to take on a mismatch.
+ * @return The created ThresholdFilter.
+ */
+ @PluginFactory
+ public static ThresholdFilter createFilter(@PluginAttribute(value = "level", defaultStringValue = "ERROR") Level level,
+ @PluginAttribute(value = "onMatch", defaultStringValue = "NEUTRAL") Result onMatch,
+ @PluginAttribute(value = "onMismatch", defaultStringValue = "DENY") Result onMismatch) {
+ return new ThresholdFilter(level, onMatch, onMismatch);
+ }
+}
+----
+
+[#Appenders]
+== Appenders
+
+Appenders are passed an event, (usually) invoke a Layout to format the
+event, and then "publish" the event in whatever manner is desired.
+Appenders are declared as Plugins with a `type` of "Core" and an
+`elementType` of "appender". The `name` attribute on the Plugin annotation
+specifies the name of the element users must provide in their
+configuration to use the Appender. Appenders should specify `printObject`
+as "true" if the toString method renders the values of the attributes
+passed to the Appender.
+
+Appenders must also declare a `@PluginFactory` method or `@PluginFactoryBuilder`
+builder class and method that will create the appender. The example below shows
+an Appender named "Stub" that can be used as an initial template.
+
+Most Appenders use Managers. A manager actually "owns" the resources,
+such as an `OutputStream` or socket. When a reconfiguration occurs a new
+Appender will be created. However, if nothing significant in the
+previous Manager has changed, the new Appender will simply reference it
+instead of creating a new one. This insures that events are not lost
+while a reconfiguration is taking place without requiring that logging
+pause while the reconfiguration takes place.
+
+[source,java]
+----
+@Plugin(name = "Stub", category = "Core", elementType = "appender", printObject = true)
+public final class StubAppender extends OutputStreamAppender {
+
+ private StubAppender(String name, Layout layout, Filter filter, StubManager manager,
+ boolean ignoreExceptions) {
+ }
+
+ @PluginFactory
+ public static StubAppender createAppender(@PluginAttribute("name") String name,
+ @PluginAttribute("ignoreExceptions") boolean ignoreExceptions,
+ @PluginElement("Layout") Layout layout,
+ @PluginElement("Filters") Filter filter) {
+
+ if (name == null) {
+ LOGGER.error("No name provided for StubAppender");
+ return null;
+ }
+
+ StubManager manager = StubManager.getStubManager(name);
+ if (manager == null) {
+ return null;
+ }
+ if (layout == null) {
+ layout = PatternLayout.createDefaultLayout();
+ }
+ return new StubAppender(name, layout, filter, manager, ignoreExceptions);
+ }
+}
+----
+
+[#Layouts]
+== Layouts
+
+Layouts perform the formatting of events into the printable text that is
+written by Appenders to some destination. All Layouts must implement the
+`Layout` interface. Layouts that format the event into a `String` should
+extend `AbstractStringLayout`, which will take care of converting the
+`String` into the required byte array.
+
+Every Layout must declare itself as a plugin using the `@Plugin`
+annotation. The `type` must be "Core", and the `elementType` must be
+"layout". `printObject` should be set to "true" if the plugin's `toString`
+method will provide a representation of the object and its parameters.
+The name of the plugin must match the value users should use to specify
+it as an element in their Appender configuration. The plugin also must
+provide a static method annotated as a `@PluginFactory` and with each of
+the methods parameters annotated with `@PluginAttribute` or `@PluginElement` as
+appropriate. The plugin can alternatively use the plugin builder notation.
+
+[source,java]
+----
+@Plugin(name = "SampleLayout", category = "Core", elementType = "layout", printObject = true)
+public class SampleLayout extends AbstractStringLayout {
+
+ protected SampleLayout(boolean locationInfo, boolean properties, boolean complete,
+ Charset charset) {
+ }
+
+ @PluginFactory
+ public static SampleLayout createLayout(@PluginAttribute("locationInfo") boolean locationInfo,
+ @PluginAttribute("properties") boolean properties,
+ @PluginAttribute("complete") boolean complete,
+ @PluginAttribute(value = "charset", defaultStringValue = "UTF-8") Charset charset) {
+ return new SampleLayout(locationInfo, properties, complete, charset);
+ }
+}
+----
+
+[#PatternConverters]
+== PatternConverters
+
+PatternConverters are used by the PatternLayout to format the log event
+into a printable `String`. Each Converter is responsible for a single kind
+of manipulation, however Converters are free to format the event in
+complex ways. For example, there are several converters that manipulate
+Throwables and format them in various ways.
+
+A PatternConverter must first declare itself as a Plugin using the
+standard `@Plugin` annotation but must specify value of "Converter" on the
+`type` attribute. Furthermore, the Converter must also specify the
+`@ConverterKeys` annotation to define the tokens that can be specified in
+the pattern (preceded by a '%' character) to identify the Converter.
+
+Unlike most other Plugins, Converters do not use a `@PluginFactory`.
+Instead, each Converter is required to provide a static `newInstance`
+method that accepts an array of `String` as the only parameter. The
+`String[]` is the values that are specified within the curly braces
+that can follow the converter key.
+
+The following shows the skeleton of a Converter plugin.
+
+[source,java]
+----
+@Plugin(name = "query", category = "Converter")
+@ConverterKeys({"q", "query"})
+public final class QueryConverter extends LogEventPatternConverter {
+
+ public QueryConverter(String[] options) {
+ }
+
+ public static QueryConverter newInstance(final String[] options) {
+ return new QueryConverter(options);
+ }
+}
+----
+
+[#Plugin_Builders]
+== Plugin Builders
+
+Some plugins take a lot of optional configuration options. When a plugin
+takes many options, it is more maintainable to use a builder class
+rather than a factory method (see _Item 2: Consider a builder when faced
+with many constructor parameters_ in _Effective Java_ by Joshua Bloch).
+There are some other advantages to using an annotated builder class over
+an annotated factory method:
+
+* Attribute names don't need to be specified if they match the field
+name.
+* Default values can be specified in code rather than through an
+annotation (also allowing a runtime-calculated default value which isn't
+allowed in annotations).
+* Adding new optional parameters doesn't require existing programmatic
+configuration to be refactored.
+* Easier to write unit tests using builders rather than factory methods
+with optional parameters.
+* Default values are specified via code rather than relying on
+reflection and injection, so they work programmatically as well as in a
+configuration file.
+
+Here is an example of a plugin factory from `ListAppender`:
+
+[source,java]
+----
+@PluginFactory
+public static ListAppender createAppender(
+ @PluginAttribute("name") @Required(message = "No name provided for ListAppender") final String name,
+ @PluginAttribute("entryPerNewLine") final boolean newLine,
+ @PluginAttribute("raw") final boolean raw,
+ @PluginElement("Layout") final Layout<? extends Serializable> layout,
+ @PluginElement("Filter") final Filter filter) {
+ return new ListAppender(name, filter, layout, newLine, raw);
+}
+----
+
+Here is that same factory using a builder pattern instead:
+
+[source,java]
+----
+@PluginBuilderFactory
+public static Builder newBuilder() {
+ return new Builder();
+}
+
+public static class Builder implements org.apache.logging.log4j.core.util.Builder<ListAppender> {
+
+ @PluginBuilderAttribute
+ @Required(message = "No name provided for ListAppender")
+ private String name;
+
+ @PluginBuilderAttribute
+ private boolean entryPerNewLine;
+
+ @PluginBuilderAttribute
+ private boolean raw;
+
+ @PluginElement("Layout")
+ private Layout<? extends Serializable> layout;
+
+ @PluginElement("Filter")
+ private Filter filter;
+
+ public Builder setName(final String name) {
+ this.name = name;
+ return this;
+ }
+
+ public Builder setEntryPerNewLine(final boolean entryPerNewLine) {
+ this.entryPerNewLine = entryPerNewLine;
+ return this;
+ }
+
+ public Builder setRaw(final boolean raw) {
+ this.raw = raw;
+ return this;
+ }
+
+ public Builder setLayout(final Layout<? extends Serializable> layout) {
+ this.layout = layout;
+ return this;
+ }
+
+ public Builder setFilter(final Filter filter) {
+ this.filter = filter;
+ return this;
+ }
+
+ @Override
+ public ListAppender build() {
+ return new ListAppender(name, filter, layout, entryPerNewLine, raw);
+ }
+}
+----
+
+The only difference in annotations is using `@PluginBuilderAttribute`
+instead of `@PluginAttribute` so that default values and reflection can
+be used instead of specifying them in the annotation. Either annotation
+can be used in a builder, but the former is better suited for field
+injection while the latter is better suited for parameter injection.
+Otherwise, the same annotations (`@PluginConfiguration`,
+`@PluginElement`, `@PluginNode`, and `@PluginValue`) are all supported
+on fields. Note that a factory method is still required to supply a
+builder, and this factory method should be annotated with
+`@PluginBuilderFactory`.
+// TODO: this will change with LOG4J2-1188
+
+When plugins are being constructed after a configuration has been
+parsed, a plugin builder will be used if available, otherwise a plugin
+factory method will be used as a fallback. If a plugin contains neither
+factory, then it cannot be used from a configuration file (it can still
+be used programmatically of course).
+
+Here is an example of using a plugin factory versus a plugin builder
+programmatically:
+
+[source,java]
+----
+ListAppender list1 = ListAppender.createAppender("List1", true, false, null, null);
+ListAppender list2 = ListAppender.newBuilder().setName("List1").setEntryPerNewLine(true).build();
+----
+
+[#Custom_ContextDataInjector]
+== Custom ContextDataInjector
+
+The `ContextDataInjector` (introduced in Log4j 2.7) is responsible for
+populating the LogEvent's
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/LogEvent.html#getContextData()[context
+data] with key-value pairs or replacing it completely. The default
+implementation is `ThreadContextDataInjector`, which obtains context
+attributes from the ThreadContext.
+
+Applications may replace the default `ContextDataInjector` by setting the
+value of the system property `log4j2.contextDataInjector` to the name of
+the custom `ContextDataInjector` class.
+
+Implementors should be aware there are some subtleties related to
+thread-safety and implementing a context data injector in a garbage-free
+manner. See the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/ContextDataInjector.html[`ContextDataInjector`]
+javadoc for detail.
+
+== Custom ThreadContextMap implementations
+
+A garbage-free `StringMap`-based context map can be installed by setting
+system property `log4j2.garbagefreeThreadContextMap` to true. (Log4j
+must be link:garbagefree.html#Config[enabled] to use ThreadLocals.)
+
+Any custom `ThreadContextMap` implementation can be installed by setting
+system property `log4j2.threadContextMap` to the fully qualified class
+name of the class implementing the `ThreadContextMap` interface. By also
+implementing the `ReadOnlyThreadContextMap` interface, your custom
+`ThreadContextMap` implementation will be accessible to applications via the
+link:../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html#getThreadContextMap()[`ThreadContext::getThreadContextMap`]
+method.
+
+[#Custom_Plugins]
+== Custom Plugins
+
+// TODO
+See the link:plugins.html[Plugins] section of the manual.
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7b4493f2/src/site/xdoc/manual/extending.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/extending.xml b/src/site/xdoc/manual/extending.xml
deleted file mode 100644
index ee0dd01..0000000
--- a/src/site/xdoc/manual/extending.xml
+++ /dev/null
@@ -1,565 +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>Extending Log4j 2</title>
- <author email="rgoers@apache.org">Ralph Goers</author>
- </properties>
-<!-- TODO: add in documentation regarding typed attributes -->
- <body>
- <section name="Extending Log4j">
- <p>
- Log4j 2 provides numerous ways that it can be manipulated and extended. This section includes an
- overview of the various ways that are directly supported by the Log4j 2 implementation.
- </p>
- <subsection name="LoggerContextFactory">
- <p>
- The <code>LoggerContextFactory</code> binds the Log4j API to its implementation. The Log4j
- <code>LogManager</code> locates a <code>LoggerContextFactory</code> by using java.util.ServiceLoader
- to locate all instances of <code>org.apache.logging.log4j.spi.Provider</code>. Each implementation must
- provide a class that extends<code>org.apache.logging.log4j.spi.Provider</code> and should have a
- no-arg constructor that delegates to Provider's constructor passing the <var>Priority</var>,
- the API versions it is compatible with, and the class that implements
- <code>org.apache.logging.log4j.spi.LoggerContextFactory</code>. Log4j will compare the current API
- version and if it is compatible the implementation will be added to the list of providers. The
- API version in <code>org.apache.logging.log4j.LogManager</code> is only changed when a feature is added
- to the API that implementations need to be aware of. If more than one valid implementation is located
- the value for the <var>Priority</var> will be used to identify the factory with the highest priority.
- Finally, the class that implements <code>org.apache.logging.log4j.spi.LoggerContextFactory</code> will be
- instantiated and bound to the LogManager. In Log4j 2 this is provided by <code>Log4jContextFactory</code>.
- </p>
- <p>
- Applications may change the LoggerContextFactory that will be used by
- </p>
- <ol>
- <li>Create a binding to the logging implementation.
- <ol style="list-style-type: lower-alpha">
- <li>Implement a new <code>LoggerContextFactory</code>.</li>
- <li>Implement a class that extends <code>org.apache.logging.spi.Provider.</code> with a no-arg
- constructor that calls super-class's constructor with the <var>Priority</var>, the API version(s),
- <code>LoggerContextFactory</code> class, and optionally, a <code>ThreadContextMap</code>
- implementation class.</li>
- <li>Create a <code>META-INF/services/org.apache.logging.spi.Provider</code> file that contains the
- name of the class that implements <code>org.apache.logging.spi.Provider</code>.
- </li>
- </ol></li>
- <li>Setting the system property <var>log4j2.loggerContextFactory</var> to the name of the
- <code>LoggerContextFactory</code> class to use.
- </li>
- <li>Setting the property "log4j2.loggerContextFactory" in a properties file named
- "log4j2.LogManager.properties" to the name of the LoggerContextFactory class to use. The properties
- file must be on the classpath.
- </li>
- </ol>
- </subsection>
- <subsection name="ContextSelector">
- <p>
- ContextSelectors are called by the
- <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/impl/Log4jContextFactory.html">Log4j
- LoggerContext factory</a>. They perform the actual work of
- locating or creating a LoggerContext, which is the anchor for Loggers and their configuration.
- ContextSelectors are free to implement any mechanism they desire to manage LoggerContexts. The
- default Log4jContextFactory checks for the presence of a System Property named "Log4jContextSelector".
- If found, the property is expected to contain the name of the Class that implements the
- ContextSelector to be used.
- </p>
- <p>
- Log4j provides five ContextSelectors:
- </p>
- <dl>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/BasicContextSelector.html">BasicContextSelector</a></dt>
- <dd>Uses either a LoggerContext that has been stored in a ThreadLocal or a common LoggerContext.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.html">ClassLoaderContextSelector</a></dt>
- <dd>Associates LoggerContexts with the ClassLoader that created the caller of the getLogger call. This is
- the default ContextSelector.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/JndiContextSelector.html">JndiContextSelector</a></dt>
- <dd>Locates the LoggerContext by querying JNDI.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector.html">AsyncLoggerContextSelector</a></dt>
- <dd>Creates a LoggerContext that ensures that all loggers are AsyncLoggers.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/osgi/BundleContextSelector.html">BundleContextSelector</a></dt>
- <dd>Associates LoggerContexts with the ClassLoader of the bundle that created the caller of the getLogger
- call. This is enabled by default in OSGi environments.</dd>
- </dl>
- </subsection>
- <subsection name="ConfigurationFactory">
- <p>
- Modifying the way in which logging can be configured is usually one of the areas with the most
- interest. The primary method for doing that is by implementing or extending a
- <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/ConfigurationFactory.html">ConfigurationFactory</a>.
- Log4j provides two ways of adding new ConfigurationFactories. The first is by defining the system
- property named "log4j.configurationFactory" to the name of the class that should be searched first
- for a configuration. The second method is by defining the ConfigurationFactory as a Plugin.
- </p>
- <p>
- All the ConfigurationFactories are then processed in order. Each factory is called on its
- getSupportedTypes method to determine the file extensions it supports. If a configuration file
- is located with one of the specified file extensions then control is passed to that
- ConfigurationFactory to load the configuration and create the Configuration object.
- </p>
- <p>
- Most Configuration extend the BaseConfiguration class. This class expects that the subclass will
- process the configuration file and create a hierarchy of Node objects. Each Node is fairly simple
- in that it consists of the name of the node, the name/value pairs associated with the node, The
- PluginType of the node and a List of all of its child Nodes. BaseConfiguration will then be
- passed the Node tree and instantiate the configuration objects from that.
- </p>
- <pre class="prettyprint linenums">
-@Plugin(name = "XMLConfigurationFactory", category = "ConfigurationFactory")
-@Order(5)
-public class XMLConfigurationFactory extends ConfigurationFactory {
-
- /**
- * Valid file extensions for XML files.
- */
- public static final String[] SUFFIXES = new String[] {".xml", "*"};
-
- /**
- * Returns the Configuration.
- * @param loggerContext The logger context.
- * @param source The InputSource.
- * @return The Configuration.
- */
- @Override
- public Configuration getConfiguration(final LoggerContext loggerContext, final ConfigurationSource source) {
- return new XmlConfiguration(loggerContext, source);
- }
-
- /**
- * Returns the file suffixes for XML files.
- * @return An array of File extensions.
- */
- public String[] getSupportedTypes() {
- return SUFFIXES;
- }
-}</pre>
- </subsection>
- <subsection name="LoggerConfig">
- <p>
- LoggerConfig objects are where Loggers created by applications tie into the configuration. The Log4j
- implementation requires that all LoggerConfigs be based on the LoggerConfig class, so applications
- wishing to make changes must do so by extending the LoggerConfig class. To declare the new
- LoggerConfig, declare it as a Plugin of type "Core" and providing the name that applications
- should specify as the element name in the configuration. The LoggerConfig should also define
- a PluginFactory that will create an instance of the LoggerConfig.
- </p>
- <p>
- The following example shows how the root LoggerConfig simply extends a generic LoggerConfig.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-@Plugin(name = "root", category = "Core", printObject = true)
-public static class RootLogger extends LoggerConfig {
-
- @PluginFactory
- public static LoggerConfig createLogger(@PluginAttribute(value = "additivity", defaultBooleanValue = true) boolean additivity,
- @PluginAttribute(value = "level", defaultStringValue = "ERROR") Level level,
- @PluginElement("AppenderRef") AppenderRef[] refs,
- @PluginElement("Filters") Filter filter) {
- List<AppenderRef> appenderRefs = Arrays.asList(refs);
- return new LoggerConfig(LogManager.ROOT_LOGGER_NAME, appenderRefs, filter, level, additivity);
- }
-}]]></pre>
- </subsection>
- <subsection name="LogEventFactory">
- <p>A LogEventFactory is used to generate LogEvents. Applications may replace the standard LogEventFactory
- by setting the value of the system property Log4jLogEventFactory to the name of the custom
- LogEventFactory class. </p>
- <p>Note: When log4j is configured to have <a href="async.html#AllAsync">all loggers asynchronous</a>,
- log events are pre-allocated in a ring buffer and the LogEventFactory is not used.</p>
- </subsection>
- <subsection name="MessageFactory">
- <p>A MessageFactory is used to generate Message objects. Applications may replace the standard
- ParameterizedMessageFactory (or ReusableMessageFactory in garbage-free mode)
- by setting the value of the system property log4j2.messageFactory to the name of the custom
- MessageFactory class. </p>
- <p>Flow messages for the <tt>Logger.entry()</tt> and <tt>Logger.exit()</tt> methods have a separate FlowMessageFactory.
- Applications may replace the DefaultFlowMessageFactory by setting the value of the system property
- log4j2.flowMessageFactory to the name of the custom FlowMessageFactory class.
- </p>
- </subsection>
- <subsection name="Lookups">
- <p>
- Lookups are the means in which parameter substitution is performed. During Configuration initialization
- an "Interpolator" is created that locates all the Lookups and registers them for use when a variable
- needs to be resolved. The interpolator matches the "prefix" portion of the variable name to a
- registered Lookup and passes control to it to resolve the variable.
- </p>
- <p>
- A Lookup must be declared using a Plugin annotation with a type of "Lookup". The name specified on
- the Plugin annotation will be used to match the prefix. Unlike other Plugins, Lookups do not
- use a PluginFactory. Instead, they are required to provide a constructor that accepts no arguments.
- The example below shows a Lookup that will return the value of a System Property.
- </p>
- <p>The provided Lookups are documented here: <a href="./lookups.html">Lookups</a></p>
- <pre class="prettyprint linenums">
-@Plugin(name = "sys", category = "Lookup")
-public class SystemPropertiesLookup implements StrLookup {
-
- /**
- * Lookup the value for the key.
- * @param key the key to be looked up, may be null
- * @return The value for the key.
- */
- public String lookup(String key) {
- return System.getProperty(key);
- }
-
- /**
- * Lookup the value for the key using the data in the LogEvent.
- * @param event The current LogEvent.
- * @param key the key to be looked up, may be null
- * @return The value associated with the key.
- */
- public String lookup(LogEvent event, String key) {
- return System.getProperty(key);
- }
-}</pre>
- </subsection>
- <subsection name="Filters">
- <p>
- As might be expected, Filters are the used to reject or accept log events as they pass through the
- logging system. A Filter is declared using a Plugin annotation of type "Core" and an elementType of
- "filter". The name attribute on the Plugin annotation is used to specify the name of the element
- users should use to enable the Filter. Specifying the printObject attribute with a value of "true"
- indicates that a call to toString will format the arguments to the filter as the configuration
- is being processed. The Filter must also specify a PluginFactory method that will be called to
- create the Filter.
- </p>
- <p>
- The example below shows a Filter used to reject LogEvents based upon their logging level. Notice the
- typical pattern where all the filter methods resolve to a single filter method.
- </p>
- <pre class="prettyprint linenums">
-@Plugin(name = "ThresholdFilter", category = "Core", elementType = "filter", printObject = true)
-public final class ThresholdFilter extends AbstractFilter {
-
- private final Level level;
-
- private ThresholdFilter(Level level, Result onMatch, Result onMismatch) {
- super(onMatch, onMismatch);
- this.level = level;
- }
-
- public Result filter(Logger logger, Level level, Marker marker, String msg, Object[] params) {
- return filter(level);
- }
-
- public Result filter(Logger logger, Level level, Marker marker, Object msg, Throwable t) {
- return filter(level);
- }
-
- public Result filter(Logger logger, Level level, Marker marker, Message msg, Throwable t) {
- return filter(level);
- }
-
- @Override
- public Result filter(LogEvent event) {
- return filter(event.getLevel());
- }
-
- private Result filter(Level level) {
- return level.isAtLeastAsSpecificAs(this.level) ? onMatch : onMismatch;
- }
-
- @Override
- public String toString() {
- return level.toString();
- }
-
- /**
- * Create a ThresholdFilter.
- * @param loggerLevel The log Level.
- * @param match The action to take on a match.
- * @param mismatch The action to take on a mismatch.
- * @return The created ThresholdFilter.
- */
- @PluginFactory
- public static ThresholdFilter createFilter(@PluginAttribute(value = "level", defaultStringValue = "ERROR") Level level,
- @PluginAttribute(value = "onMatch", defaultStringValue = "NEUTRAL") Result onMatch,
- @PluginAttribute(value = "onMismatch", defaultStringValue = "DENY") Result onMismatch) {
- return new ThresholdFilter(level, onMatch, onMismatch);
- }
-}</pre>
- </subsection>
- <subsection name="Appenders">
- <p>
- Appenders are passed an event, (usually) invoke a Layout to format the event, and then "publish"
- the event in whatever manner is desired. Appenders are declared as Plugins with a type of "Core"
- and an elementType of "appender". The name attribute on the Plugin annotation specifies the name
- of the element users must provide in their configuration to use the Appender. Appenders should
- specify printObject as "true" if the toString method renders the values of the attributes passed
- to the Appender.
- </p>
- <p>
- Appenders must also declare a PluginFactory method that will create the appender. The example
- below shows an Appender named "Stub" that can be used as an initial template.
- </p>
- <p>
- Most Appenders use Managers. A manager actually "owns" the resources, such as an OutputStream or
- socket. When a reconfiguration occurs a new Appender will be created. However, if nothing significant
- in the previous Manager has changed, the new Appender will simply reference it instead of creating a
- new one. This insures that events are not lost while a reconfiguration is taking place without
- requiring that logging pause while the reconfiguration takes place.
- </p>
- <pre class="prettyprint linenums">
-@Plugin(name = "Stub", category = "Core", elementType = "appender", printObject = true)
-public final class StubAppender extends OutputStreamAppender {
-
- private StubAppender(String name, Layout layout, Filter filter, StubManager manager,
- boolean ignoreExceptions) {
- }
-
- @PluginFactory
- public static StubAppender createAppender(@PluginAttribute("name") String name,
- @PluginAttribute("ignoreExceptions") boolean ignoreExceptions,
- @PluginElement("Layout") Layout layout,
- @PluginElement("Filters") Filter filter) {
-
- if (name == null) {
- LOGGER.error("No name provided for StubAppender");
- return null;
- }
-
- StubManager manager = StubManager.getStubManager(name);
- if (manager == null) {
- return null;
- }
- if (layout == null) {
- layout = PatternLayout.createDefaultLayout();
- }
- return new StubAppender(name, layout, filter, manager, ignoreExceptions);
- }
-}</pre>
- </subsection>
- <subsection name="Layouts">
- <p>
- Layouts perform the formatting of events into the printable text that is written by Appenders to
- some destination. All Layouts must implement the Layout interface. Layouts that format the
- event into a String should extend AbstractStringLayout, which will take care of converting the
- String into the required byte array.
- </p>
- <p>
- Every Layout must declare itself as a plugin using the Plugin annotation. The type must be "Core",
- and the elementType must be "layout". printObject should be set to true if the plugin's toString
- method will provide a representation of the object and its parameters. The name of the plugin must
- match the value users should use to specify it as an element in their Appender configuration.
- The plugin also must provide a static method annotated as a PluginFactory and with each of the
- methods parameters annotated with PluginAttr or PluginElement as appropriate.
- </p>
- <pre class="prettyprint linenums">
-@Plugin(name = "SampleLayout", category = "Core", elementType = "layout", printObject = true)
-public class SampleLayout extends AbstractStringLayout {
-
- protected SampleLayout(boolean locationInfo, boolean properties, boolean complete,
- Charset charset) {
- }
-
- @PluginFactory
- public static SampleLayout createLayout(@PluginAttribute("locationInfo") boolean locationInfo,
- @PluginAttribute("properties") boolean properties,
- @PluginAttribute("complete") boolean complete,
- @PluginAttribute(value = "charset", defaultStringValue = "UTF-8") Charset charset) {
- return new SampleLayout(locationInfo, properties, complete, charset);
- }
-}</pre>
- </subsection>
- <subsection name="PatternConverters">
- <p>
- PatternConverters are used by the PatternLayout to format the log event into a printable String. Each
- Converter is responsible for a single kind of manipulation, however Converters are free to format
- the event in complex ways. For example, there are several converters that manipulate Throwables and
- format them in various ways.
- </p>
- <p>
- A PatternConverter must first declare itself as a Plugin using the standard Plugin annotation but
- must specify value of "Converter" on the type attribute. Furthermore, the Converter must also
- specify the ConverterKeys attribute to define the tokens that can be specified in the pattern
- (preceded by a '%' character) to identify the Converter.
- </p>
- <p>
- Unlike most other Plugins, Converters do not use a PluginFactory. Instead, each Converter is
- required to provide a static newInstance method that accepts an array of Strings as the only
- parameter. The String array are the values that are specified within the curly braces that can
- follow the converter key.
- </p>
- <p>
- The following shows the skeleton of a Converter plugin.
- </p>
- <pre class="prettyprint linenums">
-@Plugin(name = "query", category = "Converter")
-@ConverterKeys({"q", "query"})
-public final class QueryConverter extends LogEventPatternConverter {
-
- public QueryConverter(String[] options) {
- }
-
- public static QueryConverter newInstance(final String[] options) {
- return new QueryConverter(options);
- }
-}</pre>
- </subsection>
- <subsection name="Plugin Builders">
- <p>
- Some plugins take a lot of optional configuration options. When a plugin takes many options, it is more
- maintainable to use a builder class rather than a factory method (see <i>Item 2: Consider a builder when
- faced with many constructor parameters</i> in <i>Effective Java</i> by Joshua Bloch). There are some other
- advantages to using an annotated builder class over an annotated factory method:
- </p>
- <ul>
- <li>Attribute names don't need to be specified if they match the field name.</li>
- <li>Default values can be specified in code rather than through an annotation (also allowing a
- runtime-calculated default value which isn't allowed in annotations).</li>
- <li>Adding new optional parameters doesn't require existing programmatic configuration to be refactored.</li>
- <li>Easier to write unit tests using builders rather than factory methods with optional parameters.</li>
- <li>Default values are specified via code rather than relying on reflection and injection, so they work
- programmatically as well as in a configuration file.</li>
- </ul>
- <p>
- Here is an example of a plugin factory from <code>ListAppender</code>:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-@PluginFactory
-public static ListAppender createAppender(
- @PluginAttribute("name") @Required(message = "No name provided for ListAppender") final String name,
- @PluginAttribute("entryPerNewLine") final boolean newLine,
- @PluginAttribute("raw") final boolean raw,
- @PluginElement("Layout") final Layout<? extends Serializable> layout,
- @PluginElement("Filter") final Filter filter) {
- return new ListAppender(name, filter, layout, newLine, raw);
-}]]></pre>
- <p>
- Here is that same factory using a builder pattern instead:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-@PluginBuilderFactory
-public static Builder newBuilder() {
- return new Builder();
-}
-
-public static class Builder implements org.apache.logging.log4j.core.util.Builder<ListAppender> {
-
- @PluginBuilderAttribute
- @Required(message = "No name provided for ListAppender")
- private String name;
-
- @PluginBuilderAttribute
- private boolean entryPerNewLine;
-
- @PluginBuilderAttribute
- private boolean raw;
-
- @PluginElement("Layout")
- private Layout<? extends Serializable> layout;
-
- @PluginElement("Filter")
- private Filter filter;
-
- public Builder setName(final String name) {
- this.name = name;
- return this;
- }
-
- public Builder setEntryPerNewLine(final boolean entryPerNewLine) {
- this.entryPerNewLine = entryPerNewLine;
- return this;
- }
-
- public Builder setRaw(final boolean raw) {
- this.raw = raw;
- return this;
- }
-
- public Builder setLayout(final Layout<? extends Serializable> layout) {
- this.layout = layout;
- return this;
- }
-
- public Builder setFilter(final Filter filter) {
- this.filter = filter;
- return this;
- }
-
- @Override
- public ListAppender build() {
- return new ListAppender(name, filter, layout, entryPerNewLine, raw);
- }
-}]]></pre>
- <p>
- The only difference in annotations is using <code>@PluginBuilderAttribute</code> instead of
- <code>@PluginAttribute</code> so that default values and reflection can be used instead of specifying
- them in the annotation. Either annotation can be used in a builder, but the former is better suited
- for field injection while the latter is better suited for parameter injection. Otherwise, the same
- annotations (<code>@PluginConfiguration</code>, <code>@PluginElement</code>, <code>@PluginNode</code>,
- and <code>@PluginValue</code>) are all supported on fields. Note that a factory method is still required
- to supply a builder, and this factory method should be annotated with <code>@PluginBuilderFactory</code>.
- <!-- TODO: this will change with LOG4J2-1188 -->
- </p>
- <p>
- When plugins are being constructed after a configuration has been parsed, a plugin builder will be used
- if available, otherwise a plugin factory method will be used as a fallback. If a plugin contains neither
- factory, then it cannot be used from a configuration file (it can still be used programmatically of
- course).
- </p>
- <p>
- Here is an example of using a plugin factory versus a plugin builder programmatically:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-ListAppender list1 = ListAppender.createAppender("List1", true, false, null, null);
-ListAppender list2 = ListAppender.newBuilder().setName("List1").setEntryPerNewLine(true).build();
-]]></pre>
- </subsection>
- <subsection name="Custom ContextDataInjector">
- <p>
- The <code>ContextDataInjector</code> (introduced in Log4j 2.7) is responsible for
- populating the LogEvent's
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/LogEvent.html#getContextData()">context data</a>
- with key-value pairs or replacing it completely.
- The default implementation is ThreadContextDataInjector, which obtains context attributes from the ThreadContext.
- </p><p>
- Applications may replace the default ContextDataInjector by setting the value of the system property
- <tt>log4j2.contextDataInjector</tt> to the name of the custom ContextDataInjector class.
- </p><p>
- Implementors should be aware there are some subtleties related to thread-safety and implementing a
- context data injector in a garbage-free manner.
- See the <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/ContextDataInjector.html">ContextDataInjector</a>
- javadoc for detail.
- </p>
- </subsection>
- <subsection name="Custom ThreadContextMap implementations">
- <p>
- A garbage-free StringMap-based context map can be installed by setting system property <tt>log4j2.garbagefreeThreadContextMap</tt>
- to true. (Log4j must be <a href="garbagefree.html#Config">enabled</a> to use ThreadLocals.)
- </p><p>
- Any custom <tt>ThreadContextMap</tt> implementation can be installed by setting system property
- <tt>log4j2.threadContextMap</tt> to the fully qualified class name of the class implementing the
- ThreadContextMap interface. By also implementing the <tt>ReadOnlyThreadContextMap</tt> interface, your custom
- ThreadContextMap implementation will be accessible to applications via the
- <a href="../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html#getThreadContextMap()">ThreadContext::getThreadContextMap</a>
- method.
- </p>
- </subsection>
- <subsection name="Custom Plugins">
- <p>See the <a href="plugins.html">Plugins</a> section of the manual.</p>
-<!-- TODO: some documentation here! -->
- </subsection>
- </section>
-
- </body>
-</document>
[6/7] logging-log4j2 git commit: LOG4J2-1802: Convert logging
separation manual page to asciidoc
Posted by ma...@apache.org.
LOG4J2-1802: Convert logging separation 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/fa0135e2
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/fa0135e2
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/fa0135e2
Branch: refs/heads/master
Commit: fa0135e20a238cc22276e0a2a5c4b764359115f2
Parents: 7b4493f
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 15:49:45 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 16:03:36 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/logsep.adoc | 121 +++++++++++++++++++++++++++++
src/site/xdoc/manual/logsep.xml | 123 ------------------------------
2 files changed, 121 insertions(+), 123 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/fa0135e2/src/site/asciidoc/manual/logsep.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/logsep.adoc b/src/site/asciidoc/manual/logsep.adoc
new file mode 100644
index 0000000..ae52bc3
--- /dev/null
+++ b/src/site/asciidoc/manual/logsep.adoc
@@ -0,0 +1,121 @@
+////
+ 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.
+////
+= Logging Separation
+Ralph Goers <rg...@apache.org>
+
+There are many well known use cases where applications may share an
+environment with other applications and each has a need to have its own,
+separate logging environment. This purpose of this section is to discuss
+some of these cases and ways to accomplish this.
+
+[#UseCases]
+== Use Cases
+
+This section describes some of the use cases where Log4j could be used
+and what its desired behavior might be.
+
+=== Standalone Application
+
+Standalone applications are usually relatively simple. They typically
+have one bundled executable that requires only a single logging
+configuration.
+
+=== Web Applications
+
+A typical web application will be packaged as a WAR file and will
+include all of its dependencies in WEB-INF/lib and will have its
+configuration file located in the class path or in a location configured
+in the web.xml. Be sure to follow the link:webapp.html[instructions to
+initialize Log4j 2 in a web application].
+
+=== Java EE Applications
+
+A Java EE application will consist of one or more WAR files and possible
+some EJBs, typically all packaged in an EAR file. Usually, it is
+desirable to have a single configuration that applies to all the
+components in the EAR. The logging classes will generally be placed in a
+location shared across all the components and the configuration needs to
+also be shareable. Be sure to follow the link:webapp.html[instructions
+to initialize Log4j 2 in a web application].
+
+=== "Shared" Web Applications and REST Service Containers
+
+In this scenario there are multiple WAR files deployed into a single
+container. Each of the applications should use the same logging
+configuration and share the same logging implementation across each of
+the web applications. When writing to files and streams each of the
+applications should share them to avoid the issues that can occur when
+multiple components try to write to the same file(s) through different
+File objects, channels, etc.
+
+=== OSGi Applications
+
+An OSGi container physically separates each JAR into its own
+ClassLoader, thus enforcing modularity of JARs as well as providing
+standardized ways for JARs to share code based on version numbers.
+Suffice to say, the OSGi framework is beyond the scope of this manual.
+There are some differences when using Log4j in an OSGi container. By
+default, each JAR bundle is scanned for its own Log4j configuration
+file. Similar to the web application paradigm, every bundle has its own
+LoggerContext. As this may be undesirable when a global Log4j
+configuration is wanted, then the
+link:extending.html#ContextSelector[ContextSelector] should be
+overridden with `BasicContextSelector` or `JndiContextSelector`.
+
+[#Approaches]
+== Approaches
+
+=== The Simple Approach
+
+The simplest approach for separating logging within applications is to
+package each application with its own copy of Log4j and to use the
+BasicContextSelector. While this works for standalone applications and
+may work for web applications and possibly Java EE applications, it does
+not work at all in the last case. However, when this approach does work
+it should be used as it is ultimately the simplest and most
+straightforward way of implementing logging.
+
+=== Using Context Selectors
+
+There are a few patterns for achieving the desired state of logging
+separation using ContextSelectors:
+
+1. Place the logging jars in the container's classpath and set the
+system property `log4j2.contextSelector` to
+`org.apache.logging.log4j.core.selector.BasicContextSelector`. This will
+create a single LoggerContext using a single configuration that will be
+shared across all applications.
+2. Place the logging jars in the container's classpath and use the
+default ClassLoaderContextSelector. Follow the
+link:webapp.html[instructions to initialize Log4j 2 in a web
+application]. Each application can be configured to share the same
+configuration used at the container or can be individually configured.
+If status logging is set to debug in the configuration there will be
+output from when logging is initialized in the container and then again
+in each web application.
+3. Follow the link:webapp.html[instructions to initialize Log4j 2 in a
+web application] and set the system property or servlet context
+parameter `log4j2.contextSelector` to
+org.apache.logging.log4j.core.selector.JndiContextSelector. This will
+cause the container to use JNDI to locate each web application's
+`LoggerContext`. Be sure to set the `isLog4jContextSelectorNamed`
+context parameter to true and also set the `log4jContextName` and
+`log4jConfiguration` context parameters.
+
+The exact method for setting system properties depends on the container.
+For Tomcat, edit `$CATALINA_HOME/conf/catalina.properties`. Consult the
+documentation for other web containers.
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/fa0135e2/src/site/xdoc/manual/logsep.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/logsep.xml b/src/site/xdoc/manual/logsep.xml
deleted file mode 100644
index 55b59eb..0000000
--- a/src/site/xdoc/manual/logsep.xml
+++ /dev/null
@@ -1,123 +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>Logging Separation</title>
- <author email="rgoers@apache.org">Ralph Goers</author>
- </properties>
-
- <body>
- <section name="Logging Separation">
- <p>
- There are many well known use cases where applications may share an environment with other applications
- and each has a need to have its own, separate logging environment. This purpose of this section is to
- discuss some of these cases and ways to accomplish this.
- </p>
- <subsection name="Use Cases">
- <a name="UseCases"/>
- <p>
- This section describes some of the use cases where Log4j could be used and what its desired behavior
- might be.
- </p>
- <h4>Standalone Application</h4>
- <p>
- Standalone applications are usually relatively simple. They typically have one bundled executable
- that requires only a single logging configuration.
- </p>
- <h4>Web Applications</h4>
- <p>
- A typical web application will be packaged as a WAR file and will include all of its dependencies in
- WEB-INF/lib and will have its configuration file located in the class path or in a location
- configured in the web.xml. Be sure to follow the <a href="webapp.html">instructions to initialize Log4j 2
- in a web application</a>.
- </p>
- <h4>Java EE Applications</h4>
- <p>
- A Java EE application will consist of one or more WAR files and possible some EJBs, typically all
- packaged in an EAR file. Usually, it is desirable to have a single configuration that applies to
- all the components in the EAR. The logging classes will generally be placed in a location shared
- across all the components and the configuration needs to also be shareable. Be sure to follow the
- <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>.
- </p>
- <h4>"Shared" Web Applications and REST Service Containers</h4>
- <p>
- In this scenario there are multiple WAR files deployed into a single container. Each of the applications
- should use the same logging configuration and share the same logging implementation across each of the
- web applications. When writing to files and streams each of the applications should share them to avoid
- the issues that can occur when multiple components try to write to the same file(s) through different
- File objects, channels, etc.
- </p>
- <h4>OSGi Applications</h4>
- <p>
- An OSGi container physically separates each JAR into its own ClassLoader, thus enforcing modularity of
- JARs as well as providing standardized ways for JARs to share code based on version numbers. Suffice to
- say, the OSGi framework is beyond the scope of this manual. There are some differences when using Log4j
- in an OSGi container. By default, each JAR bundle is scanned for its own Log4j configuration file.
- Similar to the web application paradigm, every bundle has its own LoggerContext. As this may be
- undesirable when a global Log4j configuration is wanted, then the
- <a href="extending.html#ContextSelector">ContextSelector</a> should be overridden with
- <code>BasicContextSelector</code> or <code>JndiContextSelector</code>.
- </p>
- </subsection>
- <subsection name="Approaches">
- <a name="Approaches"/>
- <h4>The Simple Approach</h4>
- <p>
- The simplest approach for separating logging within applications is to package each application with
- its own copy of Log4j and to use the BasicContextSelector. While this works for standalone applications
- and may work for web applications and possibly Java EE applications, it does not work at all in the
- last case. However, when this approach does work it should be used as it is ultimately the simplest
- and most straightforward way of implementing logging.
- </p>
-
- <h4>Using Context Selectors</h4>
- <p>
- There are a few patterns for achieving the desired state of logging separation using ContextSelectors:
- </p>
- <ol>
- <li>Place the logging jars in the container's classpath and set the system property
- <tt>log4j2.contextSelector</tt> to <code>org.apache.logging.log4j.core.selector.BasicContextSelector</code>.
- This will create a single LoggerContext using a single configuration that will be shared across all
- applications.</li>
- <li>
- Place the logging jars in the container's classpath and use the default ClassLoaderContextSelector.
- Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a>. Each
- application can be configured to share the same configuration used at the container or can be
- individually configured. If status logging is set to debug in the configuration there will be output
- from when logging is initialized in the container and then again in each web application.
- </li>
- <li>
- Follow the <a href="webapp.html">instructions to initialize Log4j 2 in a web application</a> and set
- the system property or servlet context parameter <tt>log4j2.contextSelector</tt> to
- <kbd>org.apache.logging.log4j.core.selector.JndiContextSelector</kbd>. This will cause the container
- to use JNDI to locate each web application's <code>LoggerContext</code>. Be sure to set the
- <code>isLog4jContextSelectorNamed</code> context parameter to <kbd>true</kbd> and also set the
- <code>log4jContextName</code> and <code>log4jConfiguration</code> context parameters.
- </li>
- </ol>
- <p>
- The exact method for setting system properties depends on the container. For Tomcat, edit
- <code>$CATALINA_HOME/conf/catalina.properties</code>. Consult the documentation for other web containers.
- </p>
- </subsection>
- </section>
- </body>
-</document>
[3/7] logging-log4j2 git commit: LOG4J2-1802: Convert plugins manual
page to asciidoc
Posted by ma...@apache.org.
LOG4J2-1802: Convert plugins 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/a6744a65
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/a6744a65
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/a6744a65
Branch: refs/heads/master
Commit: a6744a659cbbc2a0758fdade5fe3c2bc679fe34e
Parents: 8dea0f4
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 15:04:57 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 16:03:36 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/plugins.adoc | 262 +++++++++++++++++++++++++++++
src/site/xdoc/manual/plugins.xml | 257 ----------------------------
2 files changed, 262 insertions(+), 257 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/a6744a65/src/site/asciidoc/manual/plugins.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/plugins.adoc b/src/site/asciidoc/manual/plugins.adoc
new file mode 100644
index 0000000..5b3a988
--- /dev/null
+++ b/src/site/asciidoc/manual/plugins.adoc
@@ -0,0 +1,262 @@
+////
+ 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.
+////
+= Plugins
+Ralph Goers <rg...@apache.org>; Matt Sicker <ma...@apache.org>
+
+Log4j 1.x allowed for extension by requiring class attributes on most of
+the configuration declarations. In the case of some elements, notably
+the PatternLayout, the only way to add new pattern converters was to
+extend the PatternLayout class and add them via code. One goal of Log4j
+2 is to make extending it extremely easy through the use of plugins.
+
+In Log4j 2 a plugin is declared by adding a
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/Plugin.html[`@Plugin`]
+annotation to the class declaration. During initialization the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`]
+will invoke the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/util/PluginManager.html[`PluginManager`]
+to load the built-in Log4j plugins as well as any custom plugins. The
+`PluginManager` locates plugins by looking in five places:
+
+1. Serialized plugin listing files on the classpath. These files are
+generated automatically during the build (more details below).
+2. (OSGi only) Serialized plugin listing files in each active OSGi
+bundle. A `BundleListener` is added on activation to continue checking
+new bundles after `log4j-core` has started.
+3. A comma-separated list of packages specified by the
+`log4j.plugin.packages` system property.
+4. Packages passed to the static `PluginManager.addPackages` method
+(before Log4j configuration occurs).
+5. The link:./configuration.html#ConfigurationSyntax[packages] declared
+in your log4j2 configuration file.
+
+If multiple Plugins specify the same (case-insensitive) `name`, then the
+load order above determines which one will be used. For example, to
+override the `File` plugin which is provided by the built-in
+`FileAppender` class, you would need to place your plugin in a JAR file
+in the CLASSPATH ahead of`log4j-core.jar`. This is not recommended;
+plugin name collisions will cause a warning to be emitted. Note that in
+an OSGi environment, the order that bundles are scanned for plugins
+generally follows the same order that bundles were installed into the
+framework. See
+http://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()[`getBundles()`]
+and
+http://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html[`SynchronousBundleListener`].
+In short, name collisions are even more unpredictable in an OSGi environment.
+////
+TODO: in future, plugins will be able to be annotated with @Order which can override priorities
+////
+
+Serialized plugin listing files are generated by an annotation processor
+contained in the log4j-core artifact which will automatically scan your
+code for Log4j 2 plugins and output a metadata file in your processed
+classes. There is nothing extra that needs to be done to enable this;
+the Java compiler will automatically pick up the annotation processor on
+the class path unless you explicitly disable it. In that case, it would
+be important to add another compiler pass to your build process that
+only handles annotation processing using the Log4j 2 annotation
+processor class,
+`org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor`.
+To do this using Apache Maven, add the following execution to your
+_maven-compiler-plugin_ (version 2.2 or higher) build plugin:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.1</version>
+ <executions>
+ <execution>
+ <id>log4j-plugin-processor</id>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ <phase>process-classes</phase>
+ <configuration>
+ <proc>only</proc>
+ <annotationProcessors>
+ <annotationProcessor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</annotationProcessor>
+ </annotationProcessors>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>
+----
+
+As the configuration is processed the appropriate plugins will be
+automatically configured and initialized. Log4j 2 utilizes a few
+different categories of plugins which are described in the following
+sections.
+
+[#Core]
+== Core
+
+Core plugins are those that are directly represented by an element in a
+configuration file, such as an Appender, Layout, Logger or Filter.
+Custom plugins that conform to the rules laid out in the next paragraph
+may simply be referenced in the configuration, provided they are
+appropriate configured to be loaded by the PluginManager.
+
+Every Core plugin must declare a static method annotated with
+`@PluginFactory` or `@PluginBuilderFactory`. The former is used for
+static factory methods that provide all options as method parameters,
+and the latter is used to construct a new `Builder<T>` class whose
+fields are used for injecting attributes and child nodes. To allow the
+`Configuration` to pass the correct parameters to the method, every
+parameter to the method must be annotated as one of the following
+attribute types. Each attribute or element annotation must include the
+name that must be present in the configuration in order to match the
+configuration item to its respective parameter. For plugin builders, the
+names of the fields will be used by default if no name is specified in
+the annotation. There are dozens of plugins in Log4j Core that can be
+used as examples for more complex scenarios including hierarchical
+builder classes (e.g., see `FileAppender`). See
+link:extending.html#Plugin_Builders[Extending Log4j with Plugin
+Builders] for more details.
+
+=== Attribute Types
+
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginAttribute.html[`PluginAttribute`]::
+ The parameter must be convertible from a String using a
+ link:#TypeConverters[TypeConverter]. Most built-in types are already
+ supported, but custom `TypeConverter` plugins may also be provided for
+ more type support. Note that `PluginBuilderAttribute` can be used in
+ builder class fields as an easier way to provide default values.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginElement.html[`PluginElement`]::
+ The parameter may represent a complex object that itself has
+ parameters that can be configured. This also supports injecting an
+ array of elements.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginConfiguration.html[`PluginConfiguration`]::
+ The current `Configuration` object will be passed to the plugin as a
+ parameter.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginNode.html[`PluginNode`]::
+ The current `Node` being parsed will be passed to the plugin as a
+ parameter.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginValue.html[`PluginValue`]::
+ The value of the current `Node` or its attribute named `value`.
+
+=== Constraint Validators
+
+Plugin factory fields and parameters can be automatically validated at
+runtime using constraint validators inspired by the
+http://beanvalidation.org/[Bean Validation spec]. The following
+annotations are bundled in Log4j, but custom
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/ConstraintValidator.html[`ConstraintValidators`]
+can be created as well.
+
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/Required.html[`Required`]::
+ This annotation validates that a value is non-empty. This covers a
+ check for `null` as well as several other scenarios: empty
+ `CharSequence` objects, empty arrays, empty `Collection` instances,
+ and empty `Map` instances.
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidHost.html[`ValidHost`]::
+ This annotation validates that a value corresponds to a valid
+ hostname. This uses the same validation as
+ http://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html#getByName-java.lang.String-[`InetAddress::getByName`].
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidPort.html[`ValidPort`]::
+ This annotation validates that a value corresponds to a valid port
+ number between 0 and 65535.
+
+[#Converters]
+== Converters
+
+Converters are used by
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html[`PatternLayout`]
+to render the elements identified by the conversion pattern. Every
+converter must specify its category as "Converter" on the `@Plugin`
+annotation, have a static `newInstance` method that accepts an array of
+`String` as its only parameter and returns an instance of the
+Converter, and must have a `@ConverterKeys` annotation present that
+contains the array of converter patterns that will cause the Converter
+to be selected. Converters that are meant to handle `LogEvent` must
+extend the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/LogEventPatternConverter.html[`LogEventPatternConverter`]
+class and must implement a format method that accepts a `LogEvent` and a
+`StringBuilder` as arguments. The Converter should append the result of
+its operation to the `StringBuilder`.
+
+A second type of Converter is the FileConverter - which must have
+"FileConverter" specified in the category attribute of the `@Plugin`
+annotation. While similar to a `LogEventPatternConverter`, instead of a
+single format method these Converters will have two variations; one that
+takes an `Object` and one that takes an array of `Object` instead of
+the `LogEvent`. Both append to the provided `StringBuilder` in the same
+fashion as a `LogEventPatternConverter`. These Converters are typically
+used by the `RollingFileAppender` to construct the name of the file to
+log to.
+
+If multiple Converters specify the same `ConverterKeys`, then the load
+order above determines which one will be used. For example, to override
+the `%date` converter which is provided by the built-in
+`DatePatternConverter` class, you would need to place your plugin in a
+JAR file in the CLASSPATH ahead of`log4j-core.jar`. This is not
+recommended; pattern ConverterKeys collisions will cause a warning to be
+emitted. Try to use unique ConverterKeys for your custom pattern
+converters.
+
+[#KeyProviders]
+== KeyProviders
+
+Some components within Log4j may provide the ability to perform data
+encryption. These components require a secret key to perform the
+encryption. Applications may provide the key by creating a class that
+implements the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/util/SecretKeyProvider.html[`SecretKeyProvider`]
+interface.
+
+[#Lookups]
+== Lookups
+
+Lookups are perhaps the simplest plugins of all. They must declare their
+type as "Lookup" on the plugin annotation and must implement the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
+interface. They will have two methods; a `lookup` method that accepts a
+`String` key and returns a `String` value and a second `lookup` method that
+accepts both a `LogEvent` and a `String` key and returns a `String`. Lookups
+may be referenced by specifying $\{name:key} where name is the name
+specified in the Plugin annotation and key is the name of the item to
+locate.
+
+[#TypeConverters]
+== TypeConverters
+
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html[`TypeConverter`]s
+are a sort of meta-plugin used for converting strings into other types
+in a plugin factory method parameter. Other plugins can already be
+injected via the `@PluginElement` annotation; now, any type supported by
+the type conversion system can be used in a `@PluginAttribute`
+parameter. Conversion of enum types are supported on demand and do not
+require custom `TypeConverter` classes. A large number of built-in Java
+classes are already supported; see
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.html[`TypeConverters`]
+for a more exhaustive listing.
+
+Unlike other plugins, the plugin name of a `TypeConverter` is purely
+cosmetic. Appropriate type converters are looked up via the `Type`
+interface rather than via `Class<?>` objects only. Do note that
+`TypeConverter` plugins must have a default constructor.
+
+[#DeveloperNotes]
+== Developer Notes
+
+If a plugin class implements
+http://docs.oracle.com/javase/6/docs/api/java/util/Collection.html[`Collection`]
+or http://docs.oracle.com/javase/6/docs/api/java/util/Map.html[`Map`],
+then no factory method is used. Instead, the class is instantiated using
+the default constructor, and all child configuration nodes are added to
+the `Collection` or `Map`.
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/a6744a65/src/site/xdoc/manual/plugins.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/plugins.xml b/src/site/xdoc/manual/plugins.xml
deleted file mode 100644
index c6addc8..0000000
--- a/src/site/xdoc/manual/plugins.xml
+++ /dev/null
@@ -1,257 +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 Plugins</title>
- <author email="rgoers@apache.org">Ralph Goers</author>
- <author email="mattsicker@apache.org">Matt Sicker</author>
- </properties>
-
- <body>
- <section name="Plugins">
- <subsection name="Introduction">
- <a name="Introduction"/>
- <p>
- Log4j 1.x allowed for extension by requiring class attributes on most of the configuration
- declarations. In the case of some elements, notably the PatternLayout, the only way to add
- new pattern converters was to extend the PatternLayout class and add them via code. One
- goal of Log4j 2 is to make extending it extremely easy through the use of plugins.
- </p>
- <p>
- In Log4j 2 a plugin is declared by adding a
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/Plugin.html">@Plugin</a>
- annotation to the class declaration. During initialization the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html">Configuration</a>
- will invoke the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/util/PluginManager.html">PluginManager</a>
- to load the built-in Log4j plugins as well as any custom plugins. The <code>PluginManager</code> locates
- plugins by looking in five places:
- </p>
- <ol>
- <li>Serialized plugin listing files on the classpath. These files are generated automatically during
- the build (more details below).</li>
- <li>(OSGi only) Serialized plugin listing files in each active OSGi bundle. A <code>BundleListener</code>
- is added on activation to continue checking new bundles after <code>log4j-core</code> has started.</li>
- <li>A comma-separated list of packages specified by the <code>log4j.plugin.packages</code>
- system property.</li>
- <li>Packages passed to the static <code>PluginManager.addPackages</code> method (before Log4j configuration
- occurs).</li>
- <li>The <a href="./configuration.html#ConfigurationSyntax">packages</a> declared in your log4j2
- configuration file.</li>
- </ol>
- <p>
- If multiple Plugins specify the same (case-insensitive) <code>name</code>, then the load order above
- determines which one will be used. For example, to override the <code>File</code> plugin which is provided
- by the built-in <code>FileAppender</code> class, you would need to place your plugin in a JAR file in the
- CLASSPATH ahead of<code>log4j-core.jar</code>. This is not recommended; plugin name collisions will cause a
- warning to be emitted. Note that in an OSGi environment, the order that bundles are scanned for plugins
- generally follows the same order that bundles were installed into the framework. See
- <a class="javadoc" href="http://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()">getBundles()</a>
- and
- <a class="javadoc" href="http://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html">SynchronousBundleListener</a>.
- In short, name collisions are even more unpredictable in an OSGi environment.
- <!--
- TODO: in future, plugins will be able to be annotated with @Order which can override priorities
- -->
- </p>
- <p>
- Serialized plugin listing files are generated by an annotation processor contained in the
- log4j-core artifact which will automatically scan your code for Log4j 2 plugins and output a metadata
- file in your processed classes. There is nothing extra that needs to be done to enable this; the Java
- compiler will automatically pick up the annotation processor on the class path unless you explicitly
- disable it. In that case, it would be important to add another compiler pass to your build process that
- only handles annotation processing using the Log4j 2 annotation processor class,
- <code>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</code>. To do this using
- Apache Maven, add the following execution to your <i>maven-compiler-plugin</i> (version 2.2 or higher)
- build plugin:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.1</version>
- <executions>
- <execution>
- <id>log4j-plugin-processor</id>
- <goals>
- <goal>compile</goal>
- </goals>
- <phase>process-classes</phase>
- <configuration>
- <proc>only</proc>
- <annotationProcessors>
- <annotationProcessor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</annotationProcessor>
- </annotationProcessors>
- </configuration>
- </execution>
- </executions>
-</plugin>
- ]]></pre>
- <p>
- As the configuration is processed the appropriate plugins will be automatically configured and
- initialized. Log4j 2 utilizes a few different categories of plugins which are described in the following
- sections.
- </p>
- </subsection>
- <subsection name="Core">
- <a name="Core"/>
- <p>
- Core plugins are those that are directly represented by an element in a configuration file, such as an
- Appender, Layout, Logger or Filter. Custom plugins that conform to the rules laid out in the next paragraph
- may simply be referenced in the configuration, provided they are appropriate configured to be
- loaded by the PluginManager.
- </p>
- <p>
- Every Core plugin must declare a static method annotated with <code>@PluginFactory</code> or
- <code>@PluginBuilderFactory</code>. The former is used for static factory methods that provide all options
- as method parameters, and the latter is used to construct a new <code>Builder<T></code> class whose
- fields are used for injecting attributes and child nodes. To allow the <code>Configuration</code> to pass
- the correct parameters to the method, every parameter to the method must be annotated as one of the following
- attribute types. Each attribute or element annotation must include the name that must be present in the
- configuration in order to match the configuration item to its respective parameter. For plugin builders,
- the names of the fields will be used by default if no name is specified in the annotation. There are dozens
- of plugins in Log4j Core that can be used as examples for more complex scenarios including hierarchical
- builder classes (e.g., see <code>FileAppender</code>). See <a href="extending.html#Plugin_Builders">Extending
- Log4j with Plugin Builders</a> for more details.
- </p>
- <h4>Attribute Types</h4>
- <dl>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginAttribute.html">PluginAttribute</a></dt>
- <dd>The parameter must be convertible from a String using a <a href="#TypeConverters">TypeConverter</a>.
- Most built-in types are already supported, but custom <code>TypeConverter</code> plugins may also be
- provided for more type support. Note that <code>PluginBuilderAttribute</code> can be used in builder class
- fields as an easier way to provide default values.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginElement.html">PluginElement</a></dt>
- <dd>The parameter may represent a complex object that itself has parameters that can be configured.
- This also supports injecting an array of elements.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginConfiguration.html">PluginConfiguration</a></dt>
- <dd>The current <code>Configuration</code> object will be passed to the plugin as a parameter.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginNode.html">PluginNode</a></dt>
- <dd>The current <code>Node</code> being parsed will be passed to the plugin as a parameter.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginValue.html">PluginValue</a></dt>
- <dd>The value of the current <code>Node</code> or its attribute named <code>value</code>.</dd>
- </dl>
- <h4>Constraint Validators</h4>
- <p>
- Plugin factory fields and parameters can be automatically validated at runtime using constraint validators
- inspired by the <a href="http://beanvalidation.org/">Bean Validation spec</a>. The following annotations
- are bundled in Log4j, but custom
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/ConstraintValidator.html">ConstraintValidators</a>
- can be created as well.
- </p>
- <dl>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/Required.html">Required</a></dt>
- <dd>This annotation validates that a value is non-empty. This covers a check for <code>null</code> as well
- as several other scenarios: empty <code>CharSequence</code> objects, empty arrays, empty <code>Collection</code>
- instances, and empty <code>Map</code> instances.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidHost.html">ValidHost</a></dt>
- <dd>This annotation validates that a value corresponds to a valid hostname. This uses the same validation as
- <a class="javadoc" href="http://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html#getByName-java.lang.String-">InetAddress::getByName</a>.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidPort.html">ValidPort</a></dt>
- <dd>This annotation validates that a value corresponds to a valid port number between 0 and 65535.</dd>
- </dl>
- </subsection>
- <subsection name="Converters">
- <a name="Converters"/>
- <p>
- Converters are used by
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html">PatternLayout</a>
- to render the elements identified by the conversion pattern. Every converter must specify its category as
- "Converter" on the <code>@Plugin</code> annotation, have a static <code>newInstance</code> method that
- accepts an array of <code>String</code>s as its only parameter and returns an instance of the Converter, and
- must have a <code>@ConverterKeys</code> annotation present that contains the array of converter patterns
- that will cause the Converter to be selected. Converters that are meant to handle <code>LogEvent</code>s
- must extend the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/LogEventPatternConverter.html">LogEventPatternConverter</a>
- class and must implement a format method that accepts a <code>LogEvent</code> and a <code>StringBuilder</code>
- as arguments. The Converter should append the result of its operation to the <code>StringBuilder</code>.
- </p>
- <p>
- A second type of Converter is the FileConverter - which must have "FileConverter" specified in the
- category attribute of the <code>@Plugin</code> annotation. While similar to a <code>LogEventPatternConverter</code>,
- instead of a single format method these Converters will have two variations; one that takes an
- <code>Object</code> and one that takes an array of <code>Object</code>s instead of the <code>LogEvent</code>.
- Both append to the provided <code>StringBuilder</code> in the same fashion as a <code>LogEventPatternConverter</code>.
- These Converters are typically used by the <code>RollingFileAppender</code> to construct the name of the
- file to log to.
- </p>
- <p>
- If multiple Converters specify the same <code>ConverterKeys</code>, then the load order above determines
- which one will be used. For example, to override the <code>%date</code> converter which is provided by the
- built-in <code>DatePatternConverter</code> class, you would need to place your plugin in a JAR file in the
- CLASSPATH ahead of<code>log4j-core.jar</code>. This is not recommended; pattern ConverterKeys collisions
- will cause a warning to be emitted. Try to use unique ConverterKeys for your custom pattern converters.
- </p>
- </subsection>
- <subsection name="KeyProviders">
- <a name="KeyProviders"/>
- <p>
- Some components within Log4j may provide the ability to perform data encryption. These components require
- a secret key to perform the encryption. Applications may provide the key by creating a class that
- implements the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/util/SecretKeyProvider.html">SecretKeyProvider</a>
- interface.
- </p>
- </subsection>
- <subsection name="Lookups">
- <a name="Lookups"/>
- <p>
- Lookups are perhaps the simplest plugins of all. They must declare their type as "Lookup" on the
- plugin annotation and must implement the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html">StrLookup</a>
- interface. They will have two methods; a
- lookup method that accepts a String key and returns a String value and a second lookup method that
- accepts both a LogEvent and a String key and returns a String. Lookups may be referenced by
- specifying ${<var>name</var>:key} where <var>name</var> is the name specified in the Plugin annotation and
- key is the name of the item to locate.
- </p>
- </subsection>
- <subsection name="TypeConverters">
- <a name="TypeConverters"/>
- <p>
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html">TypeConverter</a>s
- are a sort of meta-plugin used for converting strings into other types in a plugin factory method
- parameter. Other plugins can already be injected via the <code>@PluginElement</code> annotation; now, any
- type supported by the type conversion system can be used in a <code>@PluginAttribute</code> parameter.
- Conversion of enum types are supported on demand and do not require custom <code>TypeConverter</code>
- classes. A large number of built-in Java classes are already supported; see
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.html">TypeConverters</a>
- for a more exhaustive listing.
- </p>
- <p>
- Unlike other plugins, the plugin name of a <code>TypeConverter</code> is purely cosmetic. Appropriate
- type converters are looked up via the <code>Type</code> interface rather than via <code>Class<?></code>
- objects only. Do note that <code>TypeConverter</code> plugins must have a default constructor.
- </p>
- </subsection>
- </section>
- <section name="Developer Notes">
- <a name="DeveloperNotes"/>
- <p>
- If a plugin class implements
- <a class="javadoc" href="http://docs.oracle.com/javase/6/docs/api/java/util/Collection.html">Collection</a> or
- <a class="javadoc" href="http://docs.oracle.com/javase/6/docs/api/java/util/Map.html">Map</a>, then no
- factory method is used. Instead, the class is instantiated using the default constructor, and all child
- configuration nodes are added to the <code>Collection</code> or <code>Map</code>.
- </p>
- </section>
- </body>
-</document>
[4/7] logging-log4j2 git commit: LOG4J2-1802: Convert log4j 1.x
migration page to asciidoc
Posted by ma...@apache.org.
LOG4J2-1802: Convert log4j 1.x migration 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/8dea0f4f
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/8dea0f4f
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/8dea0f4f
Branch: refs/heads/master
Commit: 8dea0f4fb1eef58b266874e5b14cf3955f4d739e
Parents: d7f2fd7
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 14:47:56 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 16:03:36 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/migration.adoc | 359 +++++++++++++++++++++++++++
src/site/xdoc/manual/migration.xml | 351 --------------------------
2 files changed, 359 insertions(+), 351 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/8dea0f4f/src/site/asciidoc/manual/migration.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/migration.adoc b/src/site/asciidoc/manual/migration.adoc
new file mode 100644
index 0000000..9d217b4
--- /dev/null
+++ b/src/site/asciidoc/manual/migration.adoc
@@ -0,0 +1,359 @@
+= Migrating from Log4j 1.x
+Ralph Goers <rg...@apache.org>
+
+[#Log4j1.2Bridge]
+== Using the Log4j 1.x bridge
+
+Perhaps the simplest way to convert to using Log4j 2 is to replace the
+log4j 1.x jar file with Log4j 2's `log4j-1.2-api.jar`. However, to use
+this successfully applications must meet the following requirements:
+
+1. They must not access methods and classes internal to the Log4j 1.x
+implementation such as `Appender`s, `LoggerRepository` or `Category`'s
+`callAppenders` method.
+2. They must not programmatically configure Log4j.
+3. They must not configure by calling the classes `DOMConfigurator` or
+`PropertyConfigurator`.
+
+== Converting to the Log4j 2 API
+
+For the most part, converting from the Log4j 1.x API to Log4j 2 should
+be fairly simple. Many of the log statements will require no
+modification. However, where necessary the following changes must be
+made.
+
+. The main package in version 1 is `org.apache.log4j`, in version 2 it
+is `org.apache.logging.log4j`
+. Calls to `org.apache.log4j.Logger.getLogger()` must be modified to
+`org.apache.logging.log4j.LogManager.getLogger()`.
+. Calls to `org.apache.log4j.Logger.getRootLogger()` or
+`org.apache.log4j.LogManager.getRootLogger()` must be replaced with
+`org.apache.logging.log4j.LogManager.getRootLogger()`.
+. Calls to `org.apache.log4j.Logger.getLogger` that accept a
+`LoggerFactory` must remove the `org.apache.log4j.spi.LoggerFactory` and
+use one of Log4j 2's other extension mechanisms.
+. Replace calls to `org.apache.log4j.Logger.getEffectiveLevel()` with
+`org.apache.logging.log4j.Logger.getLevel()`.
+. Remove calls to `org.apache.log4j.LogManager.shutdown()`, they are
+not needed in version 2 because the Log4j Core now automatically adds a
+JVM shutdown hook on start up to perform any Core clean ups.
+.. Starting in Log4j 2.1, you can specify a custom
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html[`ShutdownCallbackRegistry`]
+to override the default JVM shutdown hook strategy.
+.. Starting in Log4j 2.6, you can now use
+`org.apache.logging.log4j.LogManager.shutdown()` to initiate shutdown
+manually.
+. Calls to `org.apache.log4j.Logger.setLevel()` or similar methods are
+not supported in the API. Applications should remove these. Equivalent
+functionality is provided in the Log4j 2 implementation classes, see
+`org.apache.logging.log4j.core.config.Configurator.setLevel()`, but may
+leave the application susceptible to changes in Log4j 2 internals.
+. Where appropriate, applications should convert to use parameterized
+messages instead of String concatenation.
+. http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html[`org.apache.log4j.MDC`]
+and
+http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/NDC.html[`org.apache.log4j.NDC`]
+have been replaced by the link:thread-context.html[Thread Context].
+
+== Configuring Log4j 2
+
+Although the Log4j 2 configuration syntax is different than that of
+Log4j 1.x, most, if not all, of the same functionality is available.
+
+Note that system property interpolation via the `${foo}` syntax has been
+extended to allow property lookups from many different sources. See the
+link:lookups.html[Lookups] documentation for more details. For example,
+using a lookup for the system property named `catalina.base`, in Log4j
+1.x, the syntax would be `${catalina.base}`. In Log4j 2, the syntax
+would be `${sys:catalina.base}`.
+
+Log4j 1.x has a XMLLayout which is different from the XmlLayout in Log4j
+2, the log4j-1.2-api module contains a `Log4j1XmlLayout` which produce
+output in the format as in Log4j 1.x. The Log4j 1.x `SimpleLayout` can
+be emulated with PatternLayout "%level - %m%n". The Log4j 1.x
+`TTCCLayout` can be emulated with PatternLayout "%r [%t] %p %c
+%notEmpty\{%ndc }- %m%n".
+
+Both `PatternLayout` and `EnhancedPatternLayout` in Log4j 1.x can be
+replaced with `PatternLayout` in Log4j 2. The log4j-1.2-api module
+contains two pattern conversions "%ndc" and "%properties" which can be
+used to emulate "%x" and "%X" in Log4j 1.x PatternLayout ("%x" and %X"
+in Log4j 2 have a slightly different format).
+
+Below are the example configurations for Log4j 1.x and their
+counterparts in Log4j 2.
+
+=== Sample 1 - Simple configuration using a Console Appender
+
+Log4j 1.x XML configuration
+
+.log4j.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
+<log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
+ <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+ <category name="org.apache.log4j.xml">
+ <priority value="info" />
+ </category>
+ <Root>
+ <priority value ="debug" />
+ <appender-ref ref="STDOUT" />
+ </Root>
+</log4j:configuration>
+----
+
+Log4j 2 XML configuration
+
+.log4j2.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration>
+ <Appenders>
+ <Console name="STDOUT" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.log4j.xml" level="info"/>
+ <Root level="debug">
+ <AppenderRef ref="STDOUT"/>
+ </Root>
+ </Loggers>
+</Configuration>
+----
+
+=== Sample 2 - Simple configuration using a File Appender, XMLLayout and SimpleLayout
+
+Log4j 1.x XML configuration
+
+.log4j.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+ <appender name="A1" class="org.apache.log4j.FileAppender">
+ <param name="File" value="A1.log" />
+ <param name="Append" value="false" />
+ <layout class="org.apache.log4j.xml.XMLLayout" />
+ </appender>
+ <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.SimpleLayout" />
+ </appender>
+ <category name="org.apache.log4j.xml">
+ <priority value="debug" />
+ <appender-ref ref="A1" />
+ </category>
+ <root>
+ <priority value ="debug" />
+ <appender-ref ref="STDOUT" />
+ </Root>
+</log4j:configuration>
+----
+
+Log4j 2 XML configuration
+
+.log4j2.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration>
+ <Appenders>
+ <File name="A1" fileName="A1.log" append="false">
+ <Log4j1XmlLayout />
+ </File>
+ <Console name="STDOUT" target="SYSTEM_OUT">
+ <PatternLayout pattern="%level - %m%n"/>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.log4j.xml" level="debug">
+ <AppenderRef ref="A1"/>
+ </Logger>
+ <Root level="debug">
+ <AppenderRef ref="STDOUT"/>
+ </Root>
+ </Loggers>
+</Configuration>
+----
+
+=== Sample 3 - SocketAppender
+
+Log4j 1.x XML configuration. This example from Log4j 1.x is misleading.
+The SocketAppender does not actually use a Layout. Configuring one will
+have no effect.
+
+.log4j.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+ <appender name="A1" class="org.apache.log4j.net.SocketAppender">
+ <param name="RemoteHost" value="localhost"/>
+ <param name="Port" value="5000"/>
+ <param name="LocationInfo" value="true"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/>
+ </layout>
+ </appender>
+ <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+ <category name="org.apache.log4j.xml">
+ <priority value="debug"/>
+ <appender-ref ref="A1"/>
+ </category>
+ <root>
+ <priority value="debug"/>
+ <appender-ref ref="STDOUT"/>
+ </Root>
+</log4j:configuration>
+----
+
+Log4j 2 XML configuration
+
+.log4j2.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration>
+ <Appenders>
+ <Socket name="A1" host="localHost" port="5000">
+ <PatternLayout pattern="%t %-5p %c{2} - %m%n"/>
+ </Socket>
+ <Console name="STDOUT" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.log4j.xml" level="debug">
+ <AppenderRef ref="A1"/>
+ </Logger>
+ <Root level="debug">
+ <AppenderRef ref="STDOUT"/>
+ </Root>
+ </Loggers>
+</Configuration>
+----
+
+=== Sample 4 - AsyncAppender and TTCCLayout
+
+Log4j 1.x XML configuration using the AsyncAppender.
+
+.log4j.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true">
+ <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
+ <appender-ref ref="TEMP"/>
+ </appender>
+ <appender name="TEMP" class="org.apache.log4j.FileAppender">
+ <param name="File" value="temp"/>
+ <layout class="org.apache.log4j.TTCCLayout">
+ <param name="ThreadPrinting" value="true"/>
+ <param name="CategoryPrefixing" value="true"/>
+ <param name="ContextPrinting" value="true"/>
+ </layout>
+ </appender>
+ <root>
+ <priority value="debug"/>
+ <appender-ref ref="ASYNC"/>
+ </Root>
+</log4j:configuration>
+----
+
+Log4j 2 XML configuration.
+
+.log4j2.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="debug">
+ <Appenders>
+ <File name="TEMP" fileName="temp">
+ <PatternLayout pattern="%r [%t] %p %c %notEmpty{%ndc }- %m%n"/>
+ </File>
+ <Async name="ASYNC">
+ <AppenderRef ref="TEMP"/>
+ </Async>
+ </Appenders>
+ <Loggers>
+ <Root level="debug">
+ <AppenderRef ref="ASYNC"/>
+ </Root>
+ </Loggers>
+</Configuration>
+----
+
+=== Sample 5 - AsyncAppender with Console and File
+
+Log4j 1.x XML configuration using the AsyncAppender.
+
+.log4j.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true">
+ <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
+ <appender-ref ref="TEMP"/>
+ <appender-ref ref="CONSOLE"/>
+ </appender>
+ <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+ <appender name="TEMP" class="org.apache.log4j.FileAppender">
+ <param name="File" value="temp"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+ <root>
+ <priority value="debug"/>
+ <appender-ref ref="ASYNC"/>
+ </Root>
+</log4j:configuration>
+----
+
+Log4j 2 XML configuration. Note that the Async Appender should be
+configured after the appenders it references. This will allow it to
+shutdown properly.
+
+.log4j2.xml
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="debug">
+ <Appenders>
+ <Console name="CONSOLE" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </Console>
+ <File name="TEMP" fileName="temp">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </File>
+ <Async name="ASYNC">
+ <AppenderRef ref="TEMP"/>
+ <AppenderRef ref="CONSOLE"/>
+ </Async>
+ </Appenders>
+ <Loggers>
+ <Root level="debug">
+ <AppenderRef ref="ASYNC"/>
+ </Root>
+ </Loggers>
+</Configuration>
+----
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/8dea0f4f/src/site/xdoc/manual/migration.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/migration.xml b/src/site/xdoc/manual/migration.xml
deleted file mode 100644
index e503277..0000000
--- a/src/site/xdoc/manual/migration.xml
+++ /dev/null
@@ -1,351 +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>Migrating from Log4j 1.x</title>
- <author email="rgoers@apache.org">Ralph Goers</author>
- </properties>
-
- <body>
- <section name="Migrating from Log4j 1.x">
- <a name="Log4j1.2Bridge"/>
- <subsection name="Using the Log4j 1.x bridge">
- <p>
- Perhaps the simplest way to convert to using Log4j 2 is to replace the log4j 1.x jar file with
- Log4j 2's <code>log4j-1.2-api.jar</code>. However, to use this successfully applications must meet the
- following requirements:
- </p>
- <ol>
- <li>They must not access methods and classes internal to the Log4j 1.x implementation such
- as <code>Appender</code>s, <code>LoggerRepository</code> or <code>Category</code>'s
- <code>callAppenders</code> method.</li>
- <li>They must not programmatically configure Log4j.</li>
- <li>They must not configure by calling the classes <code>DOMConfigurator</code> or
- <code>PropertyConfigurator</code>.</li>
- </ol>
- </subsection>
- <subsection name="Converting to the Log4j 2 API">
- <p>For the most part, converting from the Log4j 1.x API to Log4j 2 should be fairly simple. Many
- of the log statements will require no modification. However, where necessary the following changes must be
- made.</p>
- <ol>
- <li>
- The main package in version 1 is <code>org.apache.log4j</code>, in version 2 it is
- <code>org.apache.logging.log4j</code>
- </li>
- <li>
- Calls to <code>org.apache.log4j.Logger.getLogger()</code> must be modified to
- <code>org.apache.logging.log4j.LogManager.getLogger()</code>.
- </li>
- <li>
- Calls to <code>org.apache.log4j.Logger.getRootLogger()</code> or
- <code>org.apache.log4j.LogManager.getRootLogger()</code> must be replaced with
- <code>org.apache.logging.log4j.LogManager.getRootLogger()</code>.</li>
- <li>
- Calls to <code>org.apache.log4j.Logger.getLogger</code> that accept a <code>LoggerFactory</code> must
- remove the <code>org.apache.log4j.spi.LoggerFactory</code> and use one of Log4j 2's other extension
- mechanisms.
- </li>
- <li>
- Replace calls to <code>org.apache.log4j.Logger.getEffectiveLevel()</code> with
- <code>org.apache.logging.log4j.Logger.getLevel()</code>.
- </li>
- <li>
- Remove calls to <code>org.apache.log4j.LogManager.shutdown()</code>, they are not needed in version 2
- because the Log4j Core now automatically adds a JVM shutdown hook on start up to perform any Core
- clean ups.
- <ol>
- <li>
- Starting in Log4j 2.1, you can specify a custom
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html">ShutdownCallbackRegistry</a>
- to override the default JVM shutdown hook strategy.
- </li>
- <li>
- Starting in Log4j 2.6, you can now use <code>org.apache.logging.log4j.LogManager.shutdown()</code>
- to initiate shutdown manually.
- </li>
- </ol>
- </li>
- <li>
- Calls to <code>org.apache.log4j.Logger.setLevel()</code> or similar methods are not supported in the API.
- Applications should remove these. Equivalent functionality is provided in the Log4j 2 implementation
- classes, see <code>org.apache.logging.log4j.core.config.Configurator.setLevel()</code>, but may leave
- the application susceptible to changes in Log4j 2 internals.
- </li>
- <li>
- Where appropriate, applications should convert to use parameterized messages instead of String
- concatenation.
- </li>
- <li>
- <a href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html"><code>org.apache.log4j.MDC</code></a> and
- <a href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/NDC.html"><code>org.apache.log4j.NDC</code></a>
- have been replaced by the <a href="thread-context.html">Thread Context</a>.
- </li>
- </ol>
- </subsection>
- <subsection name="Configuring Log4j 2">
- <p>
- Although the Log4j 2 configuration syntax is different than that of Log4j 1.x, most, if not all, of
- the same functionality is available.
- </p>
- <p>
- Note that system property interpolation via the <code>${foo}</code> syntax has been extended to allow
- property lookups from many different sources. See the <a href="lookups.html">Lookups</a> documentation
- for more details. For example, using a lookup for the system property named <code>catalina.base</code>,
- in Log4j 1.x, the syntax would be <code>${catalina.base}</code>. In Log4j 2, the syntax would be
- <code>${sys:catalina.base}</code>.
- </p>
- <p>
- Log4j 1.x has a XMLLayout which is different from the XmlLayout in Log4j 2, the log4j-1.2-api module
- contains a <code>Log4j1XmlLayout</code> which produce output in the format as in Log4j 1.x.
- The Log4j 1.x <code>SimpleLayout</code> can be emulated with PatternLayout "%level - %m%n".
- The Log4j 1.x <code>TTCCLayout</code> can be emulated with PatternLayout "%r [%t] %p %c %notEmpty{%ndc }- %m%n".
- </p>
- <p>
- Both <code>PatternLayout</code> and <code>EnhancedPatternLayout</code> in Log4j 1.x can be replaced with
- <code>PatternLayout</code> in Log4j 2. The log4j-1.2-api module contains two pattern conversions "%ndc" and "%properties" which
- can be used to emulate "%x" and "%X" in Log4j 1.x PatternLayout ("%x" and %X" in Log4j 2 have a slightly different format).
- </p>
- <p>
- Below are the example configurations for Log4j 1.x and their counterparts in Log4j 2.
- </p>
-
- <h4>Sample 1 - Simple configuration using a Console Appender</h4>
- <p>Log4j 1.x XML configuration</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
-<log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
- <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
- </layout>
- </appender>
- <category name="org.apache.log4j.xml">
- <priority value="info" />
- </category>
- <Root>
- <priority value ="debug" />
- <appender-ref ref="STDOUT" />
- </Root>
-</log4j:configuration>]]></pre>
- <p>Log4j 2 XML configuration</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<Configuration>
- <Appenders>
- <Console name="STDOUT" target="SYSTEM_OUT">
- <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.log4j.xml" level="info"/>
- <Root level="debug">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-</Configuration>]]></pre>
-
- <h4>Sample 2 - Simple configuration using a File Appender, XMLLayout and SimpleLayout</h4>
- <p>Log4j 1.x XML configuration</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
-<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
- <appender name="A1" class="org.apache.log4j.FileAppender">
- <param name="File" value="A1.log" />
- <param name="Append" value="false" />
- <layout class="org.apache.log4j.xml.XMLLayout" />
- </appender>
- <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
- <layout class="org.apache.log4j.SimpleLayout" />
- </appender>
- <category name="org.apache.log4j.xml">
- <priority value="debug" />
- <appender-ref ref="A1" />
- </category>
- <root>
- <priority value ="debug" />
- <appender-ref ref="STDOUT" />
- </Root>
-</log4j:configuration>]]></pre>
-
- <p>Log4j 2 XML configuration</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<Configuration>
- <Appenders>
- <File name="A1" fileName="A1.log" append="false">
- <Log4j1XmlLayout />
- </File>
- <Console name="STDOUT" target="SYSTEM_OUT">
- <PatternLayout pattern="%level - %m%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.log4j.xml" level="debug">
- <AppenderRef ref="A1"/>
- </Logger>
- <Root level="debug">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-</Configuration>]]></pre>
-
- <h4>Sample 3 - SocketAppender</h4>
- <p>Log4j 1.x XML configuration. This example from Log4j 1.x is misleading. The SocketAppender does not
- actually use a Layout. Configuring one will have no effect.</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
-<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
- <appender name="A1" class="org.apache.log4j.net.SocketAppender">
- <param name="RemoteHost" value="localhost"/>
- <param name="Port" value="5000"/>
- <param name="LocationInfo" value="true"/>
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/>
- </layout>
- </appender>
- <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
- </layout>
- </appender>
- <category name="org.apache.log4j.xml">
- <priority value="debug"/>
- <appender-ref ref="A1"/>
- </category>
- <root>
- <priority value="debug"/>
- <appender-ref ref="STDOUT"/>
- </Root>
-</log4j:configuration>]]></pre>
-
- <p>Log4j 2 XML configuration</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<Configuration>
- <Appenders>
- <Socket name="A1" host="localHost" port="5000">
- <PatternLayout pattern="%t %-5p %c{2} - %m%n"/>
- </Socket>
- <Console name="STDOUT" target="SYSTEM_OUT">
- <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.log4j.xml" level="debug">
- <AppenderRef ref="A1"/>
- </Logger>
- <Root level="debug">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-</Configuration>]]></pre>
-
- <h4>Sample 4 - AsyncAppender and TTCCLayout</h4>
- <p>Log4j 1.x XML configuration using the AsyncAppender.</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
-<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true">
- <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
- <appender-ref ref="TEMP"/>
- </appender>
- <appender name="TEMP" class="org.apache.log4j.FileAppender">
- <param name="File" value="temp"/>
- <layout class="org.apache.log4j.TTCCLayout">
- <param name="ThreadPrinting" value="true"/>
- <param name="CategoryPrefixing" value="true"/>
- <param name="ContextPrinting" value="true"/>
- </layout>
- </appender>
- <root>
- <priority value="debug"/>
- <appender-ref ref="ASYNC"/>
- </Root>
-</log4j:configuration>]]></pre>
-
- <p>Log4j 2 XML configuration. </p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug">
- <Appenders>
- <File name="TEMP" fileName="temp">
- <PatternLayout pattern="%r [%t] %p %c %notEmpty{%ndc }- %m%n"/>
- </File>
- <Async name="ASYNC">
- <AppenderRef ref="TEMP"/>
- </Async>
- </Appenders>
- <Loggers>
- <Root level="debug">
- <AppenderRef ref="ASYNC"/>
- </Root>
- </Loggers>
-</Configuration>]]></pre>
-
-
- <h4>Sample 5 - AsyncAppender with Console and File</h4>
- <p>Log4j 1.x XML configuration using the AsyncAppender.</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
-<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true">
- <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
- <appender-ref ref="TEMP"/>
- <appender-ref ref="CONSOLE"/>
- </appender>
- <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
- </layout>
- </appender>
- <appender name="TEMP" class="org.apache.log4j.FileAppender">
- <param name="File" value="temp"/>
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
- </layout>
- </appender>
- <root>
- <priority value="debug"/>
- <appender-ref ref="ASYNC"/>
- </Root>
-</log4j:configuration>]]></pre>
-
- <p>Log4j 2 XML configuration. Note that the Async Appender should be configured after the appenders it
- references. This will allow it to shutdown properly.</p>
- <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug">
- <Appenders>
- <Console name="CONSOLE" target="SYSTEM_OUT">
- <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
- </Console>
- <File name="TEMP" fileName="temp">
- <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
- </File>
- <Async name="ASYNC">
- <AppenderRef ref="TEMP"/>
- <AppenderRef ref="CONSOLE"/>
- </Async>
- </Appenders>
- <Loggers>
- <Root level="debug">
- <AppenderRef ref="ASYNC"/>
- </Root>
- </Loggers>
-</Configuration>]]></pre>
- </subsection>
- </section>
- </body>
-</document>
[7/7] logging-log4j2 git commit: LOG4J2-1802: Convert programmatic
config manual page to asciidoc
Posted by ma...@apache.org.
LOG4J2-1802: Convert programmatic config 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/77a3712d
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/77a3712d
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/77a3712d
Branch: refs/heads/master
Commit: 77a3712df0364e73ae5aa7bbfaaab58c2f738efb
Parents: de9e42e
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 15:22:57 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 16:03:36 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/customconfig.adoc | 386 ++++++++++++++++++++++++
src/site/xdoc/manual/customconfig.xml | 375 -----------------------
2 files changed, 386 insertions(+), 375 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/77a3712d/src/site/asciidoc/manual/customconfig.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/customconfig.adoc b/src/site/asciidoc/manual/customconfig.adoc
new file mode 100644
index 0000000..7f4c9ea
--- /dev/null
+++ b/src/site/asciidoc/manual/customconfig.adoc
@@ -0,0 +1,386 @@
+////
+ 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.
+////
+= Programmatic Configuration
+Ralph Goers <rg...@apache.org>
+
+Log4j 2 provides a few ways for applications to create their own
+programmatic configuration:
+
+* Specify a custom `ConfigurationFactory` to start Log4j with a
+programmatic configuration
+* Use the `Configurator` to replace the configuration after Log4j started
+* Initialize Log4j with a combination of a configuration file and
+programmatic configuration
+* Modify the current `Configuration` after initialization
+
+[#ConfigurationBuilder]
+== The ConfigurationBuilder API
+
+Starting with release 2.4, Log4j provides a `ConfigurationBuilder` and a
+set of component builders that allow a `Configuration` to be created
+fairly easily. Actual configuration objects like `LoggerConfig` or
+`Appender` can be unwieldy; they require a lot of knowledge about Log4j
+internals which makes them difficult to work with if all you want is to
+create a `Configuration`.
+
+The new `ConfigurationBuilder` API (in the
+`org.apache.logging.log4j.core.config.builder.api` package) allows users
+to create Configurations in code by constructing component
+_definitions_. There is no need to work directly with actual
+configuration objects. Component definitions are added to the
+`ConfigurationBuilder`, and once all the definitions have been collected
+all the actual configuration objects (like Loggers and Appenders) are
+constructed.
+
+`ConfigurationBuilder` has convenience methods for the base components
+that can be configured such as Loggers, Appenders, Filter, Properties,
+etc. However, Log4j 2's plugin mechanism means that users can create any
+number of custom components. As a trade-off, the `ConfigurationBuilder`
+API provides only a limited number of "strongly typed" convenience
+methods like `newLogger()`, `newLayout()` etc. The generic
+`builder.newComponent()` method can be used if no convenience method
+exists for the component you want to configure.
+
+For example, the builder does not know what sub-components can be
+configured on specific components such as the RollingFileAppender vs.
+the RoutingAppender. To specify a triggering policy on a
+RollingFileAppender you would use builder.newComponent().
+
+Examples of using the `ConfigurationBuilder` API are in the sections that
+follow.
+
+[#ConfigurationFactory]
+== Understanding ConfigurationFactory
+
+During initialization, Log4j 2 will search for available
+link:extending.html#ConfigurationFactory[ConfigurationFactories] and
+then select the one to use. The selected `ConfigurationFactory` creates
+the `Configuration` that Log4j will use. Here is how Log4j finds the
+available ConfigurationFactories:
+
+1. A system property named `log4j2.configurationFactory` can be set
+with the name of the ConfigurationFactory to be used.
+2. `ConfigurationFactory.setConfigurationFactory(ConfigurationFactory)`
+can be called with the instance of the `ConfigurationFactory` to be used.
+This must be called before any other calls to Log4j.
+3. A `ConfigurationFactory` implementation can be added to the classpath
+and configured as a plugin in the "ConfigurationFactory" category. The
+`@Order` annotation can be used to specify the relative priority when
+multiple applicable ConfigurationFactories are found.
+
+ConfigurationFactories have the concept of "supported types", which
+basically maps to the file extension of the configuration file that the
+ConfigurationFactory can handle. If a configuration file location is
+specified, ConfigurationFactories whose supported type does not include
+"*" or the matching file extension will not be used.
+
+[#Example]
+== Initialize Log4j Using ConfigurationBuilder with a Custom ConfigurationFactory
+
+One way to programmatically configure Log4j 2 is to create a custom
+`ConfigurationFactory` that uses the
+link:#ConfigurationBuilder[`ConfigurationBuilder`] to create a
+Configuration. The below example overrides the `getConfiguration()`
+method to return a `Configuration` created by the `ConfigurationBuilder`.
+This will cause the `Configuration` to automatically be hooked into Log4j
+when the `LoggerContext` is created. In the example below, because it
+specifies a supported type of "*" it will override any configuration
+files provided.
+
+[source,java]
+----
+@Plugin(name = "CustomConfigurationFactory", category = ConfigurationFactory.CATEGORY)
+@Order(50)
+public class CustomConfigurationFactory extends ConfigurationFactory {
+
+ static Configuration createConfiguration(final String name, ConfigurationBuilder<BuiltConfiguration> builder) {
+ builder.setConfigurationName(name);
+ builder.setStatusLevel(Level.ERROR);
+ builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL).
+ addAttribute("level", Level.DEBUG));
+ AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").
+ addAttribute("target", ConsoleAppender.Target.SYSTEM_OUT);
+ appenderBuilder.add(builder.newLayout("PatternLayout").
+ addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
+ appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY,
+ Filter.Result.NEUTRAL).addAttribute("marker", "FLOW"));
+ builder.add(appenderBuilder);
+ builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG).
+ add(builder.newAppenderRef("Stdout")).
+ addAttribute("additivity", false));
+ builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout")));
+ return builder.build();
+ }
+
+ @Override
+ public Configuration getConfiguration(final LoggerContext loggerContext, final ConfigurationSource source) {
+ return getConfiguration(loggerContext, source.toString(), null);
+ }
+
+ @Override
+ public Configuration getConfiguration(final LoggerContext loggerContext, final String name, final URI configLocation) {
+ ConfigurationBuilder<BuiltConfiguration> builder = newConfigurationBuilder();
+ return createConfiguration(name, builder);
+ }
+
+ @Override
+ protected String[] getSupportedTypes() {
+ return new String[] {"*"};
+ }
+}
+----
+
+As of version 2.7, the `ConfigurationFactory.getConfiguration()` methods
+take an additional `LoggerContext` parameter.
+
+[#Configurator]
+== Reconfigure Log4j Using ConfigurationBuilder with the Configurator
+
+An alternative to a custom `ConfigurationFactory` is to configure with the
+`Configurator`. Once a `Configuration` object has been constructed, it can
+be passed to one of the `Configurator.initialize` methods to set up the
+Log4j configuration.
+
+Using the `Configurator` in this manner allows the application control
+over when Log4j is initialized. However, should any logging be attempted
+before `Configurator.initialize()` is called then the default
+configuration will be used for those log events.
+
+[source,java]
+----
+ConfigurationBuilder<BuiltConfiguration> builder = ConfigurationBuilderFactory.newConfigurationBuilder();
+builder.setStatusLevel(Level.ERROR);
+builder.setConfigurationName("BuilderTest");
+builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL)
+ .addAttribute("level", Level.DEBUG));
+AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target",
+ ConsoleAppender.Target.SYSTEM_OUT);
+appenderBuilder.add(builder.newLayout("PatternLayout")
+ .addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
+appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY, Filter.Result.NEUTRAL)
+ .addAttribute("marker", "FLOW"));
+builder.add(appenderBuilder);
+builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG)
+ .add(builder.newAppenderRef("Stdout")).addAttribute("additivity", false));
+builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout")));
+ctx = Configurator.initialize(builder.build());
+----
+
+This example shows how to create a configuration that includes a
+RollingFileAppender.
+
+[source,java]
+----
+ConfigurationBuilder<BuiltConfiguration> builder = ConfigurationBuilderFactory.newConfigurationBuilder();
+
+builder.setStatusLevel(Level.ERROR);
+builder.setConfigurationName("RollingBuilder");
+// create a console appender
+AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target",
+ ConsoleAppender.Target.SYSTEM_OUT);
+appenderBuilder.add(builder.newLayout("PatternLayout")
+ .addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
+builder.add(appenderBuilder);
+// create a rolling file appender
+LayoutComponentBuilder layoutBuilder = builder.newLayout("PatternLayout")
+ .addAttribute("pattern", "%d [%t] %-5level: %msg%n");
+ComponentBuilder triggeringPolicy = builder.newComponent("Policies")
+ .addComponent(builder.newComponent("CronTriggeringPolicy").addAttribute("schedule", "0 0 0 * * ?"))
+ .addComponent(builder.newComponent("SizeBasedTriggeringPolicy").addAttribute("size", "100M"));
+appenderBuilder = builder.newAppender("rolling", "RollingFile")
+ .addAttribute("fileName", "target/rolling.log")
+ .addAttribute("filePattern", "target/archive/rolling-%d{MM-dd-yy}.log.gz")
+ .add(layoutBuilder)
+ .addComponent(triggeringPolicy);
+builder.add(appenderBuilder);
+
+// create the new logger
+builder.add(builder.newLogger("TestLogger", Level.DEBUG)
+ .add(builder.newAppenderRef("rolling"))
+ .addAttribute("additivity", false));
+
+builder.add(builder.newRootLogger(Level.DEBUG)
+ .add(builder.newAppenderRef("rolling")));
+LoggerContext ctx = Configurator.initialize(builder.build());
+----
+
+[#Hybrid]
+== Initialize Log4j by Combining Configuration File with Programmatic Configuration
+
+Sometimes you want to configure with a configuration file but do some
+additional programmatic configuration. A possible use case might be that
+you want to allow for a flexible configuration using XML but at the same
+time make sure there are a few configuration elements that are always
+present that can't be removed.
+
+The easiest way to achieve this is to extend one of the standard
+`Configuration` classes (`XMLConfiguration`, `JSONConfiguration`) and then
+create a new `ConfigurationFactory` for the extended class. After the
+standard configuration completes the custom configuration can be added
+to it.
+
+The example below shows how to extend `XMLConfiguration` to manually add
+an `Appender` and a `LoggerConfig` to the configuration.
+
+[source,java]
+----
+@Plugin(name = "MyXMLConfigurationFactory", category = "ConfigurationFactory")
+@Order(10)
+public class MyXMLConfigurationFactory extends ConfigurationFactory {
+
+ /**
+ * Valid file extensions for XML files.
+ */
+ public static final String[] SUFFIXES = new String[] {".xml", "*"};
+
+ /**
+ * Return the Configuration.
+ * @param source The InputSource.
+ * @return The Configuration.
+ */
+ public Configuration getConfiguration(InputSource source) {
+ return new MyXMLConfiguration(source, configFile);
+ }
+
+ /**
+ * Returns the file suffixes for XML files.
+ * @return An array of File extensions.
+ */
+ public String[] getSupportedTypes() {
+ return SUFFIXES;
+ }
+}
+
+public class MyXMLConfiguration extends XMLConfiguration {
+ public MyXMLConfiguration(final ConfigurationFactory.ConfigurationSource configSource) {
+ super(configSource);
+ }
+
+ @Override
+ protected void doConfigure() {
+ super.doConfigure();
+ final LoggerContext ctx = (LoggerContext) LogManager.getContext(false);
+ final Layout layout = PatternLayout.createLayout(PatternLayout.SIMPLE_CONVERSION_PATTERN, config, null,
+ null,null, null);
+ final Appender appender = FileAppender.createAppender("target/test.log", "false", "false", "File", "true",
+ "false", "false", "4000", layout, null, "false", null, config);
+ appender.start();
+ addAppender(appender);
+ LoggerConfig loggerConfig = LoggerConfig.createLogger("false", "info", "org.apache.logging.log4j",
+ "true", refs, null, config, null );
+ loggerConfig.addAppender(appender, null, null);
+ addLogger("org.apache.logging.log4j", loggerConfig);
+ }
+}
+----
+
+[#AddingToCurrent]
+== Programmatically Modifying the Current Configuration after Initialization
+
+Applications sometimes have the need to customize logging separate from
+the actual configuration. Log4j allows this although it suffers from a
+few limitations:
+
+1. If the configuration file is changed the configuration will be
+reloaded and the manual changes will be lost.
+2. Modification to the running configuration requires that all the
+methods being called (addAppender and addLogger) be synchronized.
+
+As such, the recommended approach for customizing a configuration is to
+extend one of the standard Configuration classes, override the setup
+method to first do super.setup() and then add the custom Appenders,
+Filters and LoggerConfigs to the configuration before it is registered
+for use.
+
+The following example adds an Appender and a new LoggerConfig using that
+Appender to the current configuration.
+
+//TODO: update code example below with new plugin API
+[source,java]
+----
+ final LoggerContext ctx = (LoggerContext) LogManager.getContext(false);
+ final Configuration config = ctx.getConfiguration();
+ Layout layout = PatternLayout.createLayout(PatternLayout.SIMPLE_CONVERSION_PATTERN, config, null,
+ null,null, null);
+ Appender appender = FileAppender.createAppender("target/test.log", "false", "false", "File", "true",
+ "false", "false", "4000", layout, null, "false", null, config);
+ appender.start();
+ config.addAppender(appender);
+ AppenderRef ref = AppenderRef.createAppenderRef("File", null, null);
+ AppenderRef[] refs = new AppenderRef[] {ref};
+ LoggerConfig loggerConfig = LoggerConfig.createLogger("false", "info", "org.apache.logging.log4j",
+ "true", refs, null, config, null );
+ loggerConfig.addAppender(appender, null, null);
+ config.addLogger("org.apache.logging.log4j", loggerConfig);
+ ctx.updateLoggers();
+}
+----
+
+[#AppendingToWritersAndOutputStreams]
+== Appending Log Events to Writers and OutputStreams Programmatically
+
+Log4j 2.5 provides facilities to append log events to Writers and
+OutputStreams. For example, this provides simple integration for JDBC
+Driver implementors that use Log4j internally and still want to support
+the JDBC APIs `CommonDataSource.setLogWriter(PrintWriter)`,
+`java.sql.DriverManager.setLogWriter(PrintWriter)`, and
+`java.sql.DriverManager.setLogStream(PrintStream)`.
+
+Given any `Writer`, like a `PrintWriter`, you tell Log4j to append
+events to that writer by creating a `WriterAppender` and updating the
+Log4j configuration:
+
+[source,java]
+----
+void addAppender(final Writer writer, final String writerName) {
+ final LoggerContext context = LoggerContext.getContext(false);
+ final Configuration config = context.getConfiguration();
+ final PatternLayout layout = PatternLayout.createDefaultLayout(config);
+ final Appender appender = WriterAppender.createAppender(layout, null, writer, writerName, false, true);
+ appender.start();
+ config.addAppender(appender);
+ updateLoggers(appender, config);
+}
+
+private void updateLoggers(final Appender appender, final Configuration config) {
+ final Level level = null;
+ final Filter filter = null;
+ for (final LoggerConfig loggerConfig : config.getLoggers().values()) {
+ loggerConfig.addAppender(appender, level, filter);
+ }
+ config.getRootLogger().addAppender(appender, level, filter);
+}
+----
+
+You can achieve the same effect with an `OutputStream`, like a
+`PrintStream`:
+
+[source,java]
+----
+void addAppender(final OutputStream outputStream, final String outputStreamName) {
+ final LoggerContext context = LoggerContext.getContext(false);
+ final Configuration config = context.getConfiguration();
+ final PatternLayout layout = PatternLayout.createDefaultLayout(config);
+ final Appender appender = OutputStreamAppender.createAppender(layout, null, outputStream, outputStreamName, false, true);
+ appender.start();
+ config.addAppender(appender);
+ updateLoggers(appender, config);
+}
+----
+
+The difference is the use of `OutputStreamAppender` instead of
+`WriterAppender`.
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/77a3712d/src/site/xdoc/manual/customconfig.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/customconfig.xml b/src/site/xdoc/manual/customconfig.xml
deleted file mode 100644
index e57af39..0000000
--- a/src/site/xdoc/manual/customconfig.xml
+++ /dev/null
@@ -1,375 +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>Extending Log4j 2 Configuration</title>
- <author email="rgoers@apache.org">Ralph Goers</author>
- </properties>
-
- <body>
- <section name="Programmatic Configuration">
- <p>
- Log4j 2 provides a few ways for applications to create their own programmatic configuration:
- </p>
- <ul>
- <li>Specify a custom ConfigurationFactory to start Log4j with a programmatic configuration</li>
- <li>Use the Configurator to replace the configuration after Log4j started</li>
- <li>Initialize Log4j with a combination of a configuration file and programmatic configuration</li>
- <li>Modify the current Configuration after initialization</li>
- </ul>
- <a name="ConfigurationBuilder"/>
- <subsection name="The ConfigurationBuilder API">
- <p>
- Starting with release 2.4, Log4j provides a ConfigurationBuilder and a set of component builders that
- allow a Configuration to be created fairly easily.
- Actual configuration objects like LoggerConfig or Appender can be unwieldy; they require a lot
- of knowledge about Log4j internals which makes them difficult to work with if all you want is to
- create a Configuration.
- </p>
- <p>
- The new ConfigurationBuilder API (in the <code>org.apache.logging.log4j.core.config.builder.api</code> package)
- allows users to create Configurations in code by constructing component <i>definitions</i>.
- There is no need to work directly with actual configuration objects.
- Component definitions are added to the ConfigurationBuilder, and once all the definitions have
- been collected all the actual configuration objects (like Loggers and Appenders) are constructed.
- </p>
- <p>
- ConfigurationBuilder has convenience methods for the base components that can be configured such as
- Loggers, Appenders, Filter, Properties, etc.
- However, Log4j 2's plugin mechanism means that users can create any number of custom components.
- As a trade-off, the ConfigurationBuilder API provides only a limited number of "strongly typed"
- convenience methods like <code>newLogger()</code>, <code>newLayout()</code> etc.
- The generic <code>builder.newComponent()</code> method can be used if no convenience method exists
- for the component you want to configure.
- </p>
- <p>
- For example, the builder does not know what sub-components can be configured on specific components
- such as the RollingFileAppender vs. the RoutingAppender. To specify a triggering policy on a
- RollingFileAppender you would use builder.newComponent().
- </p>
- <p>
- Examples of using the ConfigurationBuilder API are in the sections that follow.
- </p>
- </subsection>
- <a name="ConfigurationFactory"/>
- <subsection name="Understanding ConfigurationFactory">
- <p>
- During initialization, Log4j 2 will search for available <a href="extending.html#ConfigurationFactory">ConfigurationFactories</a>
- and then select the one to use. The
- selected ConfigurationFactory creates the Configuration that Log4j will use. Here is how Log4j finds
- the available ConfigurationFactories:
- </p>
- <ol>
- <li>A system property named <tt>log4j2.configurationFactory</tt> can be set with the name of the ConfigurationFactory to be used.</li>
- <li><code>ConfigurationFactory.setConfigurationFactory(ConfigurationFactory)</code> can be called with the instance of the
- ConfigurationFactory to be used. This must be called before any other calls to Log4j.</li>
- <li>A ConfigurationFactory implementation can be added to the classpath and configured as a plugin
- in the "ConfigurationFactory" category.
- The Order annotation can be used to specify the relative priority when multiple applicable
- ConfigurationFactories are found.</li>
- </ol>
- <p>
- ConfigurationFactories have the concept of "supported types", which basically maps to the
- file extension of the configuration file that the ConfigurationFactory can handle.
- If a configuration file location is specified, ConfigurationFactories whose supported type
- does not include "*" or the matching file extension will not be used.
- </p>
- </subsection>
- <a name="Example"/>
- <subsection name="Initialize Log4j Using ConfigurationBuilder with a Custom ConfigurationFactory">
- <p>
- One way to programmatically configure Log4j 2 is to create a custom ConfigurationFactory
- that uses the <a href="#ConfigurationBuilder">ConfigurationBuilder</a> to create a Configuration.
- The below example overrides the <code>getConfiguration()</code> method to return a
- Configuration created by the ConfigurationBuilder.
- This will cause the Configuration to automatically be hooked into Log4j when the LoggerContext is created.
- In the example below, because it specifies a supported type of "*" it will override any configuration files provided.
- </p>
- <pre class="prettyprint linenum"><![CDATA[
-@Plugin(name = "CustomConfigurationFactory", category = ConfigurationFactory.CATEGORY)
-@Order(50)
-public class CustomConfigurationFactory extends ConfigurationFactory {
-
- static Configuration createConfiguration(final String name, ConfigurationBuilder<BuiltConfiguration> builder) {
- builder.setConfigurationName(name);
- builder.setStatusLevel(Level.ERROR);
- builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL).
- addAttribute("level", Level.DEBUG));
- AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").
- addAttribute("target", ConsoleAppender.Target.SYSTEM_OUT);
- appenderBuilder.add(builder.newLayout("PatternLayout").
- addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
- appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY,
- Filter.Result.NEUTRAL).addAttribute("marker", "FLOW"));
- builder.add(appenderBuilder);
- builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG).
- add(builder.newAppenderRef("Stdout")).
- addAttribute("additivity", false));
- builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout")));
- return builder.build();
- }
-
- @Override
- public Configuration getConfiguration(final LoggerContext loggerContext, final ConfigurationSource source) {
- return getConfiguration(loggerContext, source.toString(), null);
- }
-
- @Override
- public Configuration getConfiguration(final LoggerContext loggerContext, final String name, final URI configLocation) {
- ConfigurationBuilder<BuiltConfiguration> builder = newConfigurationBuilder();
- return createConfiguration(name, builder);
- }
-
- @Override
- protected String[] getSupportedTypes() {
- return new String[] {"*"};
- }
-}]]></pre>
- <p>
- As of version 2.7, the <code>ConfigurationFactory.getConfiguration()</code> methods take an
- additional <code>LoggerContext</code> parameter.
- </p>
- </subsection>
- <a name="Configurator"/>
- <subsection name="Reconfigure Log4j Using ConfigurationBuilder with the Configurator">
- <p>
- An alternative to a custom ConfigurationFactory is to configure with the <code>Configurator</code>.
- Once a Configuration object has been constructed, it can be passed to one of the
- <code>Configurator.initialize</code> methods to set up the Log4j configuration.
- </p>
- <p>
- Using the Configurator in this manner allows the application control over when Log4j is initialized.
- However, should any logging be attempted before Configurator.initialize() is called then the
- default configuration will be used for those log events.
- </p>
- <pre class="prettyprint linenum"><![CDATA[
-ConfigurationBuilder<BuiltConfiguration> builder = ConfigurationBuilderFactory.newConfigurationBuilder();
-builder.setStatusLevel(Level.ERROR);
-builder.setConfigurationName("BuilderTest");
-builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL)
- .addAttribute("level", Level.DEBUG));
-AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target",
- ConsoleAppender.Target.SYSTEM_OUT);
-appenderBuilder.add(builder.newLayout("PatternLayout")
- .addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
-appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY, Filter.Result.NEUTRAL)
- .addAttribute("marker", "FLOW"));
-builder.add(appenderBuilder);
-builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG)
- .add(builder.newAppenderRef("Stdout")).addAttribute("additivity", false));
-builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout")));
-ctx = Configurator.initialize(builder.build());
-]]></pre>
- <p>This example shows how to create a configuration that includes a RollingFileAppender.</p>
- <pre class="prettyprint linenum"><![CDATA[
-ConfigurationBuilder< BuiltConfiguration > builder = ConfigurationBuilderFactory.newConfigurationBuilder();
-
-builder.setStatusLevel( Level.ERROR);
-builder.setConfigurationName("RollingBuilder");
-// create a console appender
-AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target",
- ConsoleAppender.Target.SYSTEM_OUT);
-appenderBuilder.add(builder.newLayout("PatternLayout")
- .addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
-builder.add( appenderBuilder );
-// create a rolling file appender
-LayoutComponentBuilder layoutBuilder = builder.newLayout("PatternLayout")
- .addAttribute("pattern", "%d [%t] %-5level: %msg%n");
-ComponentBuilder triggeringPolicy = builder.newComponent("Policies")
- .addComponent(builder.newComponent("CronTriggeringPolicy").addAttribute("schedule", "0 0 0 * * ?"))
- .addComponent(builder.newComponent("SizeBasedTriggeringPolicy").addAttribute("size", "100M"));
-appenderBuilder = builder.newAppender("rolling", "RollingFile")
- .addAttribute("fileName", "target/rolling.log")
- .addAttribute("filePattern", "target/archive/rolling-%d{MM-dd-yy}.log.gz")
- .add(layoutBuilder)
- .addComponent(triggeringPolicy);
-builder.add(appenderBuilder);
-
-// create the new logger
-builder.add( builder.newLogger( "TestLogger", Level.DEBUG )
- .add( builder.newAppenderRef( "rolling" ) )
- .addAttribute( "additivity", false ) );
-
-builder.add( builder.newRootLogger( Level.DEBUG )
- .add( builder.newAppenderRef( "rolling" ) ) );
-LoggerContext ctx = Configurator.initialize(builder.build());
-]]></pre>
- </subsection>
-
- <a name="Hybrid"/>
- <subsection name="Initialize Log4j by Combining Configuration File with Programmatic Configuration">
- <p>
- Sometimes you want to configure with a configuration file but do some additional programmatic
- configuration. A possible use case might be that you want to allow for a flexible configuration using XML
- but at the same time make sure there are a few configuration elements that are always present that can't be removed.
- </p>
- <p>
- The easiest way to achieve this is to extend one of the standard Configuration classes
- (XMLConfiguration, JSONConfiguration) and then create a new ConfigurationFactory for the extended class.
- After the standard configuration completes the custom configuration can be added to it.
- </p>
- <p>
- The example below shows how to extend XMLConfiguration to manually add an Appender and a LoggerConfig
- to the configuration.
- </p>
- <pre class="prettyprint linenums">
-@Plugin(name = "MyXMLConfigurationFactory", category = "ConfigurationFactory")
-@Order(10)
-public class MyXMLConfigurationFactory extends ConfigurationFactory {
-
- /**
- * Valid file extensions for XML files.
- */
- public static final String[] SUFFIXES = new String[] {".xml", "*"};
-
- /**
- * Return the Configuration.
- * @param source The InputSource.
- * @return The Configuration.
- */
- public Configuration getConfiguration(InputSource source) {
- return new MyXMLConfiguration(source, configFile);
- }
-
- /**
- * Returns the file suffixes for XML files.
- * @return An array of File extensions.
- */
- public String[] getSupportedTypes() {
- return SUFFIXES;
- }
-}
-
-public class MyXMLConfiguration extends XMLConfiguration {
- public MyXMLConfiguration(final ConfigurationFactory.ConfigurationSource configSource) {
- super(configSource);
- }
-
- @Override
- protected void doConfigure() {
- super.doConfigure();
- final LoggerContext ctx = (LoggerContext) LogManager.getContext(false);
- final Layout layout = PatternLayout.createLayout(PatternLayout.SIMPLE_CONVERSION_PATTERN, config, null,
- null,null, null);
- final Appender appender = FileAppender.createAppender("target/test.log", "false", "false", "File", "true",
- "false", "false", "4000", layout, null, "false", null, config);
- appender.start();
- addAppender(appender);
- LoggerConfig loggerConfig = LoggerConfig.createLogger("false", "info", "org.apache.logging.log4j",
- "true", refs, null, config, null );
- loggerConfig.addAppender(appender, null, null);
- addLogger("org.apache.logging.log4j", loggerConfig);
- }
-}</pre>
- </subsection>
- <a name="AddingToCurrent"/>
- <subsection name="Programmatically Modifying the Current Configuration after Initialization">
- <p>
- Applications sometimes have the need to customize logging separate from the actual configuration.
- Log4j allows this although it suffers from a few limitations:
- </p>
- <ol>
- <li>If the configuration file is changed the configuration will be reloaded and the manual changes
- will be lost.</li>
- <li>Modification to the running configuration requires that all the methods being called (addAppender
- and addLogger) be synchronized.</li>
- </ol>
- <p>
- As such, the recommended approach for customizing a configuration is to extend one of the standard
- Configuration classes, override the setup method to first do super.setup() and then add the custom
- Appenders, Filters and LoggerConfigs to the configuration before it is registered for use.
- </p>
- <p>
- The following example adds an Appender and a new LoggerConfig using that Appender to the current
- configuration.
- </p>
- <!-- TODO: update code example below with new plugin API -->
- <pre class="prettyprint linenums"><![CDATA[
- final LoggerContext ctx = (LoggerContext) LogManager.getContext(false);
- final Configuration config = ctx.getConfiguration();
- Layout layout = PatternLayout.createLayout(PatternLayout.SIMPLE_CONVERSION_PATTERN, config, null,
- null,null, null);
- Appender appender = FileAppender.createAppender("target/test.log", "false", "false", "File", "true",
- "false", "false", "4000", layout, null, "false", null, config);
- appender.start();
- config.addAppender(appender);
- AppenderRef ref = AppenderRef.createAppenderRef("File", null, null);
- AppenderRef[] refs = new AppenderRef[] {ref};
- LoggerConfig loggerConfig = LoggerConfig.createLogger("false", "info", "org.apache.logging.log4j",
- "true", refs, null, config, null );
- loggerConfig.addAppender(appender, null, null);
- config.addLogger("org.apache.logging.log4j", loggerConfig);
- ctx.updateLoggers();
-}]]></pre>
- </subsection>
- <a name="AppendingToWritersAndOutputStreams"/>
- <subsection name="Appending Log Events to Writers and OutputStreams Programmatically">
- <p>
- Log4j 2.5 provides facilities to append log events to Writers and OutputStreams. For example, this
- provides simple integration for JDBC Driver implementors that use Log4j internally and still want
- to support the JDBC APIs <code>CommonDataSource.setLogWriter(PrintWriter)</code>,
- <code>java.sql.DriverManager.setLogWriter(PrintWriter)</code>, and
- <code>java.sql.DriverManager.setLogStream(PrintStream)</code>.
- </p>
- <p>
- Given any <code>Writer</code>, like a <code>PrintWriter</code>, you tell Log4j to append events to
- that writer by creating a <code>WriterAppender</code> and updating the Log4j configuration:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-void addAppender(final Writer writer, final String writerName) {
- final LoggerContext context = LoggerContext.getContext(false);
- final Configuration config = context.getConfiguration();
- final PatternLayout layout = PatternLayout.createDefaultLayout(config);
- final Appender appender = WriterAppender.createAppender(layout, null, writer, writerName, false, true);
- appender.start();
- config.addAppender(appender);
- updateLoggers(appender, config);
-}
-
-private void updateLoggers(final Appender appender, final Configuration config) {
- final Level level = null;
- final Filter filter = null;
- for (final LoggerConfig loggerConfig : config.getLoggers().values()) {
- loggerConfig.addAppender(appender, level, filter);
- }
- config.getRootLogger().addAppender(appender, level, filter);
-}]]></pre>
- <p>
- You can achieve the same effect with an <code>OutputStream</code>, like a <code>PrintStream</code>:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-void addAppender(final OutputStream outputStream, final String outputStreamName) {
- final LoggerContext context = LoggerContext.getContext(false);
- final Configuration config = context.getConfiguration();
- final PatternLayout layout = PatternLayout.createDefaultLayout(config);
- final Appender appender = OutputStreamAppender.createAppender(layout, null, outputStream, outputStreamName, false, true);
- appender.start();
- config.addAppender(appender);
- updateLoggers(appender, config);
-}]]></pre>
- </subsection>
- <p>
- The difference is the use of <code>OutputStreamAppender</code> instead of <code>WriterAppender</code>.
- </p>
- </section>
-
- </body>
-</document>
[5/7] logging-log4j2 git commit: Fix table headers and table display
Posted by ma...@apache.org.
Fix table headers and table display
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/de9e42e6
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/de9e42e6
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/de9e42e6
Branch: refs/heads/master
Commit: de9e42e6aa956101c5bc21630d87a051bc0d8795
Parents: a6744a6
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 15:09:04 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 16:03:36 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/faq.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/de9e42e6/src/site/asciidoc/faq.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/faq.adoc b/src/site/asciidoc/faq.adoc
index d9a4629..71278a5 100644
--- a/src/site/asciidoc/faq.adoc
+++ b/src/site/asciidoc/faq.adoc
@@ -59,7 +59,7 @@ shows for each Log4j dependency on the left (implicit groupId of
`org.apache.logging.log4j`), the following dependencies on the right can
be safely excluded (given in the format `groupId:artifactId`).
-[cols="4*"]
+[cols="4*m",options="header"]
|===
|Log4j Dependency
3+|Dependencies to Exclude