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/06 21:42:03 UTC
[1/2] logging-log4j2 git commit: LOG4J2-1802: Add prettyprint support
for asciidoc output
Repository: logging-log4j2
Updated Branches:
refs/heads/master e4733bac2 -> 332383104
LOG4J2-1802: Add prettyprint support for asciidoc output
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/7bd1c464
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/7bd1c464
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/7bd1c464
Branch: refs/heads/master
Commit: 7bd1c4646e0d9b81580478361443baca50c47c38
Parents: e4733ba
Author: Matt Sicker <bo...@gmail.com>
Authored: Fri Apr 6 16:41:17 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Fri Apr 6 16:41:17 2018 -0500
----------------------------------------------------------------------
src/site/resources/js/site.js | 6 ++++++
1 file changed, 6 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/7bd1c464/src/site/resources/js/site.js
----------------------------------------------------------------------
diff --git a/src/site/resources/js/site.js b/src/site/resources/js/site.js
index 72a0f8c..50bff12 100644
--- a/src/site/resources/js/site.js
+++ b/src/site/resources/js/site.js
@@ -52,6 +52,12 @@ $(document).ready(function() {
$(this).addClass('linenums');
}
});
+
+ // decorator for prettyprint support in asciidoc
+ $('pre.highlight > code').each(function() {
+ var parent = $(this).parent();
+ parent.addClass('prettyprint')
+ });
// Hack to add default visuals to tables
$('table').each(function() {
[2/2] logging-log4j2 git commit: LOG4J2-1802: Convert api manual page
to asciidoc
Posted by ma...@apache.org.
LOG4J2-1802: Convert api 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/33238310
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/33238310
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/33238310
Branch: refs/heads/master
Commit: 3323831043ddb2b0612f134380acbe8e02a1c76c
Parents: 7bd1c46
Author: Matt Sicker <bo...@gmail.com>
Authored: Fri Apr 6 16:41:55 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Fri Apr 6 16:41:55 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/api.adoc | 184 +++++++++++++++++++++++++++++++++
src/site/xdoc/manual/api.xml | 168 ------------------------------
2 files changed, 184 insertions(+), 168 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/33238310/src/site/asciidoc/manual/api.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/api.adoc b/src/site/asciidoc/manual/api.adoc
new file mode 100644
index 0000000..d708aa1
--- /dev/null
+++ b/src/site/asciidoc/manual/api.adoc
@@ -0,0 +1,184 @@
+= Log4j 2 API
+
+== Overview
+
+The Log4j 2 API provides the interface that applications should code to
+and provides the adapter components required for implementers to create
+a logging implementation. Although Log4j 2 is broken up between an API
+and an implementation, the primary purpose of doing so was not to allow
+multiple implementations, although that is certainly possible, but to
+clearly define what classes and methods are safe to use in "normal"
+application code.
+
+=== Hello World!
+
+No introduction would be complete without the customary Hello, World
+example. Here is ours. First, a Logger with the name "HelloWorld" is
+obtained from the
+link:../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html[`LogManager`].
+Next, the logger is used to write the "Hello, World!" message, however
+the message will be written only if the Logger is configured to allow
+informational messages.
+
+[source,java]
+----
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+public class HelloWorld {
+ private static final Logger logger = LogManager.getLogger("HelloWorld");
+ public static void main(String[] args) {
+ logger.info("Hello, World!");
+ }
+}
+----
+
+The output from the call to `logger.info()` will vary significantly
+depending on the configuration used. See the
+link:configuration.html[Configuration] section for more details.
+
+=== Substituting Parameters
+
+Frequently the purpose of logging is to provide information about what
+is happening in the system, which requires including information about
+the objects being manipulated. In Log4j 1.x this could be accomplished
+by doing:
+
+[source,java]
+----
+if (logger.isDebugEnabled()) {
+ logger.debug("Logging in user " + user.getName() + " with birthday " + user.getBirthdayCalendar());
+}
+----
+
+Doing this repeatedly has the effect of making the code feel like it is
+more about logging than the actual task at hand. In addition, it results
+in the logging level being checked twice; once on the call to
+isDebugEnabled and once on the debug method. A better alternative would
+be:
+
+[source,java]
+----
+logger.debug("Logging in user {} with birthday {}", user.getName(), user.getBirthdayCalendar());
+----
+
+With the code above the logging level will only be checked once and the
+String construction will only occur when debug logging is enabled.
+
+=== Formatting Parameters
+
+Formatter Loggers leave formatting up to you if `toString()` is not what
+you want. To facilitate formatting, you can use the same format strings
+as Java's
+http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax[`Formatter`].
+For example:
+
+[source,java]
+----
+public static Logger logger = LogManager.getFormatterLogger("Foo");
+
+logger.debug("Logging in user %s with birthday %s", user.getName(), user.getBirthdayCalendar());
+logger.debug("Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar());
+logger.debug("Integer.MAX_VALUE = %,d", Integer.MAX_VALUE);
+logger.debug("Long.MAX_VALUE = %,d", Long.MAX_VALUE);
+----
+
+To use a formatter Logger, you must call one of the `LogManager`
+link:../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html#getFormatterLogger(java.lang.Class)[`getFormatterLogger`]
+methods. The output for this example shows that `Calendar::toString` is
+verbose compared to custom formatting:
+
+[source,java]
+----
+2012-12-12 11:56:19,633 [main] DEBUG: User John Smith with birthday java.util.GregorianCalendar[time=?,areFieldsSet=false,areAllFieldsSet=false,lenient=true,zone=sun.util.calendar.ZoneInfo[id="America/New_York",offset=-18000000,dstSavings=3600000,useDaylight=true,transitions=235,lastRule=java.util.SimpleTimeZone[id=America/New_York,offset=-18000000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]],firstDayOfWeek=1,minimalDaysInFirstWeek=1,ERA=?,YEAR=1995,MONTH=4,WEEK_OF_YEAR=?,WEEK_OF_MONTH=?,DAY_OF_MONTH=23,DAY_OF_YEAR=?,DAY_OF_WEEK=?,DAY_OF_WEEK_IN_MONTH=?,AM_PM=0,HOUR=0,HOUR_OF_DAY=0,MINUTE=0,SECOND=0,MILLISECOND=?,ZONE_OFFSET=?,DST_OFFSET=?]
+2012-12-12 11:56:19,643 [main] DEBUG: User John Smith with birthday 05 23, 1995
+2012-12-12 11:56:19,643 [main] DEBUG: Integer.MAX_VALUE = 2,147,483,647
+2012-12-12 11:56:19,643 [main] DEBUG: Long.MAX_VALUE = 9,223,372,036,854,775,807
+----
+
+=== Mixing Loggers with Formatter Loggers
+
+Formatter loggers give fine-grained control over the output format, but
+have the drawback that the correct type must be specified (for example,
+passing anything other than a decimal integer for a %d format parameter
+gives an exception).
+
+If your main usage is to use \{}-style parameters, but occasionally you
+need fine-grained control over the output format, you can use the
+`printf` method:
+
+[source,java]
+----
+public static Logger logger = LogManager.getLogger("Foo");
+
+logger.debug("Opening connection to {}...", someDataSource);
+logger.printf(Level.INFO, "Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar());
+----
+
+[#LambdaSupport]
+=== Java 8 lambda support for lazy logging
+
+In release 2.4, the `Logger` interface added support for lambda
+expressions. This allows client code to lazily log messages without
+explicitly checking if the requested log level is enabled. For example,
+previously you would write:
+
+[source,java]
+----
+// pre-Java 8 style optimization: explicitly check the log level
+// to make sure the expensiveOperation() method is only called if necessary
+if (logger.isTraceEnabled()) {
+ logger.trace("Some long-running operation returned {}", expensiveOperation());
+}
+----
+
+With Java 8 you can achieve the same effect with a lambda expression.
+You no longer need to explicitly check the log level:
+
+[source,java]
+----
+// Java-8 style optimization: no need to explicitly check the log level:
+// the lambda expression is not evaluated if the TRACE level is not enabled
+logger.trace("Some long-running operation returned {}", () -> expensiveOperation());
+----
+
+=== Logger Names
+
+Most logging implementations use a hierarchical scheme for matching
+logger names with logging configuration. In this scheme, the logger name
+hierarchy is represented by `'.'` characters in the logger name, in a
+fashion very similar to the hierarchy used for Java package names. For
+example, `org.apache.logging.appender` and `org.apache.logging.filter`
+both have `org.apache.logging` as their parent. In most cases,
+applications name their loggers by passing the current class's name to
+`LogManager.getLogger(...)`. Because this usage is so common, Log4j 2
+provides that as the default when the logger name parameter is either
+omitted or is null. For example, in all examples below the Logger will
+have a name of `"org.apache.test.MyTest"`.
+
+[source,java]
+----
+package org.apache.test;
+
+public class MyTest {
+ private static final Logger logger = LogManager.getLogger(MyTest.class);
+}
+----
+
+[source,java]
+----
+package org.apache.test;
+
+public class MyTest {
+ private static final Logger logger = LogManager.getLogger(MyTest.class.getName());
+}
+----
+
+[source,java]
+----
+package org.apache.test;
+
+public class MyTest {
+ private static final Logger logger = LogManager.getLogger();
+}
+----
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/33238310/src/site/xdoc/manual/api.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/api.xml b/src/site/xdoc/manual/api.xml
deleted file mode 100644
index 84d7b51..0000000
--- a/src/site/xdoc/manual/api.xml
+++ /dev/null
@@ -1,168 +0,0 @@
-<?xml version="1.0"?>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<document xmlns="http://maven.apache.org/XDOC/2.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
- <properties>
- <title>Log4j 2 API</title>
- <author email="rgoers@apache.org">Ralph Goers</author>
- <author email="ggregory@apache.org">Gary Gregory</author>
- </properties>
-
- <body>
- <section name="Log4j 2 API">
- <a name="Overview"/>
- <subsection name="Overview">
- <p>
- The Log4j 2 API provides the interface that applications should code to and provides the
- adapter components required for implementers to create a logging implementation. Although Log4j 2
- is broken up between an API and an implementation, the primary purpose of doing so was not to
- allow multiple implementations, although that is certainly possible, but to clearly define
- what classes and methods are safe to use in "normal" application code.
- </p>
- <h4>Hello World!</h4>
- <p>
- No introduction would be complete without the customary Hello, World example. Here is ours. First,
- a Logger with the name "HelloWorld" is obtained from the
- <a href="../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html">LogManager</a>.
- Next, the logger is used to write the "Hello, World!" message, however the message will be written
- only if the Logger is configured to allow informational messages.
- </p>
- <pre class="prettyprint linenums">import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
-
-public class HelloWorld {
- private static final Logger logger = LogManager.getLogger("HelloWorld");
- public static void main(String[] args) {
- logger.info("Hello, World!");
- }
-}</pre>
- <p>
- The output from the call to logger.info() will vary significantly depending on the configuration
- used. See the <a href="./configuration.html">Configuration</a> section for more details.
- </p>
- <h4>Substituting Parameters</h4>
- <p>
- Frequently the purpose of logging is to provide information about what is happening in the system,
- which requires including information about the objects being manipulated. In Log4j 1.x this could
- be accomplished by doing:
- </p>
- <pre class="prettyprint linenums">if (logger.isDebugEnabled()) {
- logger.debug("Logging in user " + user.getName() + " with birthday " + user.getBirthdayCalendar());
-}</pre>
- <p>
- Doing this repeatedly has the effect of making the code feel like it is more about logging than the
- actual task at hand. In addition, it results in the logging level being checked twice; once on the
- call to isDebugEnabled and once on the debug method. A better alternative would be:
- </p>
- <pre class="prettyprint">logger.debug("Logging in user {} with birthday {}", user.getName(), user.getBirthdayCalendar());</pre>
- <p>
- With the code above the logging level will only be checked once and the String construction will
- only occur when debug logging is enabled.
- </p>
- <h4>Formatting Parameters</h4>
- <p>
- Formatter Loggers leave formatting up to you if <code>toString()</code> is not what you want.
- To facilitate formatting, you can use the same format strings as Java's
- <a href="http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax">Formatter</a>.
- For example:
- </p>
- <pre class="prettyprint linenums">public static Logger logger = LogManager.getFormatterLogger("Foo");
-
-logger.debug("Logging in user %s with birthday %s", user.getName(), user.getBirthdayCalendar());
-logger.debug("Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar());
-logger.debug("Integer.MAX_VALUE = %,d", Integer.MAX_VALUE);
-logger.debug("Long.MAX_VALUE = %,d", Long.MAX_VALUE);
-</pre>
- <p>
- To use a formatter Logger, you must call one of the LogManager
- <a href="../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html#getFormatterLogger(java.lang.Class)">getFormatterLogger</a>
- methods. The output for this example shows that Calendar toString() is verbose compared to custom formatting:
- </p>
- <pre class="prettyprint linenums">2012-12-12 11:56:19,633 [main] DEBUG: User John Smith with birthday java.util.GregorianCalendar[time=?,areFieldsSet=false,areAllFieldsSet=false,lenient=true,zone=sun.util.calendar.ZoneInfo[id="America/New_York",offset=-18000000,dstSavings=3600000,useDaylight=true,transitions=235,lastRule=java.util.SimpleTimeZone[id=America/New_York,offset=-18000000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]],firstDayOfWeek=1,minimalDaysInFirstWeek=1,ERA=?,YEAR=1995,MONTH=4,WEEK_OF_YEAR=?,WEEK_OF_MONTH=?,DAY_OF_MONTH=23,DAY_OF_YEAR=?,DAY_OF_WEEK=?,DAY_OF_WEEK_IN_MONTH=?,AM_PM=0,HOUR=0,HOUR_OF_DAY=0,MINUTE=0,SECOND=0,MILLISECOND=?,ZONE_OFFSET=?,DST_OFFSET=?]
-2012-12-12 11:56:19,643 [main] DEBUG: User John Smith with birthday 05 23, 1995
-2012-12-12 11:56:19,643 [main] DEBUG: Integer.MAX_VALUE = 2,147,483,647
-2012-12-12 11:56:19,643 [main] DEBUG: Long.MAX_VALUE = 9,223,372,036,854,775,807
-</pre>
- <h4>Mixing Loggers with Formatter Loggers</h4>
- <p>
- Formatter loggers give fine-grained control over the output format, but have the drawback
- that the correct type must be specified (for example, passing anything other than a decimal integer
- for a %d format parameter gives an exception).
- </p>
- <p>
- If your main usage is to use {}-style parameters, but occasionally you need fine-grained
- control over the output format, you can use the <code>printf</code> method:</p>
- <pre class="prettyprint linenums">public static Logger logger = LogManager.getLogger("Foo");
-
-logger.debug("Opening connection to {}...", someDataSource);
-logger.printf(Level.INFO, "Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar());
-</pre>
-
- <a name="LambdaSupport"/>
- <h4>Java 8 lambda support for lazy logging</h4>
- <p>
- In release 2.4, the <code>Logger</code> interface added support for lambda expressions.
- This allows client code to lazily log messages without explicitly checking if the requested log
- level is enabled. For example, previously you would write:
- </p>
- <pre class="prettyprint linenums">// pre-Java 8 style optimization: explicitly check the log level
-// to make sure the expensiveOperation() method is only called if necessary
-if (logger.isTraceEnabled()) {
- logger.trace("Some long-running operation returned {}", expensiveOperation());
-}</pre>
- <p>
- With Java 8 you can achieve the same effect with a lambda expression.
- You no longer need to explicitly check the log level:
- </p>
- <pre class="prettyprint linenums">// Java-8 style optimization: no need to explicitly check the log level:
-// the lambda expression is not evaluated if the TRACE level is not enabled
-logger.trace("Some long-running operation returned {}", () -> expensiveOperation());</pre>
-
- <h4>Logger Names</h4>
- <p>
- Most logging implementations use a hierarchical scheme for matching logger names with logging
- configuration. In this scheme, the logger name hierarchy is represented by <code>'.'</code> characters
- in the logger name, in a fashion very similar to the hierarchy used for Java package names. For example,
- <code>org.apache.logging.appender</code> and <code>org.apache.logging.filter</code> both have
- <code>org.apache.logging</code> as their parent. In most cases, applications name their loggers by
- passing the current class's name to <code>LogManager.getLogger(...)</code>. Because this usage is so
- common, Log4j 2 provides that as the default when the logger name parameter is either omitted or is
- null. For example, in all examples below the Logger will have a name of
- <code>"org.apache.test.MyTest"</code>.
- </p>
- <pre class="prettyprint linenums">package org.apache.test;
-
-public class MyTest {
- private static final Logger logger = LogManager.getLogger(MyTest.class);
-}</pre>
- <pre class="prettyprint linenums">package org.apache.test;
-
-public class MyTest {
- private static final Logger logger = LogManager.getLogger(MyTest.class.getName());
-}</pre>
- <pre class="prettyprint linenums">package org.apache.test;
-
-public class MyTest {
- private static final Logger logger = LogManager.getLogger();
-}</pre>
- </subsection>
- </section>
- </body>
-</document>