Author: seb Date: Fri Dec 1 18:13:51 2006 New Revision: 1053 Added: logback/trunk/logback-examples/src/main/java/chapter4/CountingConsoleAppender.java logback/trunk/logback-examples/src/main/java/chapter4/countingConsole.xml Modified: logback/trunk/logback-examples/ (props changed) logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml Log: added "create your own appender" section in chapter 4 Added: logback/trunk/logback-examples/src/main/java/chapter4/CountingConsoleAppender.java ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter4/CountingConsoleAppender.java Fri Dec 1 18:13:51 2006 @@ -0,0 +1,65 @@ +/** + * Logback: the reliable, generic, fast and flexible logging framework. + * + * Copyright (C) 1999-2006, 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 chapter4; + +import ch.qos.logback.core.AppenderBase; +import ch.qos.logback.core.Layout; + + +public class CountingConsoleAppender extends AppenderBase { + static int DEFAULT_LIMIT = 10; + int counter = 0; + int limit = DEFAULT_LIMIT; + + private Layout layout; + + public CountingConsoleAppender() { + } + + public void setLimit(int limit) { + this.limit = limit; + } + + public int getLimit() { + return limit; + } + + @Override + public void start() { + if (this.layout == null) { + addError("No layout set for the appender named ["+ name +"]."); + return; + } + + super.start(); + } + + public void append(Object eventObject) { + + if (counter >= limit) { + return; + } + + // output the events as formatted by our layout + System.out.print(this.layout.doLayout(eventObject)); + + // prepare for next event + counter++; + } + + public Layout getLayout() { + return layout; + } + + public void setLayout(Layout layout) { + this.layout = layout; + } +} Added: logback/trunk/logback-examples/src/main/java/chapter4/countingConsole.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter4/countingConsole.xml Fri Dec 1 18:13:51 2006 @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<configuration> + + + <appender name="CUSTOM" class="chapter4.CountingConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%date [%thread] %-5level %logger - %msg%n</Pattern> + </layout> + <limit>5</limit> + </appender> + + <root> + <level value="debug"/> + <appender-ref ref="CUSTOM" /> + </root> +</configuration> + + + 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 Fri Dec 1 18:13:51 2006 @@ -2633,5 +2633,107 @@ <appender-ref ref="DB" /> </configuration></pre></div> - </body> + + <a name="WriteOwnAppender" /> + <h2>Writing your own Appender</h2> + + + <p>You can easily write your appender by sub-classing <code>AppenderBase</code>. + It handles support for filters, status among other functionality shared by most appenders. + The derived class only needs to implement one method, namely + <code>append(Object eventObject)</code>. + </p> + + <p>The <code>CountingConsoleAppender</code>, which we list next, appends a limited + number of incoming events on the console. It shuts down after the limit is reached. + It uses a <code>Layout</code> to format the events and accepts a parameter, + thus a few more methods are needed. + </p> + +<em>Example 4.16: <code>CountingConsoleAppender</code> (logback-examples/src/main/java/chapter4/CountingConsoleAppender.java)</em> +<div class="source"><pre>package chapter4; + +import ch.qos.logback.core.AppenderBase; +import ch.qos.logback.core.Layout; + + +public class CountingConsoleAppender extends AppenderBase { + static int DEFAULT_LIMIT = 16; + int counter = 0; + int limit = DEFAULT_LIMIT; + + private Layout layout; + + public CountingConsoleAppender() { + } + + public void setLimit(int limit) { + this.limit = limit; + } + + public int getLimit() { + return limit; + } + + @Override + public void start() { + if (this.layout == null) { + addError("No layout set for the appender named ["+ name +"]."); + return; + } + + super.start(); + } + + public void append(Object eventObject) { + + if (counter >= limit) { + return; + } + + // output the events as formatted by our layout + System.out.print(this.layout.doLayout(eventObject)); + + // prepare for next event + counter++; + } + + public Layout getLayout() { + return layout; + } + + public void setLayout(Layout layout) { + this.layout = layout; + } +}</pre></div> + + <p> + The <code>start()</code> method checks for the presence of a <code>Layout</code>. + In case none is found, the appender is not started. + </p> + + <p> + This custom appender illustrates a two points: + </p> + + <ul> + <li> + All options that follow the setter/getter JavaBeans conventions + are handled transparently. The <code>start()</code> method, that is + called automatically, has the responsability to check that the given + options are coherent. + </li> + <li> + The <code>AppenderBase.doAppend()</code> method invokes the append() + method of its derived classes where actual output operations occur. + It is in this method that appenders format events by invoking their layouts. + </li> + </ul> + + <p> + The <code>CountingConsoleAppender</code> can be configured like any appender. + See sample file <em>logback-examples/src/main/java/chapter4/countingConsole.xml</em> + for an example. + </p> + </body> </document> \ No newline at end of file