So in #3692 I had to modify the entry point for PMD. #3692 (comment) proposed to introduce a forward compatible API on master, which this PR implements.

The entry point for PMD has already been modified several times in PMD 6 to be forward compatible. Unfortunately changes in PMD 7 regularly invalidate these compatibility overloads so that the class PMD is accumulating a lot of cruft. I believe one of the problems is that we conceive this processFiles static method as the entry point of PMD. Maintaining a compatible signature is much harder than if it were hidden behind a configuration builder.

#3692 (comment) further suggests that the API to execute PMD from CLI and the programmatic API should be better separated.

This PR reduces the (supported) functionality of the PMD class to be just CLI-related things:

• the main function
• the runPmd overloads, which mimic the main function but return the status code
• the StatusCode enum

All other members are now deprecated for removal in PMD 7.

The programmatic interface of PMD is now fronted by PmdAnalysis. Instances may be created from a PMDConfiguration easily, and collect files, rulesets and renderers (all the parameters to PMD::processFiles). It encapsulates the logic of processFiles inside a no-arg function performAnalysis. Given a complete PMDConfiguration, the only thing you have to do is the following:

try (PmdAnalysis pmd = PmdAnalysis.create(configuration)) { 
  // `create` reads rulesets and collect analysed files as configured in PMDConfiguration
  // optional further configuration
  pmd.files().addFileOrDirectory(Paths.get("/tmp/sources"));
  pmd.addRenderer(new TextRenderer()); 
  // do the analysis
  pmd.performAnalysis();

} // finally, close all data sources registered in the file collector and release other resources

This will be easier to keep forward compatible, as the user-facing API does not deal with DataSource (which is turned into TextFile in PMD 7), and wraps nicely the logic that handles renderers (which is refactored to use GlobalAnalysisListener in #3692). I think the API will also be compatible with #3782.

About separating CLI and programmatic API: some responsibilities of PMDConfiguration could be gradually shifted into the PmdAnalysis. For instance, all that stuff with input paths and exclude files can be implemented easily using the FileCollector directly (and so getInputPaths and such can be removed from PMDConfiguration). In a cleaner model, PMD's programmatic API would rely less on unvalidated strings given to the PMD configuration (this should instead be done in the CLI module). I think removing them from the PMDConfiguration also removes possible error situations, as the data put in PMDConfiguration for "what rulesets to use" and "what files to process" may be out of sync with the actual contents of the FileCollector and of the rulesets, if the user modified those programmatically. Overall, decreasing the importance of PMDConfiguration is I believe a good idea, as it currently infiltrates the codebase very deep and infects it with irrelevant config options that should be handled elsewhere.

This PR introduces 4 new important types:

• TextFile: this is something I've extracted from my PMD 7 branches. It's what will replace DataSource in PMD 7 (see [core] Text documents epic #3784). TextFile is related to TextDocument but not identical. The version on master is simplified and converted to DataSource before processing so that everything works like before.
• FileCollector: this one is tasked with collecting TextFiles to analyse in a PMD run. This is a programmatic API to finely control which files are added by PMD. It now is the implementation of PMD.getApplicableFiles
• PmdLogger: this is a logging strategy, that I feel is needed to uniformize the logging of traces and errors. Currently it's used by internally FileCollector and forwards to a java.util.Logger. I believe this will make it easier to migrate to SLF4J. Maybe it can be replaced with SLF4J's Logger, or extend from it when we migrate.
• PmdAnalysis: described above

PmdLogger is internal, and TextFile is experimental until PMD 7 (as it will be modified by #3784).

TODO

• Update release notes
  • There is a source-incompatible change: PMDConfiguration#prependClasspath does not throw IOException anymore