001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2026 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.io.FileNotFoundException; 023import java.io.IOException; 024import java.util.HashMap; 025import java.util.HashSet; 026import java.util.Locale; 027import java.util.Map; 028import java.util.Set; 029import java.util.regex.PatternSyntaxException; 030 031import javax.xml.parsers.ParserConfigurationException; 032 033import org.xml.sax.Attributes; 034import org.xml.sax.InputSource; 035import org.xml.sax.SAXException; 036 037import com.puppycrawl.tools.checkstyle.TreeWalkerFilter; 038import com.puppycrawl.tools.checkstyle.XmlLoader; 039import com.puppycrawl.tools.checkstyle.api.CheckstyleException; 040import com.puppycrawl.tools.checkstyle.api.FilterSet; 041import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 042 043/** 044 * Loads a filter chain of suppressions. 045 */ 046public final class SuppressionsLoader extends XmlLoader { 047 048 /** The public ID for the configuration dtd. */ 049 private static final String DTD_PUBLIC_ID_1_0 = 050 "-//Puppy Crawl//DTD Suppressions 1.0//EN"; 051 /** The new public ID for version 1_0 configuration dtd. */ 052 private static final String DTD_PUBLIC_CS_ID_1_0 = 053 "-//Checkstyle//DTD SuppressionFilter Configuration 1.0//EN"; 054 /** The resource for the configuration dtd. */ 055 private static final String DTD_SUPPRESSIONS_NAME_1_0 = 056 "com/puppycrawl/tools/checkstyle/suppressions_1_0.dtd"; 057 /** The public ID for the configuration dtd. */ 058 private static final String DTD_PUBLIC_ID_1_1 = 059 "-//Puppy Crawl//DTD Suppressions 1.1//EN"; 060 /** The new public ID for version 1_1 configuration dtd. */ 061 private static final String DTD_PUBLIC_CS_ID_1_1 = 062 "-//Checkstyle//DTD SuppressionFilter Configuration 1.1//EN"; 063 /** The resource for the configuration dtd. */ 064 private static final String DTD_SUPPRESSIONS_NAME_1_1 = 065 "com/puppycrawl/tools/checkstyle/suppressions_1_1.dtd"; 066 /** The public ID for the configuration dtd. */ 067 private static final String DTD_PUBLIC_ID_1_2 = 068 "-//Puppy Crawl//DTD Suppressions 1.2//EN"; 069 /** The new public ID for version 1_2 configuration dtd. */ 070 private static final String DTD_PUBLIC_CS_ID_1_2 = 071 "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"; 072 /** The resource for the configuration dtd. */ 073 private static final String DTD_SUPPRESSIONS_NAME_1_2 = 074 "com/puppycrawl/tools/checkstyle/suppressions_1_2.dtd"; 075 076 /** The old public ID for the configuration dtd. */ 077 private static final String DTD_PUBLIC_ID_1_1_XPATH_EXPERIMENTAL = 078 "-//Puppy Crawl//DTD Suppressions Xpath Experimental 1.1//EN"; 079 /** The old public ID for version 1_1 configuration dtd. */ 080 private static final String DTD_PUBLIC_CS_ID_1_1_XPATH_EXPERIMENTAL = 081 "-//Checkstyle//DTD SuppressionXpathFilter Experimental Configuration 1.1//EN"; 082 /** The new public ID for the configuration dtd. */ 083 private static final String DTD_PUBLIC_ID_1_1_XPATH = 084 "-//Puppy Crawl//DTD Suppressions Xpath 1.1//EN"; 085 /** The new public ID for version 1_1 configuration dtd. */ 086 private static final String DTD_PUBLIC_CS_ID_1_1_XPATH = 087 "-//Checkstyle//DTD SuppressionXpathFilter Configuration 1.1//EN"; 088 /** The resource for the configuration dtd. */ 089 private static final String DTD_SUPPRESSIONS_NAME_1_1_XPATH = 090 "com/puppycrawl/tools/checkstyle/suppressions_1_1_xpath.dtd"; 091 092 /** The old public ID for the configuration dtd. */ 093 private static final String DTD_PUBLIC_ID_1_2_XPATH_EXPERIMENTAL = 094 "-//Puppy Crawl//DTD Suppressions Xpath Experimental 1.2//EN"; 095 /** The old public ID for version 1_2 configuration dtd. */ 096 private static final String DTD_PUBLIC_CS_ID_1_2_XPATH_EXPERIMENTAL = 097 "-//Checkstyle//DTD SuppressionXpathFilter Experimental Configuration 1.2//EN"; 098 /** The new public ID for the configuration dtd. */ 099 private static final String DTD_PUBLIC_ID_1_2_XPATH = 100 "-//Puppy Crawl//DTD Suppressions Xpath 1.2//EN"; 101 /** The new public ID for version 1_2 configuration dtd. */ 102 private static final String DTD_PUBLIC_CS_ID_1_2_XPATH = 103 "-//Checkstyle//DTD SuppressionXpathFilter Configuration 1.2//EN"; 104 /** The resource for the configuration dtd. */ 105 private static final String DTD_SUPPRESSIONS_NAME_1_2_XPATH = 106 "com/puppycrawl/tools/checkstyle/suppressions_1_2_xpath.dtd"; 107 108 /** File search error message. */ 109 private static final String UNABLE_TO_FIND_ERROR_MESSAGE = "Unable to find: "; 110 /** String literal for attribute name. */ 111 private static final String ATTRIBUTE_NAME_FILES = "files"; 112 /** String literal for attribute name. */ 113 private static final String ATTRIBUTE_NAME_CHECKS = "checks"; 114 /** String literal for attribute name. */ 115 private static final String ATTRIBUTE_NAME_MESSAGE = "message"; 116 /** String literal for attribute name. */ 117 private static final String ATTRIBUTE_NAME_ID = "id"; 118 /** String literal for attribute name. */ 119 private static final String ATTRIBUTE_NAME_QUERY = "query"; 120 /** String literal for attribute name. */ 121 private static final String ATTRIBUTE_NAME_LINES = "lines"; 122 /** String literal for attribute name. */ 123 private static final String ATTRIBUTE_NAME_COLUMNS = "columns"; 124 125 /** 126 * The filter chain to return in getAFilterChain(), 127 * configured during parsing. 128 */ 129 private final FilterSet filterChain = new FilterSet(); 130 131 /** 132 * The set of the {@code TreeWalkerFilter} filters. Being filled during parsing. 133 */ 134 private final Set<TreeWalkerFilter> treeWalkerFilters = new HashSet<>(); 135 136 /** 137 * Creates a new {@code SuppressionsLoader} instance. 138 * 139 * @throws ParserConfigurationException if an error occurs 140 * @throws SAXException if an error occurs 141 */ 142 private SuppressionsLoader() 143 throws ParserConfigurationException, SAXException { 144 super(createIdToResourceNameMap()); 145 } 146 147 @Override 148 public void startElement(String namespaceUri, 149 String localName, 150 String qName, 151 Attributes attributes) 152 throws SAXException { 153 if ("suppress".equals(qName)) { 154 // add SuppressFilterElement filter to the filter chain 155 final SuppressFilterElement suppress = getSuppressElement(attributes); 156 filterChain.addFilter(suppress); 157 } 158 else if ("suppress-xpath".equals(qName)) { 159 final XpathFilterElement filter = getXpathFilter(attributes); 160 treeWalkerFilters.add(filter); 161 } 162 } 163 164 /** 165 * Returns the suppress element, initialized from given attributes. 166 * 167 * @param attributes the attributes of xml-tag {@literal "<suppress></suppress>"}, 168 * specified inside suppression file. 169 * @return the suppress element 170 * @throws SAXException if an error occurs. 171 */ 172 private static SuppressFilterElement getSuppressElement(Attributes attributes) 173 throws SAXException { 174 final String checks = attributes.getValue(ATTRIBUTE_NAME_CHECKS); 175 final String modId = attributes.getValue(ATTRIBUTE_NAME_ID); 176 final String message = attributes.getValue(ATTRIBUTE_NAME_MESSAGE); 177 if (checks == null && modId == null && message == null) { 178 // -@cs[IllegalInstantiation] SAXException is in the overridden method signature 179 throw new SAXException("missing checks or id or message attribute"); 180 } 181 final SuppressFilterElement suppress; 182 try { 183 final String files = attributes.getValue(ATTRIBUTE_NAME_FILES); 184 final String lines = attributes.getValue(ATTRIBUTE_NAME_LINES); 185 final String columns = attributes.getValue(ATTRIBUTE_NAME_COLUMNS); 186 suppress = new SuppressFilterElement(files, checks, message, modId, lines, columns); 187 } 188 catch (final PatternSyntaxException exc) { 189 // -@cs[IllegalInstantiation] SAXException is in the overridden method signature 190 throw new SAXException("invalid files or checks or message format for checks: " 191 + checks, exc); 192 } 193 return suppress; 194 } 195 196 /** 197 * Returns the xpath filter, initialized from given attributes. 198 * 199 * @param attributes the attributes of xml-tag {@literal "<suppress-xpath></suppress-xpath>"}, 200 * specified inside suppression file. 201 * @return the xpath filter 202 * @throws SAXException if an error occurs. 203 */ 204 private static XpathFilterElement getXpathFilter(Attributes attributes) throws SAXException { 205 final String checks = attributes.getValue(ATTRIBUTE_NAME_CHECKS); 206 final String modId = attributes.getValue(ATTRIBUTE_NAME_ID); 207 final String message = attributes.getValue(ATTRIBUTE_NAME_MESSAGE); 208 if (checks == null && modId == null && message == null) { 209 // -@cs[IllegalInstantiation] SAXException is in the overridden method signature 210 throw new SAXException("missing checks or id or message attribute for suppress-xpath"); 211 } 212 final XpathFilterElement filter; 213 try { 214 final String files = attributes.getValue(ATTRIBUTE_NAME_FILES); 215 final String xpathQuery = attributes.getValue(ATTRIBUTE_NAME_QUERY); 216 filter = new XpathFilterElement(files, checks, message, modId, xpathQuery); 217 } 218 catch (final PatternSyntaxException exc) { 219 // -@cs[IllegalInstantiation] SAXException is in the overridden method signature 220 throw new SAXException("invalid files or checks or message format for suppress-xpath: " 221 + checks, exc); 222 } 223 return filter; 224 } 225 226 /** 227 * Returns the suppression filters in a specified file. 228 * 229 * @param filename name of the suppressions file. 230 * @return the filter chain of suppression elements specified in the file. 231 * @throws CheckstyleException if an error occurs. 232 */ 233 public static FilterSet loadSuppressions(String filename) 234 throws CheckstyleException { 235 return loadSuppressions(CommonUtil.sourceFromFilename(filename), filename); 236 } 237 238 /** 239 * Returns the suppression filters in a specified source. 240 * 241 * @param source the source for the suppressions. 242 * @param sourceName the name of the source. 243 * @return the filter chain of suppression elements in source. 244 * @throws CheckstyleException if an error occurs. 245 */ 246 private static FilterSet loadSuppressions( 247 InputSource source, String sourceName) 248 throws CheckstyleException { 249 return getSuppressionLoader(source, sourceName).filterChain; 250 } 251 252 /** 253 * Returns the suppression {@code TreeWalker} filters in a specified file. 254 * 255 * @param filename name of the suppressions file. 256 * @return the set of xpath suppression elements specified in the file. 257 * @throws CheckstyleException if an error occurs. 258 */ 259 public static Set<TreeWalkerFilter> loadXpathSuppressions(String filename) 260 throws CheckstyleException { 261 return loadXpathSuppressions(CommonUtil.sourceFromFilename(filename), filename); 262 } 263 264 /** 265 * Returns the suppression {@code TreeWalker} filters in a specified source. 266 * 267 * @param source the source for the suppressions. 268 * @param sourceName the name of the source. 269 * @return the set of xpath suppression elements specified in source. 270 * @throws CheckstyleException if an error occurs. 271 */ 272 private static Set<TreeWalkerFilter> loadXpathSuppressions( 273 InputSource source, String sourceName) 274 throws CheckstyleException { 275 return getSuppressionLoader(source, sourceName).treeWalkerFilters; 276 } 277 278 /** 279 * Parses specified source and returns the suppression loader. 280 * 281 * @param source the source for the suppressions. 282 * @param sourceName the name of the source. 283 * @return the suppression loader 284 * @throws CheckstyleException if an error occurs. 285 */ 286 private static SuppressionsLoader getSuppressionLoader(InputSource source, String sourceName) 287 throws CheckstyleException { 288 try { 289 final SuppressionsLoader suppressionsLoader = 290 new SuppressionsLoader(); 291 suppressionsLoader.parseInputSource(source); 292 return suppressionsLoader; 293 } 294 catch (final FileNotFoundException exc) { 295 throw new CheckstyleException(UNABLE_TO_FIND_ERROR_MESSAGE + sourceName, exc); 296 } 297 catch (final ParserConfigurationException | SAXException exc) { 298 final String message = String.format(Locale.ROOT, "Unable to parse %s - %s", 299 sourceName, exc.getMessage()); 300 throw new CheckstyleException(message, exc); 301 } 302 catch (final IOException exc) { 303 throw new CheckstyleException("Unable to read " + sourceName, exc); 304 } 305 catch (final NumberFormatException exc) { 306 final String message = String.format(Locale.ROOT, "Number format exception %s - %s", 307 sourceName, exc.getMessage()); 308 throw new CheckstyleException(message, exc); 309 } 310 } 311 312 /** 313 * Creates mapping between local resources and dtd ids. 314 * 315 * @return map between local resources and dtd ids. 316 */ 317 private static Map<String, String> createIdToResourceNameMap() { 318 final Map<String, String> map = new HashMap<>(); 319 map.put(DTD_PUBLIC_ID_1_0, DTD_SUPPRESSIONS_NAME_1_0); 320 map.put(DTD_PUBLIC_ID_1_1, DTD_SUPPRESSIONS_NAME_1_1); 321 map.put(DTD_PUBLIC_ID_1_2, DTD_SUPPRESSIONS_NAME_1_2); 322 map.put(DTD_PUBLIC_CS_ID_1_0, DTD_SUPPRESSIONS_NAME_1_0); 323 map.put(DTD_PUBLIC_CS_ID_1_1, DTD_SUPPRESSIONS_NAME_1_1); 324 map.put(DTD_PUBLIC_CS_ID_1_2, DTD_SUPPRESSIONS_NAME_1_2); 325 326 // 1.1 Xpath mappings 327 map.put(DTD_PUBLIC_ID_1_1_XPATH_EXPERIMENTAL, DTD_SUPPRESSIONS_NAME_1_1_XPATH); 328 map.put(DTD_PUBLIC_CS_ID_1_1_XPATH_EXPERIMENTAL, DTD_SUPPRESSIONS_NAME_1_1_XPATH); 329 map.put(DTD_PUBLIC_ID_1_1_XPATH, DTD_SUPPRESSIONS_NAME_1_1_XPATH); 330 map.put(DTD_PUBLIC_CS_ID_1_1_XPATH, DTD_SUPPRESSIONS_NAME_1_1_XPATH); 331 332 // 1.2 Xpath mappings 333 map.put(DTD_PUBLIC_ID_1_2_XPATH_EXPERIMENTAL, DTD_SUPPRESSIONS_NAME_1_2_XPATH); 334 map.put(DTD_PUBLIC_CS_ID_1_2_XPATH_EXPERIMENTAL, DTD_SUPPRESSIONS_NAME_1_2_XPATH); 335 map.put(DTD_PUBLIC_ID_1_2_XPATH, DTD_SUPPRESSIONS_NAME_1_2_XPATH); 336 map.put(DTD_PUBLIC_CS_ID_1_2_XPATH, DTD_SUPPRESSIONS_NAME_1_2_XPATH); 337 return map; 338 } 339 340}