writinglisteners.html

<!DOCTYPE html>


<!--
 | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/writinglisteners.xml.vm at 2025-03-04
 | Rendered using Apache Maven Fluido Skin 2.0.1
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
    <title>Writing Listeners – checkstyle</title>
    <link rel="stylesheet" href="./css/apache-maven-fluido-2.0.1.min.css" />
    <link rel="stylesheet" href="./css/site.css" />
    <link rel="stylesheet" href="./css/print.css" media="print" />
    <script src="./js/apache-maven-fluido-2.0.1.min.js"></script>
<script type="text/javascript" src="./js/checkstyle.js"></script>
        <script type="text/javascript"
              src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
        <script type="text/javascript" src="./js/anchors.js"></script>
        <script type="text/javascript" src="./js/google-analytics.js"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/prettify/r298/prettify.min.js"></script>
        <script type="text/javascript"
              src="https://cdn.jsdelivr.net/gh/google/code-prettify@master/loader/run_prettify.js"></script>
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prettify/r298/prettify.min.css">
        <link rel="icon" href="./images/favicon.png" type="image/x-icon" />
        <link rel="shortcut icon" href="./images/favicon.ico" type="image/ico" />
  </head>
  <body>
    <div class="container-fluid container-fluid-top">
      <header>
        <div id="banner">
          <div class="pull-left"><div id="bannerLeft"><h1><a href="./"><img class="class java.lang.Object" src="images/header-checkstyle-logo.png" alt="Checkstyle" /></a></h1></div></div>
          <div class="pull-right"><div id="bannerRight"><h1><img class="class java.lang.Object" src="images/header-right-ruller.png" alt="Checkstyle" /></h1></div></div>
          <div class="clear"><hr/></div>
        </div>

        <div id="breadcrumbs">
          <ul class="breadcrumb">
        <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2025-03-04</li>
          <li id="projectVersion" class="pull-right"><span class="divider">|</span>Version: 10.21.4</li>
        <li class="pull-right"><a>toTop</a></li>
          </ul>
        </div>
      </header>
      <div class="row-fluid">
        <header id="leftColumn" class="span2">
          <nav class="well sidebar-nav">
  <ul class="nav nav-list">
   <li class="nav-header">About</li>
    <li><a href="index.html">Checkstyle</a></li>
    <li><a href="releasenotes.html">Release Notes</a></li>
    <li><a href="consulting.html">Consulting</a></li>
    <li><a href="sponsoring.html">Sponsoring</a></li>
   <li class="nav-header">Documentation</li>
    <li><a href="config.html"><span class="icon-chevron-down"></span>Configuration</a>
     <ul class="nav nav-list">
      <li><a href="property_types.html">Property Types</a></li>
      <li><a href="config_system_properties.html">System Properties</a></li>
     </ul></li>
    <li><a href="running.html"><span class="icon-chevron-down"></span>Running</a>
     <ul class="nav nav-list">
      <li><a href="anttask.html">Ant Task</a></li>
      <li><a href="cmdline.html">Command Line</a></li>
     </ul></li>
    <li><a href="checks.html"><span class="icon-chevron-down"></span>Checks</a>
     <ul class="nav nav-list">
      <li><a href="checks/annotation/index.html"><span class="icon-chevron-right"></span>Annotations</a></li>
      <li><a href="checks/blocks/index.html"><span class="icon-chevron-right"></span>Block Checks</a></li>
      <li><a href="checks/design/index.html"><span class="icon-chevron-right"></span>Class Design</a></li>
      <li><a href="checks/coding/index.html"><span class="icon-chevron-right"></span>Coding</a></li>
      <li><a href="checks/header/index.html"><span class="icon-chevron-right"></span>Headers</a></li>
      <li><a href="checks/imports/index.html"><span class="icon-chevron-right"></span>Imports</a></li>
      <li><a href="checks/javadoc/index.html"><span class="icon-chevron-right"></span>Javadoc Comments</a></li>
      <li><a href="checks/metrics/index.html"><span class="icon-chevron-right"></span>Metrics</a></li>
      <li><a href="checks/misc/index.html"><span class="icon-chevron-right"></span>Miscellaneous</a></li>
      <li><a href="checks/modifier/index.html"><span class="icon-chevron-right"></span>Modifiers</a></li>
      <li><a href="checks/naming/index.html"><span class="icon-chevron-right"></span>Naming Conventions</a></li>
      <li><a href="checks/regexp/index.html"><span class="icon-chevron-right"></span>Regexp</a></li>
      <li><a href="checks/sizes/index.html"><span class="icon-chevron-right"></span>Size Violations</a></li>
      <li><a href="checks/whitespace/index.html"><span class="icon-chevron-right"></span>Whitespace</a></li>
     </ul></li>
    <li><a href="filters/index.html"><span class="icon-chevron-right"></span>Filters</a></li>
    <li><a href="filefilters/index.html"><span class="icon-chevron-right"></span>File Filters</a></li>
    <li><a href="style_configs.html"><span class="icon-chevron-down"></span>Style Configurations</a>
     <ul class="nav nav-list">
      <li><a href="google_style.html">Google&apos;s Style</a></li>
      <li><a href="sun_style.html">Sun&apos;s Style</a></li>
     </ul></li>
   <li class="nav-header">Developers</li>
    <li><a href="extending.html"><span class="icon-chevron-down"></span>Extending Checkstyle</a>
     <ul class="nav nav-list">
      <li><a href="writingchecks.html">Writing Checks</a></li>
      <li><a href="writingjavadocchecks.html">Writing Javadoc Checks</a></li>
      <li><a href="writingfilters.html">Writing Filters</a></li>
      <li><a href="writingfilefilters.html">Writing File Filters</a></li>
      <li class="active"><a>Writing Listeners</a></li>
     </ul></li>
    <li><a href="contributing.html">Contributing</a></li>
    <li><a href="beginning_development.html"><span class="icon-chevron-down"></span>Beginning Development</a>
     <ul class="nav nav-list">
      <li><a href="eclipse.html">Eclipse IDE</a></li>
      <li><a href="netbeans.html">NetBeans IDE</a></li>
      <li><a href="idea.html">IntelliJ IDE</a></li>
     </ul></li>
    <li><a href="apidocs/index.html">Javadoc</a></li>
   <li class="nav-header">Project Documentation</li>
    <li><a href="project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
    <li><a href="project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
  </ul>
          </nav>
          <div class="well sidebar-nav">
            <div id="poweredBy">
              <div class="clear"></div>
              <div class="clear"></div>
<a href="https://github.com/checkstyle/checkstyle" class="builtBy"><img class="builtBy" src="images/github_logo_social_coding_outlined.png" alt="GitHub" /></a>
<a href="https://twitter.com/checkstyle_java/" class="builtBy"><img class="builtBy" src="images/twitter_button.png" alt="Twitter" /></a>
<a href="https://stackoverflow.com/questions/tagged/checkstyle" class="builtBy"><img class="builtBy" src="images/stackoverflow.jpeg" alt="Stackoverflow" /></a>
<a href="https://groups.google.com/forum/#!forum/checkstyle" class="builtBy"><img class="builtBy" src="images/groups.png" alt="GoogleGroups" /></a>
<a href="https://www.ej-technologies.com/products/jprofiler/overview.html" class="builtBy"><img class="builtBy" src="https://www.ej-technologies.com/images/product_banners/jprofiler_medium.png" alt="JProfiler" /></a>
            </div>
          </div>
        </header>
        <main id="bodyColumn" class="span10">


    <section><a id="Overview"></a>
<h1>Overview</h1>
      
<p>
        A Checkstyle listener monitors the progress of a <code>Checker</code> during the audit
        of files. The <code>Checker</code> notifies its attached listeners of
        significant events such as the start of the audit of a file and
        the logging of a Check violation, and the listeners respond
        appropriately.  Any number of listeners can be attached to a
        <code> Checker</code>. An audit always adds one of
        the distribution listeners, <a href="apidocs/com/puppycrawl/tools/checkstyle/DefaultLogger.html">DefaultLogger</a>
        or <a href="apidocs/com/puppycrawl/tools/checkstyle/XMLLogger.html">XMLLogger</a>,
        to report events. A <code>DefaultLogger</code>
        produces simple text output for the events it receives, and a
        <code>XMLLogger</code> produces an XML document for
        its events.
      </p>

      
<p>
        Listeners <code>DefaultLogger</code> and <code> XMLLogger</code> are sufficient for most
        Checkstyle users, but you may find a need for a custom
        listener. For example, a user has requested verbose output of
        progress information during a Checkstyle run. Another user would
        like to filter violation events. This document explains how to write
        listeners for such tasks and how to integrate them in a Checker
        module. It also describes two custom listeners that are inspired
        by ANT listeners: a listener that is a wrapper for the Jakarta
        Commons Logging API, and a listener that sends its results via
        email.
      </p>

      
<p>
        A listener is an implementation of the <a href="apidocs/com/puppycrawl/tools/checkstyle/api/AuditListener.html">AuditListener</a>
        interface. During an audit, a <code>Checker</code>
        informs its attached <code>AuditListeners</code> of
        six kinds of events: audit started/ended, file started/ended,
        and logging of an error(violation)/exception.
      </p>

      
<p>
        An audit passes an event to a listener as an <a href="apidocs/com/puppycrawl/tools/checkstyle/api/AuditEvent.html">AuditEvent</a>.
        A file-related <code>AuditEvent</code> contains the
        name of that file. An <code>AuditEvent</code> for
        violation logging has a message, a severity level, a message source
        such as the name of a <code>Check</code>, and file
        line and column numbers that may be relevant to the violation. The
        notification of an exception to a <code>AuditListener</code> includes a violation
        <code>AuditEvent</code> and the details of the exception. Here is a UML diagram for
        classes <code>AuditListener</code> and <code>AuditEvent</code>.
      </p>

      <span class="wrapper">
        <img src="images/AuditListener.gif" width="381" height="488" alt="AuditListener UML diagram" />
      </span>

    </section>

    <section><a id="Writing_Listeners"></a>
<h1>Writing Listeners</h1>
      
<p>
        A custom listener is an implementation of the <a href="apidocs/com/puppycrawl/tools/checkstyle/api/AuditListener.html">AuditListener</a>
        interface. If the listener has properties that can be set from a
        configuration, the listener must extend <a href="apidocs/com/puppycrawl/tools/checkstyle/api/AutomaticBean.html">AutomaticBean</a>.
        An <code>AutomaticBean</code> uses JavaBean
        introspection to set JavaBean properties.
      </p>

      
<p>
        The custom listener that we demonstrate here is a verbose
        listener that simply prints each event notification to an output
        stream, and reports the number of violations per audited file and
        the total number of violations. The default output stream is <code>System.out</code>.
        In order to enable the specification of output to a file through property
        <code>file</code>, the class extends <code>AutomaticBean</code> and defines method
        <code>setFile(String)</code>.
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
package com.mycompany.listeners;

import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.io.OutputStream;
import java.io.PrintWriter;

import com.puppycrawl.tools.checkstyle.api.AuditEvent;
import com.puppycrawl.tools.checkstyle.api.AuditListener;
import com.puppycrawl.tools.checkstyle.AbstractAutomaticBean;
import com.puppycrawl.tools.checkstyle.api.SeverityLevel;

public class VerboseListener
    extends AutomaticBean
    implements AuditListener
{
  private PrintWriter mWriter = new PrintWriter(System.out);
  private boolean mCloseOut = false;
  private int mTotalErrors;
  private int mErrors;

  public void setFile(String aFileName)
      throws FileNotFoundException
  {
    final OutputStream out = new FileOutputStream(aFileName);
    mWriter = new PrintWriter(out);
    mCloseOut = true;
  }

  public void auditStarted(AuditEvent aEvt)
  {
    mTotalErrors = 0;
    mWriter.println(&quot;Audit started.&quot;);
  }

  public void auditFinished(AuditEvent aEvt)
  {
    mWriter.println(&quot;Audit finished. Total errors: &quot; + mTotalErrors);
    mWriter.flush();
    if (mCloseOut) {
      mWriter.close();
    }
  }

  public void fileStarted(AuditEvent aEvt)
  {
    mErrors = 0;
    mWriter.println(
        &quot;Started checking file '&quot; + aEvt.getFileName() + &quot;'.&quot;);
  }

  public void fileFinished(AuditEvent aEvt)
  {
    mWriter.println(&quot;Finished checking file '&quot; + aEvt.getFileName()
        + &quot;'. Errors: &quot; + mErrors);
  }

  public void addError(AuditEvent aEvt)
  {
    printEvent(aEvt);
    if (SeverityLevel.ERROR.equals(aEvt.getSeverityLevel())) {
      mErrors++;
      mTotalErrors++;
    }
  }

  public void addException(AuditEvent aEvt, Throwable aThrowable)
  {
    printEvent(aEvt);
    aThrowable.printStackTrace(System.out);
    mErrors++;
    mTotalErrors++;
  }

  private void printEvent(AuditEvent aEvt)
  {
    mWriter.println(&quot;Logging error -&quot;
        + &quot; file: '&quot; + aEvt.getFileName() + &quot;'&quot;
        + &quot; line: &quot; + aEvt.getLine()
        + &quot; column: &quot; + aEvt.getColumn()
        + &quot; severity: &quot; + aEvt.getSeverityLevel()
        + &quot; message: &quot; + aEvt.getMessage()
        + &quot; source: &quot; + aEvt.getSourceName());
  }
}
      </code></pre></div>

      
<p>
        A listener that filters error events could perform the filtering
        in methods <code> addError</code> and <code>addException</code>. As further examples of
        listeners, <a href="#CommonsLoggingListener">CommonsLoggingListener</a>
        reports its events through the Commons Logging API, and <a href="#MailLogger">MailLogger</a> e-mails the audit report of a
        <code>DefaultLogger</code>.
      </p>
    </section>

    <section><a id="Using_Listeners"></a>
<h1>Using Listeners</h1>
      
<p>
        To incorporate a custom listener in the set of listeners for a
        <code>Checker</code>, include a module element for
        the listener in the <a href="config.html#Audit_Listeners">configuration file</a>. For
        example, to configure a <code>Checker</code> so
        that it uses custom listener
        <a href="https://github.com/checkstyle/contribution/blob/master/examples/listeners/com/mycompany/listeners/VerboseListener.java" class="externalLink">
            VerboseListener</a>
        to print audit messages to a
        file named &quot;audit.txt&quot;, include the following module
        in the configuration file:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-xml">
&lt;module name=&quot;com.mycompany.listeners.VerboseListener&quot;&gt;
  &lt;property name=&quot;file&quot; value=&quot;audit.txt&quot;/&gt;
&lt;/module&gt;
      </code></pre></div>

      
<p>
        Here is a truncated example of audit output from a <code> VerboseListener</code>:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
Audit started.
Started checking file 'CommonsLoggingListener.java'.
Finished checking file 'CommonsLoggingListener.java'. Errors: 0
Started checking file 'MailLogger.java'.
Finished checking file 'MailLogger.java'. Errors: 0
Started checking file 'VerboseListener.java'.
Logging error - file: 'VerboseListener.java' line: 23 ...
Finished checking file 'VerboseListener.java'. Errors: 1
Audit finished. Total errors: 1
      </code></pre></div>
    </section>

    <section><a id="Examples"></a>
<h1>Examples</h1>
      
<p>
        This section describes two examples based on <a href="https://ant.apache.org/" class="externalLink">ANT</a> listeners. The first
        listener, <code> CommonsLoggingListener</code>,
        hands off events to the <a href="https://commons.apache.org/proper/commons-logging/" class="externalLink">Apache
        Commons Logging</a> facade and the second, <code>MailLogger</code>,
        sends a report of an audit via
        e-mail. The discussion of these examples and how to use them is
        derived from material in <a href="https://www.manning.com/books/java-development-with-ant" class="externalLink">&quot;Java Development
        with Ant&quot;</a> by Eric Hatcher and Steve Loughran, an
        excellent ANT book.
      </p>

      <a id="CommonsLoggingListener"></a>
      <section><section><section><a id="CommonsLoggingListener"></a>
<h4>CommonsLoggingListener</h4>

      
<p>
        <a href="https://commons.apache.org/proper/commons-logging/" class="externalLink">Apache
        Commons Logging</a> provides a facade for logging tools
        <a href="https://logging.apache.org/log4j/2.x/index.html" class="externalLink">log4j</a>,
        J2SE 1.4, and others. Checkstyle listener <code>CommonsLoggingListener</code>
        responds to an AuditEvent by handing it off to the current Commons Logging Log.
      </p>

      
<p>
        The source code for
        <a href="https://github.com/checkstyle/contribution/blob/master/examples/listeners/com/mycompany/listeners/CommonsLoggingListener.java" class="externalLink">
        CommonsLoggingListener</a>.  Notice that
        each <code>AuditListener</code> method that
        receives an <code> AuditEvent</code> calls a method
        for the Commons Logging log level corresponding to the
        Checkstyle <code>SeverityLevel</code> of the <code> AuditEvent</code>.
      </p>

      
<p>
        The easiest way to use <code>CommonsLoggingListener</code> is to include
        <code>checkstyle-10.21.4-all.jar</code>
        in the classpath because that jar file contains all the Commons
        Logging classes.  The default Log under J2SE 1.4 is wrapper
        class <a href="https://commons.apache.org/proper/commons-logging/apidocs/org/apache/commons/logging/impl/Jdk14Logger.html" class="externalLink">
          Jdk14Logger</a>.
        Under earlier Java versions, the default Log is a simple wrapper
        class, <a href="https://commons.apache.org/proper/commons-logging/apidocs/org/apache/commons/logging/impl/SimpleLog.html" class="externalLink">
          SimpleLog</a>.
        Both default logging tools can be used directly from Commons
        Logging; if you need to use other tools such as log4j, then you
        must include the appropriate jar file(s) in the classpath.
      </p>

      
<p>
        Logging configuration details for Jakarta Commons Logging are in
        the <a href="https://commons.apache.org/proper/commons-logging/" class="externalLink">documentation</a>.
        As a simple example, assume that <code>log4j.jar</code> is in the classpath and the
        following <code>log4j.properties</code> file is
        in the current directory:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
# Set root logger level to INFO and its only appender to A1.
log4j.rootLogger=INFO, A1

# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-5p %c %x- %m%n
      </code></pre></div>

      
<p>
        Running a Checkstyle audit with a <code>CommonsLoggingListener</code> yields this
        (abbreviated) output:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-java">
INFO  com.puppycrawl...Checker  - Audit started.
INFO  com.puppycrawl...Checker  - File &quot;CommonsLoggingListener.java&quot; started.
INFO  com.puppycrawl...Checker  - File &quot;CommonsLoggingListener.java&quot; finished.
INFO  com.puppycrawl...Checker  - File &quot;MailLogger.java&quot; started.
INFO  com.puppycrawl...Checker  - File &quot;MailLogger.java&quot; finished.
INFO  com.puppycrawl...Checker  - File &quot;VerboseListener.java&quot; started.
ERROR com.puppycrawl...ParenPadCheck  - Line: 23 Column: 28 ...
INFO  com.puppycrawl...Checker  - File &quot;VerboseListener.java&quot; finished.
INFO  com.puppycrawl...Checker  - Audit finished.
      </code></pre></div>

      <a id="MailLogger"></a>
      </section><section><a id="MailLogger"></a>
<h4>MailLogger</h4>
      
<p>
        <a href="https://github.com/checkstyle/contribution/blob/master/examples/listeners/com/mycompany/listeners/MailLogger.java" class="externalLink">
        MailLogger</a>
        sends an audit report in an
        email message.  The listener uses a <code>DefaultLogger</code> to prepare the text of the
        message. The listener obtains other message parameters such as
        <code>to</code> and <code>subject</code> from environment properties that
        can be read from a properties file.
      </p>

      
<p>
        This
        implementation uses the <a href="https://www.oracle.com/java/technologies/javamail.html" class="externalLink">JavaMail API</a> as
        the mail system, and you must include appropriate jar files in
        the classpath.
      </p>

      
<p>
        As an example of using <code>MailLogger</code>, set
        system property <code>-DMailLogger.properties.file=MailLogger.properties</code>,
        so that <code>MailLogger</code> reads message
        parameters from file <code>MailLogger.properties</code> of the current
        directory:
      </p>

      
<div class="wrapper">
<pre class="prettyprint"><code class="language-text">
MailLogger.from=user@example.org
MailLogger.failure.to=user@example.org
MailLogger.success.to=user@example.org
MailLogger.mailhost=localhost
      </code></pre></div>
    </section></section></section></section>

    <section><a id="Huh.3F_I_can.27t_figure_it_out.21"></a>
<h1>Huh? I can't figure it out!</h1>
      
<p>
        That's probably our fault, and it means that we have to
        provide better documentation. Please do not hesitate to ask
        questions on the user mailing list, this will help us to improve
        this document.  Please ask your questions as precisely as
        possible. We will not be able to answer questions like &quot;I
        want to write a listener but I don't know how, can you help
        me?&quot;. Tell us what you are trying to do (the purpose of the
        listener), what you have understood so far, and what exactly you
        are getting stuck on.
      </p>
    </section>

    <section><a id="Contributing"></a>
<h1>Contributing</h1>
      
<p>
        We need <em>your</em> help to keep improving Checkstyle.
        Whenever you write a listener that you think is generally
        useful, please consider <a href="contributing.html">contributing</a> it to the Checkstyle
        community and submit it for inclusion in the next release of
        Checkstyle.
      </p>
    </section>
  
        </main>
      </div>
    </div>
    <hr/>
    <footer>
      <div class="container-fluid">
        <div class="row-fluid">
            <p>©      2001–2025
</p>
        </div>
      </div>
    </footer>
  </body>
</html>