From a9bfdceec2a2d86a622c03fbd4052f007b5e70cc Mon Sep 17 00:00:00 2001 From: Rick Giles Date: Tue, 15 Jul 2003 11:10:15 +0000 Subject: [PATCH] completed Filter docs. --- .../com/mycompany/filters/FilesFilter.java | 44 +++++ docs/Filter.gif | Bin 0 -> 4254 bytes docs/index.html | 1 + docs/releasenotes.html | 3 + docs/writingfilters.html | 187 ++++++++++++++++++ 5 files changed, 235 insertions(+) create mode 100644 contrib/examples/filters/com/mycompany/filters/FilesFilter.java create mode 100644 docs/Filter.gif create mode 100644 docs/writingfilters.html diff --git a/contrib/examples/filters/com/mycompany/filters/FilesFilter.java b/contrib/examples/filters/com/mycompany/filters/FilesFilter.java new file mode 100644 index 000000000..584dd3779 --- /dev/null +++ b/contrib/examples/filters/com/mycompany/filters/FilesFilter.java @@ -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); + } +} diff --git a/docs/Filter.gif b/docs/Filter.gif new file mode 100644 index 0000000000000000000000000000000000000000..b123fcc3ca54c69d3fda7be4a045b0eba0eb9877 GIT binary patch literal 4254 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 Line
  • Writing Checks
  • Writing Listeners
    • +
  • Writing Filters

    • SourceForge

    diff --git a/docs/releasenotes.html b/docs/releasenotes.html index 684788209..f40efa642 100644 --- a/docs/releasenotes.html +++ b/docs/releasenotes.html @@ -121,6 +121,9 @@
  • Added usage checks OneMethodPrivateFieldCheck, UnusedLocalVariableCheck, UnusedParameterCheck, UnusedPrivateFieldCheck, UnusedPrivateMethodCheck.
    • +
  • Added filters for audit events (partially fulfills request 559103). + A SuppressionFilter denies events according to a suppressions file (request 756416).
    • +

    diff --git a/docs/writingfilters.html b/docs/writingfilters.html new file mode 100644 index 000000000..0c583e77d --- /dev/null +++ b/docs/writingfilters.html @@ -0,0 +1,187 @@ + + + + + Writing your own filters + + + + + + + + + + +

    Writing your own Filters

    		Checkstyle Logo
    + + + + + + + + +
    +

    + Overview +

    +

    + Writing Filters +

    +

    + Using Filters +

    +

    + Huh? +

    +

    + Contributing +

    +

    Overview

    +

    + A Checker has a chain of Filters + that decide which audit events the Checker reports through its listeners. + Interface Filter and class FilterChain + are intended to support general Object filtering in a filter chain. +

    +

    + A Filter has one method, decide(Object), + that determines the result of filtering an Object. + Method decide(Object) should return one of three constants, + Filter.ACCEPT, Filter.DENY, + or Filter.NEUTRAL which may be interpreted as the Filter + accepts, denies, or is neutral towards the Object parameter. +

    +

    + A FilterChain is a particular Filter + that contains a chain of Filters. + FilterChain method decide(Object) + applies the Filters in chain order. + If a Filter in the chain + accepts the Object, then the FilterChain + accepts the Object without consulting the remaining Filters. + If a Filter + denies the Object, then the FilterChain + denies the Object without consulting the remaining Filters. + If all Filters are neutral towards the Object, + then so too is the FilterChain. When you require filtering based on a sequence + of simpler decisions, you should consider incorporating Filters + in a FilterChain. + CSVFilter, a filter for comma-separated values, + is an example of such filtering. +

    +

    + Here is a UML diagram for interface Filter + and class FilterChain. +

    + Filter UML diagram + +

    Writing Filters

    + +

    + The Filter that we demonstrate here denies audit events for files whose name matches a + regular expression. + In order to enable the specification of the file name pattern as a property in a configuration file, + the Filter is an + AutomaticBean + with mutator method setFiles(String) that receives the file name pattern. + An AutomaticBean uses JavaBean introspection to set JavaBean properties such as + files. +

    + + 
    +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);
+    }
+}
    +

    Using Filters

    + +

    + To incorporate a Filter in the filter chain for a Checker, + include a module element for the Filter in the + configuration file. For example, to configure a Checker + so that it uses custom filter FilesFilter to deny reporting of + audit events for files whose name contains "Generated", include the following module in the + configuration file: +

    + + 
         
+    <module name="com.mycompany.filters.FilesFilter">
+        <property name="files" value="Generated"/>
+    </module>
+
    + +

    Huh? I can't figure it out!

    +

    + 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 listener 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. +

    + +

    Contributing

    +

    + We need your help to keep improving Checkstyle. + + Whenever you write a filter that you think is generally useful, please + consider contributing it to the Checkstyle + community and submit it for inclusion in the next release of Checkstyle. + +

    + +
    +

    + +

    +Copyright © 2002-2003 Oliver Burn. All rights Reserved. +

    + +