Author: ceki Date: Thu Dec 4 23:14:25 2008 New Revision: 2061 Added: logback/trunk/logback-examples/src/main/java/chapter3/contextName.xml logback/trunk/logback-examples/src/main/java/chapter3/insertFromJNDI.xml Modified: logback/trunk/logback-classic/pom.xml logback/trunk/logback-examples/pom.xml logback/trunk/logback-site/src/site/pages/css/common.css logback/trunk/logback-site/src/site/pages/faq.html logback/trunk/logback-site/src/site/pages/manual/architecture.html logback/trunk/logback-site/src/site/pages/manual/joran.html logback/trunk/logback-site/src/site/pages/manual/layouts.html logback/trunk/logback-site/src/site/pages/news.html logback/trunk/pom.xml Log: - removed slf4j-ext declaration from the parent pom. In child modules the slf4j-ext was being inserted in compile scope instead of test scope. - updated documentation in relation to contextName and insertFromJNDI configuration directives. Modified: logback/trunk/logback-classic/pom.xml ============================================================================== --- logback/trunk/logback-classic/pom.xml (original) +++ logback/trunk/logback-classic/pom.xml Thu Dec 4 23:14:25 2008 @@ -48,6 +48,7 @@ <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-ext</artifactId> + <version>${slf4j.version}</version> <scope>test</scope> </dependency> @@ -62,6 +63,7 @@ <dependency> <groupId>org.slf4j</groupId> <artifactId>log4j-over-slf4j</artifactId> + <version>${slf4j.version}</version> <scope>test</scope> </dependency> Modified: logback/trunk/logback-examples/pom.xml ============================================================================== --- logback/trunk/logback-examples/pom.xml (original) +++ logback/trunk/logback-examples/pom.xml Thu Dec 4 23:14:25 2008 @@ -48,6 +48,7 @@ <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-ext</artifactId> + <version>${slf4j.version}</version> </dependency> <dependency> Added: logback/trunk/logback-examples/src/main/java/chapter3/contextName.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter3/contextName.xml Thu Dec 4 23:14:25 2008 @@ -0,0 +1,15 @@ +<configuration> + + <contextName>myAppName</contextName> + + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern> + </layout> + </appender> + + <root level="debug"> + <appender-ref ref="STDOUT" /> + </root> + +</configuration> \ No newline at end of file Added: logback/trunk/logback-examples/src/main/java/chapter3/insertFromJNDI.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter3/insertFromJNDI.xml Thu Dec 4 23:14:25 2008 @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<configuration> + <insertFromJNDI env-entry-name="java:comp/env/appName" as="appName" /> + <contextName>${appName}</contextName> + + <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%d %contextName %level %msg %logger{50}%n</Pattern> + </layout> + </appender> + + <root level="DEBUG"> + <appender-ref ref="CONSOLE" /> + </root> +</configuration> Modified: logback/trunk/logback-site/src/site/pages/css/common.css ============================================================================== --- logback/trunk/logback-site/src/site/pages/css/common.css (original) +++ logback/trunk/logback-site/src/site/pages/css/common.css Thu Dec 4 23:14:25 2008 @@ -100,7 +100,7 @@ font-size: smaller; } -strong { +.strong { /*font-size: 13px;*/ font-weight: bold; } @@ -198,6 +198,13 @@ font-family: Courier, monospace; } +.variable { + font-family: Courier, monospace; + font-style:italic; +} + + + .attr { font-family: Courier, monospace; font-style:italic; Modified: logback/trunk/logback-site/src/site/pages/faq.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/faq.html (original) +++ logback/trunk/logback-site/src/site/pages/faq.html Thu Dec 4 23:14:25 2008 @@ -54,6 +54,12 @@ </li> <li> + <a href="#overrideFromCL"> + How can I disable logging from the command line? + </a> + </li> + + <li> <a href="#setup_jetty">How can Jetty be instructed to use logback-classic as its logging implementataion? </a> @@ -190,6 +196,49 @@ <!-- ========================================================= --> + + <dt> + <a name="overrideFromCL" href="#overrideFromCL"> + How can I disable logging from the command line? + </a> + </dt> + <dd> + <p>Logback does not allow disabling logging from the command + line. However, if the configuration file allows it, you can + set the level of logers on the command line via a java + system property. Here is such a configuration file.</p> + + <p class="source"><configuration> + <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%d [%thread] %level %logger - %m%n</Pattern> + </layout> + </appender> + <root level="<b>${root-level:-INFO}</b>"> + <appender-ref ref="CONSOLE"/> + </root> +</configuration></p> + + + <p>Making use of <a + href="manual/joran.html#variableSubstitution">variable + substitution</a> as well as <a + href="manual/joran.html#defaultValuesForVariables">default + values for variables</a>, if the <span + class="variable">root-level</span> system property is set to + <code>OFF</code>, then all logging will be turned + off. However, if it is not set, it will assume the default + value of <code>INFO</code>. Note that you can set the <span + class="variable">root-level</span> system property to any + level value of your choice. The value <code>OFF</code> is + just an example. + + </p> + <hr/> + </dd> + + + <!-- ========================================================= --> <dt> <a name="setup_jetty" href="#"> Modified: logback/trunk/logback-site/src/site/pages/manual/architecture.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/architecture.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/architecture.html Thu Dec 4 23:14:25 2008 @@ -77,11 +77,12 @@ <p>The <code>Logger</code> class is part of the logback-classic module. On the other hand, the <code>Appender</code> and <code>Layout</code> interfaces are part of logback-core. As a - general-purpose module, logback-core has no notion of loggers. + general-purpose module, logback-core has no notion of + loggers. </p> - <a name="LoggerContext"></a> - <h3>Logger context</h3> + <h3><a name="LoggerContext" href="#LoggerContext">Logger + context</a></h3> <p>The first and foremost advantage of any logging API over plain <code>System.out.println</code> resides in its ability to disable @@ -89,13 +90,16 @@ unhindered. This capability assumes that the logging space, that is, the space of all possible logging statements, is categorized according to some developer-chosen criteria. In logback-classic, - this categorization is an inherent part of loggers. + this categorization is an inherent part of loggers. Every single + loggers is attached to a <code>LoggerContext</code> which is + responsible for manufacturing loggers as well as arranging them in + a tree like hierarchy. </p> - <p> - Loggers are named entities. Their names are case-sensitive and - they follow the hierarchical naming rule: + <p>Loggers are named entities. Their names are case-sensitive and + they follow the hierarchical naming rule: </p> + <div class="definition"> <div class="deftitle">Named Hierarchy</div> <p> @@ -107,44 +111,42 @@ </p> </div> - <p> - For example, the logger named <code>"com.foo"</code> - is a parent of the logger named <code>"com.foo.Bar"</code>. - Similarly, <code>"java"</code> - is a parent of <code>"java.util"</code> and an ancestor of - <code>"java.util.Vector"</code>. - This naming scheme should be familiar to most developers. + <p>For example, the logger named <code>"com.foo"</code> is a + parent of the logger named <code>"com.foo.Bar"</code>. Similarly, + <code>"java"</code> is a parent of <code>"java.util"</code> and an + ancestor of <code>"java.util.Vector"</code>. This naming scheme + should be familiar to most developers. </p> - <p> - The root logger resides at the top of the logger hierarchy. It - is exceptional in that it is part of every hierarchy at its - inception. Like every logger, it can be retrieved by its name, - as follows: + + <p>The root logger resides at the top of the logger hierarchy. It + is exceptional in that it is part of every hierarchy at its + inception. Like every logger, it can be retrieved by its name, as + follows: </p> - <div class="source"><pre>Logger rootLogger = LoggerFactory.getLogger(<a href="../apidocs/constant-values.html#ch.qos.logback.classic.LoggerContext.ROOT_NAME">LoggerContext.<em>ROOT_NAME</em></a>);</pre></div> + + <p class="source">Logger rootLogger = LoggerFactory.getLogger(<a href="../apidocs/constant-values.html#ch.qos.logback.classic.LoggerContext.ROOT_NAME">LoggerContext.<em>ROOT_NAME</em></a>);</p> - <p> - All other loggers are also retrieved with the class static - <code>getLogger</code> method found in the <a - href="http://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.LoggerFactory</a> - class. This method takes the name of the desired logger as a - parameter. Some of the basic methods in the <code>Logger</code> - interface are listed below. + <p>All other loggers are also retrieved with the class static + <code>getLogger</code> method found in the <a + href="http://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.LoggerFactory</a> + class. This method takes the name of the desired logger as a + parameter. Some of the basic methods in the <code>Logger</code> + interface are listed below. </p> - <div class="source"><pre>package org.slf4j; + <p class="source">package org.slf4j; public interface Logger { // Printing methods: + public void trace(String message); public void debug(String message); public void info(String message); public void warn(String message); public void error(String message); - public void fatal(String message); -}</pre></div> +}</p> <p>Loggers may be assigned levels. The set of possible levels, - that is DEBUG, INFO, WARN and ERROR are defined in the + that is TRACE, DEBUG, INFO, WARN and ERROR are defined in the <code>ch.qos.logback.classic.Level</code> class. Note that in logback, the level class is final and cannot be derived, as a much more flexible approach exist in the form of <code>Marker</code> @@ -166,15 +168,13 @@ </p> </div> - <p> - To ensure that all loggers can eventually inherit a level, the - root logger always has an assigned level. By default, this level - is DEBUG. - </p> - <p> - Below are four examples with various assigned level values and - the resulting effective (inherited) levels according to the - level inheritance rule. + <p>To ensure that all loggers can eventually inherit a level, the + root logger always has an assigned level. By default, this level + is DEBUG. + </p> + <p>Below are four examples with various assigned level values and + the resulting effective (inherited) levels according to the level + inheritance rule. </p> <em>Example 1</em> 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 Thu Dec 4 23:14:25 2008 @@ -1148,8 +1148,9 @@ "golden".</p> - <a name="Include"></a> - <h3>File inclusion</h3> + + <h3><a name="fileInclusion" href="#fileInclusion">File + inclusion</a></h3> <p>Joran supports including parts of a configuration file from another file. This is done by declaring a <code><include></code> @@ -1192,8 +1193,75 @@ </p> + <h3><a name="contextName" href="#contextName">Setting the context name</a></h3> + <p>As mentioned <a href="architecture.html#LoggerContext">in an + earlier chapter</a>, every logger is attached to logger context. By + default, the logger context is called "default". However, you can + set a different name with the help of the + <code><contextName></code> configuration directive. Note that + once set, the logger context name <a + href="../apidocs/ch/qos/logback/core/ContextBase.html#setName(java.lang.String)">cannot + be changed</a>. Setting the context name is a simple and + straightforward method in order to distinguish between multiple + applications logging to the same target. + </p> + + <em>Example 3.<span class="autoEx"/>: Set the context name and display it + (logback-examples/src/main/java/chapter3/contextName.xml)</em> + <p class="source"><configuration> + <b><contextName>myAppName</contextName></b> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%d <b>%contextName</b> [%t] %level %logger{36} - %msg%n</Pattern> + </layout> + </appender> + + <root level="debug"> + <appender-ref ref="STDOUT" /> + </root> +</configuration></p> + + <p>This last examples illustrates naming of the logger + context. Adding the the <a + href="layouts.html#conversionWord">contextName conversion word</a> + in layout's pattern will output the said name.</p> + + <h3><a name="insertFromJNDI" href="#insertFromJNDI">Obtaining + variables from JNDI</a></h3> + + <p>Under certain circumstances, you may want to make use of + env-entries in JNDI. The <code><insertFromJNDI></code> + configuration directive extracts an env-entry from JNDI and inserts + it as variable specified by the <span class="attr">as</span> + attribute. + </p> + + <em>Example 3.<span class="autoEx"/>: Insert as properties env-entries obtained via JNDI + (logback-examples/src/main/java/chapter3/insertFromJNDI.xml)</em> + <p class="source"><configuration> + <b><insertFromJNDI env-entry-name="java:comp/env/appName" as="<span class="green">appName"</span> /></b> + <b><contextName><span class="green">${appName}</span></contextName></b> + + <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%d %contextName %level %msg %logger{50}%n</Pattern> + </layout> + </appender> + + <root level="DEBUG"> + <appender-ref ref="CONSOLE" /> + </root> +</configuration></p> + + <p>In this last example, the "java:comp/env/appName" env-entry is + inserted as the <span class="variable">appName</span> property. Note + that the <code><contextName></code> directive sets the context + name based on the value of the <span class="variable">appName</span> + property inserted by the previous <code><insertFromJNDI></code> + directive.. +</p> <script src="../templates/footer.js" type="text/javascript"></script> </div> Modified: logback/trunk/logback-site/src/site/pages/manual/layouts.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/layouts.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/layouts.html Thu Dec 4 23:14:25 2008 @@ -382,7 +382,7 @@ <table class="bodyTable properties" border="0"> <tr> - <th>Conversion Word</th> + <th><a name="conversionWord" href="#conversionWord">Conversion Word</a></th> <th>Effect</th> </tr> @@ -477,12 +477,20 @@ </td> </tr> - <tr> + <tr> + <td align="center"> + <b>contextName</b><br/> + <b>cn</b><br/></td> + <td>Outputs the name of the logger context to which the + logger at the origin of the logging event is attached + to. </td> + </tr> + <tr class="alt"> <td align="center"> <b>d</b>{<em>pattern</em>} <br /> <b>date</b>{<em>pattern</em>} <br /> </td> - <td> + <td > <p>Used to output the date of the logging event. The date conversion word may be followed by an option enclosed between braces.</p> @@ -524,7 +532,7 @@ </td> </tr> - <tr class="alt"> + <tr> <td align="center"> <b>F / file</b> </td> @@ -541,7 +549,7 @@ </td> </tr> - <tr> + <tr class="alt"> <td align="center"> <b>caller{depth}</b> <b>caller{depth, evaluator-1, ... evaluator-n}</b> @@ -591,7 +599,7 @@ </td> </tr> - <tr class="alt"> + <tr> <td align="center"> <b>L / line</b> </td> @@ -610,7 +618,7 @@ </tr> - <tr> + <tr class="alt"> <td align="center"> <b>m / msg / message</b> </td> @@ -620,7 +628,7 @@ </td> </tr> - <tr class="alt"> + <tr> <td align="center"> <b>M / method</b> </td> @@ -638,7 +646,7 @@ </td> </tr> - <tr> + <tr class="alt"> <td align="center"> <b>n</b> </td> @@ -659,14 +667,14 @@ </tr> - <tr class="alt"> + <tr> <td align="center"> <b>p / le / level</b> </td> <td>Used to output the level of the logging event.</td> </tr> - <tr> + <tr class="alt"> <td align="center"> <b>r / relative</b> @@ -680,7 +688,7 @@ </tr> - <tr class="alt"> + <tr> <td align="center"> <b>t / thread</b> </td> @@ -692,7 +700,7 @@ </tr> - <tr> + <tr class="alt"> <td align="center"> <b>X</b>{<em>key</em>} <br /> <b>mdc</b>{<em>key</em>} <br /> @@ -721,7 +729,7 @@ </td> </tr> - <tr class="alt"> + <tr> <td align="center"> <b>ex</b>{<em>length</em>} <br /> <b>exception</b>{<em>length</em>} <br /> @@ -801,8 +809,7 @@ </td> </tr> - - <tr> + <tr class="alt"> <td align="center"> <b>xEx</b>{<em>length</em>} <br /> <b>xException</b>{<em>length</em>} <br /> @@ -856,10 +863,9 @@ </td> - </tr> - <tr class="b"> + <tr> <td align="center"> <b>nopex</b> <br /> <b>nopexception</b> @@ -879,7 +885,7 @@ </td> </tr> - <tr class="a"> + <tr class="alt"> <td align="center"> <b>marker</b> </td> Modified: logback/trunk/logback-site/src/site/pages/news.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/news.html (original) +++ logback/trunk/logback-site/src/site/pages/news.html Thu Dec 4 23:14:25 2008 @@ -96,6 +96,13 @@ a JVM with a <code>SecurityManager</code>. </p> + <p>Invoking the <code>LoggerContext.reset()</code> method resets + logger levels to their default value, that is <code>DEBUG</code> + for the root logger and <code>null</code> for all other + loggers. This was requested in <a + href="http://jira.qos.ch/browse/LBCLASSIC-90">LBCLASSIC-90</a> by + Mateusz Jedruch. + </p> <!-- ======================== minor ================== --> Modified: logback/trunk/pom.xml ============================================================================== --- logback/trunk/pom.xml (original) +++ logback/trunk/pom.xml Thu Dec 4 23:14:25 2008 @@ -73,17 +73,6 @@ <version>${slf4j.version}</version> </dependency> <dependency> - <groupId>org.slf4j</groupId> - <artifactId>log4j-over-slf4j</artifactId> - <version>${slf4j.version}</version> - </dependency> - <dependency> - <groupId>org.slf4j</groupId> - <artifactId>slf4j-ext</artifactId> - <version>${slf4j.version}</version> - </dependency> - - <dependency> <groupId>janino</groupId> <artifactId>janino</artifactId> <version>2.4.3</version>