1 /////////////////////////////////////////////////////////////////////////////////////////////// 2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules. 3 // Copyright (C) 2001-2024 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 * <p> 30 * Filter {@code SuppressionXpathSingleFilter} suppresses audit events for Checks 31 * violations in the specified file, class, checks, message, module id, and xpath. 32 * </p> 33 * <p> 34 * Rationale: To allow users use suppressions configured in the same config with 35 * other modules. SuppressionFilter and SuppressionXpathFilter are require separate file. 36 * </p> 37 * <p> 38 * Advice: If checkstyle configuration is used for several projects, single suppressions 39 * on common files/folders is better to put in checkstyle configuration as common rule. 40 * All suppression that are for specific file names is better to keep in project 41 * specific config file. 42 * </p> 43 * <p> 44 * Attention: This filter only supports single suppression, and will need multiple 45 * instances if users wants to suppress multiple violations. 46 * </p> 47 * <p> 48 * SuppressionXpathSingleFilter can suppress Checks that have Treewalker as parent module. 49 * </p> 50 * <ul> 51 * <li> 52 * Property {@code checks} - Define a Regular Expression matched against the name 53 * of the check associated with an audit event. 54 * Type is {@code java.util.regex.Pattern}. 55 * Default value is {@code null}. 56 * </li> 57 * <li> 58 * Property {@code files} - Define a Regular Expression matched against the file 59 * name associated with an audit event. 60 * Type is {@code java.util.regex.Pattern}. 61 * Default value is {@code null}. 62 * </li> 63 * <li> 64 * Property {@code id} - Define a string matched against the ID of the check 65 * associated with an audit event. 66 * Type is {@code java.lang.String}. 67 * Default value is {@code null}. 68 * </li> 69 * <li> 70 * Property {@code message} - Define a Regular Expression matched against the message 71 * of the check associated with an audit event. 72 * Type is {@code java.util.regex.Pattern}. 73 * Default value is {@code null}. 74 * </li> 75 * <li> 76 * Property {@code query} - Define a string xpath query. 77 * Type is {@code java.lang.String}. 78 * Default value is {@code null}. 79 * </li> 80 * </ul> 81 * <p> 82 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 83 * </p> 84 * 85 * @since 8.18 86 */ 87 public class SuppressionXpathSingleFilter extends AbstractAutomaticBean implements 88 TreeWalkerFilter { 89 /** 90 * XpathFilterElement instance. 91 */ 92 private XpathFilterElement xpathFilter; 93 /** 94 * Define a Regular Expression matched against the file name associated with an audit event. 95 */ 96 private Pattern files; 97 /** 98 * Define a Regular Expression matched against the name of the check associated 99 * with an audit event. 100 */ 101 private Pattern checks; 102 /** 103 * Define a Regular Expression matched against the message of the check 104 * associated with an audit event. 105 */ 106 private Pattern message; 107 /** 108 * Define a string matched against the ID of the check associated with an audit event. 109 */ 110 private String id; 111 /** 112 * Define a string xpath query. 113 */ 114 private String query; 115 116 /** 117 * Setter to define a Regular Expression matched against the file name 118 * associated with an audit event. 119 * 120 * @param files the name of the file 121 * @since 8.18 122 */ 123 public void setFiles(String files) { 124 if (files == null) { 125 this.files = null; 126 } 127 else { 128 this.files = Pattern.compile(files); 129 } 130 } 131 132 /** 133 * Setter to define a Regular Expression matched against the name of the check 134 * associated with an audit event. 135 * 136 * @param checks the name of the check 137 * @since 8.18 138 */ 139 public void setChecks(String checks) { 140 if (checks == null) { 141 this.checks = null; 142 } 143 else { 144 this.checks = Pattern.compile(checks); 145 } 146 } 147 148 /** 149 * Setter to define a Regular Expression matched against the message of 150 * the check associated with an audit event. 151 * 152 * @param message the message of the check 153 * @since 8.18 154 */ 155 public void setMessage(String message) { 156 if (message == null) { 157 this.message = null; 158 } 159 else { 160 this.message = Pattern.compile(message); 161 } 162 } 163 164 /** 165 * Setter to define a string matched against the ID of the check associated 166 * with an audit event. 167 * 168 * @param id the ID of the check 169 * @since 8.18 170 */ 171 public void setId(String id) { 172 this.id = id; 173 } 174 175 /** 176 * Setter to define a string xpath query. 177 * 178 * @param query the xpath query 179 * @since 8.18 180 */ 181 public void setQuery(String query) { 182 this.query = query; 183 } 184 185 @Override 186 protected void finishLocalSetup() { 187 xpathFilter = new XpathFilterElement(files, checks, message, id, query); 188 } 189 190 @Override 191 public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent) { 192 return xpathFilter.accept(treeWalkerAuditEvent); 193 } 194 195 }