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 <[email protected]> Authored: Fri Aug 7 01:03:51 2015 +0900 Committer: rpopma <[email protected]> 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
