You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rp...@apache.org on 2015/08/06 18:08:24 UTC
[4/4] logging-log4j2 git commit: LOG4J2-599 documentation
LOG4J2-599 documentation
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/cf3ced44
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/cf3ced44
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/cf3ced44
Branch: refs/heads/LOG4J2-599-LambdaSupport
Commit: cf3ced44344ee46e5ff24399882e540de3f59fac
Parents: faa36c3
Author: rpopma <rp...@apache.org>
Authored: Fri Aug 7 01:03:51 2015 +0900
Committer: rpopma <rp...@apache.org>
Committed: Fri Aug 7 01:03:51 2015 +0900
----------------------------------------------------------------------
.../org/apache/logging/log4j/LambdaLogger.java | 2 +-
src/site/xdoc/index.xml | 8 +++++++
src/site/xdoc/manual/api.xml | 23 ++++++++++++++++++++
src/site/xdoc/manual/index.xml | 3 +++
4 files changed, 35 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/cf3ced44/log4j-api/src/main/java/org/apache/logging/log4j/LambdaLogger.java
----------------------------------------------------------------------
diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/LambdaLogger.java b/log4j-api/src/main/java/org/apache/logging/log4j/LambdaLogger.java
index ea08013..84a3fef 100644
--- a/log4j-api/src/main/java/org/apache/logging/log4j/LambdaLogger.java
+++ b/log4j-api/src/main/java/org/apache/logging/log4j/LambdaLogger.java
@@ -39,7 +39,7 @@ import java.util.concurrent.Callable;
* <pre>
* // 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
- * Logger2 logger = LogManager.getLambdaLogger();
+ * LambdaLogger logger = LogManager.getLambdaLogger();
* logger.trace("Some long-running operation returned {}", () -> expensiveOperation());
* </pre>
*/
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/cf3ced44/src/site/xdoc/index.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
index 7d72630..0678a6b 100644
--- a/src/site/xdoc/index.xml
+++ b/src/site/xdoc/index.xml
@@ -88,6 +88,14 @@
Map, and data present in the event. Users can further customize the property providers by
adding their own <a href="manual/lookups.html">Lookup</a> Plugin.
</dd>
+ <dt>Java 8 Lambda Support</dt>
+ <dd>
+ Previously, if a log message was expensive to construct, you would often explicitly check if the
+ requested log level is enabled before constructing the message.
+ Client code running on Java 8 can benefit from Log4j's <a href="manual/api.html#LambdaSupport">lambda
+ support</a>. Since Log4j will not evaluate a lambda
+ expression if the requested log level is not enabled, the same effect can be achieved with less code.
+ </dd>
</dl>
<subsection name="Documentation">
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/cf3ced44/src/site/xdoc/manual/api.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/api.xml b/src/site/xdoc/manual/api.xml
index 4a60f5c..1783353 100644
--- a/src/site/xdoc/manual/api.xml
+++ b/src/site/xdoc/manual/api.xml
@@ -114,6 +114,29 @@ logger.debug("Long.MAX_VALUE = %,d", Long.MAX_VALUE);
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>
+ The <code>LambdaLogger</code> interface extends <code>Logger</code> to add support for lambda expressions.
+ This logger 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
+Logger logger = LogManager.getLogger();
+if (logger.isTraceEnabled()) {
+ logger.trace("Some long-running operation returned {}", expensiveOperation());
+}</pre>
+ <p>
+ With Java 8 and the <code>LambdaLogger</code> interface, you can achieve the same effect by using 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
+LambdaLogger logger = LogManager.getLambdaLogger();
+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
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/cf3ced44/src/site/xdoc/manual/index.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/index.xml b/src/site/xdoc/manual/index.xml
index 54c47ec..35c0077 100644
--- a/src/site/xdoc/manual/index.xml
+++ b/src/site/xdoc/manual/index.xml
@@ -104,6 +104,9 @@
do not require a class name to be specified.</li>
<li>Support for <a href="customloglevels.html">custom log levels</a>.
Custom log levels can be defined in code or in configuration.</li>
+ <li>Support for <a href="api.html#LambdaSupport">lambda expressions</a>.
+ Client code running on Java 8 can use lambda expressions to lazily construct a log message only if
+ the requested log level is enabled. Explicit level checks are not needed, resulting in cleaner code.</li>
<li>Support for <a href="messages.html">Message objects</a>. Messages allow support for interesting and
complex constructs to be passed through the logging system and be efficiently
manipulated. Users are free to create their own