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.TreeWalkerAuditEvent;
026import com.puppycrawl.tools.checkstyle.TreeWalkerFilter;
027
028/**
029 * <div>
030 * Filter {@code SuppressionXpathSingleFilter} suppresses audit events for Checks
031 * violations in the specified file, class, checks, message, module id, and xpath.
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
041 * on common files/folders is better to put in checkstyle configuration as common rule.
042 * All suppression that are for specific file names is better to keep in project
043 * specific config file.
044 * </p>
045 *
046 * <p>
047 * Attention: This filter only supports single suppression, and will need multiple
048 * instances if users wants to suppress multiple violations.
049 * </p>
050 *
051 * <p>
052 * {@code SuppressionXpathSingleFilter} can suppress Checks that have {@code Treewalker} as parent module.
053 * </p>
054 * <ul>
055 * <li>
056 * Property {@code checks} - Define a Regular Expression matched against the name
057 * of the check 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 files} - Define a Regular Expression matched against the file
063 * name associated with an audit event.
064 * Type is {@code java.util.regex.Pattern}.
065 * Default value is {@code null}.
066 * </li>
067 * <li>
068 * Property {@code id} - Define a string matched against the ID of the check
069 * associated with an audit event.
070 * Type is {@code java.lang.String}.
071 * Default value is {@code null}.
072 * </li>
073 * <li>
074 * Property {@code message} - Define a Regular Expression matched against the message
075 * of the check associated with an audit event.
076 * Type is {@code java.util.regex.Pattern}.
077 * Default value is {@code null}.
078 * </li>
079 * <li>
080 * Property {@code query} - Define a string xpath query.
081 * Type is {@code java.lang.String}.
082 * Default value is {@code null}.
083 * </li>
084 * </ul>
085 *
086 * <p>
087 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
088 * </p>
089 *
090 * @since 8.18
091 */
092public class SuppressionXpathSingleFilter extends AbstractAutomaticBean implements
093        TreeWalkerFilter {
094    /**
095     * XpathFilterElement instance.
096     */
097    private XpathFilterElement xpathFilter;
098    /**
099     * Define a Regular Expression matched against the file name associated with an audit event.
100     */
101    private Pattern files;
102    /**
103     * Define a Regular Expression matched against the name of the check associated
104     * with an audit event.
105     */
106    private Pattern checks;
107    /**
108     * Define a Regular Expression matched against the message of the check
109     * associated with an audit event.
110     */
111    private Pattern message;
112    /**
113     * Define a string matched against the ID of the check associated with an audit event.
114     */
115    private String id;
116    /**
117     * Define a string xpath query.
118     */
119    private String query;
120
121    /**
122     * Setter to define a Regular Expression matched against the file name
123     * associated with an audit event.
124     *
125     * @param files the name of the file
126     * @since 8.18
127     */
128    public void setFiles(String files) {
129        if (files == null) {
130            this.files = null;
131        }
132        else {
133            this.files = Pattern.compile(files);
134        }
135    }
136
137    /**
138     * Setter to define a Regular Expression matched against the name of the check
139     * associated with an audit event.
140     *
141     * @param checks the name of the check
142     * @since 8.18
143     */
144    public void setChecks(String checks) {
145        if (checks == null) {
146            this.checks = null;
147        }
148        else {
149            this.checks = Pattern.compile(checks);
150        }
151    }
152
153    /**
154     * Setter to define a Regular Expression matched against the message of
155     * the check associated with an audit event.
156     *
157     * @param message the message of the check
158     * @since 8.18
159     */
160    public void setMessage(String message) {
161        if (message == null) {
162            this.message = null;
163        }
164        else {
165            this.message = Pattern.compile(message);
166        }
167    }
168
169    /**
170     * Setter to define a string matched against the ID of the check associated
171     * with an audit event.
172     *
173     * @param id the ID of the check
174     * @since 8.18
175     */
176    public void setId(String id) {
177        this.id = id;
178    }
179
180    /**
181     * Setter to define a string xpath query.
182     *
183     * @param query the xpath query
184     * @since 8.18
185     */
186    public void setQuery(String query) {
187        this.query = query;
188    }
189
190    @Override
191    protected void finishLocalSetup() {
192        xpathFilter = new XpathFilterElement(files, checks, message, id, query);
193    }
194
195    @Override
196    public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent) {
197        return xpathFilter.accept(treeWalkerAuditEvent);
198    }
199
200}