001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2023 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle.filters; 021 022import java.util.regex.Pattern; 023 024import com.puppycrawl.tools.checkstyle.AbstractAutomaticBean; 025import com.puppycrawl.tools.checkstyle.api.AuditEvent; 026import com.puppycrawl.tools.checkstyle.api.Filter; 027 028/** 029 * <p> 030 * Filter {@code SuppressionSingleFilter} suppresses audit events for Checks violations in the 031 * specified file, class, checks, message, module id, lines, and columns. 032 * </p> 033 * <p> 034 * Rationale: To allow users use suppressions configured in the same config with other modules. 035 * SuppressionFilter and SuppressionXpathFilter are require separate file. 036 * </p> 037 * <p> 038 * Advice: If checkstyle configuration is used for several projects, single suppressions on common 039 * files/folders is better to put in checkstyle configuration as common rule. All suppression that 040 * are for specific file names is better to keep in project specific config file. 041 * </p> 042 * <p> 043 * Attention: This filter only supports single suppression, and will need multiple instances if 044 * users wants to suppress multiple violations. 045 * </p> 046 * <p> 047 * SuppressionSingleFilter can suppress Checks that have Treewalker or 048 * Checker as parent module. 049 * </p> 050 * <ul> 051 * <li> 052 * Property {@code files} - Define the RegExp for matching against the file name associated with 053 * an audit event. 054 * Type is {@code java.util.regex.Pattern}. 055 * Default value is {@code null}. 056 * </li> 057 * <li> 058 * Property {@code checks} - Define the RegExp for matching against the name of the check 059 * associated with an audit event. 060 * Type is {@code java.util.regex.Pattern}. 061 * Default value is {@code null}. 062 * </li> 063 * <li> 064 * Property {@code message} - Define the RegExp for matching against the message of the check 065 * associated with an audit event. 066 * Type is {@code java.util.regex.Pattern}. 067 * Default value is {@code null}. 068 * </li> 069 * <li> 070 * Property {@code id} - Specify a string matched against the ID of the check associated with 071 * an audit event. 072 * Type is {@code java.lang.String}. 073 * Default value is {@code null}. 074 * </li> 075 * <li> 076 * Property {@code lines} - Specify a comma-separated list of values, where each value is an 077 * integer or a range of integers denoted by integer-integer. 078 * Type is {@code java.lang.String}. 079 * Default value is {@code null}. 080 * </li> 081 * <li> 082 * Property {@code columns} - Specify a comma-separated list of values, where each value is an 083 * integer or a range of integers denoted by integer-integer. 084 * Type is {@code java.lang.String}. 085 * Default value is {@code null}. 086 * </li> 087 * </ul> 088 * <p> 089 * The following suppressions directs a {@code SuppressionSingleFilter} to reject 090 * {@code JavadocStyleCheck} violations for lines 82 and 108 to 122 of file 091 * {@code AbstractComplexityCheck.java}, and 092 * {@code MagicNumberCheck} violations for line 221 of file 093 * {@code JavadocStyleCheck.java}, and {@code 'Missing a Javadoc comment'} violations for all lines 094 * and files: 095 * </p> 096 * <pre> 097 * <module name="SuppressionSingleFilter"> 098 * <property name="checks" value="JavadocStyleCheck"/> 099 * <property name="files" value="AbstractComplexityCheck.java"/> 100 * <property name="lines" value="82,108-122"/> 101 * </module> 102 * <module name="SuppressionSingleFilter"> 103 * <property name="checks" value="MagicNumberCheck"/> 104 * <property name="files" value="JavadocStyleCheck.java"/> 105 * <property name="lines" value="221"/> 106 * </module> 107 * <module name="SuppressionSingleFilter"> 108 * <property name="message" value="Missing a Javadoc comment"/> 109 * </module> 110 * </pre> 111 * <p> 112 * Suppress check by <a href="https://checkstyle.org/config.html#Id">module id</a> when config 113 * have two instances on the same check: 114 * </p> 115 * <pre> 116 * <module name="SuppressionSingleFilter"> 117 * <property name="id" value="stringEqual"/> 118 * <property name="files" value="SomeTestCode.java"/> 119 * </module> 120 * </pre> 121 * <p> 122 * Suppress all checks for hidden files and folders: 123 * </p> 124 * <pre> 125 * <module name="SuppressionSingleFilter"> 126 * <property name="files" value="[/\\]\..+"/> 127 * <property name="checks" value=".*"/> 128 * </module> 129 * </pre> 130 * <p> 131 * Suppress all checks for Maven-generated code: 132 * </p> 133 * <pre> 134 * <module name="SuppressionSingleFilter"> 135 * <property name="files" value="[/\\]target[/\\]"/> 136 * <property name="checks" value=".*"/> 137 * </module> 138 * </pre> 139 * <p> 140 * Suppress all checks for archives, classes and other binary files: 141 * </p> 142 * <pre> 143 * <module name="SuppressionSingleFilter"> 144 * <property name="files" value=".+\.(?:jar|zip|war|class|tar|bin)$"/> 145 * <property name="checks" value=".*"/> 146 * </module> 147 * </pre> 148 * <p> 149 * Suppress all checks for image files: 150 * </p> 151 * <pre> 152 * <module name="SuppressionSingleFilter"> 153 * <property name="files" value=".+\.(?:png|gif|jpg|jpeg)$"/> 154 * <property name="checks" value=".*"/> 155 * </module> 156 * </pre> 157 * <p> 158 * Suppress all checks for non-java files: 159 * </p> 160 * <pre> 161 * <module name="SuppressionSingleFilter"> 162 * <property name="files" 163 * value=".+\.(?:txt|xml|csv|sh|thrift|html|sql|eot|ttf|woff|css|png)$"/> 164 * <property name="checks" value=".*"/> 165 * </module> 166 * </pre> 167 * <p> 168 * Suppress all checks in generated sources: 169 * </p> 170 * <pre> 171 * <module name="SuppressionSingleFilter"> 172 * <property name="files" value="com[\\/]mycompany[\\/]app[\\/]gen[\\/]"/> 173 * <property name="checks" value=".*"/> 174 * </module> 175 * </pre> 176 * <p> 177 * Suppress FileLength check on integration tests in certain folder: 178 * </p> 179 * <pre> 180 * <module name="SuppressionSingleFilter"> 181 * <property name="files" value="com[\\/]mycompany[\\/]app[\\/].*IT.java"/> 182 * <property name="checks" value="FileLength"/> 183 * </module> 184 * </pre> 185 * <p> 186 * Suppress naming violations on variable named 'log' in all files: 187 * </p> 188 * <pre> 189 * <module name="SuppressionSingleFilter"> 190 * <property name="message" value="Name 'log' must match pattern"/> 191 * </module> 192 * </pre> 193 * <p> 194 * Parent is {@code com.puppycrawl.tools.checkstyle.Checker} 195 * </p> 196 * 197 * @since 8.23 198 */ 199public class SuppressionSingleFilter extends AbstractAutomaticBean implements Filter { 200 201 /** 202 * SuppressFilterElement instance. 203 */ 204 private SuppressFilterElement filter; 205 /** 206 * Define the RegExp for matching against the file name associated with an audit event. 207 */ 208 private Pattern files; 209 /** 210 * Define the RegExp for matching against the name of the check associated with an audit event. 211 */ 212 private Pattern checks; 213 /** 214 * Define the RegExp for matching against the message of the check associated with an audit 215 * event. 216 */ 217 private Pattern message; 218 /** 219 * Specify a string matched against the ID of the check associated with an audit event. 220 */ 221 private String id; 222 /** 223 * Specify a comma-separated list of values, where each value is an integer or a range of 224 * integers denoted by integer-integer. 225 */ 226 private String lines; 227 /** 228 * Specify a comma-separated list of values, where each value is an integer or a range of 229 * integers denoted by integer-integer. 230 */ 231 private String columns; 232 233 /** 234 * Setter to define the RegExp for matching against the file name associated with an audit 235 * event. 236 * 237 * @param files regular expression for filtered file names 238 */ 239 public void setFiles(Pattern files) { 240 this.files = files; 241 } 242 243 /** 244 * Setter to define the RegExp for matching against the name of the check associated with an 245 * audit event. 246 * 247 * @param checks the name of the check 248 */ 249 public void setChecks(String checks) { 250 this.checks = Pattern.compile(checks); 251 } 252 253 /** 254 * Setter to define the RegExp for matching against the message of the check associated with 255 * an audit event. 256 * 257 * @param message the message of the check 258 */ 259 public void setMessage(Pattern message) { 260 this.message = message; 261 } 262 263 /** 264 * Setter to specify a string matched against the ID of the check associated with an audit 265 * event. 266 * 267 * @param id the ID of the check 268 */ 269 public void setId(String id) { 270 this.id = id; 271 } 272 273 /** 274 * Setter to specify a comma-separated list of values, where each value is an integer or a 275 * range of integers denoted by integer-integer. 276 * 277 * @param lines the lines of the check 278 */ 279 public void setLines(String lines) { 280 this.lines = lines; 281 } 282 283 /** 284 * Setter to specify a comma-separated list of values, where each value is an integer or a 285 * range of integers denoted by integer-integer. 286 * 287 * @param columns the columns of the check 288 */ 289 public void setColumns(String columns) { 290 this.columns = columns; 291 } 292 293 @Override 294 protected void finishLocalSetup() { 295 filter = new SuppressFilterElement(files, checks, message, id, lines, columns); 296 } 297 298 @Override 299 public boolean accept(AuditEvent event) { 300 return filter.accept(event); 301 } 302 303}