165 lines
6.3 KiB
HTML
165 lines
6.3 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<title>Writing your own filters</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css"/>
|
|
</head>
|
|
|
|
<body>
|
|
<!-- The header -->
|
|
<table border="0" width="100%" summary="header layout">
|
|
<tr>
|
|
<td><h1>Writing your own Filters</h1></td>
|
|
<td align="right"><img src="logo.png" alt="Checkstyle Logo"/></td>
|
|
</tr>
|
|
</table>
|
|
<!-- content -->
|
|
<table border="0" width="100%" cellpadding="5" summary="body layout">
|
|
<tr>
|
|
<!--Left menu-->
|
|
<td class="menu" valign="top">
|
|
<p>
|
|
<a href="#overview">Overview</a>
|
|
</p>
|
|
<p>
|
|
<a href="#writing">Writing Filters</a>
|
|
</p>
|
|
<p>
|
|
<a href="#using">Using Filters</a>
|
|
</p>
|
|
<p>
|
|
<a href="#huh">Huh?</a>
|
|
</p>
|
|
<p>
|
|
<a href="#contributeback">Contributing</a>
|
|
</p>
|
|
</td>
|
|
<!--Content-->
|
|
<td class="content" valign="top" align="left"><a name="overview"></a> <h2>Overview</h2>
|
|
<p class="body">
|
|
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 class="body">
|
|
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 class="body">
|
|
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 class="body">
|
|
Here is a UML diagram for interface <span class="code">Filter</span>
|
|
and class <span class="code">FilterSet</span>.
|
|
</p>
|
|
<img src="Filter.gif" width="233" height="324" alt="Filter UML diagram"/>
|
|
|
|
<a name="writing"></a> <h2>Writing Filters</h2>
|
|
|
|
<p class="body">
|
|
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>
|
|
|
|
<pre class="body">
|
|
package com.mycompany.filters;
|
|
|
|
import org.apache.regexp.RE;
|
|
import org.apache.regexp.RESyntaxException;
|
|
|
|
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 RE mFileRegexp;
|
|
|
|
public FilesFilter()
|
|
throws RESyntaxException
|
|
{
|
|
setFiles("^$");
|
|
}
|
|
|
|
public boolean accept(AuditEvent aEvent)
|
|
{
|
|
final String fileName = aEvent.getFileName();
|
|
return ((fileName == null) || !mFileRegexp.match(fileName));
|
|
}
|
|
|
|
public void setFiles(String aFilesPattern)
|
|
throws RESyntaxException
|
|
{
|
|
mFileRegexp = Utils.getRE(aFilesPattern);
|
|
}
|
|
}
|
|
</pre>
|
|
<a name="using"></a> <h2>Using Filters</h2>
|
|
|
|
<p class="body">
|
|
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>
|
|
|
|
<pre class="body">
|
|
<module name="com.mycompany.filters.FilesFilter">
|
|
<property name="files" value="Generated"/>
|
|
</module>
|
|
</pre>
|
|
|
|
<a name="huh"></a> <h2>Huh? I can't figure it out!</h2>
|
|
<p class="body">
|
|
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 name="contributeback"></a> <h2>Contributing</h2>
|
|
<p class="body">
|
|
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>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr/>
|
|
<div>
|
|
<a href="index.html">Back to the Checkstyle Home Page</a>
|
|
</div>
|
|
<p class="copyright">
|
|
Copyright © 2002-2004 Oliver Burn. All rights Reserved.
|
|
</p>
|
|
</body>
|
|
</html>
|