[logback-dev] svn commit: r1908 - in logback/trunk: logback-core/src/main/java/ch/qos/logback/core/status logback-examples/src/main/java/chapter3 logback-site/src/site/pages/manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Wed Oct 29 19:42:08 CET 2008
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>
More information about the logback-dev
mailing list