001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2025 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 * Notes:
053 * {@code SuppressionXpathSingleFilter} can suppress Checks that have {@code Treewalker} as parent module.
054 * </p>
055 *
056 * @since 8.18
057 */
058public class SuppressionXpathSingleFilter extends AbstractAutomaticBean implements
059        TreeWalkerFilter {
060    /**
061     * XpathFilterElement instance.
062     */
063    private XpathFilterElement xpathFilter;
064    /**
065     * Define a Regular Expression matched against the file name associated with an audit event.
066     */
067    private Pattern files;
068    /**
069     * Define a Regular Expression matched against the name of the check associated
070     * with an audit event.
071     */
072    private Pattern checks;
073    /**
074     * Define a Regular Expression matched against the message of the check
075     * associated with an audit event.
076     */
077    private Pattern message;
078    /**
079     * Define a string matched against the ID of the check associated with an audit event.
080     */
081    private String id;
082    /**
083     * Define a string xpath query.
084     */
085    private String query;
086
087    /**
088     * Setter to define a Regular Expression matched against the file name
089     * associated with an audit event.
090     *
091     * @param files the name of the file
092     * @since 8.18
093     */
094    public void setFiles(String files) {
095        if (files == null) {
096            this.files = null;
097        }
098        else {
099            this.files = Pattern.compile(files);
100        }
101    }
102
103    /**
104     * Setter to define a Regular Expression matched against the name of the check
105     * associated with an audit event.
106     *
107     * @param checks the name of the check
108     * @since 8.18
109     */
110    public void setChecks(String checks) {
111        if (checks == null) {
112            this.checks = null;
113        }
114        else {
115            this.checks = Pattern.compile(checks);
116        }
117    }
118
119    /**
120     * Setter to define a Regular Expression matched against the message of
121     * the check associated with an audit event.
122     *
123     * @param message the message of the check
124     * @since 8.18
125     */
126    public void setMessage(String message) {
127        if (message == null) {
128            this.message = null;
129        }
130        else {
131            this.message = Pattern.compile(message);
132        }
133    }
134
135    /**
136     * Setter to define a string matched against the ID of the check associated
137     * with an audit event.
138     *
139     * @param id the ID of the check
140     * @since 8.18
141     */
142    public void setId(String id) {
143        this.id = id;
144    }
145
146    /**
147     * Setter to define a string xpath query.
148     *
149     * @param query the xpath query
150     * @since 8.18
151     */
152    public void setQuery(String query) {
153        this.query = query;
154    }
155
156    @Override
157    protected void finishLocalSetup() {
158        xpathFilter = new XpathFilterElement(files, checks, message, id, query);
159    }
160
161    @Override
162    public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent) {
163        return xpathFilter.accept(treeWalkerAuditEvent);
164    }
165
166}