1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2026 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 *
56 * @since 8.18
57 */
58 public class SuppressionXpathSingleFilter extends AbstractAutomaticBean implements
59 TreeWalkerFilter {
60
61 /**
62 * XpathFilterElement instance.
63 */
64 private XpathFilterElement xpathFilter;
65 /**
66 * Define a Regular Expression matched against the file name associated with an audit event.
67 */
68 private Pattern files;
69 /**
70 * Define a Regular Expression matched against the name of the check associated
71 * with an audit event.
72 */
73 private Pattern checks;
74 /**
75 * Define a Regular Expression matched against the message of the check
76 * associated with an audit event.
77 */
78 private Pattern message;
79 /**
80 * Define a string matched against the ID of the check associated with an audit event.
81 */
82 private String id;
83 /**
84 * Define a string xpath query.
85 */
86 private String query;
87
88 /**
89 * Creates a new {@code SuppressionXpathSingleFilter} instance.
90 */
91 public SuppressionXpathSingleFilter() {
92 // no code by default
93 }
94
95 /**
96 * Setter to define a Regular Expression matched against the file name
97 * associated with an audit event.
98 *
99 * @param files the name of the file
100 * @since 8.18
101 */
102 public void setFiles(String files) {
103 if (files == null) {
104 this.files = null;
105 }
106 else {
107 this.files = Pattern.compile(files);
108 }
109 }
110
111 /**
112 * Setter to define a Regular Expression matched against the name of the check
113 * associated with an audit event.
114 * The pattern is matched against the fully qualified class name of the Check.
115 *
116 * @param checks the name of the check
117 * @since 8.18
118 */
119 public void setChecks(String checks) {
120 if (checks == null) {
121 this.checks = null;
122 }
123 else {
124 this.checks = Pattern.compile(checks);
125 }
126 }
127
128 /**
129 * Setter to define a Regular Expression matched against the message of
130 * the check associated with an audit event.
131 *
132 * @param message the message of the check
133 * @since 8.18
134 */
135 public void setMessage(String message) {
136 if (message == null) {
137 this.message = null;
138 }
139 else {
140 this.message = Pattern.compile(message);
141 }
142 }
143
144 /**
145 * Setter to define a string matched against the ID of the check associated
146 * with an audit event.
147 *
148 * @param id the ID of the check
149 * @since 8.18
150 */
151 public void setId(String id) {
152 this.id = id;
153 }
154
155 /**
156 * Setter to define a string xpath query.
157 *
158 * @param query the xpath query
159 * @since 8.18
160 */
161 public void setQuery(String query) {
162 this.query = query;
163 }
164
165 @Override
166 protected void finishLocalSetup() {
167 xpathFilter = new XpathFilterElement(files, checks, message, id, query);
168 }
169
170 @Override
171 public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent) {
172 return xpathFilter.accept(treeWalkerAuditEvent);
173 }
174
175 }