[logback-dev] [GIT] Logback: the generic, reliable, fast and flexible logging framework. branch, master, updated. v0.9.18-69-g4af0b83
added by portage for gitosis-gentoo
git-noreply at pixie.qos.ch
Mon Mar 8 22:13:47 CET 2010
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Logback: the generic, reliable, fast and flexible logging framework.".
The branch, master has been updated
via 4af0b83eac54b45fb9d7e78697b2c222a8ef1845 (commit)
from 9a9462cf0af145a7c80fc655ff8298416393b3bd (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=4af0b83eac54b45fb9d7e78697b2c222a8ef1845
http://github.com/ceki/logback/commit/4af0b83eac54b45fb9d7e78697b2c222a8ef1845
commit 4af0b83eac54b45fb9d7e78697b2c222a8ef1845
Author: Ceki Gulcu <ceki at qos.ch>
Date: Mon Mar 8 22:13:05 2010 +0100
Ongoing work on the documentation
diff --git a/logback-core/src/main/java/ch/qos/logback/core/encoder/Encoder.java b/logback-core/src/main/java/ch/qos/logback/core/encoder/Encoder.java
index 42a46d9..4379580 100644
--- a/logback-core/src/main/java/ch/qos/logback/core/encoder/Encoder.java
+++ b/logback-core/src/main/java/ch/qos/logback/core/encoder/Encoder.java
@@ -19,9 +19,50 @@ import java.io.OutputStream;
import ch.qos.logback.core.spi.ContextAware;
import ch.qos.logback.core.spi.LifeCycle;
+/**
+ * Encoders are responsible for transform an incoming event into a byte array
+ * *and* writing out the byte array onto the appropriate {@link OutputStream}.
+ * Thus, encoders have total control of what and when gets written to the
+ * {@link OutputStream} maintained by the owning appender.
+ *
+ *
+ * @author Ceki Gülcü
+ * @author Joen Huxhorn
+ * @author Maarten Bosteels
+ *
+ * @param <E>
+ * event type
+ * @since 0.9.19
+ */
public interface Encoder<E> extends ContextAware, LifeCycle {
+ /**
+ * This method is called when the owning appender starts or whenever output
+ * needs to be directed to a new OutputStream, for instance as a result of a
+ * rollover. Implementing encoders should at the very least remember the
+ * OutputStream passed as argument and use it in future operations.
+ *
+ * @param os
+ * @throws IOException
+ */
void init(OutputStream os) throws IOException;
+
+ /**
+ * Encode and write an event to the appropriate {@link OutputStream}.
+ * Implementations are free to differ writing out of the encoded event and
+ * instead write in batches.
+ *
+ * @param event
+ * @throws IOException
+ */
void doEncode(E event) throws IOException;
+
+ /**
+ * This method is called prior to the closing of the underling
+ * {@link OutputStream}. Implementations MUST not close the underlying
+ * {@link OutputStream} which is the responsibility of the owning appender.
+ *
+ * @throws IOException
+ */
void close() throws IOException;
}
diff --git a/logback-core/src/main/java/ch/qos/logback/core/html/LayoutWrappingEncoder.java b/logback-core/src/main/java/ch/qos/logback/core/encoder/LayoutWrappingEncoder.java
similarity index 97%
rename from logback-core/src/main/java/ch/qos/logback/core/html/LayoutWrappingEncoder.java
rename to logback-core/src/main/java/ch/qos/logback/core/encoder/LayoutWrappingEncoder.java
index ed91af0..0c3f2bf 100644
--- a/logback-core/src/main/java/ch/qos/logback/core/html/LayoutWrappingEncoder.java
+++ b/logback-core/src/main/java/ch/qos/logback/core/encoder/LayoutWrappingEncoder.java
@@ -1,4 +1,4 @@
-package ch.qos.logback.core.html;
+package ch.qos.logback.core.encoder;
import java.io.IOException;
import java.io.OutputStream;
@@ -6,7 +6,6 @@ import java.nio.charset.Charset;
import ch.qos.logback.core.CoreConstants;
import ch.qos.logback.core.Layout;
-import ch.qos.logback.core.encoder.EncoderBase;
public class LayoutWrappingEncoder<E> extends EncoderBase<E> {
diff --git a/logback-core/src/main/java/ch/qos/logback/core/encoder/ObjectStreamEncoder.java b/logback-core/src/main/java/ch/qos/logback/core/encoder/ObjectStreamEncoder.java
index 036e498..c97c139 100644
--- a/logback-core/src/main/java/ch/qos/logback/core/encoder/ObjectStreamEncoder.java
+++ b/logback-core/src/main/java/ch/qos/logback/core/encoder/ObjectStreamEncoder.java
@@ -83,7 +83,8 @@ public class ObjectStreamEncoder<E> extends EncoderBase<E> {
int offset = 2*CoreConstants.BYTES_PER_INT;
ByteArrayUtil.writeInt(byteArray,offset, byteArray.length-offset);
}
-
+
+ @Override
public void init(OutputStream os) throws IOException {
super.init(os);
bufferList.clear();
diff --git a/logback-core/src/main/java/ch/qos/logback/core/pattern/PatternLayoutEncoderBase.java b/logback-core/src/main/java/ch/qos/logback/core/pattern/PatternLayoutEncoderBase.java
index da84cb9..1128459 100644
--- a/logback-core/src/main/java/ch/qos/logback/core/pattern/PatternLayoutEncoderBase.java
+++ b/logback-core/src/main/java/ch/qos/logback/core/pattern/PatternLayoutEncoderBase.java
@@ -1,7 +1,7 @@
package ch.qos.logback.core.pattern;
import ch.qos.logback.core.Layout;
-import ch.qos.logback.core.html.LayoutWrappingEncoder;
+import ch.qos.logback.core.encoder.LayoutWrappingEncoder;
public class PatternLayoutEncoderBase<E> extends LayoutWrappingEncoder<E> {
diff --git a/logback-core/src/test/java/ch/qos/logback/core/OutputStreamAppenderTest.java b/logback-core/src/test/java/ch/qos/logback/core/OutputStreamAppenderTest.java
index 0d475c8..1774d0a 100644
--- a/logback-core/src/test/java/ch/qos/logback/core/OutputStreamAppenderTest.java
+++ b/logback-core/src/test/java/ch/qos/logback/core/OutputStreamAppenderTest.java
@@ -22,7 +22,7 @@ import org.junit.After;
import org.junit.Before;
import org.junit.Test;
-import ch.qos.logback.core.html.LayoutWrappingEncoder;
+import ch.qos.logback.core.encoder.LayoutWrappingEncoder;
import ch.qos.logback.core.pattern.parser.SamplePatternLayout;
public class OutputStreamAppenderTest {
diff --git a/logback-examples/src/main/java/chapters/layouts/PatternSample.java b/logback-examples/src/main/java/chapters/layouts/PatternSample.java
index d4d7786..8b8ec89 100644
--- a/logback-examples/src/main/java/chapters/layouts/PatternSample.java
+++ b/logback-examples/src/main/java/chapters/layouts/PatternSample.java
@@ -16,6 +16,7 @@ package chapters.layouts;
import org.slf4j.LoggerFactory;
import ch.qos.logback.classic.Logger;
+import ch.qos.logback.classic.LoggerContext;
import ch.qos.logback.classic.encoder.PatternLayoutEncoder;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.ConsoleAppender;
@@ -24,14 +25,17 @@ public class PatternSample {
static public void main(String[] args) throws Exception {
Logger rootLogger = (Logger) LoggerFactory.getLogger("root");
+ LoggerContext loggerContext = rootLogger.getLoggerContext();
+ loggerContext.reset();
- PatternLayoutEncoder layout = new PatternLayoutEncoder();
- layout.setPattern("%-5level [%thread]: %message%n");
- layout.start();
+ PatternLayoutEncoder encoder = new PatternLayoutEncoder();
+ encoder.setContext(loggerContext);
+ encoder.setPattern("%-5level [%thread]: %message%n");
+ encoder.start();
ConsoleAppender<ILoggingEvent> appender = new ConsoleAppender<ILoggingEvent>();
- appender.setContext(rootLogger.getLoggerContext());
- appender.setEncoder(layout);
+ appender.setContext(loggerContext);
+ appender.setEncoder(encoder);
appender.start();
rootLogger.addAppender(appender);
diff --git a/logback-examples/src/main/java/chapters/layouts/SampleLogging.java b/logback-examples/src/main/java/chapters/layouts/SampleLogging.java
index 8a694cc..5e7d55c 100644
--- a/logback-examples/src/main/java/chapters/layouts/SampleLogging.java
+++ b/logback-examples/src/main/java/chapters/layouts/SampleLogging.java
@@ -23,20 +23,17 @@ import ch.qos.logback.core.util.StatusPrinter;
public class SampleLogging {
- public static void main(String[] args) {
+ public static void main(String[] args) throws JoranException {
Logger logger = LoggerFactory.getLogger(SampleLogging.class);
LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
- try {
- JoranConfigurator configurator = new JoranConfigurator();
- lc.reset();
- configurator.setContext(lc);
- configurator.doConfigure(args[0]);
- } catch (JoranException je) {
- StatusPrinter.print(lc);
- }
-
+ JoranConfigurator configurator = new JoranConfigurator();
+ lc.reset();
+ configurator.setContext(lc);
+ configurator.doConfigure(args[0]);
+ StatusPrinter.printInCaseOfErrorsOrWarnings(lc);
+
logger.debug("Everything's going well");
logger.error("maybe not quite...");
}
diff --git a/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml b/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml
index 9cff3bb..22a13f9 100644
--- a/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml
+++ b/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml
@@ -1,11 +1,12 @@
-<configuration>
+<configuration debug="true">
- <appender name="STDOUT"
- class="ch.qos.logback.core.ConsoleAppender">
- <layout class="chapters.layouts.MySampleLayout" />
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+ <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
+ <layout class="chapters.layouts.MySampleLayout" />
+ </encoder>
</appender>
- <root level="debug">
+ <root level="DEBUG">
<appender-ref ref="STDOUT" />
</root>
</configuration>
\ No newline at end of file
diff --git a/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig2.xml b/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig2.xml
index 5c302fb..776b085 100644
--- a/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig2.xml
+++ b/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig2.xml
@@ -1,11 +1,13 @@
<configuration>
- <appender name="STDOUT"
- class="ch.qos.logback.core.ConsoleAppender">
- <layout class="chapters.layouts.MySampleLayout2">
- <prefix>MyPrefix</prefix>
- <printThreadName>false</printThreadName>
- </layout>
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+
+ <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
+ <layout class="chapters.layouts.MySampleLayout2">
+ <prefix>MyPrefix</prefix>
+ <printThreadName>false</printThreadName>
+ </layout>
+ </encoder>
</appender>
<root level="debug">
diff --git a/logback-site/src/site/pages/manual/encoders.html b/logback-site/src/site/pages/manual/encoders.html
index 9b2ccad..fcb07d4 100644
--- a/logback-site/src/site/pages/manual/encoders.html
+++ b/logback-site/src/site/pages/manual/encoders.html
@@ -7,7 +7,7 @@
<link rel="stylesheet" type="text/css" href="../css/common.css" />
<link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" />
<link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" />
- <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" /
+ <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" />
</head>
<body onload="prettyPrint()">
<script type="text/javascript">prefix='../';</script>
@@ -23,7 +23,168 @@
<div id="content">
- <h1>Chapter 6: Encoders</h1>
+ <h1>Chapter 5: Encoders</h1>
+
+ <div class="quote">
+ <p><b>ACTION THIS DAY</b> Make sure they have all they want on
+ extreme priority and report to me that this has been done.
+ </p>
+ <p>—CHURCHILL on October 1941 to General Hastings Ismay in
+ response to a request for more resources signed by Alan Turing
+ and his cryptanalyst colleagues at Bletchley Park</p>
+ </div>
+
+ <script src="../templates/creative.js" type="text/javascript"></script>
+ <script src="../templates/setup.js" type="text/javascript"></script>
+
+
+ <h2>What is an encoder</h2>
+
+ <p>Encoders are responsible for transforming an event into a byte
+ array as well as writing out that byte array into an
+ <code>OutputStream</code>. Encoders were introduced in logback
+ version 0.9.19. In previous versions, most appenders relied on a
+ layout to transform an event into a string and write it out using
+ a <code>java.io.Writer</code>. In previous versions of logback,
+ users would nest a <code>PatternLayout</code> within
+ <code>FileAppender</code>. As for logback 0.9.19,
+ <code>FileAppender</code> and sub-classes <a
+ href="../codes.html#layoutInsteadOfEncoder">expect an encoder and no
+ longer admit a layout</a>.
+ </p>
+
+ <p>Why the breaking change?
+ </p>
+
+ <p>Layouts, as discussed in detail in the next chapter, are only
+ able to transform an event into a String. Moreover, given that a
+ layout has no control over when events get written out, layouts
+ cannot aggregate events into batches. Contrast this with encoders
+ which not only have total control over the format of the bytes
+ written out, also control when (and if) those bytes get written
+ out.
+ </p>
+
+ <p>At present time (2010-03-08), <code>PatternLayotEncoder</code>
+ is the only really useful encoder. It merely wraps a
+ <code>PatternLayout</code> which does most of the work. Thus, may
+ seem that encoders do not bring much to the table except needless
+ complexity. However, we hope that with the advent of new and
+ powerful encoders this impression will change.</p>
+
+ <h2><a name="interface" href="#interface">Encoder
+ interface</a></h2>
+
+ <p>Encoders are responsible for transforming an incoming event
+ into a byte array <b>and</b> writing out the resulting byte array
+ onto the appropriate OutputStream. Thus, encoders have total
+ control of what and when bytes gets written to the
+ <code>OutputStream</code> maintained by the owning appender. Here
+ is the <a
+ href="../xref/ch/qos/logback/core/encoder/Encoder.html">Encoder
+ interface:</a>
+
+ </p>
+ <pre class="prettyprint source">package ch.qos.logback.core.encoder;
+
+public interface Encoder<E> extends ContextAware, LifeCycle {
+
+ /**
+ * This method is called when the owning appender starts or whenever output
+ * needs to be directed to a new OutputStream, for instance as a result of a
+ * rollover.
+ */
+ void init(OutputStream os) throws IOException;
+
+ /**
+ * Encode and write an event to the appropriate {@link OutputStream}.
+ * Implementations are free to differ writing out of the encoded event and
+ * instead write in batches.
+ */
+ void doEncode(E event) throws IOException;
+
+
+ /**
+ * This method is called prior to the closing of the underling
+ * {@link OutputStream}. Implementations MUST not close the underlying
+ * {@link OutputStream} which is the responsibility of the owning appender.
+ */
+ void close() throws IOException;
+}</pre>
+
+ <p>As you can see, the Encoder interface consists of few method
+ but surprisingly enough many useful things can be accomplished with
+ those methods.
+ </p>
+
+ <h2><a name="LayoutWrappingEncoder"
+ href="#LayoutWrappingEncoder">LayoutWrappingEncoder</a></h2>
+
+ <p>Until logback version 0.9.19, appenders which offered
+ flexibility with respect to the output format relied on
+ layouts. As there exists a substantial body of code based on the
+ layout interface, we need a way for encoders inter-operate with
+ layouts. <a
+ href="../xref/ch/qos/logback/core/encoder/LayoutWrappingEncoder.html">LayoutWrappingEncoder</a>
+ bridges the gap between encoders and layouts. It implements the
+ encoder interface and wraps a layout to which it delegates the
+ work of transforming an event into string.
+ </p>
+
+ <p>Below is an excerpt from the <code>LayoutWrappingEncoder</code>
+ class illustrating how delegation to the wrapped layout instance
+ is done.</p>
+
+ <pre class="prettyprint source">package ch.qos.logback.core.encoder;
+
+public class LayoutWrappingEncoder<E> extends EncoderBase<E> {
+
+ protected Layout<E> layout;
+ private Charset charset;
+
+ public void doEncode(E event) throws IOException {
+ String txt = layout.doLayout(event);
+ outputStream.write(convertToBytes(txt));
+ outputStream.flush();
+ }
+
+ private byte[] convertToBytes(String s) {
+ if (charset == null) {
+ return s.getBytes();
+ } else {
+ return s.getBytes(charset);
+ }
+ }
+}</pre>
+
+ <p>The <code>doEncode</code>() method starts by having the wrapped
+ layout convert the incoming event into string. The resulting text
+ string is converted to bytes according to the charset encoding
+ chosen by the user. Those bytes are then written to the
+ <code>OutputStream</code> given by the owning appender and the
+ <code>OutputStream</code> is immediately flushed.
+ </p>
+
+
+ <h2><a name="PatternLayoutEncoder"
+ href="#PatternLayoutEncoder">PatternLayoutEncoder</a></h2>
+
+ <p>Given that <code>PatternLayout</code> is the most commonly used
+ layout, logback caters for this common use case with
+ <code>PatternLayoutEncoder</code>, an extension of
+ <code>LayoutWrappingEncoder</code> restricted to wrapping
+ instances of <code>PatternLayout</code>.
+ </p>
+
+ <p>As of logback version 9.9.19, whenever a
+ <code>FileAppender</code> or one of its sub-classes was configured
+ with a <code>PatternLayout</code>, a
+ <code>PatternLayoutEncoder</code> must be used instead. This is
+ explained in the <a
+ href="../codes.html#layoutInsteadOfEncoder">relevant entry in the
+ logback error codes</a>.
+ </p>
+
</div>
</body>
</html>
diff --git a/logback-site/src/site/pages/manual/index.html b/logback-site/src/site/pages/manual/index.html
index e8d7e21..8b832d0 100644
--- a/logback-site/src/site/pages/manual/index.html
+++ b/logback-site/src/site/pages/manual/index.html
@@ -47,8 +47,8 @@
<li><p>discussion of best logback practices and anti-patterns</p></li>
<li><p>logback configuration scripts in XML format</p></li>
<li><p>appenders</p></li>
- <li><p>layouts</p></li>
<li><p>encoders</p></li>
+ <li><p>layouts</p></li>
<li><p>filters</p></li>
<li><p>mapped diagnostic contexts</p></li>
<li><p>joran, logback's configuration system</p></li>
@@ -85,13 +85,13 @@
<li><p>
<a href="appenders.html"><b>Chapter 4: Appenders</b></a>
</p></li>
-
+
+ <li><p><a href="encoders.html"><b>Chapter 5:
+ Encoders</b></a></p>
+ </li>
+
<li><p>
- <a href="layouts.html"><b>Chapter 5: Layouts</b></a>
- </p></li>
-
- <li><p>
- <a href="encoders.html"><b>Chapter 6: Encoders</b></a>
+ <a href="layouts.html"><b>Chapter 6: Layouts</b></a>
</p></li>
<li><p>
diff --git a/logback-site/src/site/pages/manual/layouts.html b/logback-site/src/site/pages/manual/layouts.html
index 35e165a..b4b176f 100644
--- a/logback-site/src/site/pages/manual/layouts.html
+++ b/logback-site/src/site/pages/manual/layouts.html
@@ -24,7 +24,7 @@
</div>
<div id="content">
- <h1>Chapter 5: Layouts</h1>
+ <h1>Chapter 6: Layouts</h1>
<div class="quote">
<p>TCP implementations will follow a general principle of
@@ -39,10 +39,9 @@
<h2>What is a layout?</h2>
- <p>While appenders are responsible for writing logging output to
- an appender dependent device, layouts are responsible for the
- format of the output. In case you were wondering, layouts have
- nothing to do with large estates in Florida. The
+ <p>In case you were wondering, layouts have nothing to do with
+ large estates in Florida. Layouts are logback components
+ responsible for transforming an incoming event into a String. The
<code>format()</code> 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)
@@ -53,13 +52,15 @@
<pre class="prettyprint source">public interface Layout<E> extends ContextAware, LifeCycle {
String doLayout(E event);
- String getHeader();
- String getFooter();
+ String getFileHeader();
+ String getPresentationHeader();
+ String getFileFooter();
+ String getPresentationFooter();
String getContentType();
}</pre>
<p>This interface is rather simple and yet is sufficent for many
- formatting needs. The Texan developer from Texas, who you might
+ formatting needs. The Texan developer from Texas, whom you might
know from Joseph Heller's <em>Catch-22</em>, might exclaim: it
just takes five methods to implement a layout!!?
</p>
@@ -71,7 +72,9 @@
<code>ch.qos.logback.classic.spi.ILoggingEvent</code></a>. This
fact will be apparent throughout this section.</p>
- <h3>Writing your own Layout</h3>
+ <h2><a name="writingYourOwnLayout"
+ href="#writingYourOwnLayout">Writing your own custom
+ Layout</a></h2>
<p>Let us implement a simple yet functional layout for the
logback-classic module that prints the time elapsed since the
@@ -114,14 +117,13 @@ public class MySampleLayout extends LayoutBase<ILoggingEvent> {
<p>Note that <code>MySampleLayout</code> extends <a
href="../xref/ch/qos/logback/core/LayoutBase.html">
- <code>LayoutBase</code></a>. This class manages state shared by
- all <code>Layout</code> classes, such as whether the layout is
- started or stopped, header, footer and content type data. It
- allows the developer to concentrate on the formatting expected
- from his/her <code>Layout</code>. Note that the
- <code>LayoutBase</code> class is generic. In its class
- declaration, <code>MySampleLayout</code> extends
- <code>LayoutBase<ILoggingEvent></code>.
+ <code>LayoutBase</code></a>. This class manages state common to
+ all layout instances, such as whether the layout is started or
+ stopped, header, footer and content type data. It allows the
+ developer to concentrate on the formatting expected from his/her
+ <code>Layout</code>. Note that the <code>LayoutBase</code> class
+ is generic. In its class declaration, <code>MySampleLayout</code>
+ extends <code>LayoutBase<ILoggingEvent></code>.
</p>
<p>The <code>doLayout(ILoggingEvent event)</code> method, i.e. the
@@ -144,21 +146,27 @@ public class MySampleLayout extends LayoutBase<ILoggingEvent> {
contents of exceptions as well.
</p>
- <h3>Configuring your custom layout</h3>
+ <h3><a name="configuringYourOwnLayout"
+ href="#configuringYourOwnLayout">Configuring your custom
+ layout</a></h3>
- <p>Custom layouts are configured as any other layout. Here is as
- example:</p>
+ <p>Custom layouts are configured as any other component. As
+ mentioned earlier, <code>FileAppender</code> and its sub-classes
+ expect an encoder which we provide in the form of
+ <code>LayoutWrappingEncoder</code> which wraps
+ <code>MySampleLayout</code>. Here is the configuration file:</p>
- <em>Example 5.0: Configuration of MySampleLayout
- (logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml)</em>
+ <em>Example: Configuration of MySampleLayout
+ (logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml)</em>
<pre class="prettyprint source"><configuration>
- <appender name="STDOUT"
- class="ch.qos.logback.core.ConsoleAppender">
- <b><layout class="chapters.layouts.MySampleLayout" /></b>
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+ <b><encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder"></b>
+ <b><layout class="chapters.layouts.MySampleLayout" /></b>
+ <b></encoder></b>
</appender>
- <root level="debug">
+ <root level="DEBUG">
<appender-ref ref="STDOUT" />
</root>
</configuration></pre>
@@ -255,15 +263,16 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> {
<pre class="prettyprint source"><configuration>
- <appender name="STDOUT"
- class="ch.qos.logback.core.ConsoleAppender">
- <layout class="chapters.layouts.MySampleLayout2">
- <b><prefix>MyPrefix</prefix></b>
- <b><printThreadName>false</printThreadName></b>
- </layout>
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+ <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
+ <layout class="chapters.layouts.MySampleLayout2">
+ <b><prefix>MyPrefix</prefix></b>
+ <b><printThreadName>false</printThreadName></b>
+ </layout>
+ </encoder>
</appender>
- <root level="debug">
+ <root level="DEBUG">
<appender-ref ref="STDOUT" />
</root>
</configuration></pre>
@@ -272,8 +281,8 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> {
- <h3><a name="ClassicPatternLayout"
- href="#ClassicPatternLayout">PatternLayout</a></h3>
+ <h2><a name="ClassicPatternLayout"
+ href="#ClassicPatternLayout">PatternLayout</a></h2>
<p>Logback classic ships with a flexible layout called <a
href="../xref/ch/qos/logback/classic/PatternLayout.html">
@@ -295,8 +304,17 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> {
braces. The conversion word controls the type of data to use, e.g.
logger name, level, date, thread name. The format modifiers
control such things as field width, padding, and left or right
- justification. The following is a simple example.
+ justification.
</p>
+
+ <p>Given that <code>FileAppender</code> and sub-classes expect an
+ encoder, the <code>PatternLayout</code> instance must be wrapped
+ within an encoder before being used as a sub-component of
+ <code>FileAppender</code>. <code>PatternLayoutEncoder</code> is
+ designed solely for the purpose of wrapping a
+ <code>PatternLayout</code> instance so that it can be seen as
+ encoder. Here is an example:</p>
+
<em>
Example 5.1: Sample usage of a PatternLayout
<a href="../xref/chapters/layouts/PatternSample.html">
@@ -307,21 +325,28 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> {
import org.slf4j.LoggerFactory;
import ch.qos.logback.classic.Logger;
-import ch.qos.logback.classic.PatternLayout;
+import ch.qos.logback.classic.LoggerContext;
+import ch.qos.logback.classic.encoder.PatternLayoutEncoder;
+import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.ConsoleAppender;
public class PatternSample {
static public void main(String[] args) throws Exception {
- Logger rootLogger = (Logger)LoggerFactory.getLogger("root");
+ Logger rootLogger = (Logger)LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);
+ LoggerContext loggerContext = rootLogger.getLoggerContext();
+ // we are not interested in auto-configuration
+ loggerContext.reset();
- <b>PatternLayout layout = new PatternLayout();</b>
- <b>layout.setPattern("%-5level [%thread]: %message%n");</b>
- <b>layout.start();</b>
+ <b>PatternLayoutEncoder encoder = new PatternLayoutEncoder();</b>
+ <b>encoder.setContext(loggerContext);</b>
+ <b>encoder.setPattern("%-5level [%thread]: %message%n");</b>
+ <b>encoder.start();</b>
ConsoleAppender<ILoggingEvent> appender = new ConsoleAppender<ILoggingEvent>();
- appender.setContext(rootLogger.getLoggerContext());
- appender.setLayout(layout); appender.start();
+ appender.setContext(loggerContext);
+ appender.setEncoder(encoder);
+ appender.start();
rootLogger.addAppender(appender);
@@ -1731,7 +1756,8 @@ public class TrivialMain {
modules address different needs, but in general offer comparable
functionality.</p>
- <h3>Writing your own Layout</h3>
+ <h2>Writing your own Layout</h2>
+
<p>Writing a custom <code>Layout</code> for logback access is
nearly identical to its sibling<code>Layout</code> in
logback-classic.</p>
diff --git a/logback-site/src/site/pages/manual/menu.js b/logback-site/src/site/pages/manual/menu.js
index c41b284..d7679cb 100644
--- a/logback-site/src/site/pages/manual/menu.js
+++ b/logback-site/src/site/pages/manual/menu.js
@@ -4,8 +4,8 @@ document.write('<p class="menu"><a href="introduction.html"><b>Ch1: Introduction
document.write('<p class="menu"><a href="architecture.html"><b>Ch2: Architecture</b></a>');
document.write('<p class="menu"><a href="configuration.html"><b>Ch3: Configuration</b></a>');
document.write('<p class="menu"><a href="appenders.html"><b>Ch4: Appenders</b></a>');
-document.write('<p class="menu"><a href="layouts.html"><b>Ch5: Layouts</b></a>');
-document.write('<p class="menu"><a href="encoders.html"><b>Ch6: Encoders</b></a>');
+document.write('<p class="menu"><a href="encoders.html"><b>Ch5: Encoders</b></a>');
+document.write('<p class="menu"><a href="layouts.html"><b>Ch6: Layouts</b></a>');
document.write('<p class="menu"><a href="filters.html"><b>Ch7: Filters</b></a>');
document.write('<p class="menu"><a href="mdc.html"><b>Ch8: Mapped Diagnostic Contexts</b></a>');
document.write('<p class="menu"><a href="loggingSeparation.html"><b>Ch9: Logging Separation</b></a>');
-----------------------------------------------------------------------
Summary of changes:
.../java/ch/qos/logback/core/encoder/Encoder.java | 41 +++++
.../{html => encoder}/LayoutWrappingEncoder.java | 3 +-
.../logback/core/encoder/ObjectStreamEncoder.java | 3 +-
.../core/pattern/PatternLayoutEncoderBase.java | 2 +-
.../qos/logback/core/OutputStreamAppenderTest.java | 2 +-
.../main/java/chapters/layouts/PatternSample.java | 14 +-
.../main/java/chapters/layouts/SampleLogging.java | 17 +--
.../java/chapters/layouts/sampleLayoutConfig.xml | 11 +-
.../java/chapters/layouts/sampleLayoutConfig2.xml | 14 +-
logback-site/src/site/pages/manual/encoders.html | 165 +++++++++++++++++++-
logback-site/src/site/pages/manual/index.html | 14 +-
logback-site/src/site/pages/manual/layouts.html | 114 ++++++++-----
logback-site/src/site/pages/manual/menu.js | 4 +-
13 files changed, 318 insertions(+), 86 deletions(-)
rename logback-core/src/main/java/ch/qos/logback/core/{html => encoder}/LayoutWrappingEncoder.java (97%)
hooks/post-receive
--
Logback: the generic, reliable, fast and flexible logging framework.
More information about the logback-dev
mailing list