Author: seb Date: Mon Nov 13 18:27:38 2006 New Revision: 906 Modified: logback/trunk/logback-access/src/main/java/ch/qos/logback/access/net/SMTPAppender.java logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/SMTPAppender.java logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/net/SMTPAppenderTest.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/net/SMTPAppenderBase.java logback/trunk/logback-examples/src/main/java/chapter4/mail/EMail.java logback/trunk/logback-examples/src/main/java/chapter4/mail/mail3.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml Log: Removed references to event evaluators in SMTPAppender, using TriggeringPolicy instead. Updated configuration scripts and examples accondingly. Other improvements to the documentation Modified: logback/trunk/logback-access/src/main/java/ch/qos/logback/access/net/SMTPAppender.java ============================================================================== --- logback/trunk/logback-access/src/main/java/ch/qos/logback/access/net/SMTPAppender.java (original) +++ logback/trunk/logback-access/src/main/java/ch/qos/logback/access/net/SMTPAppender.java Mon Nov 13 18:27:38 2006 @@ -61,7 +61,7 @@ * TriggeringEventEvaluator} for this SMTPAppender. */ public SMTPAppender(TriggeringPolicy evaluator) { - this.evaluator = evaluator; + this.triggeringPolicy = evaluator; } /** Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/SMTPAppender.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/SMTPAppender.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/net/SMTPAppender.java Mon Nov 13 18:27:38 2006 @@ -44,19 +44,19 @@ /** * The default constructor will instantiate the appender with a - * {@link TriggeringEventEvaluator} that will trigger on events with level + * {@link TriggeringPolicy} that will trigger on events with level * ERROR or higher. */ public SMTPAppender() { - this(new DefaultEvaluator()); + this(new DefaultSMTPTriggeringPolicy()); } /** - * Use <code>evaluator</code> passed as parameter as the {@link - * TriggeringEventEvaluator} for this SMTPAppender. + * Use the parameter as the {@link + * TriggeringPolicy} for this SMTPAppender. */ - public SMTPAppender(TriggeringPolicy evaluator) { - this.evaluator = evaluator; + public SMTPAppender(TriggeringPolicy triggeringPolicy) { + this.triggeringPolicy = triggeringPolicy; } /** @@ -112,7 +112,7 @@ } } -class DefaultEvaluator implements TriggeringPolicy { +class DefaultSMTPTriggeringPolicy implements TriggeringPolicy { private boolean started; Modified: logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/net/SMTPAppenderTest.java ============================================================================== --- logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/net/SMTPAppenderTest.java (original) +++ logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/net/SMTPAppenderTest.java Mon Nov 13 18:27:38 2006 @@ -74,8 +74,8 @@ assertEquals(1, appender.getContext().getStatusManager().getCount()); } - public void testEntryConditionsCheckNoEvaluator() { - appender.setEvaluator(null); + public void setTriggeringPolicy() { + appender.setTriggeringPolicy(null); appender.checkEntryConditions(); assertEquals(1, appender.getContext().getStatusManager().getCount()); } @@ -87,14 +87,14 @@ } public void testDefaultEvaluatorNoTrigger() { - DefaultEvaluator evaluator = new DefaultEvaluator(); + DefaultSMTPTriggeringPolicy evaluator = new DefaultSMTPTriggeringPolicy(); LoggingEvent le = new LoggingEvent(); le.setLevel(Level.DEBUG); assertFalse(evaluator.isTriggeringEvent(null, le)); } public void testDefaultEvaluatorTrigger() { - DefaultEvaluator evaluator = new DefaultEvaluator(); + DefaultSMTPTriggeringPolicy evaluator = new DefaultSMTPTriggeringPolicy(); LoggingEvent le = new LoggingEvent(); le.setLevel(Level.ERROR); assertTrue(evaluator.isTriggeringEvent(null, le)); Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/net/SMTPAppenderBase.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/net/SMTPAppenderBase.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/net/SMTPAppenderBase.java Mon Nov 13 18:27:38 2006 @@ -27,7 +27,6 @@ import ch.qos.logback.core.AppenderBase; import ch.qos.logback.core.Layout; import ch.qos.logback.core.rolling.TriggeringPolicy; -import ch.qos.logback.core.util.OptionHelper; /** * An abstract class that provides basic support for @@ -50,7 +49,7 @@ protected Message msg; - protected TriggeringPolicy evaluator; + protected TriggeringPolicy triggeringPolicy; /** * return a layout for the subjet string as appropriate for the @@ -106,7 +105,7 @@ subAppend(eventObject); - if (evaluator.isTriggeringEvent(null, eventObject)) { + if (triggeringPolicy.isTriggeringEvent(null, eventObject)) { sendBuffer(eventObject); } } @@ -127,7 +126,7 @@ return false; } - if (this.evaluator == null) { + if (this.triggeringPolicy == null) { addError("No TriggeringPolicy is set for appender [" + name + "]."); return false; } @@ -210,13 +209,6 @@ abstract protected void fillBuffer(StringBuffer sbuf); /** - * Returns value of the <b>EvaluatorClass</b> option. - */ - public String getEvaluatorClass() { - return evaluator == null ? null : evaluator.getClass().getName(); - } - - /** * Returns value of the <b>From</b> option. */ public String getFrom() { @@ -279,25 +271,16 @@ this.msg = msg; } - public void setEvaluator(TriggeringPolicy evaluator) { - this.evaluator = evaluator; - } - /** - * The <b>EvaluatorClass</b> option takes a string value representing the - * name of the class implementing the {@link TriggeringEventEvaluator} + * The <b>TriggeringPolicy</b> option takes a string value representing the + * name of the class implementing the {@link TriggeringPolicy} * interface. A corresponding object will be instantiated and assigned as the * triggering event evaluator for the SMTPAppender. */ - public void setEvaluatorClass(String value) { - try { - evaluator = (TriggeringPolicy) OptionHelper.instantiateByClassName(value, - TriggeringPolicy.class); - } catch (Exception ex) { - addError("Evaluator class instanciation failed"); - } + public void setTriggeringPolicy(TriggeringPolicy triggeringPolicy) { + this.triggeringPolicy = triggeringPolicy; } - + public Layout getLayout() { return layout; } Modified: logback/trunk/logback-examples/src/main/java/chapter4/mail/EMail.java ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/mail/EMail.java (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/mail/EMail.java Mon Nov 13 18:27:38 2006 @@ -20,7 +20,7 @@ /** * This application generates log messages in numbers specified by the - * user. It is intended to let users test RollingFileAppender. See + * user. See * also configuration scripts rolling.properties and rolling.xml. * */ public class EMail { Modified: logback/trunk/logback-examples/src/main/java/chapter4/mail/mail3.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/mail/mail3.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/mail/mail3.xml Mon Nov 13 18:27:38 2006 @@ -2,12 +2,12 @@ <!-- ============================================================= --> <!-- Sample SMTPAppender configuration using the HTMLLayout and a --> -<!-- custom trigger event evaluator. --> +<!-- custom triggering policy. --> <!-- ============================================================= --> <configuration> <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> - <EvaluatorClass>chapter4.mail.CounterBasedTP</EvaluatorClass> + <TriggeringPolicy class="chapter4.mail.CounterBasedTP" /> <BufferSize>1050</BufferSize> <SMTPHost>${smtpHost}</SMTPHost> <To>${to}</To> 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 Mon Nov 13 18:27:38 2006 @@ -203,6 +203,13 @@ that are dynamically inferred using JavaBeans introspection. </p> <h2>Logback Core</h2> + + <p> + Core is logback's central module. It offers functionnalities that are available + to any other module based on logback core. The <code>Appender</code> classes + contained in the core module are can be used by any module without any customization. + </p> + <a name="WriterAppender" /> <h3>WriterAppender</h3> @@ -314,7 +321,7 @@ ensures that all appenders in the hierarchy are closed and their buffers are flushed. The <code>ExitWoes2</code> class uses this statement and outputs a logging - request. <b>DOES NOT WORK ??</b> + request. </p> <p> @@ -375,7 +382,7 @@ <b><appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%-4relative [%thread] %-5level - %msg %n</Pattern> + <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg %n</Pattern> </layout> </appender></b> @@ -387,8 +394,8 @@ <p> To run this example, as well as others in this - chapter, please add the <em>logback-examples-VERSION.hjar</em> to your classpath. - Then, use the provided <code>ConfigurationTester</code> by + chapter, please run the script provided in logback's main directory. + Then, use the <code>ConfigurationTester</code> by issuing the following command, once in the <em>logback-examples</em> directory: </p> @@ -501,22 +508,22 @@ <em>Example 4.3: FileAppender configuration (logback-examples/src/main/java/chapter4/conf/logback-fileAppender.xml)</em> <div class="source"><pre><configuration> - <b><appender name="FILE" class="ch.qos.logback.core.FileAppender"> - <File>testFile.log</File> - <Append>true</Append> - <Encoding>UTF-8</Encoding> - <BufferedIO>false</BufferedIO> - <ImmediateFlush>true</ImmediateFlush> - - <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> - </layout> - </appender></b> - - <root> - <level value="debug" /> - <appender-ref ref="FILE" /> - </root> + <b><appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <File>testFile.log</File> + <Append>true</Append> + <Encoding>UTF-8</Encoding> + <BufferedIO>false</BufferedIO> + <ImmediateFlush>true</ImmediateFlush> + + <layout class="ch.qos.logback.classic.PatternLayout"> + <Pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</Pattern> + </layout> + </appender></b> + + <root> + <level value="debug" /> + <appender-ref ref="FILE" /> + </root> </configuration></pre></div> <p> @@ -597,7 +604,7 @@ <td><code>RollingPolicy</code></td> <td> This option is the component that will dictate - <code>RollingFileAppender</code>'s behaviour when the rollover + <code>RollingFileAppender</code>'s behaviour when rollover occurs. See more information below. </td> </tr> @@ -616,9 +623,9 @@ <p><a href="../xref/ch/qos/logback/core/rolling/RollingPolicy.html"><code>RollingPolicy</code></a> implementations are responsible for the - procedure of the rollover. They manage file renaming and sometimes deleting.</p> + rollover procedure. They manage file renaming and in occasion file deleting.</p> - <p>The <code>RollingPolicy</code> interface is rather simple:</p> + <p>The <code>RollingPolicy</code> interface is presented below:</p> <div class="source"><pre>package ch.qos.logback.core.rolling; @@ -650,7 +657,7 @@ <p> The <span class="option">File</span> option, which is configured in the <code>FileAppender</code> element, is required. It represents the name of the file - where current logging output will be written. The <span class="option">FileNamePattern</span> + to write to. The <span class="option">FileNamePattern</span> option represents the file name pattern for the archived (rolled over) log files. The <span class="option">FileNamePattern</span> option, which is also required, must include an integer token, that is the string <em>%i</em> @@ -1015,10 +1022,10 @@ <p> As we have seen, the <span class="option">FileNamePattern</span> serves two purposes. First, by studying the pattern, logback computes the requested rollover periodicity. Second, - it uses the pattern to custom each rolled files. It is entirely possible for two different + it computes each files' name based on the pattern. It is entirely possible for two different file name patterns to specify the same periodicity. The date patterns <em>yyyy-MM</em> and <em>yyyy@MM</em> both specify monthly - rollover periodicity, although the rolled files will carry different customizations. + rollover periodicity, although the rolled files will carry different names. </p> <p> @@ -1094,7 +1101,7 @@ <p><a href="../xref/ch/qos/logback/core/rolling/TriggeringPolicy.html"><code>TriggeringPolicy</code></a> implementations are responsible for instructing - the <code>RollingFileAppender</code> to proceed to the rollover.</p> + the <code>RollingFileAppender</code> to rollover.</p> <p>The <code>TriggeringPolicy</code> interface is pretty simple.</p> @@ -1105,7 +1112,7 @@ public interface TriggeringPolicy extends LifeCycle { - <b>public boolean isTriggeringEvent(final File file, final Object event);</b> + <b>public boolean isTriggeringEvent(final File activeFile, final Object event);</b> }</pre></div> <p> @@ -1124,7 +1131,7 @@ <a href="../xref/ch/qos/logback/core/rolling/SizeBasedTriggeringPolicy.html"> <code>SizeBasedTriggeringPolicy</code></a> looks at size of the file being currently written to. If it - grows bigger than the specified size, the + grows larger than the specified size, the <code>FileAppender</code> using the <code>SizeBasedTriggeringPolicy</code> will proceed to the rollover of the current file and log to @@ -1200,10 +1207,10 @@ they are instances of the <code>LoggingEvent</code> class in logback classic.</p> <a name="SocketAppender" /> - <h3>SockerAppender</h3> + <h3>SocketAppender</h3> <p> - The appenders covered this far were only able to log to local resources. + The appenders covered this far were only able to log on local resources. In contrast, the <a href="../xref/ch/qos/logback/classic/net/SocketAppender.html"> <code>SocketAppender</code></a> is designed to log to a remote entity by transmitting serialized <code>LoggingEvent</code> objects over the wire. @@ -1211,7 +1218,8 @@ On the receiving end after de-serialization, the event can be logged as if it were generated locally. Multiple <code>SocketAppender</code> instances running of different machines can direct their logging output - to a central log server. <code>SocketAppender</code> does not admit an + to a central log server whose format is fixed. + <code>SocketAppender</code> does not admit an associated layout because it sends serialized events to a remote server. <code>SocketAppender</code> operates above the <em>Transmission Control Protocol (TCP)</em> @@ -1233,7 +1241,7 @@ network rate. In particular, in the extreme case where the network link to the server is down, the client will be eventually blocked. Alternatively, if the network link is up, but the server is down, - the client will not be blocked although the log events will be + the client will not be blocked, although the log events will be lost due to server unavailability. </p> @@ -1357,7 +1365,7 @@ <code>SimpleSocketServer</code> the client will transparently reconnect to the new server instance, although the events generated while disconnected - will be simply and irrevocably lost. + will be simply (and irrevocably) lost. </p> <p> @@ -1410,8 +1418,8 @@ Allow us to repeat for emphasis that serialization of logging events is not intrusive. A de-serialized event carries the same information as any other logging event. It can be manipulated as if it were generated locally; - except that serialized logging events by default do not include location - information. Here is an example to illustrate the point. First, start + except that serialized logging events by default do not include caller + data. Here is an example to illustrate the point. First, start <code>SimpleSocketServer</code> with the following command: </p> @@ -1509,7 +1517,7 @@ </p> <p> By default, <code>SMTPAppender</code> will form a subject with - the message of the last logging event. + logger name and the message of the last logging event. </p> </td> </tr> @@ -1525,16 +1533,22 @@ </td> </tr> <tr> - <td><b><span class="option">EvaluatorClass</span></b></td> + <td><b><span class="option">TriggeringPolicy</span></b></td> <td><code>String</code></td> <td> - The <span class="option">EvaluatorClass</span> option takes a string - value representing the name of the class implementing the - <code>TriggeringPolicy</code> interface. A corresponding object will be - instantiated and assigned as the triggering event evaluator for the - <code>SMTPAppender</code>. In the absence of this option, - <code>SMTPAppender</code> is assigned a default evaluator which triggers + <p>This option is declared by creating a new <code><TriggeringPolicy/></code> + element. The name of the class that the user wishes to use as the + <code>SMTPAppender</code>'s <code>TriggeringPolicy</code> can be given + by adding an attribute to the newly created element. + </p> + <p> + More details about the use of triggering policies with <code>SMTPAppender</code> + follow further down this document. + </p> + <p>In the absence of this option, + <code>SMTPAppender</code> is assigned a default triggering policy which triggers email transmission as a response to any event of level <em>ERROR</em> or higher. + </p> </td> </tr> </table> @@ -1544,7 +1558,7 @@ in its cyclic buffer, throwing away older events when its buffer becomes full. The number of logging events delivered in any e-mail sent by <code>SMTPAppender</code> is upper-bounded by <span class="option">BufferSize</span>. This keeps memory - requirements bounded while still delivering the desired amount of application context. + requirements bounded while still delivering a reasonable amount of application context. </p> <p> @@ -1578,7 +1592,7 @@ <To>DESTINATION-EMAIL</To> <From>SENDER-EMAIL</From> <layout class="ch.qos.logback.classic.PatternLayout"> - <Pattern>%date %-5level %logger - %message%n</Pattern> + <Pattern>%date %-5level %logger{35} - %message%n</Pattern> </layout> </appender> @@ -1593,10 +1607,10 @@ configuration file, you must set the <span class="option">SMTPHost</span>, <span class="option">To</span> and <span class="option">From</span> options to values appropriate for your environment. Once you have set the proper values, - execute the following command: + change directory to <em>logback-examples</em> and execute the following command: </p> -<div class="source"><pre>java chapter4.mail.EMail 300 chapter4/mail/mail.xml</pre></div> +<div class="source"><pre>java chapter4.mail.EMail 300 src/main/java/chapter4/mail/mail.xml</pre></div> <p> The chosen recipient should see an email message containing 300 logging events @@ -1624,7 +1638,7 @@ </p> <div class="source"><pre>java -Dfrom=source@xyz.com -Dto=recipient@xyz.com - -DsmtpHost=some_smtp_host chapter4.mail.EMail 10000 chapter4/mail/mail2.xml + -DsmtpHost=some_smtp_host src/main/java/chapter4.mail.EMail 10000 chapter4/mail/mail2.xml </pre></div> <p> @@ -1667,7 +1681,7 @@ static int LIMIT = 1024; int counter = 0; - public boolean isTriggeringEvent(File file, Object event) { + public boolean isTriggeringEvent(File activeFile, Object event) { counter++; if (counter == LIMIT) { @@ -1684,15 +1698,15 @@ Note that this implementation extends <code>TriggeringPolicyBase</code> instead of implementing <code>TriggeringPolicy</code>. This allows the user to concentrate on the core functions of her <code>TriggeringPolicy</code> and let the base class - manage the other functionnalities. + provide the common functionnality. </p> <p> - Setting the <span class="option">EvaluatorClass</span> option of - <code>SMTPAppender</code> instructs it to use a custom evaluator. + Setting the <span class="option">TriggeringPolicy</span> option of + <code>SMTPAppender</code> instructs it to use a custom triggering policy. The next configuration file attaches a <code>SMTPAppender</code> to the root logger. This appender has a buffer size of 2048 and uses a <code>CounterBasedTP</code> instance - as its triggering event evaluator. + as its triggering policy. </p> <em>Example 4.10: <code>SMTPAppender</code> with custom @@ -1700,7 +1714,7 @@ <div class="source"><pre><configuration> <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender"> - <b><EvaluatorClass>chapter4.mail.CounterBasedTP</EvaluatorClass></b> + <b><TriggeringPolicy class="chapter4.mail.CounterBasedTP" /></b> <BufferSize>1050</BufferSize> <SMTPHost>${smtpHost}</SMTPHost> <To>${to}</To>