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 *
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 *
107 * @param checks the name of the check
108 * @since 8.18
109 */
110 public void setChecks(String checks) {
111 if (checks == null) {
112 this.checks = null;
113 }
114 else {
115 this.checks = Pattern.compile(checks);
116 }
117 }
118
119 /**
120 * Setter to define a Regular Expression matched against the message of
121 * the check associated with an audit event.
122 *
123 * @param message the message of the check
124 * @since 8.18
125 */
126 public void setMessage(String message) {
127 if (message == null) {
128 this.message = null;
129 }
130 else {
131 this.message = Pattern.compile(message);
132 }
133 }
134
135 /**
136 * Setter to define a string matched against the ID of the check associated
137 * with an audit event.
138 *
139 * @param id the ID of the check
140 * @since 8.18
141 */
142 public void setId(String id) {
143 this.id = id;
144 }
145
146 /**
147 * Setter to define a string xpath query.
148 *
149 * @param query the xpath query
150 * @since 8.18
151 */
152 public void setQuery(String query) {
153 this.query = query;
154 }
155
156 @Override
157 protected void finishLocalSetup() {
158 xpathFilter = new XpathFilterElement(files, checks, message, id, query);
159 }
160
161 @Override
162 public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent) {
163 return xpathFilter.accept(treeWalkerAuditEvent);
164 }
165
166 }