View Javadoc
1   ///////////////////////////////////////////////////////////////////////////////////////////////
2   // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3   // Copyright (C) 2001-2025 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.TreeWalkerAuditEvent;
26  import com.puppycrawl.tools.checkstyle.TreeWalkerFilter;
27  
28  /**
29   * <div>
30   * Filter {@code SuppressionXpathSingleFilter} suppresses audit events for Checks
31   * violations in the specified file, class, checks, message, module id, and xpath.
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
41   * on common files/folders is better to put in checkstyle configuration as common rule.
42   * All suppression that are for specific file names is better to keep in project
43   * specific config file.
44   * </p>
45   *
46   * <p>
47   * Attention: This filter only supports single suppression, and will need multiple
48   * instances if users wants to suppress multiple violations.
49   * </p>
50   *
51   * <p>
52   * Notes:
53   * {@code SuppressionXpathSingleFilter} can suppress Checks that have {@code Treewalker} as parent module.
54   * </p>
55   * <ul>
56   * <li>
57   * Property {@code checks} - Define a Regular Expression matched against the name
58   * of the check associated with an audit event.
59   * Type is {@code java.util.regex.Pattern}.
60   * Default value is {@code null}.
61   * </li>
62   * <li>
63   * Property {@code files} - Define a Regular Expression matched against the file
64   * name associated with an audit event.
65   * Type is {@code java.util.regex.Pattern}.
66   * Default value is {@code null}.
67   * </li>
68   * <li>
69   * Property {@code id} - Define a string matched against the ID of the check
70   * associated with an audit event.
71   * Type is {@code java.lang.String}.
72   * Default value is {@code null}.
73   * </li>
74   * <li>
75   * Property {@code message} - Define a Regular Expression matched against the message
76   * of the check associated with an audit event.
77   * Type is {@code java.util.regex.Pattern}.
78   * Default value is {@code null}.
79   * </li>
80   * <li>
81   * Property {@code query} - Define a string xpath query.
82   * Type is {@code java.lang.String}.
83   * Default value is {@code null}.
84   * </li>
85   * </ul>
86   *
87   * <p>
88   * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
89   * </p>
90   *
91   * @since 8.18
92   */
93  public class SuppressionXpathSingleFilter extends AbstractAutomaticBean implements
94          TreeWalkerFilter {
95      /**
96       * XpathFilterElement instance.
97       */
98      private XpathFilterElement xpathFilter;
99      /**
100      * Define a Regular Expression matched against the file name associated with an audit event.
101      */
102     private Pattern files;
103     /**
104      * Define a Regular Expression matched against the name of the check associated
105      * with an audit event.
106      */
107     private Pattern checks;
108     /**
109      * Define a Regular Expression matched against the message of the check
110      * associated with an audit event.
111      */
112     private Pattern message;
113     /**
114      * Define a string matched against the ID of the check associated with an audit event.
115      */
116     private String id;
117     /**
118      * Define a string xpath query.
119      */
120     private String query;
121 
122     /**
123      * Setter to define a Regular Expression matched against the file name
124      * associated with an audit event.
125      *
126      * @param files the name of the file
127      * @since 8.18
128      */
129     public void setFiles(String files) {
130         if (files == null) {
131             this.files = null;
132         }
133         else {
134             this.files = Pattern.compile(files);
135         }
136     }
137 
138     /**
139      * Setter to define a Regular Expression matched against the name of the check
140      * associated with an audit event.
141      *
142      * @param checks the name of the check
143      * @since 8.18
144      */
145     public void setChecks(String checks) {
146         if (checks == null) {
147             this.checks = null;
148         }
149         else {
150             this.checks = Pattern.compile(checks);
151         }
152     }
153 
154     /**
155      * Setter to define a Regular Expression matched against the message of
156      * the check associated with an audit event.
157      *
158      * @param message the message of the check
159      * @since 8.18
160      */
161     public void setMessage(String message) {
162         if (message == null) {
163             this.message = null;
164         }
165         else {
166             this.message = Pattern.compile(message);
167         }
168     }
169 
170     /**
171      * Setter to define a string matched against the ID of the check associated
172      * with an audit event.
173      *
174      * @param id the ID of the check
175      * @since 8.18
176      */
177     public void setId(String id) {
178         this.id = id;
179     }
180 
181     /**
182      * Setter to define a string xpath query.
183      *
184      * @param query the xpath query
185      * @since 8.18
186      */
187     public void setQuery(String query) {
188         this.query = query;
189     }
190 
191     @Override
192     protected void finishLocalSetup() {
193         xpathFilter = new XpathFilterElement(files, checks, message, id, query);
194     }
195 
196     @Override
197     public boolean accept(TreeWalkerAuditEvent treeWalkerAuditEvent) {
198         return xpathFilter.accept(treeWalkerAuditEvent);
199     }
200 
201 }