Source code

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}