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