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   *
56   * @since 8.18
57   */
58  public class SuppressionXpathSingleFilter extends AbstractAutomaticBean implements
59          TreeWalkerFilter {
60      /**
61       * XpathFilterElement instance.
62       */
63      private XpathFilterElement xpathFilter;
64      /**
65       * Define a Regular Expression matched against the file name associated with an audit event.
66       */
67      private Pattern files;
68      /**
69       * Define a Regular Expression matched against the name of the check associated
70       * with an audit event.
71       */
72      private Pattern checks;
73      /**
74       * Define a Regular Expression matched against the message of the check
75       * associated with an audit event.
76       */
77      private Pattern message;
78      /**
79       * Define a string matched against the ID of the check associated with an audit event.
80       */
81      private String id;
82      /**
83       * Define a string xpath query.
84       */
85      private String query;
86  
87      /**
88       * Setter to define a Regular Expression matched against the file name
89       * associated with an audit event.
90       *
91       * @param files the name of the file
92       * @since 8.18
93       */
94      public void setFiles(String files) {
95          if (files == null) {
96              this.files = null;
97          }
98          else {
99              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 }