001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2023 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.toList()); 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.toSet()); 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("Exception was thrown while processing " 312 + 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( 444 "if no custom moduleFactory is set, " 445 + "moduleClassLoader must be specified"); 446 } 447 448 final Set<String> packageNames = PackageNamesLoader 449 .getPackageNames(moduleClassLoader); 450 moduleFactory = new PackageObjectFactory(packageNames, 451 moduleClassLoader); 452 } 453 454 final DefaultContext context = new DefaultContext(); 455 context.add("charset", charset); 456 context.add("moduleFactory", moduleFactory); 457 context.add("severity", severity.getName()); 458 context.add("basedir", basedir); 459 context.add("tabWidth", String.valueOf(tabWidth)); 460 childContext = context; 461 } 462 463 /** 464 * {@inheritDoc} Creates child module. 465 * 466 * @noinspection ChainOfInstanceofChecks 467 * @noinspectionreason ChainOfInstanceofChecks - we treat checks and filters differently 468 */ 469 @Override 470 protected void setupChild(Configuration childConf) 471 throws CheckstyleException { 472 final String name = childConf.getName(); 473 final Object child; 474 475 try { 476 child = moduleFactory.createModule(name); 477 478 if (child instanceof AbstractAutomaticBean) { 479 final AbstractAutomaticBean bean = (AbstractAutomaticBean) child; 480 bean.contextualize(childContext); 481 bean.configure(childConf); 482 } 483 } 484 catch (final CheckstyleException ex) { 485 throw new CheckstyleException("cannot initialize module " + name 486 + " - " + ex.getMessage(), ex); 487 } 488 if (child instanceof FileSetCheck) { 489 final FileSetCheck fsc = (FileSetCheck) child; 490 fsc.init(); 491 addFileSetCheck(fsc); 492 } 493 else if (child instanceof BeforeExecutionFileFilter) { 494 final BeforeExecutionFileFilter filter = (BeforeExecutionFileFilter) child; 495 addBeforeExecutionFileFilter(filter); 496 } 497 else if (child instanceof Filter) { 498 final Filter filter = (Filter) child; 499 addFilter(filter); 500 } 501 else if (child instanceof AuditListener) { 502 final AuditListener listener = (AuditListener) child; 503 addListener(listener); 504 } 505 else { 506 throw new CheckstyleException(name 507 + " is not allowed as a child in Checker"); 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 final String message = "unsupported charset: '" + charset + "'"; 620 throw new UnsupportedEncodingException(message); 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}