<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- Content Stylesheet for Site -->
<!-- start the processing -->
<!-- ====================================================================== -->
<!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
<!-- Main Page Section -->
<!-- ====================================================================== -->
<html>
<head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type" />
<meta name="author" content="Lars K?hne">
<meta name="email" content="$au.getAttributeValue("email")">
<title>Checkstyle - Writing Filters</title>
<style type="text/css" media="all">
@import url("./css/cs-layout.css");
@import url("./css/cs-style.css");
</style>
</head>
<body>
<div class="csTopBar">
<div class="csTopBarContents">
<div class="csLeft">
<h1>Writing Filters</h1>
</div>
<div class="csRight">
<a href="http://checkstyle.sourceforge.net/">
<img src="images/logo.png" alt="Checkstyle Logo" height="70"/>
</a>
</div>
</div>
</div>
<div class="csMiddleContainer">
<div class="csLeftBar">
<div class="csLeftBarContents">
<!-- ============================================================ -->
<!-- start makeNavigationBar -->
<ul>
<li>
<strong>About</strong>
</li>
<li> <a href="./index.html">Checkstyle</a>
</li>
<li>
<strong>Documentation</strong>
</li>
<li> <a href="./releasenotes.html">Release Notes</a>
</li>
<li> <a href="./config.html">Configuration</a>
</li>
<li> <a href="./property_types.html"> Property Types</a>
</li>
<li> <a href="./running.html">Running</a>
</li>
<li> <a href="./anttask.html"> Ant Task</a>
</li>
<li> <a href="./cmdline.html"> Command Line</a>
</li>
<li> <a href="./availablechecks.html">Available Checks</a>
</li>
<li> <a href="./checks.html">Standard Checks</a>
</li>
<li> <a href="./config_javadoc.html"> Javadoc Comments</a>
</li>
<li> <a href="./config_naming.html"> Naming Conventions</a>
</li>
<li> <a href="./config_header.html"> Headers</a>
</li>
<li> <a href="./config_imports.html"> Imports</a>
</li>
<li> <a href="./config_sizes.html"> Size Violations</a>
</li>
<li> <a href="./config_whitespace.html"> Whitespace</a>
</li>
<li> <a href="./config_modifier.html"> Modifiers</a>
</li>
<li> <a href="./config_blocks.html"> Block Checks</a>
</li>
<li> <a href="./config_coding.html"> Coding</a>
</li>
<li> <a href="./config_design.html"> Class Design</a>
</li>
<li> <a href="./config_duplicates.html"> Duplicate Code</a>
</li>
<li> <a href="./config_metrics.html"> Metrics</a>
</li>
<li> <a href="./config_misc.html"> Miscellaneous</a>
</li>
<li> <a href="./optional.html">Optional Checks</a>
</li>
<li> <a href="./config_j2ee.html"> J2EE Checks</a>
</li>
<li> <a href="./extending.html">Extending Checkstyle</a>
</li>
<li> <a href="./writingchecks.html"> Writing checks</a>
</li>
<li><b> <a href="./writingfilters.html"> Writing filters</a>
</b></li>
<li><a href="#Overview"> Overview</a></li>
<li><a href="#Writing Filters"> Writing Filters</a></li>
<li><a href="#Using Filters"> Using Filters</a></li>
<li><a href="#Huh? I can't figure it out!"> Huh? I can't figure it out!</a></li>
<li><a href="#Contributing"> Contributing</a></li>
<li> <a href="./writinglisteners.html"> Writing listeners</a>
</li>
<li> <a href="./api/index.html">Javadoc</a>
</li>
<li>
<strong>SourceForge</strong>
</li>
<li> <a href="http://sourceforge.net/mail/?group_id=29721">Mailing Lists</a>
</li>
<li> <a href="http://sourceforge.net/tracker/?atid=397078&group_id=29721&func=browse">Bug Database</a>
</li>
<li> <a href="http://sourceforge.net/tracker/?atid=397081&group_id=29721&func=browse">Feature Requests</a>
</li>
<li>
<strong>Developers</strong>
</li>
<li> <a href="http://sourceforge.net/projects/checkstyle">Project Page</a>
</li>
<li> <a href="http://checkstyle.svn.sourceforge.net/viewvc/checkstyle/">SVN Repository</a>
</li>
<li> <a href="./contributing.html">Contributing</a>
</li>
</ul>
<ul>
<li>
<strong>Hosted by:</strong>
<div align="center">
<p><a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=29721&type=1" width="88" height="31" alt="SourceForge Logo"/></a>
</p>
</div>
</li>
</ul>
<!-- end makeNavigationBar -->
<!-- ============================================================ -->
</div>
</div>
<div class="csMain">
<a id="Overview"></a>
<h2>Overview</h2>
<p>
A <span class="code">Checker</span> has a set of <span class="code">Filter</span>s that decide which audit events the <span class="code">Checker</span> reports through its listeners. Interface
<span class="code">Filter</span> and class <span class="code">FilterSet</span> are intended to support general <span class="code">AuditEvent</span> filtering using a set of <span class="code">Filter</span>s.
</p>
<p>
A <span class="code">Filter</span> has <span class="code">boolean</span> method <span class="code">accept(AuditEvent)</span> that returns <span class="code">true</span> if the <span class="code">Filter</span>
accepts the <span class="code">AuditEvent</span> parameter and returns
<span class="code">false</span> if the <span class="code">Filter</span> rejects it.
</p>
<p>
A <span class="code">FilterSet</span> is a particular <span class="code">Filter</span> that contains a set of <span class="code">Filter</span>s. A <span class="code">FilterSet</span>
accepts an <span class="code">AuditEvent</span> if and only if all
<span class="code">Filter</span>s in the set accept the <span class="code">AuditEvent</span>.
</p>
<p>
Here is a UML diagram for interface <span class="code">Filter</span>
and class <span class="code">FilterSet</span>.
</p>
<image src="images/Filter.gif" width="233" height="324" alt="Filter UML diagram" />
<a id="Writing Filters"></a>
<h2>Writing Filters</h2>
<p>
The <span class="code">Filter</span> that we demonstrate here rejects
audit events for files whose name matches a <a href="property_types.html#regexp">regular expression</a>. In order to
enable the specification of the file name pattern as a property in a
configuration file, the <span class="code">Filter</span> is an <a href="api/com/puppycrawl/tools/checkstyle/api/AutomaticBean.html">AutomaticBean</a>
with mutator method <span class="code">setFiles(String)</span> that
receives the file name pattern. An <span class="code">AutomaticBean</span> uses JavaBean introspection to set
JavaBean properties such as <span class="code">files</span>.
</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>package com.mycompany.filters;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.regex.PatternSyntaxException;
import com.puppycrawl.tools.checkstyle.api.AuditEvent;
import com.puppycrawl.tools.checkstyle.api.AutomaticBean;
import com.puppycrawl.tools.checkstyle.api.Filter;
import com.puppycrawl.tools.checkstyle.api.Utils;
public class FilesFilter
extends AutomaticBean
implements Filter
{
private Pattern mFileRegexp;
public FilesFilter()
throws PatternSyntaxException
{
setFiles("^$");
}
public boolean accept(AuditEvent aEvent)
{
final String fileName = aEvent.getFileName();
return ((fileName == null) || !mFileRegexp.matcher(fileName).find());
}
public void setFiles(String aFilesPattern)
throws PatternSyntaxException
{
mFileRegexp = Utils.getPattern(aFilesPattern);
}
}</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
<a id="Using Filters"></a>
<h2>Using Filters</h2>
<p>
To incorporate a <span class="code">Filter</span> in the filter set
for a <span class="code">Checker</span>, include a module element for
the <span class="code">Filter</span> in the <a href="config.html#filters">configuration file</a>. For example, to
configure a <span class="code">Checker</span> so that it uses custom
filter <span class="code">FilesFilter</span> to prevent reporting of
audit events for files whose name contains "Generated",
include the following module in the configuration file:
</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre><module name="com.mycompany.filters.FilesFilter">
<property name="files" value="Generated"/>
</module></pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
<a id="Huh? I can't figure it out!"></a>
<h2>Huh? I can't figure it out!</h2>
<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 "I want to write a filter but I don't
know how, can you help me?". Tell us what you are trying to do
(the purpose of the filter), what you have understood so far, and what
exactly you are getting stuck on.
</p>
<a id="Contributing"></a>
<h2>Contributing</h2>
<p>
We need <em>your</em> help to keep improving Checkstyle. Whenever you
write a filter 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>
</div>
</div>
<div class="csBottomBar">
<div class="csBottomBarContents">
Copyright © 2001-2007, Oliver Burn
</div>
</div>
</body>
</html>
<!-- end the processing -->
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
main-release
>
by-pkgid
>
253d50e0122b162d839c0c787af1f0d6
>
files
>
40
