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