001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 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 ex) { 188 throw new IllegalStateException("Unable to persist cache file.", ex); 189 } 190 } 191 } 192 193 /** 194 * Removes a given listener. 195 * 196 * @param listener a listener to remove 197 */ 198 public void removeListener(AuditListener listener) { 199 listeners.remove(listener); 200 } 201 202 /** 203 * Sets base directory. 204 * 205 * @param basedir the base directory to strip off in file names 206 */ 207 public void setBasedir(String basedir) { 208 this.basedir = basedir; 209 } 210 211 @Override 212 public int process(List<File> files) throws CheckstyleException { 213 if (cacheFile != null) { 214 cacheFile.putExternalResources(getExternalResourceLocations()); 215 } 216 217 // Prepare to start 218 fireAuditStarted(); 219 for (final FileSetCheck fsc : fileSetChecks) { 220 fsc.beginProcessing(charset); 221 } 222 223 final List<File> targetFiles = files.stream() 224 .filter(file -> CommonUtil.matchesFileExtension(file, fileExtensions)) 225 .collect(Collectors.toUnmodifiableList()); 226 processFiles(targetFiles); 227 228 // Finish up 229 // It may also log!!! 230 fileSetChecks.forEach(FileSetCheck::finishProcessing); 231 232 // It may also log!!! 233 fileSetChecks.forEach(FileSetCheck::destroy); 234 235 final int errorCount = counter.getCount(); 236 fireAuditFinished(); 237 return errorCount; 238 } 239 240 /** 241 * Returns a set of external configuration resource locations which are used by all file set 242 * checks and filters. 243 * 244 * @return a set of external configuration resource locations which are used by all file set 245 * checks and filters. 246 */ 247 private Set<String> getExternalResourceLocations() { 248 return Stream.concat(fileSetChecks.stream(), filters.getFilters().stream()) 249 .filter(ExternalResourceHolder.class::isInstance) 250 .flatMap(resource -> { 251 return ((ExternalResourceHolder) resource) 252 .getExternalResourceLocations().stream(); 253 }) 254 .collect(Collectors.toUnmodifiableSet()); 255 } 256 257 /** Notify all listeners about the audit start. */ 258 private void fireAuditStarted() { 259 final AuditEvent event = new AuditEvent(this); 260 for (final AuditListener listener : listeners) { 261 listener.auditStarted(event); 262 } 263 } 264 265 /** Notify all listeners about the audit end. */ 266 private void fireAuditFinished() { 267 final AuditEvent event = new AuditEvent(this); 268 for (final AuditListener listener : listeners) { 269 listener.auditFinished(event); 270 } 271 } 272 273 /** 274 * Processes a list of files with all FileSetChecks. 275 * 276 * @param files a list of files to process. 277 * @throws CheckstyleException if error condition within Checkstyle occurs. 278 * @throws Error wraps any java.lang.Error happened during execution 279 * @noinspection ProhibitedExceptionThrown 280 * @noinspectionreason ProhibitedExceptionThrown - There is no other way to 281 * deliver filename that was under processing. 282 */ 283 // -@cs[CyclomaticComplexity] no easy way to split this logic of processing the file 284 private void processFiles(List<File> files) throws CheckstyleException { 285 for (final File file : files) { 286 String fileName = null; 287 final String filePath = file.getPath(); 288 try { 289 fileName = file.getAbsolutePath(); 290 final long timestamp = file.lastModified(); 291 if (cacheFile != null && cacheFile.isInCache(fileName, timestamp) 292 || !acceptFileStarted(fileName)) { 293 continue; 294 } 295 if (cacheFile != null) { 296 cacheFile.put(fileName, timestamp); 297 } 298 fireFileStarted(fileName); 299 final SortedSet<Violation> fileMessages = processFile(file); 300 fireErrors(fileName, fileMessages); 301 fireFileFinished(fileName); 302 } 303 // -@cs[IllegalCatch] There is no other way to deliver filename that was under 304 // processing. See https://github.com/checkstyle/checkstyle/issues/2285 305 catch (Exception ex) { 306 if (fileName != null && cacheFile != null) { 307 cacheFile.remove(fileName); 308 } 309 310 // We need to catch all exceptions to put a reason failure (file name) in exception 311 throw new CheckstyleException( 312 getLocalizedMessage("Checker.processFilesException", filePath), ex); 313 } 314 catch (Error error) { 315 if (fileName != null && cacheFile != null) { 316 cacheFile.remove(fileName); 317 } 318 319 // We need to catch all errors to put a reason failure (file name) in error 320 throw new Error("Error was thrown while processing " + filePath, error); 321 } 322 } 323 } 324 325 /** 326 * Processes a file with all FileSetChecks. 327 * 328 * @param file a file to process. 329 * @return a sorted set of violations to be logged. 330 * @throws CheckstyleException if error condition within Checkstyle occurs. 331 * @noinspection ProhibitedExceptionThrown 332 * @noinspectionreason ProhibitedExceptionThrown - there is no other way to obey 333 * haltOnException field 334 */ 335 private SortedSet<Violation> processFile(File file) throws CheckstyleException { 336 final SortedSet<Violation> fileMessages = new TreeSet<>(); 337 try { 338 final FileText theText = new FileText(file.getAbsoluteFile(), charset); 339 for (final FileSetCheck fsc : fileSetChecks) { 340 fileMessages.addAll(fsc.process(file, theText)); 341 } 342 } 343 catch (final IOException ioe) { 344 log.debug("IOException occurred.", ioe); 345 fileMessages.add(new Violation(1, 346 Definitions.CHECKSTYLE_BUNDLE, EXCEPTION_MSG, 347 new String[] {ioe.getMessage()}, null, getClass(), null)); 348 } 349 // -@cs[IllegalCatch] There is no other way to obey haltOnException field 350 catch (Exception ex) { 351 if (haltOnException) { 352 throw ex; 353 } 354 355 log.debug("Exception occurred.", ex); 356 357 final StringWriter sw = new StringWriter(); 358 final PrintWriter pw = new PrintWriter(sw, true); 359 360 ex.printStackTrace(pw); 361 362 fileMessages.add(new Violation(1, 363 Definitions.CHECKSTYLE_BUNDLE, EXCEPTION_MSG, 364 new String[] {sw.getBuffer().toString()}, 365 null, getClass(), null)); 366 } 367 return fileMessages; 368 } 369 370 /** 371 * Check if all before execution file filters accept starting the file. 372 * 373 * @param fileName 374 * the file to be audited 375 * @return {@code true} if the file is accepted. 376 */ 377 private boolean acceptFileStarted(String fileName) { 378 final String stripped = CommonUtil.relativizePath(basedir, fileName); 379 return beforeExecutionFileFilters.accept(stripped); 380 } 381 382 /** 383 * Notify all listeners about the beginning of a file audit. 384 * 385 * @param fileName 386 * the file to be audited 387 */ 388 @Override 389 public void fireFileStarted(String fileName) { 390 final String stripped = CommonUtil.relativizePath(basedir, fileName); 391 final AuditEvent event = new AuditEvent(this, stripped); 392 for (final AuditListener listener : listeners) { 393 listener.fileStarted(event); 394 } 395 } 396 397 /** 398 * Notify all listeners about the errors in a file. 399 * 400 * @param fileName the audited file 401 * @param errors the audit errors from the file 402 */ 403 @Override 404 public void fireErrors(String fileName, SortedSet<Violation> errors) { 405 final String stripped = CommonUtil.relativizePath(basedir, fileName); 406 boolean hasNonFilteredViolations = false; 407 for (final Violation element : errors) { 408 final AuditEvent event = new AuditEvent(this, stripped, element); 409 if (filters.accept(event)) { 410 hasNonFilteredViolations = true; 411 for (final AuditListener listener : listeners) { 412 listener.addError(event); 413 } 414 } 415 } 416 if (hasNonFilteredViolations && cacheFile != null) { 417 cacheFile.remove(fileName); 418 } 419 } 420 421 /** 422 * Notify all listeners about the end of a file audit. 423 * 424 * @param fileName 425 * the audited file 426 */ 427 @Override 428 public void fireFileFinished(String fileName) { 429 final String stripped = CommonUtil.relativizePath(basedir, fileName); 430 final AuditEvent event = new AuditEvent(this, stripped); 431 for (final AuditListener listener : listeners) { 432 listener.fileFinished(event); 433 } 434 } 435 436 @Override 437 protected void finishLocalSetup() throws CheckstyleException { 438 final Locale locale = new Locale(localeLanguage, localeCountry); 439 LocalizedMessage.setLocale(locale); 440 441 if (moduleFactory == null) { 442 if (moduleClassLoader == null) { 443 throw new CheckstyleException(getLocalizedMessage("Checker.finishLocalSetup")); 444 } 445 446 final Set<String> packageNames = PackageNamesLoader 447 .getPackageNames(moduleClassLoader); 448 moduleFactory = new PackageObjectFactory(packageNames, 449 moduleClassLoader); 450 } 451 452 final DefaultContext context = new DefaultContext(); 453 context.add("charset", charset); 454 context.add("moduleFactory", moduleFactory); 455 context.add("severity", severity.getName()); 456 context.add("basedir", basedir); 457 context.add("tabWidth", String.valueOf(tabWidth)); 458 childContext = context; 459 } 460 461 /** 462 * {@inheritDoc} Creates child module. 463 * 464 * @noinspection ChainOfInstanceofChecks 465 * @noinspectionreason ChainOfInstanceofChecks - we treat checks and filters differently 466 */ 467 @Override 468 protected void setupChild(Configuration childConf) 469 throws CheckstyleException { 470 final String name = childConf.getName(); 471 final Object child; 472 473 try { 474 child = moduleFactory.createModule(name); 475 476 if (child instanceof AbstractAutomaticBean) { 477 final AbstractAutomaticBean bean = (AbstractAutomaticBean) child; 478 bean.contextualize(childContext); 479 bean.configure(childConf); 480 } 481 } 482 catch (final CheckstyleException ex) { 483 throw new CheckstyleException( 484 getLocalizedMessage("Checker.setupChildModule", name, ex.getMessage()), ex); 485 } 486 if (child instanceof FileSetCheck) { 487 final FileSetCheck fsc = (FileSetCheck) child; 488 fsc.init(); 489 addFileSetCheck(fsc); 490 } 491 else if (child instanceof BeforeExecutionFileFilter) { 492 final BeforeExecutionFileFilter filter = (BeforeExecutionFileFilter) child; 493 addBeforeExecutionFileFilter(filter); 494 } 495 else if (child instanceof Filter) { 496 final Filter filter = (Filter) child; 497 addFilter(filter); 498 } 499 else if (child instanceof AuditListener) { 500 final AuditListener listener = (AuditListener) child; 501 addListener(listener); 502 } 503 else { 504 throw new CheckstyleException( 505 getLocalizedMessage("Checker.setupChildNotAllowed", name)); 506 } 507 } 508 509 /** 510 * Adds a FileSetCheck to the list of FileSetChecks 511 * that is executed in process(). 512 * 513 * @param fileSetCheck the additional FileSetCheck 514 */ 515 public void addFileSetCheck(FileSetCheck fileSetCheck) { 516 fileSetCheck.setMessageDispatcher(this); 517 fileSetChecks.add(fileSetCheck); 518 } 519 520 /** 521 * Adds a before execution file filter to the end of the event chain. 522 * 523 * @param filter the additional filter 524 */ 525 public void addBeforeExecutionFileFilter(BeforeExecutionFileFilter filter) { 526 beforeExecutionFileFilters.addBeforeExecutionFileFilter(filter); 527 } 528 529 /** 530 * Adds a filter to the end of the audit event filter chain. 531 * 532 * @param filter the additional filter 533 */ 534 public void addFilter(Filter filter) { 535 filters.addFilter(filter); 536 } 537 538 @Override 539 public final void addListener(AuditListener listener) { 540 listeners.add(listener); 541 } 542 543 /** 544 * Sets the file extensions that identify the files that pass the 545 * filter of this FileSetCheck. 546 * 547 * @param extensions the set of file extensions. A missing 548 * initial '.' character of an extension is automatically added. 549 */ 550 public final void setFileExtensions(String... extensions) { 551 if (extensions != null) { 552 fileExtensions = new String[extensions.length]; 553 for (int i = 0; i < extensions.length; i++) { 554 final String extension = extensions[i]; 555 if (extension.startsWith(EXTENSION_SEPARATOR)) { 556 fileExtensions[i] = extension; 557 } 558 else { 559 fileExtensions[i] = EXTENSION_SEPARATOR + extension; 560 } 561 } 562 } 563 } 564 565 /** 566 * Sets the factory for creating submodules. 567 * 568 * @param moduleFactory the factory for creating FileSetChecks 569 */ 570 public void setModuleFactory(ModuleFactory moduleFactory) { 571 this.moduleFactory = moduleFactory; 572 } 573 574 /** 575 * Sets locale country. 576 * 577 * @param localeCountry the country to report messages 578 */ 579 public void setLocaleCountry(String localeCountry) { 580 this.localeCountry = localeCountry; 581 } 582 583 /** 584 * Sets locale language. 585 * 586 * @param localeLanguage the language to report messages 587 */ 588 public void setLocaleLanguage(String localeLanguage) { 589 this.localeLanguage = localeLanguage; 590 } 591 592 /** 593 * Sets the severity level. The string should be one of the names 594 * defined in the {@code SeverityLevel} class. 595 * 596 * @param severity The new severity level 597 * @see SeverityLevel 598 */ 599 public final void setSeverity(String severity) { 600 this.severity = SeverityLevel.getInstance(severity); 601 } 602 603 @Override 604 public final void setModuleClassLoader(ClassLoader moduleClassLoader) { 605 this.moduleClassLoader = moduleClassLoader; 606 } 607 608 /** 609 * Sets a named charset. 610 * 611 * @param charset the name of a charset 612 * @throws UnsupportedEncodingException if charset is unsupported. 613 */ 614 public void setCharset(String charset) 615 throws UnsupportedEncodingException { 616 if (!Charset.isSupported(charset)) { 617 throw new UnsupportedEncodingException( 618 getLocalizedMessage("Checker.setCharset", charset)); 619 } 620 this.charset = charset; 621 } 622 623 /** 624 * Sets the field haltOnException. 625 * 626 * @param haltOnException the new value. 627 */ 628 public void setHaltOnException(boolean haltOnException) { 629 this.haltOnException = haltOnException; 630 } 631 632 /** 633 * Set the tab width to report audit events with. 634 * 635 * @param tabWidth an {@code int} value 636 */ 637 public final void setTabWidth(int tabWidth) { 638 this.tabWidth = tabWidth; 639 } 640 641 /** 642 * Clears the cache. 643 */ 644 public void clearCache() { 645 if (cacheFile != null) { 646 cacheFile.reset(); 647 } 648 } 649 650 /** 651 * Extracts localized messages from properties files. 652 * 653 * @param messageKey the key pointing to localized message in respective properties file. 654 * @param args the arguments of message in respective properties file. 655 * @return a string containing extracted localized message 656 */ 657 private String getLocalizedMessage(String messageKey, Object... args) { 658 final LocalizedMessage localizedMessage = new LocalizedMessage( 659 Definitions.CHECKSTYLE_BUNDLE, getClass(), 660 messageKey, args); 661 662 return localizedMessage.getMessage(); 663 } 664 665}