001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 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.TreeWalkerAuditEvent; 026import com.puppycrawl.tools.checkstyle.TreeWalkerFilter; 027 028/** 029 * <p> 030 * Filter {@code SuppressionXpathSingleFilter} suppresses audit events for Checks 031 * violations in the specified file, class, checks, message, module id, and xpath. 032 * </p> 033 * <p> 034 * Rationale: To allow users use suppressions configured in the same config with 035 * other modules. SuppressionFilter and SuppressionXpathFilter are require separate file. 036 * </p> 037 * <p> 038 * Advice: If checkstyle configuration is used for several projects, single suppressions 039 * on common files/folders is better to put in checkstyle configuration as common rule. 040 * All suppression that are for specific file names is better to keep in project 041 * specific config file. 042 * </p> 043 * <p> 044 * Attention: This filter only supports single suppression, and will need multiple 045 * instances if users wants to suppress multiple violations. 046 * </p> 047 * <p> 048 * SuppressionXpathSingleFilter can suppress Checks that have Treewalker as parent module. 049 * </p> 050 * <ul> 051 * <li> 052 * Property {@code checks} - Define a Regular Expression matched against the name 053 * of the check associated with an audit event. 054 * Type is {@code java.util.regex.Pattern}. 055 * Default value is {@code null}. 056 * </li> 057 * <li> 058 * Property {@code files} - Define a Regular Expression matched against the file 059 * name 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 id} - Define a string matched against the ID of the check 065 * associated with an audit event. 066 * Type is {@code java.lang.String}. 067 * Default value is {@code null}. 068 * </li> 069 * <li> 070 * Property {@code message} - Define a Regular Expression matched against the message 071 * of the check associated with an audit event. 072 * Type is {@code java.util.regex.Pattern}. 073 * Default value is {@code null}. 074 * </li> 075 * <li> 076 * Property {@code query} - Define a string xpath query. 077 * Type is {@code java.lang.String}. 078 * Default value is {@code null}. 079 * </li> 080 * </ul> 081 * <p> 082 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 083 * </p> 084 * 085 * @since 8.18 086 */ 087public class SuppressionXpathSingleFilter extends AbstractAutomaticBean implements 088 TreeWalkerFilter { 089 /** 090 * XpathFilterElement instance. 091 */ 092 private XpathFilterElement xpathFilter; 093 /** 094 * Define a Regular Expression matched against the file name associated with an audit event. 095 */ 096 private Pattern files; 097 /** 098 * Define a Regular Expression matched against the name of the check associated 099 * 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}