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.Set;
23
24 import com.puppycrawl.tools.checkstyle.AbstractAutomaticBean;
25 import com.puppycrawl.tools.checkstyle.api.AuditEvent;
26 import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
27 import com.puppycrawl.tools.checkstyle.api.ExternalResourceHolder;
28 import com.puppycrawl.tools.checkstyle.api.Filter;
29 import com.puppycrawl.tools.checkstyle.api.FilterSet;
30 import com.puppycrawl.tools.checkstyle.utils.FilterUtil;
31 import com.puppycrawl.tools.checkstyle.utils.UnmodifiableCollectionUtil;
32
33 /**
34 * <p>
35 * Filter {@code SuppressionFilter} rejects audit events for Check violations according to a
36 * <a href="https://checkstyle.org/dtds/suppressions_1_2.dtd">suppressions XML document</a>
37 * in a file. If there is no configured suppressions file or the optional is set to true and
38 * suppressions file was not found the Filter accepts all audit events.
39 * </p>
40 * <p>
41 * A <a href="https://checkstyle.org/dtds/suppressions_1_2.dtd">suppressions XML document</a>
42 * contains a set of {@code suppress} elements, where each {@code suppress}
43 * element can have the following attributes:
44 * </p>
45 * <ul>
46 * <li>
47 * {@code files} - a <a href="https://checkstyle.org/property_types.html#Pattern">
48 * Pattern</a> matched against the file name associated with an audit event.
49 * It is optional.
50 * </li>
51 * <li>
52 * {@code checks} - a <a href="https://checkstyle.org/property_types.html#Pattern">
53 * Pattern</a> matched against the name of the check associated with an audit event.
54 * Optional as long as {@code id} or {@code message} is specified.
55 * </li>
56 * <li>
57 * {@code message} - a <a href="https://checkstyle.org/property_types.html#Pattern">
58 * Pattern</a> matched against the message of the check associated with an audit event.
59 * Optional as long as {@code checks} or {@code id} is specified.
60 * </li>
61 * <li>
62 * {@code id} - a <a href="https://checkstyle.org/property_types.html#String">String</a>
63 * matched against the <a href="https://checkstyle.org/config.html#Id">check id</a>
64 * associated with an audit event.
65 * Optional as long as {@code checks} or {@code message} is specified.
66 * </li>
67 * <li>
68 * {@code lines} - a comma-separated list of values, where each value is an
69 * <a href="https://checkstyle.org/property_types.html#int">int</a>
70 * or a range of integers denoted by integer-integer.
71 * It is optional.
72 * </li>
73 * <li>
74 * {@code columns} - a comma-separated list of values, where each value is an
75 * <a href="https://checkstyle.org/property_types.html#int">int</a>
76 * or a range of integers denoted by integer-integer.
77 * It is optional.
78 * </li>
79 * </ul>
80 * <p>
81 * Each audit event is checked against each {@code suppress} element.
82 * It is suppressed if all specified attributes match against the audit event.
83 * </p>
84 * <p>
85 * ATTENTION: filtering by message is dependent on runtime locale.
86 * If project is running in different languages it is better to avoid filtering by message.
87 * </p>
88 * <p>
89 * You can download template of empty suppression filter
90 * <a href="https://checkstyle.org/files/suppressions_none.xml">here</a>.
91 * </p>
92 * <p>
93 * Location of the file defined in {@code file} property is checked in the following order:
94 * </p>
95 * <ol>
96 * <li>
97 * as a filesystem location
98 * </li>
99 * <li>
100 * if no file found, and the location starts with either {@code http://} or {@code https://},
101 * then it is interpreted as a URL
102 * </li>
103 * <li>
104 * if no file found, then passed to the {@code ClassLoader.getResource()} method.
105 * </li>
106 * </ol>
107 * <p>
108 * SuppressionFilter can suppress Checks that have Treewalker or Checker as parent module.
109 * </p>
110 * <ul>
111 * <li>
112 * Property {@code file} - Specify the location of the <em>suppressions XML document</em> file.
113 * Type is {@code java.lang.String}.
114 * Default value is {@code null}.
115 * </li>
116 * <li>
117 * Property {@code optional} - Control what to do when the file is not existing.
118 * If {@code optional} is set to {@code false} the file must exist, or else it
119 * ends with error. On the other hand if optional is {@code true} and file is
120 * not found, the filter accept all audit events.
121 * Type is {@code boolean}.
122 * Default value is {@code false}.
123 * </li>
124 * </ul>
125 * <p>
126 * Parent is {@code com.puppycrawl.tools.checkstyle.Checker}
127 * </p>
128 *
129 * @since 3.2
130 */
131 public class SuppressionFilter
132 extends AbstractAutomaticBean
133 implements Filter, ExternalResourceHolder {
134
135 /** Specify the location of the <em>suppressions XML document</em> file. */
136 private String file;
137 /**
138 * Control what to do when the file is not existing. If {@code optional} is
139 * set to {@code false} the file must exist, or else it ends with error.
140 * On the other hand if optional is {@code true} and file is not found,
141 * the filter accept all audit events.
142 */
143 private boolean optional;
144 /** Set of individual suppresses. */
145 private FilterSet filters = new FilterSet();
146
147 /**
148 * Setter to specify the location of the <em>suppressions XML document</em> file.
149 *
150 * @param fileName name of the suppressions file.
151 * @since 3.2
152 */
153 public void setFile(String fileName) {
154 file = fileName;
155 }
156
157 /**
158 * Setter to control what to do when the file is not existing.
159 * If {@code optional} is set to {@code false} the file must exist, or else
160 * it ends with error. On the other hand if optional is {@code true}
161 * and file is not found, the filter accept all audit events.
162 *
163 * @param optional tells if config file existence is optional.
164 * @since 6.15
165 */
166 public void setOptional(boolean optional) {
167 this.optional = optional;
168 }
169
170 @Override
171 public boolean accept(AuditEvent event) {
172 return filters.accept(event);
173 }
174
175 @Override
176 protected void finishLocalSetup() throws CheckstyleException {
177 if (file != null) {
178 if (optional) {
179 if (FilterUtil.isFileExists(file)) {
180 filters = SuppressionsLoader.loadSuppressions(file);
181 }
182 }
183 else {
184 filters = SuppressionsLoader.loadSuppressions(file);
185 }
186 }
187 }
188
189 @Override
190 public Set<String> getExternalResourceLocations() {
191 return UnmodifiableCollectionUtil.singleton(file);
192 }
193
194 }