TouchInstinct
/
checkstyle
306
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

completed Filter docs.

This commit is contained in:
Rick Giles 2003-07-15 11:10:15 +00:00
parent 0587b63fec
commit a9bfdceec2
5 changed files with 235 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
contrib/examples/filters/com/mycompany/filters/FilesFilter.java Normal file
View File

@ -0,0 +1,44 @@
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 int decide(Object aObject)
{
if (!(aObject instanceof AuditEvent)) {
return Filter.NEUTRAL;
}
final AuditEvent event = (AuditEvent) aObject;
final String fileName = event.getFileName();
if ((fileName != null) && mFileRegexp.match(fileName)) {
return Filter.DENY;
}
else {
return Filter.NEUTRAL;
}
}
public void setFiles(String aFilesPattern)
throws RESyntaxException
{
mFileRegexp = Utils.getRE(aFilesPattern);
}
}

BIN
docs/Filter.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.2 KiB

1
docs/index.html
View File

@ -46,6 +46,7 @@
<li><a href="cmdline.html">Command Line</a></li>
<li><a href="writingchecks.html">Writing Checks</a></li>
<li><a href="writinglisteners.html">Writing Listeners</a></li>
<li><a href="writingfilters.html">Writing Filters</a></li>
</ul>
<p>SourceForge</p>

3
docs/releasenotes.html
View File

@ -121,6 +121,9 @@
<li class="body">Added usage checks OneMethodPrivateFieldCheck, UnusedLocalVariableCheck,
UnusedParameterCheck, UnusedPrivateFieldCheck, UnusedPrivateMethodCheck.</li>
<li class="body">Added filters for audit events (partially fulfills request 559103).
A SuppressionFilter denies events according to a suppressions file (request 756416).</li>
</ul>
<p class="body">

187
docs/writingfilters.html Normal file
View File

@ -0,0 +1,187 @@
<?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 chain 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">FilterChain</span>
are intended to support general <span class="code">Object</span> filtering in a filter chain.
<p>
<p class="body">
A <span class="code">Filter</span> has one method, <span class="code">decide(Object)</span>,
that determines the result of filtering an <span class="code">Object</span>.
Method <span class="code">decide(Object)</span> should return one of three constants,
<span class="code">Filter.ACCEPT</span>, <span class="code">Filter.DENY</span>,
or <span class="code">Filter.NEUTRAL</span> which may be interpreted as the <span class="code">Filter</span>
accepts, denies, or is neutral towards the <span class="code">Object</span> parameter.
</p>
<p class="body">
A <span class="code">FilterChain</span> is a particular <span class="code">Filter</span>
that contains a chain of <span class="code">Filter</span>s.
<span class="code">FilterChain</span> method <span class="code">decide(Object)</span>
applies the <span class="code">Filter</span>s in chain order.
If a <span class="code">Filter</span> in the chain
accepts the <span class="code">Object</span>, then the <span class="code">FilterChain</span>
accepts the <span class="code">Object</span> without consulting the remaining <span class="code">Filter</span>s.
If a <span class="code">Filter</span>
denies the <span class="code">Object</span>, then the <span class="code">FilterChain</span>
denies the <span class="code">Object</span> without consulting the remaining <span class="code">Filter</span>s.
If all <span class="code">Filter</span>s are neutral towards the <span class="code">Object</span>,
then so too is the <span class="code">FilterChain</span>. When you require filtering based on a sequence
of simpler decisions, you should consider incorporating <span class="code">Filter</span>s
in a <span class="code">FilterChain</span>.
<a href="api/com/puppycrawl/tools/checkstyle/filters/CSVFilter.html">CSVFilter</a>, a filter for comma-separated values,
is an example of such filtering.
</p>
<p class="body">
Here is a UML diagram for interface <span class="code">Filter</span>
and class <span class="code">FilterChain</span>.
</p>
<img src="Filter.gif" width="261" height="379" 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 denies 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 int decide(Object aObject)
{
if (!(aObject instanceof AuditEvent)) {
return Filter.NEUTRAL;
}
final AuditEvent event = (AuditEvent) aObject;
final String fileName = event.getFileName();
if ((fileName != null) && mFileRegexp.match(fileName)) {
return Filter.DENY;
}
else {
return Filter.NEUTRAL;
}
}
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 chain 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 deny reporting of
audit events for files whose name contains &quot;Generated&quot;, include the following module in the
configuration file:
</p>
<pre class="body">
&lt;module name=&quot;com.mycompany.filters.FilesFilter&quot;&gt;
&lt;property name=&quot;files&quot; value=&quot;Generated&quot;/&gt;
&lt;/module&gt;
</pre>
<a name="huh"></a> <h2>Huh? I can&#39;t figure it out!</h2>
<p class="body">
That&#39;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&#39;t know how, can you help me?&quot;. 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 &copy; 2002-2003 Oliver Burn. All rights Reserved.
</p>
</body>
</html>