You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rg...@apache.org on 2018/08/04 06:14:41 UTC
logging-log4j2 git commit: Fix download page. Add usage page
Repository: logging-log4j2
Updated Branches:
refs/heads/log4j-2.11.1-patches [created] 921082a28
Fix download page. Add usage page
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/921082a2
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/921082a2
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/921082a2
Branch: refs/heads/log4j-2.11.1-patches
Commit: 921082a28c4197dcd4403a28cab0d0f079df87dd
Parents: 51f61ad
Author: Ralph Goers <rg...@apache.org>
Authored: Fri Aug 3 23:13:29 2018 -0700
Committer: Ralph Goers <rg...@apache.org>
Committed: Fri Aug 3 23:13:29 2018 -0700
----------------------------------------------------------------------
src/site/markdown/download.md.vm | 20 +--
src/site/site.xml | 5 +
src/site/xdoc/manual/usage.xml | 262 ++++++++++++++++++++++++++++++++++
3 files changed, 277 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/921082a2/src/site/markdown/download.md.vm
----------------------------------------------------------------------
diff --git a/src/site/markdown/download.md.vm b/src/site/markdown/download.md.vm
index 3ed0fe6..2c3d0cb 100644
--- a/src/site/markdown/download.md.vm
+++ b/src/site/markdown/download.md.vm
@@ -28,25 +28,25 @@ the originals on the main distribution server.
| Distribution | Mirrors | Checksum | Signature |
| ------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------- |
-| Apache Log4j 2 binary (tar.gz) | [apache-log4j-${Log4jReleaseVersion}-bin.tar.gz][bintar] | [apache-log4j-${Log4jReleaseVersion}-bin.tar.gz.md5][bintarmd5] | [apache-log4j-${Log4jReleaseVersion}-bin.tar.gz.asc][bintarasc] |
-| Apache Log4j 2 binary (zip) | [apache-log4j-${Log4jReleaseVersion}-bin.zip][binzip] | [apache-log4j-${Log4jReleaseVersion}-bin.zip.md5][binzipmd5] | [apache-log4j-${Log4jReleaseVersion}-bin.zip.asc][binzipasc] |
-| Apache Log4j 2 source (tar.gz) | [apache-log4j-${Log4jReleaseVersion}-src.tar.gz][srctar] | [apache-log4j-${Log4jReleaseVersion}-src.tar.gz.md5][srctarmd5] | [apache-log4j-${Log4jReleaseVersion}-src.tar.gz.asc][srctarasc] |
-| Apache Log4j 2 source (zip) | [apache-log4j-${Log4jReleaseVersion}-src.zip][srczip] | [apache-log4j-${Log4jReleaseVersion}-src.zip.md5][srczipmd5] | [apache-log4j-${Log4jReleaseVersion}-src.zip.asc][srczipasc] |
+| Apache Log4j 2 binary (tar.gz) | [apache-log4j-${Log4jReleaseVersion}-bin.tar.gz][bintar] | [apache-log4j-${Log4jReleaseVersion}-bin.tar.gz.sha1][bintarsha1] | [apache-log4j-${Log4jReleaseVersion}-bin.tar.gz.asc][bintarasc] |
+| Apache Log4j 2 binary (zip) | [apache-log4j-${Log4jReleaseVersion}-bin.zip][binzip] | [apache-log4j-${Log4jReleaseVersion}-bin.zip.sha1][binzipsha1] | [apache-log4j-${Log4jReleaseVersion}-bin.zip.asc][binzipasc] |
+| Apache Log4j 2 source (tar.gz) | [apache-log4j-${Log4jReleaseVersion}-src.tar.gz][srctar] | [apache-log4j-${Log4jReleaseVersion}-src.tar.gz.sha1][srctarsha1] | [apache-log4j-${Log4jReleaseVersion}-src.tar.gz.asc][srctarasc] |
+| Apache Log4j 2 source (zip) | [apache-log4j-${Log4jReleaseVersion}-src.zip][srczip] | [apache-log4j-${Log4jReleaseVersion}-src.zip.sha1][srczipsha1] | [apache-log4j-${Log4jReleaseVersion}-src.zip.asc][srczipasc] |
[bintar]: https://www.apache.org/dyn/closer.lua/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-bin.tar.gz
-[bintarmd5]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-bin.tar.gz.md5
+[bintarsha1]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-bin.tar.gz.sha1
[bintarasc]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-bin.tar.gz.asc
[binzip]: https://www.apache.org/dyn/closer.lua/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-bin.zip
-[binzipmd5]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-bin.zip.md5
+[binzipsha1]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-bin.zip.sha1
[binzipasc]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-bin.zip.asc
[srctar]: https://www.apache.org/dyn/closer.lua/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-src.tar.gz
-[srctarmd5]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-src.tar.gz.md5
+[srctarsha1]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-src.tar.gz.sha1
[srctarasc]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-src.tar.gz.asc
[srczip]: https://www.apache.org/dyn/closer.lua/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-src.zip
-[srczipmd5]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-src.zip.md5
+[srczipsha1]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-src.zip.sha1
[srczipasc]: https://www.apache.org/dist/logging/log4j/${Log4jReleaseVersion}/apache-log4j-${Log4jReleaseVersion}-src.zip.asc
-It is essential that you verify the integrity of the downloaded files using the PGP or MD5 signatures.
+It is essential that you verify the integrity of the downloaded files using the PGP and SHA1 signatures.
Please read [Verifying Apache HTTP Server Releases](https://httpd.apache.org/dev/verification.html) for more
information on why you should verify our releases.
@@ -60,7 +60,7 @@ than from a mirror. Then verify the signatures using
Apache Log4j ${Log4jReleaseVersion} is signed by ${Log4jReleaseManager} (${Log4jReleaseKey})
-Alternatively, you can verify the MD5 signature on the files. A unix program called md5 or md5sum is included
+Alternatively, you can verify the SHA1 signature on the files. A unix program called sha or shasum is included
in many unix distributions.
$h2 Previous Releases
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/921082a2/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index baacec5..1a49332 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -108,6 +108,11 @@
<item name="System Properties" href="/manual/configuration.html#SystemProperties"/>
</item>
+ <item name="Usage" href="/manual/usage.html" collapse="true">
+ <item name="Static vs non-Static Loggers" href="/manual/usage.html#StaticVsNonStatic"/>
+ <item name="Logger Name vs Class Name" href="/manual/usage.html#LoggerVsClass"/>
+ </item>
+
<item name="Web Applications and JSPs" href="/manual/webapp.html" collapse="true">
<item name="Servlet 3.0 and Newer" href="/manual/webapp.html#Servlet-3.0" />
<item name="Servlet 2.5" href="/manual/webapp.html#Servlet-2.5" />
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/921082a2/src/site/xdoc/manual/usage.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/usage.xml b/src/site/xdoc/manual/usage.xml
new file mode 100644
index 0000000..2a09478
--- /dev/null
+++ b/src/site/xdoc/manual/usage.xml
@@ -0,0 +1,262 @@
+<?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 Architecture</title>
+ <author email="rgoers@apache.org">Ralph Goers</author>
+ </properties>
+
+ <body>
+ <section name="Usage">
+ <a name="StaticVsNonStatic"/>
+ <subsection name="Static vs Non-Static Loggers">
+ <p>As with any variable in Java, Loggers may be declared as static variables or class member variables. However,
+ there are a few factors to consider when choosing to delare a logger as static vs non-static. Generally, it
+ is better to declare Loggers as static.
+ <ol>
+ <li>
+ Instantiation of a new Logger is a fairly expensive operation when using the default ContextSelector,
+ <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.html">ClassLoaderContextSelector</a>.
+ When the Logger is created the <code>ClassLoaderContextSelector</code> will locate the ClassLoader for the Class the Logger
+ is associated with and add the Logger to the LoggerContext associated with that ClassLoader.
+ </li>
+ <li>
+ Once a Logger is created it will not be deleted until the <code>LoggerContext</code> it is associated with
+ is deleted. Typically, this will only happen when the application is shut down or un-deployed. Each call
+ to getLogger with the same logger name will return the same Logger instance. Thus, there is very little
+ difference between a static or non-static Logger.
+ </li>
+ <li>
+ There is no behavioral difference between a static and non-static Logger. Both will have the Logger name
+ assigned when they are created, which usually will be the name of the class they are associated with. See
+ the discussion below on logger names vs class names and the example for more information.
+ </li>
+ </ol>
+ </p>
+ </subsection>
+ <a name="LoggerVsClass"/>
+ <subsection name="Logging the Logger name vs the Class name">
+ <p>
+ The logger name of a Logger is specified when the Logger is created. When a log method is called the
+ class name value in the log event will reflect the name of the class the log method was called from, which is
+ not necessarily the same as the class that created the Logger. The following example illustrations this.
+ </p>
+
+ <p>The base class creates a static Logger and a logger variable that is initialized as that same Logger.
+ It has two methods that perform logging, once that uses the static logger and one that uses a Logger that
+ can be overridden.
+ </p>
+
+
+<pre class="prettyprint">
+ package org.apache.logging;
+
+ import org.apache.logging.log4j.LogManager;
+ import org.apache.logging.log4j.Logger;
+ import org.apache.logging.log4j.Marker;
+
+ /**
+ *
+ */
+ public abstract class MySuperClass {
+
+ // The name of this Logger will be "org.apache.logging.MySuperClass"
+ protected static final Logger LOGGER = LogManager.getLogger();
+
+ private Logger logger = LOGGER;
+
+ protected Logger getLogger() {
+ return logger;
+ }
+
+ protected void setLogger(Logger logger) {
+ this.logger = logger;
+ }
+
+
+ protected void demoLog(Marker marker) {
+ logger.debug(marker,"MySuperClass log message");
+ }
+ }
+</pre>
+
+ <p>
+ This class extends the base class. It provides its own logger and has two methods, one that uses the
+ logger in this class and one that uses the static logger from the base class.
+ </p>
+
+<pre class="prettyprint">
+ package org.apache.logging;
+
+ import org.apache.logging.log4j.LogManager;
+ import org.apache.logging.log4j.Logger;
+ import org.apache.logging.log4j.Marker;
+
+ /**
+ *
+ */
+ public class MyClass extends MySuperClass {
+
+ // The name of this Logge will be "org.apache.logging.MyClass"
+ public Logger logger = LogManager.getLogger();
+
+ public void log1(Marker marker) {
+ logger.debug(marker,"MyClass logger message");
+ }
+
+ public void log2(Marker marker) {
+ LOGGER.debug(marker,"MySuperClass logger message from MyClass");
+ }
+ }
+</pre>
+ <p>
+ The application exercises all the logging methods four times. The first two times the Logger in the base
+ class is set to the static Logger. The second two times the Logger in the base class is set to use the
+ Logger in the subclass. In the first and third invocation of each method a null Marker is passed. In the
+ second and fourth a Marker named "CLASS" is passed.
+ </p>
+
+<pre class="prettyprint">
+ package org.apache.logging;
+
+ import org.apache.logging.log4j.Marker;
+ import org.apache.logging.log4j.MarkerManager;
+
+ public class App {
+
+ public static void main( String[] args ) {
+ Marker marker = MarkerManager.getMarker("CLASS");
+ MyClass myclass = new MyClass();
+
+ System.out.println("------- MySuperClass Logger ----------");
+ myclass.demoLog(null);
+ myclass.demoLog(marker);
+ myclass.log1(null);
+ myclass.log1(marker);
+ myclass.log2(null);
+ myclass.log2(marker);
+
+ myclass.setLogger(myclass.logger);
+
+ System.out.println("------- MySuperClass Logger set to MyClass Logger ----------");
+ myclass.demoLog(null);
+ myclass.demoLog(marker);
+ myclass.log1(null);
+ myclass.log1(marker);
+ myclass.log2(null);
+ myclass.log2(marker);
+ }
+ }</pre>
+
+ <p>
+ The configuration takes advantage of Log4j's ability to select a pattern based upon attributes of the log event.
+ In this case %C, the class name pattern, is used when the CLASS Marker is present, and %c, the logger name
+ is used when the CLASS marker is not present.
+ </p>
+<pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+ <Appenders>
+ <Console name="Console" target="SYSTEM_OUT">
+ <PatternLayout>
+ <MarkerPatternSelector defaultPattern="%sn. Logger name %c %msg%n">
+ <PatternMatch key="CLASS" pattern="%sn. Class name %C %msg%n"/>
+ </MarkerPatternSelector>
+ </PatternLayout>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Root level="TRACE">
+ <AppenderRef ref="Console" />
+ </Root>
+ </Loggers>
+</Configuration>]]></pre>
+
+ <p>
+ The output below illustrates the difference between using the Logger name and the Class name in the pattern. All
+ the odd numbered items print the name of the logger (%c) while all the even numbered items print the
+ name of the class that called the logging method (%C). The numbers in the description of the outcomes in the
+ following list match the corresponding numbers shown in the output.
+ <ol>
+ <li>Logging is performed in the base class using the static logger with the Logger name pattern. The
+ logger name matches the name of the base class.</li>
+ <li>Logging is performed in the base class using the static logger with the Class name pattern. Although
+ the method was called against the MyClass instance it is implemented in MySuperClass so that is what
+ appears.</li>
+ <li>Logging is performed in the subclass using the logger in the subclass, so the name of the
+ subclass is printed as the logger name.</li>
+ <li>Logging is performed in the subclass using the logger in the subclass, so the name of the subclass
+ is printed since that is where the method exists.</li>
+ <li>Logging is performed in the subclass with the static logger of the base class. Thus the name
+ of the base class Logger is printed.</li>
+ <li>Logging is performed in the subclass with the static logger of the base class, so the name
+ of the subclass is printed since that is where the method performing the logging exists.</li>
+
+ <li>Logging is performed in the base class using the logger of the subclass. The
+ logger name matches the name of the subclass and so is printed.</li>
+ <li>Logging is performed in the base class using the logger of the subclass. Although
+ the method was called against the MyClass instance it is implemented in MySuperClass so that is what
+ appears as the class name.</li>
+ <li>Logging is performed in the subclass using the logger in the subclass, so the name of the
+ subclass is printed as the logger name.</li>
+ <li>Logging is performed in the subclass using the logger in the subclass, so the name of the subclass
+ is printed since that is where the method exists.</li>
+ <li>Logging is performed in the subclass with the logger of the base class. Thus the name
+ of the base class Logger is printed.</li>
+ <li>Logging is performed in the subclass with the static logger of the base class, so the name
+ of the subclass is printed since that is where the method performing the logging exists.</li>
+ </ol>
+ </p>
+<pre class="prettyprint">
+ ------- MySuperClass Logger ----------
+ 1. Logger name org.apache.logging.MySuperClass MySuperClass log message
+ 2. Class name org.apache.logging.MySuperClass MySuperClass log message
+ 3. Logger name org.apache.logging.MyClass MyClass logger message
+ 4. Class name org.apache.logging.MyClass MyClass logger message
+ 5. Logger name org.apache.logging.MySuperClass MySuperClass logger message from MyClass
+ 6. Class name org.apache.logging.MyClass MySuperClass logger message from MyClass
+ ------- MySuperClass Logger set to MyClass Logger ----------
+ 7. Logger name org.apache.logging.MyClass MySuperClass log message
+ 8. Class name org.apache.logging.MySuperClass MySuperClass log message
+ 9. Logger name org.apache.logging.MyClass MyClass logger message
+ 10. Class name org.apache.logging.MyClass MyClass logger message
+ 11. Logger name org.apache.logging.MySuperClass MySuperClass logger message from MyClass
+ 12. Class name org.apache.logging.MyClass MySuperClass logger message from MyClass
+</pre>
+
+ <p>
+ In the example above there are two Loggers declared. One is static and one is non-static. When looking at
+ the results it is clear that the outcomes would be exactly the same regardless of whether how the loggers
+ are declared. The name of the logger will always originate from the class in which it is created and the
+ Class name in each log event will always reflect the Class from which the logging method was called.
+ </p>
+ <p>
+ It should be noted that there is a substantial performance penalty for printing the location information
+ (class name, method name, and line number). If the method name and line number are not important it is
+ usually better to make sure that each class has its own Logger so the logger name accurately reflects the
+ class performing the logging.
+ </p>
+
+
+ </subsection>
+
+ </section>
+ </body>
+</document>