LOG4J2-1623 Update 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/c92c327c Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/c92c327c Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/c92c327c Branch: refs/heads/LOG4J2-1390 Commit: c92c327c3db50ff18d01234c0a427d3ad9869588 Parents: 5564556 Author: Mikael Ståldal <[email protected]> Authored: Wed Oct 5 15:07:55 2016 +0200 Committer: Mikael Ståldal <[email protected]> Committed: Wed Oct 5 15:07:55 2016 +0200 ---------------------------------------------------------------------- .../logging/log4j/core/LoggerContext.java | 21 +++++++++++++------- .../logging/log4j/core/config/Configurator.java | 13 +++++++----- src/site/xdoc/manual/configuration.xml.vm | 10 +++++----- 3 files changed, 27 insertions(+), 17 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c92c327c/log4j-core/src/main/java/org/apache/logging/log4j/core/LoggerContext.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/LoggerContext.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/LoggerContext.java index 2681485..4c759c0 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/LoggerContext.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/LoggerContext.java @@ -303,15 +303,22 @@ public class LoggerContext extends AbstractLifeCycle } /** - * How many milliseconds appenders and other plugins will get to shutdown. - * - * Not all plugins will honor this, it is a hint and not an absolute guarantee that the this method not block longer. + * Blocks until all Log4j tasks have completed execution after a shutdown request and all appenders have shut down, + * or the timeout occurs, or the current thread is interrupted, whichever happens first. + * <p> + * Not all appenders will honor this, it is a hint and not an absolute guarantee that the this method not block longer. * Setting timeout too low increase the risk of losing outstanding log events not yet written to the final * destination. - * - * @param timeout the maximum time to wait, or 0 which mean that each plugin uses its default timeout - * @param timeUnit the time unit of the timeout argument - * @return true if the context was stopped cleanly and normally, false otherwise. + * <p> + * Log4j can start threads to perform certain actions like file rollovers, calling this method with a positive timeout will + * block until the rollover thread is done. + * + * @param timeout the maximum time to wait, or 0 which mean that each apppender uses its default timeout, and don't wait for background + tasks + * @param timeUnit + * the time unit of the timeout argument + * @return {@code true} if the logger context terminated and {@code false} if the timeout elapsed before + * termination. * @since 2.7 */ @Override http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c92c327c/log4j-core/src/main/java/org/apache/logging/log4j/core/config/Configurator.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/Configurator.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/Configurator.java index 3da469d..28dd85f 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/Configurator.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/Configurator.java @@ -346,13 +346,12 @@ public final class Configurator { } /** - * Blocks until all Log4j tasks have completed execution after a shutdown request, or the timeout occurs, or the - * current thread is interrupted, whichever happens first. + * Shuts down the given logger context. * <p> - * Log4j can start threads to perform certain actions like file rollovers, calling this method with a timeout will - * block until the rollover thread is done. + * Log4j can start threads to perform certain actions like file rollovers; calling this method with a positive + * timeout will block until the rollover thread is done. * </p> - * + * * @param ctx * the logger context to shut down, may be null. * @param timeout @@ -361,6 +360,10 @@ public final class Configurator { * the time unit of the timeout argument * @return {@code true} if the logger context terminated and {@code false} if the timeout elapsed before * termination. + * + * @see LoggerContext#stop(long, TimeUnit) + * + * @since 2.7 */ public static boolean shutdown(final LoggerContext ctx, final long timeout, final TimeUnit timeUnit) { if (ctx != null) { http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c92c327c/src/site/xdoc/manual/configuration.xml.vm ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/configuration.xml.vm b/src/site/xdoc/manual/configuration.xml.vm index 2b59e8d..2117dd2 100644 --- a/src/site/xdoc/manual/configuration.xml.vm +++ b/src/site/xdoc/manual/configuration.xml.vm @@ -409,11 +409,11 @@ public class Bar { </tr> <tr> <td>shutdownTimeout</td> - <td>Specifies how many milliseconds appenders and other plugins will get to shutdown when the JVM shuts - down. Default is zero which mean that each plugin uses its default timeout. Not all plugins will honor - this, it is a hint and not an absolute guarantee that the shutdown procedure will not take longer. - Setting this too low increase the risk of losing outstanding log events not yet written to the final - destination. See <a class="javadoc" + <td>Specifies how many milliseconds appenders and background tasks will get to shutdown when the JVM shuts + down. Default is zero which mean that each appender uses its default timeout, and don't wait for background + tasks. Not all appenders will honor this, it is a hint and not an absolute guarantee that the shutdown + procedure will not take longer. Setting this too low increase the risk of losing outstanding log events + not yet written to the final destination. See <a class="javadoc" href="../log4j-core/target/site/apidocs/org/apache/logging/log4j/core/LoggerContext.html#stop(long, java.util.concurrent.TimeUnit)">LoggerContext.stop(long, java.util.concurrent.TimeUnit)</a>. (Not used if <tt>shutdownHook</tt> is set to "disable".)</td> <tr>
