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.api.AuditEvent;
26 import com.puppycrawl.tools.checkstyle.api.Filter;
27
28 /**
29 * <div>
30 * Filter {@code SuppressionSingleFilter} suppresses audit events for Checks violations in the
31 * specified file, class, checks, message, module id, lines, and columns.
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 on common
41 * files/folders is better to put in checkstyle configuration as common rule. All suppression that
42 * are for specific file names is better to keep in project specific config file.
43 * </p>
44 *
45 * <p>
46 * Attention: This filter only supports single suppression, and will need multiple instances if
47 * users wants to suppress multiple violations.
48 * </p>
49 *
50 * <p>
51 * Notes:
52 * {@code SuppressionSingleFilter} can suppress Checks that have {@code Treewalker} or
53 * {@code Checker} as parent module.
54 * </p>
55 * <ul>
56 * <li>
57 * Property {@code checks} - Define the RegExp for matching against the name of the check
58 * associated with an audit event.
59 * Type is {@code java.util.regex.Pattern}.
60 * Default value is {@code null}.
61 * </li>
62 * <li>
63 * Property {@code columns} - Specify a comma-separated list of values, where each value is an
64 * integer or a range of integers denoted by integer-integer.
65 * Type is {@code java.lang.String}.
66 * Default value is {@code null}.
67 * </li>
68 * <li>
69 * Property {@code files} - Define the RegExp for matching against the file name associated with
70 * an audit event.
71 * Type is {@code java.util.regex.Pattern}.
72 * Default value is {@code null}.
73 * </li>
74 * <li>
75 * Property {@code id} - Specify a string matched against the ID of the check associated with
76 * an audit event.
77 * Type is {@code java.lang.String}.
78 * Default value is {@code null}.
79 * </li>
80 * <li>
81 * Property {@code lines} - Specify a comma-separated list of values, where each value is an
82 * integer or a range of integers denoted by integer-integer.
83 * Type is {@code java.lang.String}.
84 * Default value is {@code null}.
85 * </li>
86 * <li>
87 * Property {@code message} - Define the RegExp for matching against the message of the check
88 * associated with an audit event.
89 * Type is {@code java.util.regex.Pattern}.
90 * Default value is {@code null}.
91 * </li>
92 * </ul>
93 *
94 * <p>
95 * Parent is {@code com.puppycrawl.tools.checkstyle.Checker}
96 * </p>
97 *
98 * @since 8.23
99 */
100 public class SuppressionSingleFilter extends AbstractAutomaticBean implements Filter {
101
102 /**
103 * SuppressFilterElement instance.
104 */
105 private SuppressFilterElement filter;
106 /**
107 * Define the RegExp for matching against the file name associated with an audit event.
108 */
109 private Pattern files;
110 /**
111 * Define the RegExp for matching against the name of the check associated with an audit event.
112 */
113 private Pattern checks;
114 /**
115 * Define the RegExp for matching against the message of the check associated with an audit
116 * event.
117 */
118 private Pattern message;
119 /**
120 * Specify a string matched against the ID of the check associated with an audit event.
121 */
122 private String id;
123 /**
124 * Specify a comma-separated list of values, where each value is an integer or a range of
125 * integers denoted by integer-integer.
126 */
127 private String lines;
128 /**
129 * Specify a comma-separated list of values, where each value is an integer or a range of
130 * integers denoted by integer-integer.
131 */
132 private String columns;
133
134 /**
135 * Setter to define the RegExp for matching against the file name associated with an audit
136 * event.
137 *
138 * @param files regular expression for filtered file names
139 * @since 8.23
140 */
141 public void setFiles(Pattern files) {
142 this.files = files;
143 }
144
145 /**
146 * Setter to define the RegExp for matching against the name of the check associated with an
147 * audit event.
148 *
149 * @param checks the name of the check
150 * @since 8.23
151 */
152 public void setChecks(String checks) {
153 this.checks = Pattern.compile(checks);
154 }
155
156 /**
157 * Setter to define the RegExp for matching against the message of the check associated with
158 * an audit event.
159 *
160 * @param message the message of the check
161 * @since 8.23
162 */
163 public void setMessage(Pattern message) {
164 this.message = message;
165 }
166
167 /**
168 * Setter to specify a string matched against the ID of the check associated with an audit
169 * event.
170 *
171 * @param id the ID of the check
172 * @since 8.23
173 */
174 public void setId(String id) {
175 this.id = id;
176 }
177
178 /**
179 * Setter to specify a comma-separated list of values, where each value is an integer or a
180 * range of integers denoted by integer-integer.
181 *
182 * @param lines the lines of the check
183 * @since 8.23
184 */
185 public void setLines(String lines) {
186 this.lines = lines;
187 }
188
189 /**
190 * Setter to specify a comma-separated list of values, where each value is an integer or a
191 * range of integers denoted by integer-integer.
192 *
193 * @param columns the columns of the check
194 * @since 8.23
195 */
196 public void setColumns(String columns) {
197 this.columns = columns;
198 }
199
200 @Override
201 protected void finishLocalSetup() {
202 filter = new SuppressFilterElement(files, checks, message, id, lines, columns);
203 }
204
205 @Override
206 public boolean accept(AuditEvent event) {
207 return filter.accept(event);
208 }
209
210 }