1 /////////////////////////////////////////////////////////////////////////////////////////////// 2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules. 3 // Copyright (C) 2001-2025 the original author or authors. 4 // 5 // This library is free software; you can redistribute it and/or 6 // modify it under the terms of the GNU Lesser General Public 7 // License as published by the Free Software Foundation; either 8 // version 2.1 of the License, or (at your option) any later version. 9 // 10 // This library is distributed in the hope that it will be useful, 11 // but WITHOUT ANY WARRANTY; without even the implied warranty of 12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 // Lesser General Public License for more details. 14 // 15 // You should have received a copy of the GNU Lesser General Public 16 // License along with this library; if not, write to the Free Software 17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 /////////////////////////////////////////////////////////////////////////////////////////////// 19 20 package com.puppycrawl.tools.checkstyle.filters; 21 22 import java.util.regex.Pattern; 23 24 import com.puppycrawl.tools.checkstyle.AbstractAutomaticBean; 25 import com.puppycrawl.tools.checkstyle.TreeWalkerAuditEvent; 26 import com.puppycrawl.tools.checkstyle.TreeWalkerFilter; 27 28 /** 29 * <div> 30 * Filter {@code SuppressionXpathSingleFilter} suppresses audit events for Checks 31 * violations in the specified file, class, checks, message, module id, and xpath. 32 * </div> 33 * 34 * <p> 35 * Rationale: To allow users to use suppressions configured in the same config as other modules. 36 * {@code SuppressionFilter} and {@code SuppressionXpathFilter} require a separate file. 37 * </p> 38 * 39 * <p> 40 * Advice: If checkstyle configuration is used for several projects, single suppressions 41 * on common files/folders is better to put in checkstyle configuration as common rule. 42 * All suppression that are for specific file names is better to keep in project 43 * specific config file. 44 * </p> 45 * 46 * <p> 47 * Attention: This filter only supports single suppression, and will need multiple 48 * instances if users wants to suppress multiple violations. 49 * </p> 50 * 51 * <p> 52 * Notes: 53 * {@code SuppressionXpathSingleFilter} can suppress Checks that have {@code Treewalker} as parent module. 54 * </p> 55 * <ul> 56 * <li> 57 * Property {@code checks} - Define a Regular Expression matched against the name 58 * of the check associated with an audit event. 59 * Type is {@code java.util.regex.Pattern}. 60 * Default value is {@code null}. 61 * </li> 62 * <li> 63 * Property {@code files} - Define a Regular Expression matched against the file 64 * name associated with an audit event. 65 * Type is {@code java.util.regex.Pattern}. 66 * Default value is {@code null}. 67 * </li> 68 * <li> 69 * Property {@code id} - Define a string matched against the ID of the check 70 * associated with an audit event. 71 * Type is {@code java.lang.String}. 72 * Default value is {@code null}. 73 * </li> 74 * <li> 75 * Property {@code message} - Define a Regular Expression matched against the message 76 * of the check associated with an audit event. 77 * Type is {@code java.util.regex.Pattern}. 78 * Default value is {@code null}. 79 * </li> 80 * <li> 81 * Property {@code query} - Define a string xpath query. 82 * Type is {@code java.lang.String}. 83 * Default value is {@code null}. 84 * </li> 85 * </ul> 86 * 87 * <p> 88 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 89 * </p> 90 * 91 * @since 8.18 92 */ 93 public class SuppressionXpathSingleFilter extends AbstractAutomaticBean implements 94 TreeWalkerFilter { 95 /** 96 * XpathFilterElement instance. 97 */ 98 private XpathFilterElement xpathFilter; 99 /** 100 * Define a Regular Expression matched against the file name associated with an audit event. 101 */ 102 private Pattern files; 103 /** 104 * Define a Regular Expression matched against the name of the check associated 105 * with an audit event. 106 */ 107 private Pattern checks; 108 /** 109 * Define a Regular Expression matched against the message of the check 110 * associated with an audit event. 111 */ 112 private Pattern message; 113 /** 114 * Define a string matched against the ID of the check associated with an audit event. 115 */ 116 private String id; 117 /** 118 * Define a string xpath query. 119 */ 120 private String query; 121 122 /** 123 * Setter to define a Regular Expression matched against the file name 124 * associated with an audit event. 125 * 126 * @param files the name of the file 127 * @since 8.18 128 */ 129 public void setFiles(String files) { 130 if (files == null) { 131 this.files = null; 132 } 133 else { 134 this.files = Pattern.compile(files); 135 } 136 } 137 138 /** 139 * Setter to define a Regular Expression matched against the name of the check 140 * associated with an audit event. 141 * 142 * @param checks the name of the check 143 * @since 8.18 144 */ 145 public void setChecks(String checks) { 146 if (checks == null) { 147 this.checks = null; 148 } 149 else { 150 this.checks = Pattern.compile(checks); 151 } 152 } 153 154 /** 155 * Setter to define a Regular Expression matched against the message of 156 * the check associated with an audit event. 157 * 158 * @param message the message of the check 159 * @since 8.18 160 */ 161 public void setMessage(String message) { 162 if (message == null) { 163 this.message = null; 164 } 165 else { 166 this.message = Pattern.compile(message); 167 } 168 } 169 170 /** 171 * Setter to define a string matched against the ID of the check associated 172 * with an audit event. 173 * 174 * @param id the ID of the check 175 * @since 8.18 176 */ 177 public void setId(String id) { 178 this.id = id; 179 } 180 181 /** 182 * Setter to define a string xpath query. 183 * 184 * @param query the xpath query 185 * @since 8.18 186 */ 187 public void setQuery(String query) { 188 this.query = query; 189 } 190 191 @Override 192 protected void finishLocalSetup() { 193 xpathFilter = new XpathFilterElement(files, checks, message, id, query); 194 } 195 196 @Override 197 public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent) { 198 return xpathFilter.accept(treeWalkerAuditEvent); 199 } 200 201 }