From 06efd65b167750ed3efcf2d53e1a84b82a9c4ccd Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Fri, 17 May 2024 14:39:09 +0200 Subject: [PATCH] [cli] Rename new parameter to be `--no-fail-on-error` --- docs/pages/pmd/userdocs/cli_reference.md | 26 ++++++-------- docs/pages/pmd/userdocs/cpd/cpd.md | 14 ++++---- docs/pages/release_notes.md | 14 ++++---- .../AbstractAnalysisPmdSubcommand.java | 12 +++---- .../pmd/cli/commands/internal/CpdCommand.java | 8 ++--- .../pmd/cli/commands/internal/PmdCommand.java | 6 ++-- .../pmd/cli/internal/CliExitCode.java | 17 +++++----- .../net/sourceforge/pmd/cli/CpdCliTest.java | 14 ++++---- .../net/sourceforge/pmd/cli/PmdCliTest.java | 10 +++--- .../pmd/AbstractConfiguration.java | 34 +++++++++---------- .../net/sourceforge/pmd/reporting/Report.java | 21 +++++++++--- 11 files changed, 92 insertions(+), 84 deletions(-) diff --git a/docs/pages/pmd/userdocs/cli_reference.md b/docs/pages/pmd/userdocs/cli_reference.md index c7a74d1697..cf90f0e39b 100644 --- a/docs/pages/pmd/userdocs/cli_reference.md +++ b/docs/pages/pmd/userdocs/cli_reference.md @@ -20,7 +20,6 @@ The tool comes with a rather extensive help text, simply running with `--help`! Default value Applies to - {% include custom/cli_option_row.html options="--rulesets,-R" option_arg="refs" description="Path to a ruleset xml file. The path may reference @@ -56,7 +55,6 @@ The tool comes with a rather extensive help text, simply running with `--help`! (\":\" on Linux, \";\" on Windows) is used to separate the entries. Alternatively, a single `file:` URL to a text file containing path elements on consecutive lines can be specified. -

See also [Providing the auxiliary classpath](pmd_languages_java.html#providing-the-auxiliary-classpath).

" languages="Java" %} @@ -81,15 +79,15 @@ The tool comes with a rather extensive help text, simply running with `--help`! The valid values are the standard character sets of `java.nio.charset.Charset`." default="UTF-8" %} - {% include custom/cli_option_row.html options="--[no-]fail-on-processing-error" - description="Specifies whether PMD exits with non-zero status if processing errors occurred. - By default PMD exits with status 5 if processing errors or violations are found. - Disable this option with `--no-fail-on-processing-error` to exit with 0 instead and just write the report." + {% include custom/cli_option_row.html options="--[no-]fail-on-error" + description="Specifies whether PMD exits with non-zero status if recoverable errors occurred. + By default PMD exits with status 5 if recoverable errors occurred (whether there are violations or not). + Disable this option with `--no-fail-on-error` to exit with 0 instead. In any case, a report with the found violations will be written." %} {% include custom/cli_option_row.html options="--[no-]fail-on-violation" description="Specifies whether PMD exits with non-zero status if violations are found. By default PMD exits with status 4 if violations are found. - Disable this feature with `--no-fail-on-violation` to exit with 0 instead and just output the report." + Disable this feature with `--no-fail-on-violation` to exit with 0 instead. In any case a report with the found violations will be written." %} {% include custom/cli_option_row.html options="--file-list" option_arg="filepath" @@ -104,9 +102,7 @@ The tool comes with a rather extensive help text, simply running with `--help`! by extension is disabled and PMD tries to parse all files with the given language `<lang>`. Parsing errors are ignored and unparsable files are skipped. -

Use `--use-version` to specify the language version to use, if it is not the default.

-

This option allows to use the xml language for files, that don't use xml as extension. See [example](#analyze-other-xml-formats) below.

" %} @@ -131,7 +127,7 @@ The tool comes with a rather extensive help text, simply running with `--help`! {% include custom/cli_option_row.html options="--minimum-priority" option_arg="priority" description="Rule priority threshold; rules with lower priority than configured here won't be used. - Valid values (case insensitive): High, Medium_High, Medium, Medium_Low, Low. + Valid values (case-insensitive): High, Medium_High, Medium, Medium_Low, Low. An integer between 1 (High) and 5 (Low) is also supported. See [Configuring rules](pmd_userdocs_configuring_rules.html) on how to override priorities in custom rulesets." default="Low" @@ -147,7 +143,7 @@ The tool comes with a rather extensive help text, simply running with `--help`! description="Enables / disable progress bar indicator of live analysis progress. This ie enabled by default." %} {% include custom/cli_option_row.html options="--property,-P" - option_arg="name>= -0Everything is fine, no violations found and no processing error occurred. +0Everything is fine, no violations found and no recoverable error occurred. 1PMD exited with an exception. 2Usage error. Command-line parameters are invalid or missing. 4At least one violation has been detected, unless --no-fail-on-violation is set.

Since PMD 5.3.

-5At least one processing error has occurred. There might be additionally zero or more violations detected. - To ignore processing errors, use --no-fail-on-processing-error.

Since PMD 7.2.0.

+5At least one recoverable error has occurred. There might be additionally zero or more violations detected. + To ignore recoverable errors, use --no-fail-on-error.

Since PMD 7.2.0.

{%include note.html content="If PMD exits with 5, then PMD had either trouble parsing one or more files or a rule failed with an exception. That means, that either no violations for the entire file or for that rule are reported. These cases can be considered as false-negatives. -In any case, the root cause should be investigated. If it's a problem in PMD itself, please create a bug report. Processing errors +In any case, the root cause should be investigated. If it's a problem in PMD itself, please create a bug report. Recoverable errors are usually part of the generated PMD report." %} ## Logging diff --git a/docs/pages/pmd/userdocs/cpd/cpd.md b/docs/pages/pmd/userdocs/cpd/cpd.md index 02775e3c78..d13416eacc 100644 --- a/docs/pages/pmd/userdocs/cpd/cpd.md +++ b/docs/pages/pmd/userdocs/cpd/cpd.md @@ -150,10 +150,10 @@ exactly identical. If the root path is mentioned (e.g. \"/\" or \"C:\\\"), then the paths will be rendered as absolute." %} - {% include custom/cli_option_row.html options="--[no-]fail-on-processing-error" - description="Specifies whether CPD exits with non-zero status if processing errors occurred. - By default CPD exits with status 5 if processing errors or violations are found. - Disable this option with `--no-fail-on-processing-error` to exit with 0 instead and just write the report." + {% include custom/cli_option_row.html options="--[no-]fail-on-error" + description="Specifies whether CPD exits with non-zero status if recoverable errors occurred. + By default CPD exits with status 5 if recoverable errors occurred (whether there are duplications or not). + Disable this option with `--no-fail-on-error` to exit with 0 instead. In any case, a report with the found duplications will be written." %} {% include custom/cli_option_row.html options="--[no-]fail-on-violation" description="Specifies whether CPD exits with non-zero status if violations are found. @@ -288,12 +288,12 @@ Please note that if CPD detects duplicated source code, it will exit with status This behavior has been introduced to ease CPD integration into scripts or hooks, such as SVN hooks. - + - +
0Everything is fine, no code duplications found and no processing errors occurred.
0Everything is fine, no code duplications found and no recoverable errors occurred.
1CPD exited with an exception.
2Usage error. Command-line parameters are invalid or missing.
4At least one code duplication has been detected unless --no-fail-on-violation is set.

Since PMD 5.0.

5At least one processing error has occurred. There might be additionally zero or more duplications detected. - To ignore processing errors, use --no-fail-on-processing-error.

Since PMD 7.2.0.

5At least one recoverable error has occurred. There might be additionally zero or more duplications detected. + To ignore recoverable errors, use --no-fail-on-error.

Since PMD 7.2.0.

{%include note.html content="If PMD exits with 5, then PMD had trouble lexing one or more files. diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md index b9600bd0c0..8a90e752d5 100644 --- a/docs/pages/release_notes.md +++ b/docs/pages/release_notes.md @@ -53,15 +53,17 @@ Since this release, PMD will also expose any getter returning a collection of an #### CLI -* New exit code 5 introduced. PMD and CPD will exit now by default with exit code 5, if any processing error - (e.g. parsing exception, lexing exception or rule exception) occurred. Such processing errors mean, that - either no violations or duplication for the entire file or for that rule are reported. These cases can be - considered as false-negatives. +* New exit code 5 introduced. PMD and CPD will exit now by default with exit code 5, if any recoverable error + (e.g. parsing exception, lexing exception or rule exception) occurred. PMD will still create a report with + all detected violations or duplications if recoverable errors occurred. Such errors mean, that the report + might be incomplete, as either violations or duplications for an entire file or for a specific rule are missing. + These cases can be considered as false-negatives. In any case, the root cause should be investigated. If it's a problem in PMD itself, please create a bug report. -* New CLI parameter `--no-fail-on-processing-error` to ignore processing errors and not exit with code 5. By default, - a build with processing errors will now fail and with that parameter, the previous behavior can be restored. +* New CLI parameter `--no-fail-on-error` to ignore such errors and not exit with code 5. By default, + a build with errors will now fail and with that parameter, the previous behavior can be restored. + This parameter is available for both PMD and CPD. #### Deprecated API diff --git a/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/AbstractAnalysisPmdSubcommand.java b/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/AbstractAnalysisPmdSubcommand.java index c553539331..02a090ab3f 100644 --- a/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/AbstractAnalysisPmdSubcommand.java +++ b/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/AbstractAnalysisPmdSubcommand.java @@ -43,16 +43,16 @@ public abstract class AbstractAnalysisPmdSubcommand relativizeRootPaths; diff --git a/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/CpdCommand.java b/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/CpdCommand.java index 30b312e69e..a02723b1b0 100644 --- a/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/CpdCommand.java +++ b/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/CpdCommand.java @@ -103,7 +103,7 @@ public class CpdCommand extends AbstractAnalysisPmdSubcommand configuration.addRelativizeRoots(relativizeRootPaths); } configuration.setFailOnViolation(failOnViolation); - configuration.setFailOnProcessingError(failOnProcessingError); + configuration.setFailOnError(failOnError); configuration.setInputFilePath(fileListPath); if (inputPaths != null) { configuration.setInputPathList(new ArrayList<>(inputPaths)); @@ -134,9 +134,9 @@ public class CpdCommand extends AbstractAnalysisPmdSubcommand MutableBoolean hasViolations = new MutableBoolean(); cpd.performAnalysis(report -> hasViolations.setValue(!report.getMatches().isEmpty())); - boolean hasProcessingErrors = configuration.getReporter().numErrors() > 0; - if (hasProcessingErrors && configuration.isFailOnProcessingError()) { - return CliExitCode.PROCESSING_ERRORS_OR_VIOLATIONS; + boolean hasErrors = configuration.getReporter().numErrors() > 0; + if (hasErrors && configuration.isFailOnError()) { + return CliExitCode.RECOVERED_ERRORS_OR_VIOLATIONS; } if (hasViolations.booleanValue() && configuration.isFailOnViolation()) { diff --git a/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/PmdCommand.java b/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/PmdCommand.java index 3684a8ca87..f60632ba63 100644 --- a/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/PmdCommand.java +++ b/pmd-cli/src/main/java/net/sourceforge/pmd/cli/commands/internal/PmdCommand.java @@ -270,7 +270,7 @@ public class PmdCommand extends AbstractAnalysisPmdSubcommand configuration.setSuppressMarker(suppressMarker); configuration.setThreads(threads); configuration.setFailOnViolation(failOnViolation); - configuration.setFailOnProcessingError(failOnProcessingError); + configuration.setFailOnError(failOnError); configuration.setAnalysisCacheLocation(cacheLocation != null ? cacheLocation.toString() : null); configuration.setIgnoreIncrementalAnalysis(noCache); @@ -331,8 +331,8 @@ public class PmdCommand extends AbstractAnalysisPmdSubcommand if (pmdReporter.numErrors() > 0) { // processing errors are ignored return CliExitCode.ERROR; - } else if (stats.getNumErrors() > 0 && configuration.isFailOnProcessingError()) { - return CliExitCode.PROCESSING_ERRORS_OR_VIOLATIONS; + } else if (stats.getNumErrors() > 0 && configuration.isFailOnError()) { + return CliExitCode.RECOVERED_ERRORS_OR_VIOLATIONS; } else if (stats.getNumViolations() > 0 && configuration.isFailOnViolation()) { return CliExitCode.VIOLATIONS_FOUND; } else { diff --git a/pmd-cli/src/main/java/net/sourceforge/pmd/cli/internal/CliExitCode.java b/pmd-cli/src/main/java/net/sourceforge/pmd/cli/internal/CliExitCode.java index 0bdf2f479d..909f942c6c 100644 --- a/pmd-cli/src/main/java/net/sourceforge/pmd/cli/internal/CliExitCode.java +++ b/pmd-cli/src/main/java/net/sourceforge/pmd/cli/internal/CliExitCode.java @@ -10,7 +10,7 @@ import net.sourceforge.pmd.AbstractConfiguration; * The execution result of any given command. */ public enum CliExitCode { - /** No errors, no processing errors, no violations. This is exit code {@code 0}. */ + /** No errors, no recoverable errors, no violations, no duplications. This is exit code {@code 0}. */ OK(0), /** * Unexpected errors were detected, PMD may have not run to the end. @@ -19,25 +19,24 @@ public enum CliExitCode { ERROR(1), /** * Indicates a problem with the CLI parameters: either a required - * parameter is missing or an invalid parameter was provided. + * parameter is missing or an invalid parameter was provided. This is exit code {@code 2}. */ USAGE_ERROR(2), /** - * No errors, but PMD found either duplications/violations or couldn't analyze all - * files due to parsing/lexing problems. This is exit code {@code 4}. + * No errors, but PMD found either duplications/violations. This is exit code {@code 4}. * *

This is only returned if {@link AbstractConfiguration#isFailOnViolation()} * is set. It can be disabled by using CLI flag {@code --no-fail-on-violation}. */ VIOLATIONS_FOUND(4), /** - * PMD did run, but there was at least one processing error. There + * PMD did run, but there was at least one recoverable error. There * might be additionally duplications or violations. This is exit code {@code 5}. * - *

This is only returned if {@link AbstractConfiguration#isFailOnProcessingError()} - * is set. It can be disabled by using CLI flag {@code --no-fail-on-processing-error}. + *

This is only returned if {@link AbstractConfiguration#isFailOnError()} + * is set. It can be disabled by using CLI flag {@code --no-fail-on-error}. */ - PROCESSING_ERRORS_OR_VIOLATIONS(5); + RECOVERED_ERRORS_OR_VIOLATIONS(5); private final int exitCode; @@ -55,7 +54,7 @@ public enum CliExitCode { case 1: return ERROR; case 2: return USAGE_ERROR; case 4: return VIOLATIONS_FOUND; - case 5: return PROCESSING_ERRORS_OR_VIOLATIONS; + case 5: return RECOVERED_ERRORS_OR_VIOLATIONS; default: throw new IllegalArgumentException("Not a known exit code: " + i); } diff --git a/pmd-cli/src/test/java/net/sourceforge/pmd/cli/CpdCliTest.java b/pmd-cli/src/test/java/net/sourceforge/pmd/cli/CpdCliTest.java index 7e41671e28..fd8a60d379 100644 --- a/pmd-cli/src/test/java/net/sourceforge/pmd/cli/CpdCliTest.java +++ b/pmd-cli/src/test/java/net/sourceforge/pmd/cli/CpdCliTest.java @@ -5,7 +5,7 @@ package net.sourceforge.pmd.cli; import static net.sourceforge.pmd.cli.internal.CliExitCode.OK; -import static net.sourceforge.pmd.cli.internal.CliExitCode.PROCESSING_ERRORS_OR_VIOLATIONS; +import static net.sourceforge.pmd.cli.internal.CliExitCode.RECOVERED_ERRORS_OR_VIOLATIONS; import static net.sourceforge.pmd.cli.internal.CliExitCode.VIOLATIONS_FOUND; import static net.sourceforge.pmd.util.CollectionUtil.listOf; import static org.hamcrest.CoreMatchers.startsWith; @@ -129,14 +129,14 @@ class CpdCliTest extends BaseCliTest { @Test void testWrongCliOptionResultsInErrorLoggingAfterDir() throws Exception { // --ignore-identifiers doesn't take an argument anymore - it is interpreted as a file for inputPaths - final CliExecutionResult result = runCli(PROCESSING_ERRORS_OR_VIOLATIONS, "--minimum-tokens", "34", "--dir", SRC_DIR, "--ignore-identifiers", "false"); + final CliExecutionResult result = runCli(RECOVERED_ERRORS_OR_VIOLATIONS, "--minimum-tokens", "34", "--dir", SRC_DIR, "--ignore-identifiers", "false"); result.checkStdErr(containsString("No such file false")); } @Test void testWrongCliOptionResultsInErrorLoggingBeforeDir() throws Exception { // --ignore-identifiers doesn't take an argument anymore - it is interpreted as a file for inputPaths - final CliExecutionResult result = runCli(PROCESSING_ERRORS_OR_VIOLATIONS, "--minimum-tokens", "34", "--ignore-identifiers", "false", "--dir", SRC_DIR); + final CliExecutionResult result = runCli(RECOVERED_ERRORS_OR_VIOLATIONS, "--minimum-tokens", "34", "--ignore-identifiers", "false", "--dir", SRC_DIR); result.checkStdErr(containsString("No such file false")); } @@ -221,7 +221,7 @@ class CpdCliTest extends BaseCliTest { */ @Test void testSkipLexicalErrors() throws Exception { - runCli(PROCESSING_ERRORS_OR_VIOLATIONS, + runCli(RECOVERED_ERRORS_OR_VIOLATIONS, "--minimum-tokens", "10", "-d", BASE_RES_PATH + "badandgood/", "--format", "text", @@ -234,7 +234,7 @@ class CpdCliTest extends BaseCliTest { @Test void testExitCodeWithLexicalErrors() throws Exception { - runCli(PROCESSING_ERRORS_OR_VIOLATIONS, + runCli(RECOVERED_ERRORS_OR_VIOLATIONS, "--minimum-tokens", "10", "-d", Paths.get(BASE_RES_PATH, "badandgood", "BadFile.java").toString(), "--format", "text") @@ -250,7 +250,7 @@ class CpdCliTest extends BaseCliTest { "--minimum-tokens", "10", "-d", Paths.get(BASE_RES_PATH, "badandgood", "BadFile.java").toString(), "--format", "text", - "--no-fail-on-processing-error") + "--no-fail-on-error") .verify(r -> { r.checkStdErr(containsPattern("Error while tokenizing: Lexical error in file '.*?BadFile\\.java'")); r.checkStdOut(emptyString()); @@ -259,7 +259,7 @@ class CpdCliTest extends BaseCliTest { @Test void testExitCodeWithLexicalErrorsAndSkipLexical() throws Exception { - runCli(PROCESSING_ERRORS_OR_VIOLATIONS, + runCli(RECOVERED_ERRORS_OR_VIOLATIONS, "--minimum-tokens", "10", "-d", Paths.get(BASE_RES_PATH, "badandgood", "BadFile.java").toString(), "--format", "text", diff --git a/pmd-cli/src/test/java/net/sourceforge/pmd/cli/PmdCliTest.java b/pmd-cli/src/test/java/net/sourceforge/pmd/cli/PmdCliTest.java index 03d91efbc2..fd77c97b42 100644 --- a/pmd-cli/src/test/java/net/sourceforge/pmd/cli/PmdCliTest.java +++ b/pmd-cli/src/test/java/net/sourceforge/pmd/cli/PmdCliTest.java @@ -6,7 +6,7 @@ package net.sourceforge.pmd.cli; import static net.sourceforge.pmd.cli.internal.CliExitCode.ERROR; import static net.sourceforge.pmd.cli.internal.CliExitCode.OK; -import static net.sourceforge.pmd.cli.internal.CliExitCode.PROCESSING_ERRORS_OR_VIOLATIONS; +import static net.sourceforge.pmd.cli.internal.CliExitCode.RECOVERED_ERRORS_OR_VIOLATIONS; import static net.sourceforge.pmd.cli.internal.CliExitCode.USAGE_ERROR; import static net.sourceforge.pmd.cli.internal.CliExitCode.VIOLATIONS_FOUND; import static net.sourceforge.pmd.util.CollectionUtil.listOf; @@ -320,8 +320,8 @@ class PmdCliTest extends BaseCliTest { } @Test - void exitStatusWithProcessingErrors() throws Exception { - runCli(PROCESSING_ERRORS_OR_VIOLATIONS, "--use-version", "dummy-parserThrows", + void exitStatusWithErrors() throws Exception { + runCli(RECOVERED_ERRORS_OR_VIOLATIONS, "--use-version", "dummy-parserThrows", "-d", srcDir.toString(), "-f", "text", "-R", RULESET_WITH_VIOLATION) .verify(r -> { r.checkStdOut(containsString("someSource.dummy\t-\tParseException: Parse exception: ohio")); @@ -330,10 +330,10 @@ class PmdCliTest extends BaseCliTest { } @Test - void exitStatusWithProcessingErrorsNoFail() throws Exception { + void exitStatusWithErrorsNoFail() throws Exception { runCli(OK, "--use-version", "dummy-parserThrows", "-d", srcDir.toString(), "-f", "text", "-R", RULESET_WITH_VIOLATION, - "--no-fail-on-processing-error") + "--no-fail-on-error") .verify(r -> { r.checkStdOut(containsString("someSource.dummy\t-\tParseException: Parse exception: ohio")); r.checkStdErr(containsString("An error occurred while executing PMD.")); diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/AbstractConfiguration.java b/pmd-core/src/main/java/net/sourceforge/pmd/AbstractConfiguration.java index 1118b97d85..d20e5cca3b 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/AbstractConfiguration.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/AbstractConfiguration.java @@ -47,7 +47,7 @@ public abstract class AbstractConfiguration { private List excludes = new ArrayList<>(); private boolean collectRecursive = true; private boolean failOnViolation = true; - private boolean failOnProcessingError = true; + private boolean failOnError = true; protected AbstractConfiguration(LanguageRegistry languageRegistry, PmdReporter messageReporter) { @@ -384,12 +384,12 @@ public abstract class AbstractConfiguration { * Whether PMD should exit with status 4 (the default behavior, true) if * violations are found or just with 0 (to not break the build, e.g.). * - *

Note: If additionally processing errors occurred, the exit status is 5. See - * {@link #isFailOnProcessingError()}. + *

Note: If additionally recoverable errors occurred, the exit status is 5. See + * {@link #isFailOnError()}. * * @return failOnViolation * - * @see #isFailOnProcessingError() + * @see #isFailOnError() */ public boolean isFailOnViolation() { return failOnViolation; @@ -399,12 +399,12 @@ public abstract class AbstractConfiguration { * Sets whether PMD should exit with status 4 (the default behavior, true) * if violations are found or just with 0 (to not break the build, e.g.). * - *

Note: If additionally processing errors occurred, the exit status is 5. See - * {@link #isFailOnProcessingError()}. + *

Note: If additionally recoverable errors occurred, the exit status is 5. See + * {@link #isFailOnError()}. * * @param failOnViolation whether to exit with 4 and fail the build if violations are found. * - * @see #isFailOnProcessingError() + * @see #isFailOnError() */ public void setFailOnViolation(boolean failOnViolation) { this.failOnViolation = failOnViolation; @@ -412,31 +412,31 @@ public abstract class AbstractConfiguration { /** * Whether PMD should exit with status 5 (the default behavior, true) if - * processing errors occurred or just with 0 (to not break the build, e.g.). + * recoverable errors occurred or just with 0 (to not break the build, e.g.). * - *

Note: If additionally violations are found, the exist status is 4. See + *

Note: If only violations are found, the exist status is 4. See * {@link #isFailOnViolation()}. * - * @return failOnProcessingError + * @return failOnError * * @see #isFailOnViolation() */ - public boolean isFailOnProcessingError() { - return failOnProcessingError; + public boolean isFailOnError() { + return failOnError; } /** * Sets whether PMD should exit with status 5 (the default behavior, true) - * if processing errors occurred or just with 0 (to not break the build, e.g.). + * if recoverable errors occurred or just with 0 (to not break the build, e.g.). * - *

Note: If additionally violations are found, the exist status is 4. See + *

Note: If only violations are found, the exist status is 4. See * {@link #isFailOnViolation()}. * - * @param failOnProcessingError whether to exit with 5 and fail the build if processing errors occurred. + * @param failOnError whether to exit with 5 and fail the build if recoverable errors occurred. * * @see #isFailOnViolation() */ - public void setFailOnProcessingError(boolean failOnProcessingError) { - this.failOnProcessingError = failOnProcessingError; + public void setFailOnError(boolean failOnError) { + this.failOnError = failOnError; } } diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/reporting/Report.java b/pmd-core/src/main/java/net/sourceforge/pmd/reporting/Report.java index a13d468952..10f0058e94 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/reporting/Report.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/reporting/Report.java @@ -22,8 +22,8 @@ import net.sourceforge.pmd.lang.rule.Rule; import net.sourceforge.pmd.util.BaseResultProducingCloseable; /** - * A {@link Report} collects all information during a PMD execution. This - * includes violations, suppressed violations, metrics, error during processing + * A {@link Report} collects all information during a PMD execution. This includes violations, + * suppressed violations, metrics, recoverable errors (that occurred during processing) * and configuration errors. * *

A report may be created by a {@link GlobalReportBuilderListener} that you @@ -50,7 +50,10 @@ public final class Report { } /** - * Represents a configuration error. + * Represents a configuration error for a specific rule. + * + *

This might be a missing rule property + * or rule property with pointless values. */ public static class ConfigurationError { @@ -90,7 +93,15 @@ public final class Report { } /** - * Represents a processing error, such as a parse error. + * Represents a recovered error that occurred during analysis. + * + *

This might be a parse error or an unexpected error originating from a rule. + * Such errors are called recoverable, because PMD can just skip + * the problematic file, continue the analysis with the other files and still create a report. + * However, due to these errors, the report might be incomplete. + * + *

Some report formats, such as {@link net.sourceforge.pmd.renderers.XMLRenderer}, include these + * errors for further investigation. */ public static class ProcessingError { @@ -98,7 +109,7 @@ public final class Report { private final FileId file; /** - * Creates a new processing error + * Creates a new processing error. * * @param error * the error