001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2024 the original author or authors.
004//
005// This library is free software; you can redistribute it and/or
006// modify it under the terms of the GNU Lesser General Public
007// License as published by the Free Software Foundation; either
008// version 2.1 of the License, or (at your option) any later version.
009//
010// This library is distributed in the hope that it will be useful,
011// but WITHOUT ANY WARRANTY; without even the implied warranty of
012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013// Lesser General Public License for more details.
014//
015// You should have received a copy of the GNU Lesser General Public
016// License along with this library; if not, write to the Free Software
017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018///////////////////////////////////////////////////////////////////////////////////////////////
019
020package com.puppycrawl.tools.checkstyle.filters;
021
022import java.util.regex.Pattern;
023
024import com.puppycrawl.tools.checkstyle.AbstractAutomaticBean;
025import com.puppycrawl.tools.checkstyle.api.AuditEvent;
026import com.puppycrawl.tools.checkstyle.api.Filter;
027
028/**
029 * <div>
030 * Filter {@code SuppressionSingleFilter} suppresses audit events for Checks violations in the
031 * specified file, class, checks, message, module id, lines, and columns.
032 * </div>
033 *
034 * <p>
035 * Rationale: To allow users to use suppressions configured in the same config as other modules.
036 * {@code SuppressionFilter} and {@code SuppressionXpathFilter} require a separate file.
037 * </p>
038 *
039 * <p>
040 * Advice: If checkstyle configuration is used for several projects, single suppressions on common
041 * files/folders is better to put in checkstyle configuration as common rule. All suppression that
042 * are for specific file names is better to keep in project specific config file.
043 * </p>
044 *
045 * <p>
046 * Attention: This filter only supports single suppression, and will need multiple instances if
047 * users wants to suppress multiple violations.
048 * </p>
049 *
050 * <p>
051 * {@code SuppressionSingleFilter} can suppress Checks that have {@code Treewalker} or
052 * {@code Checker} as parent module.
053 * </p>
054 * <ul>
055 * <li>
056 * Property {@code checks} - Define the RegExp for matching against the name of the check
057 * associated with an audit event.
058 * Type is {@code java.util.regex.Pattern}.
059 * Default value is {@code null}.
060 * </li>
061 * <li>
062 * Property {@code columns} - Specify a comma-separated list of values, where each value is an
063 * integer or a range of integers denoted by integer-integer.
064 * Type is {@code java.lang.String}.
065 * Default value is {@code null}.
066 * </li>
067 * <li>
068 * Property {@code files} - Define the RegExp for matching against the file name associated with
069 * an audit event.
070 * Type is {@code java.util.regex.Pattern}.
071 * Default value is {@code null}.
072 * </li>
073 * <li>
074 * Property {@code id} - Specify a string matched against the ID of the check associated with
075 * an audit event.
076 * Type is {@code java.lang.String}.
077 * Default value is {@code null}.
078 * </li>
079 * <li>
080 * Property {@code lines} - Specify a comma-separated list of values, where each value is an
081 * integer or a range of integers denoted by integer-integer.
082 * Type is {@code java.lang.String}.
083 * Default value is {@code null}.
084 * </li>
085 * <li>
086 * Property {@code message} - Define the RegExp for matching against the message of the check
087 * associated with an audit event.
088 * Type is {@code java.util.regex.Pattern}.
089 * Default value is {@code null}.
090 * </li>
091 * </ul>
092 *
093 * <p>
094 * Parent is {@code com.puppycrawl.tools.checkstyle.Checker}
095 * </p>
096 *
097 * @since 8.23
098 */
099public 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}