[logback-dev] svn commit: r1180 - logback/trunk/logback-site/src/site/xdocTemplates/manual
noreply.seb at qos.ch
noreply.seb at qos.ch
Tue Jan 9 15:36:41 CET 2007
Author: seb
Date: Tue Jan 9 15:36:41 2007
New Revision: 1180
Modified:
logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml
Log:
Updated doc to display generics
Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml (original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml Tue Jan 9 15:36:41 2007
@@ -67,18 +67,18 @@
import ch.qos.logback.core.spi.LifeCycle;
-public interface Appender extends LifeCycle, ContextAware, FilterAttachable {
+public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachable {
public String getName();
- <b>void doAppend(Object event);</b>
- public void setLayout(Layout layout);
- public Layout getLayout();
+ <b>void doAppend(E event);</b>
+ public void setLayout(Layout<E> layout);
+ public Layout<E> getLayout();
public void setName(String name);
}</pre></div>
<p>
- Most of the methods in the Appender interface are made of setter
+ Most of the methods in the <code>Appender</code> interface are made of setter
and getter methods. A notable exception is the <code>doAppend()</code>
method taking an Object instance as its only parameter.
This method is perhaps the most important in the logback framework.
@@ -119,7 +119,7 @@
presenting a bit of its actual source code.
</p>
-<div class="source"><pre>public synchronized void doAppend(Object eventObject) {
+<div class="source"><pre>public synchronized void doAppend(E eventObject) {
// prevent re-entry.
if (guard) {
Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml (original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml Tue Jan 9 15:36:41 2007
@@ -62,13 +62,15 @@
layouts have nothing to do with large estates in Florida.
The
<code>format()</code>
- method in the Layout class takes an object that represents
+ method in the
+ <a href="../xref/ch/qos/logback/core/Layout.html"><code>Layout</code></a>
+ interface takes an object that represents
an event (of any type) and returns a String. A synopsis of the
- Layout interface is shown below.
+ <code>Layout</code> interface is shown below.
</p>
- <div class="source"><pre>public interface Layout extends ContextAware, LifeCycle {
+ <div class="source"><pre>public interface Layout<E> extends ContextAware, LifeCycle {
- String doLayout(Object event);
+ String doLayout(E event);
String getHeader();
String getFooter();
String getContentType();
@@ -85,11 +87,12 @@
<p>
Logback classic only processes events of type
- <code>ch.qos.logback.classic.LoggingEvent</code>.
+ <a href="../xref/ch/qos/logback/classic/spi/LoggingEvent.html">
+ <code>ch.qos.logback.classic.spi.LoggingEvent</code></a>.
Therefore, logback classic module imposes that
all its layouts implement
- the <code>ClassicLayout</code> interface that is
- shown below.
+ the <a href="../xref/ch/qos/logback/classic/ClassicLayout.html"><code>ClassicLayout</code>
+ </a> interface that is shown below.
</p>
<div class="source"><pre>public interface ClassicLayout extends Layout {
@@ -111,7 +114,8 @@
<p>Here is a possible implementation, authored by the Texan developer:</p>
<em>Example 5.0: Sample implementation of a Layout
- (logback-examples/src/main/java/chapter5/MySampleLayout.java)</em>
+ <a href="../xref/chapter5/MySampleLayout.html">
+ (logback-examples/src/main/java/chapter5/MySampleLayout.java)</a></em>
<div class="source"><pre>package chapter5;
import ch.qos.logback.classic.ClassicLayout;
@@ -139,7 +143,8 @@
<p>
Note that
<code>MySampleLayout</code>
- extends <code>LayoutBase</code>.
+ extends <a href="../xref/ch/qos/logback/core/LayoutBase.html">
+ <code>LayoutBase</code></a>.
This class manages trivial components of a <code>Layout</code>
such as started or stopped status, header, footer and
content type access or logging context awareness. It allows
@@ -192,10 +197,10 @@
</root>
</configuration></pre></div>
- <p>The sample application <code>chapter5.SampleLogging</code> configures logback with the
+ <p>The sample application <a href="../xref/chapter5/SampleLogging.html">
+ <code>chapter5.SampleLogging</code></a> configures logback with the
configuration script supplied as parameter and then logs a debug message,
- followed by an error message.
- See <em>src/main/java/chapter5/SampleLogging.java</em> for precise details.</p>
+ followed by an error message. </p>
<p>
To run this example execute the command
@@ -217,7 +222,8 @@
</p>
<p>
The
- <code>MySampleLayout2</code>
+ <a href="../xref/chapter5/MySampleLayout2.html"><code>MySampleLayout2</code>
+ </a>
class contains two attributes. The first one is a prefix that
can be added to the output. The second attribute is used to
choose wether to display the name of the thread from which
@@ -298,11 +304,10 @@
<p>
Logback classic ships with a flexible layout called
- <code>PatternLayout</code>, which implements the
+ <a href="../xref/ch/qos/logback/classic/PatternLayout.html">
+ <code>PatternLayout</code></a>, which implements the
<code>ClassicLayout</code> interface.
- As all classic layouts,
- <code>PatternLayout</code>
-
+ As all classic layouts, <code>PatternLayout</code>
takes a logging event and returns a String. However, the
returned String can be customized at will by tweaking its
conversion pattern.
@@ -326,7 +331,8 @@
</p>
<em>
Example 5.1: Sample usage of a PatternLayout
- (logback-examples/src/main/java/chapter5/PatternSample.java)
+ <a href="../xref/chapter5/PatternSample.html">
+ (logback-examples/src/main/java/chapter5/PatternSample.java)</a>
</em>
<div class="source"><pre>package chapter5;
@@ -994,7 +1000,8 @@
specifier is when
<code>PatternLayout</code>
is used with
- <code>EventEvaluator</code> objects.
+ <a href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html">
+ <code>EventEvaluator</code></a> objects.
</p>
<p>
<code>EventEvaluator</code> objects
@@ -1049,7 +1056,8 @@
<p>Let us test this configuration with the following code.</p>
<em>
Example 5.2: Sample usage of EventEvaluators
- (logback-examples/src/main/java/chapter5/CallerEvaluatorExample.java)
+ <a href="../xref/chapter5/CallerEvaluatorExample.html">
+ (logback-examples/src/main/java/chapter5/CallerEvaluatorExample.java)</a>
</em>
<div class="source"><pre>package chapter5;
@@ -1096,7 +1104,7 @@
</p>
<p>
Here is the output of the
- <code>EventEvaluatorExample</code>
+ <code>CallerEvaluatorExample</code>
class.
</p>
<div class="source"><pre>0 [main] DEBUG - I know me 0
@@ -1202,14 +1210,19 @@
<p>In that case, two steps are needed.</p>
<p>First, one must implement her own <code>Converter</code>
- class. <code>Converter</code> objects are responsible to extract a specific information out of
- a <code>LoggingEvent</code>. When <em>%logger</em> is used, a <code>LoggerConverter</code>
+ class. <a href="../xref/ch/qos/logback/core/pattern/Converter.html">
+ <code>Converter</code></a> objects are responsible to extract a specific information out of
+ a <code>LoggingEvent</code>. When <em>%logger</em> is used, a
+ <a href="../xref/ch/qos/logback/classic/pattern/LoggerConverter.html">
+ <code>LoggerConverter</code></a>
is called to extract the name of the logger from the <code>LoggingEvent</code>.</p>
<p>Let us say that our customized <code>Converter</code> will output the level of the logging
event, colored following ANSI rules. Here is the necessary implementation:</p>
-<em> Example 5.4: Sample Converter Example (src/main/java/chapter5/MySampleConverter.java)</em>
+<em> Example 5.4: Sample Converter Example
+<a href="../xref/chapter5/MySampleConverter.html">
+(src/main/java/chapter5/MySampleConverter.java)</a></em>
<div class="source"><pre>package chapter5;
import ch.qos.logback.classic.Level;
@@ -1282,13 +1295,16 @@
our custom conversion word had always been here.</p>
<p>The intersted reader might want to take a look at other <code>Converter</code> implementations
- like <code>MDCConverter</code> to learn how to implement more complex behaviours, involving
+ like
+ <a href="../xref/ch/qos/logback/classic/pattern/MDCConverter.html">
+ <code>MDCConverter</code></a> to learn how to implement more complex behaviours, involving
the use of options, in her custom <code>Converter</code> objects.
</p>
<a name="ClassicHTMLLayout"/>
<h3>HTMLLayout</h3>
- <p>HTMLLayout outputs events in an HTML table. Each row of the table corresponds to a
+ <p><a href="../xref/ch/qos/logback/classic/html/HTMLLayout.html">
+ <code>HTMLLayout</code></a> outputs events in an HTML table. Each row of the table corresponds to a
logging event.</p>
<p>Here is a sample of the output that can be obtained using <code>HTMLLayout</code>
@@ -1321,19 +1337,23 @@
a better solution is available in the form of
implementations of the <code>IThrowableRenderer</code> interface.
These implementations can be called and assigned to
- HTMLLayout to manage the display of anything related to
+ <code>HTMLLayout</code> to manage the display of anything related to
Exceptions.
</p>
<p>
- By default, a <code>DefaultThrowableRenderer</code> is
- assigned to the HTMLLayout. It writes the Exception on a <em>new
+ By default, a
+ <a href="../xref/ch/qos/logback/classic/html/DefaultThrowableRenderer.html">
+ <code>DefaultThrowableRenderer</code></a> is
+ assigned to the <code>HTMLLayout</code>. It writes the Exception on a <em>new
table row</em>, along with its stacktrace, in a easily readable
manner, like presented in the picture above.
</p>
<p>
If one wants to use the
<em>%ex</em>
- pattern anyway, then a <code>NOPThrowableRenderer</code> can be specified
+ pattern anyway, then a
+ <a href="../xref/ch/qos/logback/core/html/NOPThrowableRenderer.html">
+ <code>NOPThrowableRenderer</code></a> can be specified
in the configuration file.
</p>
<p>
@@ -1405,15 +1425,6 @@
</configuration></pre></div>
<h2>Logback access</h2>
- <p>Just like <code>ClassicLayout</code> restricts the possible <code>Layout</code> classes
- for the classic module, the <code>AccessLayout</code> imposes a structure for <code>Layout</code> objects
- in the access module. It is reproduced below.</p>
-
- <div class="source"><pre>public interface AccessLayout extends Layout {
-
- String doLayout(AccessEvent event);
-
-}</pre></div>
<p>Many access layouts are mere adaptations of classic layouts. Logback
classic and access modules address different needs, but offer comparable power
@@ -1422,12 +1433,11 @@
<h3>Writing your own Layout</h3>
<p>Writing a custom <code>Layout</code> for logback access is nearly identical
as to writing a <code>Layout</code> for the classic module.</p>
- <p>The only difference comes from the fact that access layouts must implement
- the <code>AccessLayout</code> interface instead <code>ClassicLayout</code>.</p>
<a name="AccessPatternLayout" />
<h3>PatternLayout</h3>
- <p>Access' <code>PatternLayout</code> work the exact same way as it's classic counterpart.
+ <p>Access' <a href="../xref/ch/qos/logback/access/PatternLayout.html">
+ <code>PatternLayout</code></a> work the exact same way as it's classic counterpart.
</p>
<p>However, the conversion specifier are different, giving specific access to request
and response objects' attributes.</p>
@@ -1604,7 +1614,7 @@
<td>
<p>
Attribute of the request.
- </p>^
+ </p>
<p>This conversion word takes the first option in braces and looks
for the corresponding attribute in the request.</p>
<p><b>%reqAttribute{SOME_ATTRIBUTE}</b>
@@ -1655,7 +1665,9 @@
<a name="AccessHTMLLayout" />
<h3>HTMLLayout</h3>
- <p>The access version of <code>HTMLLayout</code> works like logback classic's
+ <p>The access version of
+ <a href="../xref/ch/qos/logback/access/html/HTMLLayout.html">
+ <code>HTMLLayout</code></a> works like logback classic's
version.</p>
<p>By default, it will create a table containing the following data:</p>
@@ -1672,13 +1684,13 @@
<img src="images/chapter5/htmlLayoutAccess.gif" alt="Access HTML Layout Sample Image"/>
<p>What's better than a real world example? Our own log4j properties to logback configuration
- <a href="http://logback.qos.ch/translator">translator</a>
+ <a href="http://logback.qos.ch/translator/">translator</a>
is using logback access to showcase a live ouput, using a <code>RollingFileAppender</code> and
access' <code>HTMLLayout</code>.</p>
<p>You can see the file by <a href="http://logback.qos.ch/translator/logs/access.html">following this link</a>.</p>
<p>Just like any access log, it can be altered simply by visiting the
- <a href="http://logback.qos.ch/translator">translator</a> application.</p>
+ <a href="http://logback.qos.ch/translator/">translator</a> application.</p>
</body>
</document>
More information about the logback-dev
mailing list