Author: ceki Date: Wed Oct 29 19:42:07 2008 New Revision: 1908 Added: logback/trunk/logback-examples/src/main/java/chapter3/AddStatusListenerApp.java logback/trunk/logback-examples/src/main/java/chapter3/onConsoleStatusListener.xml Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/status/StatusListener.java logback/trunk/logback-site/src/site/pages/manual/joran.html Log: LBCLASSIC-59 - documentation on status listeners Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/status/StatusListener.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/status/StatusListener.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/status/StatusListener.java Wed Oct 29 19:42:07 2008 @@ -1,5 +1,20 @@ +/** + * Logback: the generic, reliable, fast and flexible logging framework. + * + * Copyright (C) 2000-2008, QOS.ch + * + * This library is free software, you can redistribute it and/or modify it under + * the terms of the GNU Lesser General Public License as published by the Free + * Software Foundation. + */ package ch.qos.logback.core.status; +/** + * A StatusListener registered with logback context's {@link StatusManager} will + * receive notification of every incoming {@link Status status} message. + * + * @author Ceki Gülcü + */ public interface StatusListener { void addStatusEvent(Status status); } Added: logback/trunk/logback-examples/src/main/java/chapter3/AddStatusListenerApp.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter3/AddStatusListenerApp.java Wed Oct 29 19:42:07 2008 @@ -0,0 +1,37 @@ +/** + * Logback: the generic, reliable, fast and flexible logging framework. + * + * Copyright (C) 2000-2008, QOS.ch + * + * This library is free software, you can redistribute it and/or modify it under + * the terms of the GNU Lesser General Public License as published by the Free + * Software Foundation. + */ +package chapter3; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.LoggerContext; +import ch.qos.logback.core.joran.spi.JoranException; +import ch.qos.logback.core.status.OnConsoleStatusListener; +import ch.qos.logback.core.status.StatusManager; + +public class AddStatusListenerApp { + + public static void main(String[] args) throws JoranException { + + + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + StatusManager statusManager = lc.getStatusManager(); + OnConsoleStatusListener onConsoleListener = new OnConsoleStatusListener(); + statusManager.add(onConsoleListener); + + Logger logger = LoggerFactory.getLogger("myApp"); + logger.info("Entering application."); + + Foo foo = new Foo(); + foo.doIt(); + logger.info("Exiting application."); + } +} Added: logback/trunk/logback-examples/src/main/java/chapter3/onConsoleStatusListener.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter3/onConsoleStatusListener.xml Wed Oct 29 19:42:07 2008 @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<configuration debug="false"> + + <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /> + + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern> + %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n + </Pattern> + </layout> + </appender> + + <root level="debug"> + <appender-ref ref="STDOUT" /> + </root> + +</configuration> \ No newline at end of file Modified: logback/trunk/logback-site/src/site/pages/manual/joran.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/joran.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/joran.html Wed Oct 29 19:42:07 2008 @@ -94,7 +94,7 @@ </ol> <p>The third and last step is meant to provide a default (but very - basic) logging functionnality in the absence of a configuration + basic) logging functionality in the absence of a configuration file. </p> @@ -160,7 +160,7 @@ <p>In order to run the examples in this chapter, you need to make - sure that certain jar files are present on the classpath. Please + sure that certain jar files are present on the class path. Please refer to the <a href="../setup.html">setup page</a> for further details. </p> @@ -203,8 +203,8 @@ <p>As mentioned earlier, logback will try to configure itself using the files <em>logback-test.xml</em> or <em>logback.xml</em> if - found on the classpath. Here is a configuration file equivalent to - the one established by <code>BasicConfigrator</code> we've just + found on the class path. Here is a configuration file equivalent to + the one established by <code>BasicConfigurator</code> we've just seen. </p> @@ -227,7 +227,7 @@ <p>After you have renamed <em>sample0.xml</em> as <em>logback.xml</em> (or <em>logback-test.xml</em>) place it into a - directory accesible from the classpath. Running the <em>MyApp1</em> + directory accessible from the class path. Running the <em>MyApp1</em> application should give identical results to its previous run.</p> <p>If and only if there are errors during the parsing of the @@ -246,9 +246,9 @@ <div class="source"><pre> public static void main(String[] args) { - logger.info("Entering application."); - // print logback's internal status + // assume SLF4J is bound to logback in the current environment <b>LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();</b> + // print logback's internal status <b>StatusPrinter.print(lc);</b> ... }</pre></div> @@ -271,7 +271,7 @@ <p>At the end of this output, you can recognize the lines that were printed in the previous example. You should also notice the logback's internal messages, a.k.a. <code>Status</code> objects, - which allow convient access to logback's internal state. + which allow convenient access to logback's internal state. </p> <p>Instead of invoking <code>StatusPrinter</code> programmatically @@ -282,7 +282,7 @@ configuration file, as shown below. Please note that this <span class="attr">debug</span> attribute relates only to the status data. It does <em>not</em> affect logback's configuration - otherwise, in particuler with respect to logger levels. (Put + otherwise, in particular with respect to logger levels. (Put differently, no, the root logger will <em>not</em> be set to <code>DEBUG</code>.) </p> @@ -320,7 +320,7 @@ configuration file cannot be read. If the configuration file is found but is ill-formed, then logback will detect the error condition and automatically print its internal status on the - console. However, if the configration file cannot be found, since + console. However, if the configuration file cannot be found, since this is not necessarily an error condition, logback will not automatically print its status data. Programmatically invoking <code>StatusPrinter.print()</code>, as as in <em>MyApp2</em> @@ -345,10 +345,10 @@ <p>Logback relies on a configuration library called Joran which is part of logback-core. Logback's default configuration mechanism invokes JoranConfigurator on the default configuration files it - finds on the claspath. For whatever reason if you wish to override - logback's default configuration meachanism, you can do so by - invoking JoranConfigurator directly. The next application, - <em>MyApp3</em>, invokes JoranConfirator on a configuration file + finds on the class path. For whatever reason if you wish to + override logback's default configuration mechanism, you can do so + by invoking JoranConfigurator directly. The next application, + <em>MyApp3</em>, invokes JoranConfigurator on a configuration file passed as parameter.</p> <p><em>Example 3.<span class="autoEx"/>: Invoking @@ -369,7 +369,7 @@ final static Logger logger = LoggerFactory.getLogger(MyApp3.class); public static void main(String[] args) { - // assume logback is in use + // assume SLF4J is bound to logback in the current environment <b>LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();</b> <b>try { @@ -400,6 +400,65 @@ status data is printed in case errors occur. </p> + <h3> + <a name="statusListener" href="#statusListener">Listening to + status messages</a> + </h3> + + <p>Logback collects its internal status data in its <code><a + href="../xref/ch/qos/logback/core/status/StatusManager.html">StatusManager</a></code>, + accessible via the LoggerContext. + </p> + + <p>Given a <code>StatusManager</code> you an access all the status + data associated with a logback context. You may also attach a + <code>StatusListener</code> to a <code>StatusManager</code> so that + you can take immediate action in response to status messages, + especially to messages occuring after logback + configuration. Registering a status listener is a convenient way to + supervise logback's internal state without human intervention. + </p> + + <p>Logback ships with a <code>StatusListener</code> implementation + called <code><a + href="../xref/ch/qos/logback/core/status/OnConsoleStatusListener.html">OnConsoleStatusListener</a></code> + which, as its name indicates, prints all <em>new</em> incoming + status messages on the console. + </p> + + <p>Here is <a + href="../xref/chapter3/AddStatusListenerApp.html">sample code</a> + to register a OnConsoleStatusListener instance with the + StatusManager. + </p> + + <p class="source"> LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + StatusManager statusManager = lc.getStatusManager(); + OnConsoleStatusListener onConsoleListener = new OnConsoleStatusListener(); + statusManager.add(onConsoleListener);</p> + + <p>Note that the registered status listener will receive status + events subsequent to its registration. It will not receive prior + messages.</p> + + <p>It is also possible to register one or more status listeners + within a configuration file. Here is an example.</p> + + <p><em>Example 3.<span class="autoEx"/>: Registering a status listener (logback-examples/src/main/java/chapter3/onConsoleStatusListener.xml)</em></p> + + <p class="source"><configuration> + <b><statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /></b> + + ... the rest of the configuration file +</configuration></p> + + <p>One may also register a status listener by setting the + "logback.statusListenerClass" Java system property to the name of + the listener class you wish to register. For example, + </p> + + <p class="source">java <b>-Dlogback.statusListenerClass</b>=ch.qos.logback.core.status.OnConsoleStatusListener ...</p> + <h2> <a name="syntax" href="#syntax">Configuration file Syntax</a> </h2> @@ -419,8 +478,8 @@ <p>As shall become clear, the syntax of logback configuration files is extremely flexible. As such, it is not possible specify the - allowed syntax with a DTD file or an XML Schema. Nevertheles, the - very basic structure of configration can be desribed as, + allowed syntax with a DTD file or an XML Schema. Nevertheless, the + very basic structure of configuration can be described as, <configuration> element, followed by zero or more <appender> elements, followed by by zero or more <logger> elements, followed by at most one <root> element. The following diagram illustrates @@ -436,7 +495,7 @@ <p>A logger is configured using the <code>logger</code> element. A <em>logger</em> element takes exactly one mandatory <span - class="attr">name</span> atttribute, an optional <span + class="attr">name</span> attribute, an optional <span class="attr">level</span> attribute, and an optional <span class="attr">aditivity</span> attribute, which admits the values <em>true</em> or <em>false</em>. The value of the <span @@ -460,7 +519,7 @@ - <h4>Configuring the roor logger, or the <code><root></code> + <h4>Configuring the root logger, or the <code><root></code> element</h4>