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; 021 022import java.io.File; 023import java.io.IOException; 024import java.io.PrintWriter; 025import java.io.StringWriter; 026import java.io.UnsupportedEncodingException; 027import java.nio.charset.Charset; 028import java.nio.charset.StandardCharsets; 029import java.util.ArrayList; 030import java.util.List; 031import java.util.Locale; 032import java.util.Set; 033import java.util.SortedSet; 034import java.util.TreeSet; 035import java.util.stream.Collectors; 036import java.util.stream.Stream; 037 038import org.apache.commons.logging.Log; 039import org.apache.commons.logging.LogFactory; 040 041import com.puppycrawl.tools.checkstyle.api.AuditEvent; 042import com.puppycrawl.tools.checkstyle.api.AuditListener; 043import com.puppycrawl.tools.checkstyle.api.BeforeExecutionFileFilter; 044import com.puppycrawl.tools.checkstyle.api.BeforeExecutionFileFilterSet; 045import com.puppycrawl.tools.checkstyle.api.CheckstyleException; 046import com.puppycrawl.tools.checkstyle.api.Configuration; 047import com.puppycrawl.tools.checkstyle.api.Context; 048import com.puppycrawl.tools.checkstyle.api.ExternalResourceHolder; 049import com.puppycrawl.tools.checkstyle.api.FileSetCheck; 050import com.puppycrawl.tools.checkstyle.api.FileText; 051import com.puppycrawl.tools.checkstyle.api.Filter; 052import com.puppycrawl.tools.checkstyle.api.FilterSet; 053import com.puppycrawl.tools.checkstyle.api.MessageDispatcher; 054import com.puppycrawl.tools.checkstyle.api.RootModule; 055import com.puppycrawl.tools.checkstyle.api.SeverityLevel; 056import com.puppycrawl.tools.checkstyle.api.SeverityLevelCounter; 057import com.puppycrawl.tools.checkstyle.api.Violation; 058import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 059 060/** 061 * This class provides the functionality to check a set of files. 062 */ 063public class Checker extends AbstractAutomaticBean implements MessageDispatcher, RootModule { 064 065 /** Message to use when an exception occurs and should be printed as a violation. */ 066 public static final String EXCEPTION_MSG = "general.exception"; 067 068 /** The extension separator. */ 069 private static final String EXTENSION_SEPARATOR = "."; 070 071 /** Logger for Checker. */ 072 private final Log log; 073 074 /** Maintains error count. */ 075 private final SeverityLevelCounter counter = new SeverityLevelCounter( 076 SeverityLevel.ERROR); 077 078 /** Vector of listeners. */ 079 private final List<AuditListener> listeners = new ArrayList<>(); 080 081 /** Vector of fileset checks. */ 082 private final List<FileSetCheck> fileSetChecks = new ArrayList<>(); 083 084 /** The audit event before execution file filters. */ 085 private final BeforeExecutionFileFilterSet beforeExecutionFileFilters = 086 new BeforeExecutionFileFilterSet(); 087 088 /** The audit event filters. */ 089 private final FilterSet filters = new FilterSet(); 090 091 /** The basedir to strip off in file names. */ 092 private String basedir; 093 094 /** Locale country to report messages . **/ 095 @XdocsPropertyType(PropertyType.LOCALE_COUNTRY) 096 private String localeCountry = Locale.getDefault().getCountry(); 097 /** Locale language to report messages . **/ 098 @XdocsPropertyType(PropertyType.LOCALE_LANGUAGE) 099 private String localeLanguage = Locale.getDefault().getLanguage(); 100 101 /** The factory for instantiating submodules. */ 102 private ModuleFactory moduleFactory; 103 104 /** The classloader used for loading Checkstyle module classes. */ 105 private ClassLoader moduleClassLoader; 106 107 /** The context of all child components. */ 108 private Context childContext; 109 110 /** The file extensions that are accepted. */ 111 private String[] fileExtensions; 112 113 /** 114 * The severity level of any violations found by submodules. 115 * The value of this property is passed to submodules via 116 * contextualize(). 117 * 118 * <p>Note: Since the Checker is merely a container for modules 119 * it does not make sense to implement logging functionality 120 * here. Consequently, Checker does not extend AbstractViolationReporter, 121 * leading to a bit of duplicated code for severity level setting. 122 */ 123 private SeverityLevel severity = SeverityLevel.ERROR; 124 125 /** Name of a charset. */ 126 private String charset = StandardCharsets.UTF_8.name(); 127 128 /** Cache file. **/ 129 @XdocsPropertyType(PropertyType.FILE) 130 private PropertyCacheFile cacheFile; 131 132 /** Controls whether exceptions should halt execution or not. */ 133 private boolean haltOnException = true; 134 135 /** The tab width for column reporting. */ 136 private int tabWidth = CommonUtil.DEFAULT_TAB_WIDTH; 137 138 /** 139 * Creates a new {@code Checker} instance. 140 * The instance needs to be contextualized and configured. 141 */ 142 public Checker() { 143 addListener(counter); 144 log = LogFactory.getLog(Checker.class); 145 } 146 147 /** 148 * Sets cache file. 149 * 150 * @param fileName the cache file. 151 * @throws IOException if there are some problems with file loading. 152 */ 153 public void setCacheFile(String fileName) throws IOException { 154 final Configuration configuration = getConfiguration(); 155 cacheFile = new PropertyCacheFile(configuration, fileName); 156 cacheFile.load(); 157 } 158 159 /** 160 * Removes before execution file filter. 161 * 162 * @param filter before execution file filter to remove. 163 */ 164 public void removeBeforeExecutionFileFilter(BeforeExecutionFileFilter filter) { 165 beforeExecutionFileFilters.removeBeforeExecutionFileFilter(filter); 166 } 167 168 /** 169 * Removes filter. 170 * 171 * @param filter filter to remove. 172 */ 173 public void removeFilter(Filter filter) { 174 filters.removeFilter(filter); 175 } 176 177 @Override 178 public void destroy() { 179 listeners.clear(); 180 fileSetChecks.clear(); 181 beforeExecutionFileFilters.clear(); 182 filters.clear(); 183 if (cacheFile != null) { 184 try { 185 cacheFile.persist(); 186 } 187 catch (IOException exc) { 188 throw new IllegalStateException( 189 getLocalizedMessage("Checker.cacheFilesException"), exc); 190 } 191 } 192 } 193 194 /** 195 * Removes a given listener. 196 * 197 * @param listener a listener to remove 198 */ 199 public void removeListener(AuditListener listener) { 200 listeners.remove(listener); 201 } 202 203 /** 204 * Sets base directory. 205 * 206 * @param basedir the base directory to strip off in file names 207 */ 208 public void setBasedir(String basedir) { 209 this.basedir = basedir; 210 } 211 212 @Override 213 public int process(List<File> files) throws CheckstyleException { 214 if (cacheFile != null) { 215 cacheFile.putExternalResources(getExternalResourceLocations()); 216 } 217 218 // Prepare to start 219 fireAuditStarted(); 220 for (final FileSetCheck fsc : fileSetChecks) { 221 fsc.beginProcessing(charset); 222 } 223 224 final List<File> targetFiles = files.stream() 225 .filter(file -> CommonUtil.matchesFileExtension(file, fileExtensions)) 226 .toList(); 227 processFiles(targetFiles); 228 229 // Finish up 230 // It may also log!!! 231 fileSetChecks.forEach(FileSetCheck::finishProcessing); 232 233 // It may also log!!! 234 fileSetChecks.forEach(FileSetCheck::destroy); 235 236 final int errorCount = counter.getCount(); 237 fireAuditFinished(); 238 return errorCount; 239 } 240 241 /** 242 * Returns a set of external configuration resource locations which are used by all file set 243 * checks and filters. 244 * 245 * @return a set of external configuration resource locations which are used by all file set 246 * checks and filters. 247 */ 248 private Set<String> getExternalResourceLocations() { 249 return Stream.concat(fileSetChecks.stream(), filters.getFilters().stream()) 250 .filter(ExternalResourceHolder.class::isInstance) 251 .flatMap(resource -> { 252 return ((ExternalResourceHolder) resource) 253 .getExternalResourceLocations().stream(); 254 }) 255 .collect(Collectors.toUnmodifiableSet()); 256 } 257 258 /** Notify all listeners about the audit start. */ 259 private void fireAuditStarted() { 260 final AuditEvent event = new AuditEvent(this); 261 for (final AuditListener listener : listeners) { 262 listener.auditStarted(event); 263 } 264 } 265 266 /** Notify all listeners about the audit end. */ 267 private void fireAuditFinished() { 268 final AuditEvent event = new AuditEvent(this); 269 for (final AuditListener listener : listeners) { 270 listener.auditFinished(event); 271 } 272 } 273 274 /** 275 * Processes a list of files with all FileSetChecks. 276 * 277 * @param files a list of files to process. 278 * @throws CheckstyleException if error condition within Checkstyle occurs. 279 * @throws Error wraps any java.lang.Error happened during execution 280 * @noinspection ProhibitedExceptionThrown 281 * @noinspectionreason ProhibitedExceptionThrown - There is no other way to 282 * deliver filename that was under processing. 283 */ 284 // -@cs[CyclomaticComplexity] no easy way to split this logic of processing the file 285 private void processFiles(List<File> files) throws CheckstyleException { 286 for (final File file : files) { 287 String fileName = null; 288 final String filePath = file.getPath(); 289 try { 290 fileName = file.getAbsolutePath(); 291 final long timestamp = file.lastModified(); 292 if (cacheFile != null && cacheFile.isInCache(fileName, timestamp) 293 || !acceptFileStarted(fileName)) { 294 continue; 295 } 296 if (cacheFile != null) { 297 cacheFile.put(fileName, timestamp); 298 } 299 fireFileStarted(fileName); 300 final SortedSet<Violation> fileMessages = processFile(file); 301 fireErrors(fileName, fileMessages); 302 fireFileFinished(fileName); 303 } 304 // -@cs[IllegalCatch] There is no other way to deliver filename that was under 305 // processing. See https://github.com/checkstyle/checkstyle/issues/2285 306 catch (Exception exc) { 307 if (fileName != null && cacheFile != null) { 308 cacheFile.remove(fileName); 309 } 310 311 // We need to catch all exceptions to put a reason failure (file name) in exception 312 throw new CheckstyleException( 313 getLocalizedMessage("Checker.processFilesException", filePath), exc); 314 } 315 catch (Error error) { 316 if (fileName != null && cacheFile != null) { 317 cacheFile.remove(fileName); 318 } 319 320 // We need to catch all errors to put a reason failure (file name) in error 321 throw new Error(getLocalizedMessage("Checker.error", filePath), error); 322 } 323 } 324 } 325 326 /** 327 * Processes a file with all FileSetChecks. 328 * 329 * @param file a file to process. 330 * @return a sorted set of violations to be logged. 331 * @throws CheckstyleException if error condition within Checkstyle occurs. 332 * @noinspection ProhibitedExceptionThrown 333 * @noinspectionreason ProhibitedExceptionThrown - there is no other way to obey 334 * haltOnException field 335 */ 336 private SortedSet<Violation> processFile(File file) throws CheckstyleException { 337 final SortedSet<Violation> fileMessages = new TreeSet<>(); 338 try { 339 final FileText theText = new FileText(file.getAbsoluteFile(), charset); 340 for (final FileSetCheck fsc : fileSetChecks) { 341 fileMessages.addAll(fsc.process(file, theText)); 342 } 343 } 344 catch (final IOException ioe) { 345 log.debug("IOException occurred.", ioe); 346 fileMessages.add(new Violation(1, 347 Definitions.CHECKSTYLE_BUNDLE, EXCEPTION_MSG, 348 new String[] {ioe.getMessage()}, null, getClass(), null)); 349 } 350 // -@cs[IllegalCatch] There is no other way to obey haltOnException field 351 catch (Exception exc) { 352 if (haltOnException) { 353 throw exc; 354 } 355 356 log.debug("Exception occurred.", exc); 357 358 final StringWriter sw = new StringWriter(); 359 final PrintWriter pw = new PrintWriter(sw, true); 360 361 exc.printStackTrace(pw); 362 363 fileMessages.add(new Violation(1, 364 Definitions.CHECKSTYLE_BUNDLE, EXCEPTION_MSG, 365 new String[] {sw.getBuffer().toString()}, 366 null, getClass(), null)); 367 } 368 return fileMessages; 369 } 370 371 /** 372 * Check if all before execution file filters accept starting the file. 373 * 374 * @param fileName 375 * the file to be audited 376 * @return {@code true} if the file is accepted. 377 */ 378 private boolean acceptFileStarted(String fileName) { 379 final String stripped = CommonUtil.relativizePath(basedir, fileName); 380 return beforeExecutionFileFilters.accept(stripped); 381 } 382 383 /** 384 * Notify all listeners about the beginning of a file audit. 385 * 386 * @param fileName 387 * the file to be audited 388 */ 389 @Override 390 public void fireFileStarted(String fileName) { 391 final String stripped = CommonUtil.relativizePath(basedir, fileName); 392 final AuditEvent event = new AuditEvent(this, stripped); 393 for (final AuditListener listener : listeners) { 394 listener.fileStarted(event); 395 } 396 } 397 398 /** 399 * Notify all listeners about the errors in a file. 400 * 401 * @param fileName the audited file 402 * @param errors the audit errors from the file 403 */ 404 @Override 405 public void fireErrors(String fileName, SortedSet<Violation> errors) { 406 final String stripped = CommonUtil.relativizePath(basedir, fileName); 407 boolean hasNonFilteredViolations = false; 408 for (final Violation element : errors) { 409 final AuditEvent event = new AuditEvent(this, stripped, element); 410 if (filters.accept(event)) { 411 hasNonFilteredViolations = true; 412 for (final AuditListener listener : listeners) { 413 listener.addError(event); 414 } 415 } 416 } 417 if (hasNonFilteredViolations && cacheFile != null) { 418 cacheFile.remove(fileName); 419 } 420 } 421 422 /** 423 * Notify all listeners about the end of a file audit. 424 * 425 * @param fileName 426 * the audited file 427 */ 428 @Override 429 public void fireFileFinished(String fileName) { 430 final String stripped = CommonUtil.relativizePath(basedir, fileName); 431 final AuditEvent event = new AuditEvent(this, stripped); 432 for (final AuditListener listener : listeners) { 433 listener.fileFinished(event); 434 } 435 } 436 437 /** 438 * Performs final setup of the Checker after configuration is complete. 439 * 440 * @noinspection deprecation 441 * @noinspectionreason Disabled until #17646 442 */ 443 @Override 444 protected void finishLocalSetup() throws CheckstyleException { 445 final Locale locale = new Locale(localeLanguage, localeCountry); 446 LocalizedMessage.setLocale(locale); 447 448 if (moduleFactory == null) { 449 if (moduleClassLoader == null) { 450 throw new CheckstyleException(getLocalizedMessage("Checker.finishLocalSetup")); 451 } 452 453 final Set<String> packageNames = PackageNamesLoader 454 .getPackageNames(moduleClassLoader); 455 moduleFactory = new PackageObjectFactory(packageNames, 456 moduleClassLoader); 457 } 458 459 final DefaultContext context = new DefaultContext(); 460 context.add("charset", charset); 461 context.add("moduleFactory", moduleFactory); 462 context.add("severity", severity.getName()); 463 context.add("basedir", basedir); 464 context.add("tabWidth", String.valueOf(tabWidth)); 465 childContext = context; 466 } 467 468 /** 469 * {@inheritDoc} Creates child module. 470 * 471 * @noinspection ChainOfInstanceofChecks 472 * @noinspectionreason ChainOfInstanceofChecks - we treat checks and filters differently 473 */ 474 @Override 475 protected void setupChild(Configuration childConf) 476 throws CheckstyleException { 477 final String name = childConf.getName(); 478 final Object child; 479 480 try { 481 child = moduleFactory.createModule(name); 482 483 if (child instanceof AbstractAutomaticBean bean) { 484 bean.contextualize(childContext); 485 bean.configure(childConf); 486 } 487 } 488 catch (final CheckstyleException exc) { 489 throw new CheckstyleException( 490 getLocalizedMessage("Checker.setupChildModule", name, exc.getMessage()), exc); 491 } 492 if (child instanceof FileSetCheck fsc) { 493 fsc.init(); 494 addFileSetCheck(fsc); 495 } 496 else if (child instanceof BeforeExecutionFileFilter filter) { 497 addBeforeExecutionFileFilter(filter); 498 } 499 else if (child instanceof Filter filter) { 500 addFilter(filter); 501 } 502 else if (child instanceof AuditListener listener) { 503 addListener(listener); 504 } 505 else { 506 throw new CheckstyleException( 507 getLocalizedMessage("Checker.setupChildNotAllowed", name)); 508 } 509 } 510 511 /** 512 * Adds a FileSetCheck to the list of FileSetChecks 513 * that is executed in process(). 514 * 515 * @param fileSetCheck the additional FileSetCheck 516 */ 517 public void addFileSetCheck(FileSetCheck fileSetCheck) { 518 fileSetCheck.setMessageDispatcher(this); 519 fileSetChecks.add(fileSetCheck); 520 } 521 522 /** 523 * Adds a before execution file filter to the end of the event chain. 524 * 525 * @param filter the additional filter 526 */ 527 public void addBeforeExecutionFileFilter(BeforeExecutionFileFilter filter) { 528 beforeExecutionFileFilters.addBeforeExecutionFileFilter(filter); 529 } 530 531 /** 532 * Adds a filter to the end of the audit event filter chain. 533 * 534 * @param filter the additional filter 535 */ 536 public void addFilter(Filter filter) { 537 filters.addFilter(filter); 538 } 539 540 @Override 541 public final void addListener(AuditListener listener) { 542 listeners.add(listener); 543 } 544 545 /** 546 * Sets the file extensions that identify the files that pass the 547 * filter of this FileSetCheck. 548 * 549 * @param extensions the set of file extensions. A missing 550 * initial '.' character of an extension is automatically added. 551 */ 552 public final void setFileExtensions(String... extensions) { 553 if (extensions != null) { 554 fileExtensions = new String[extensions.length]; 555 for (int i = 0; i < extensions.length; i++) { 556 final String extension = extensions[i]; 557 if (extension.startsWith(EXTENSION_SEPARATOR)) { 558 fileExtensions[i] = extension; 559 } 560 else { 561 fileExtensions[i] = EXTENSION_SEPARATOR + extension; 562 } 563 } 564 } 565 } 566 567 /** 568 * Sets the factory for creating submodules. 569 * 570 * @param moduleFactory the factory for creating FileSetChecks 571 */ 572 public void setModuleFactory(ModuleFactory moduleFactory) { 573 this.moduleFactory = moduleFactory; 574 } 575 576 /** 577 * Sets locale country. 578 * 579 * @param localeCountry the country to report messages 580 */ 581 public void setLocaleCountry(String localeCountry) { 582 this.localeCountry = localeCountry; 583 } 584 585 /** 586 * Sets locale language. 587 * 588 * @param localeLanguage the language to report messages 589 */ 590 public void setLocaleLanguage(String localeLanguage) { 591 this.localeLanguage = localeLanguage; 592 } 593 594 /** 595 * Sets the severity level. The string should be one of the names 596 * defined in the {@code SeverityLevel} class. 597 * 598 * @param severity The new severity level 599 * @see SeverityLevel 600 */ 601 public final void setSeverity(String severity) { 602 this.severity = SeverityLevel.getInstance(severity); 603 } 604 605 @Override 606 public final void setModuleClassLoader(ClassLoader moduleClassLoader) { 607 this.moduleClassLoader = moduleClassLoader; 608 } 609 610 /** 611 * Sets a named charset. 612 * 613 * @param charset the name of a charset 614 * @throws UnsupportedEncodingException if charset is unsupported. 615 */ 616 public void setCharset(String charset) 617 throws UnsupportedEncodingException { 618 if (!Charset.isSupported(charset)) { 619 throw new UnsupportedEncodingException( 620 getLocalizedMessage("Checker.setCharset", charset)); 621 } 622 this.charset = charset; 623 } 624 625 /** 626 * Sets the field haltOnException. 627 * 628 * @param haltOnException the new value. 629 */ 630 public void setHaltOnException(boolean haltOnException) { 631 this.haltOnException = haltOnException; 632 } 633 634 /** 635 * Set the tab width to report audit events with. 636 * 637 * @param tabWidth an {@code int} value 638 */ 639 public final void setTabWidth(int tabWidth) { 640 this.tabWidth = tabWidth; 641 } 642 643 /** 644 * Clears the cache. 645 */ 646 public void clearCache() { 647 if (cacheFile != null) { 648 cacheFile.reset(); 649 } 650 } 651 652 /** 653 * Extracts localized messages from properties files. 654 * 655 * @param messageKey the key pointing to localized message in respective properties file. 656 * @param args the arguments of message in respective properties file. 657 * @return a string containing extracted localized message 658 */ 659 private String getLocalizedMessage(String messageKey, Object... args) { 660 final LocalizedMessage localizedMessage = new LocalizedMessage( 661 Definitions.CHECKSTYLE_BUNDLE, getClass(), 662 messageKey, args); 663 664 return localizedMessage.getMessage(); 665 } 666 667}