[doc] Provide documentation for gradle integration and plain java API integration by adangel · Pull Request #2283 · pmd/pmd

adangel · 2020-02-13T09:57:18Z

PR Description:
This improves the documentation and gives an example on how to call PMD programmatically.

Here's the content for easier reviewing:

The easiest way to run PMD is to just use a build plugin in your favorite build tool
like Apache Ant, Apache Maven or
Gradle.

There are also many integrations for IDEs available, see Tools.

If you have your own build tool or want to integrate PMD in a different way, you can call PMD programmatically,
as described here.

Dependencies

You'll need to add the dependency to the language, you want to analyze. For Java, it will be
net.sourceforge.pmd:pmd-java. If you use Maven, you can add a new (compile time) dependency like this:

<dependency>
    <groupId>net.sourceforge.pmd</groupId>
    <artifactId>pmd-java</artifactId>
    <version>${pmdVersion}</version>
</dependency>

Note: You'll need to select a specific version. This is done in the example via the property pmdVersion.

This will transitively pull in the artifact pmd-core which contains the API.

Command line interface

The easiest way is to call PMD with the same interface as from command line. The main class is
net.sourceforge.pmd.PMD:

import net.sourceforge.pmd.PMD;

public class Example {
    public static void main(String[] args) {
        String[] pmdArgs = {
            "-d", "/home/workspace/src/main/java/code",
            "-R", "rulesets/java/quickstart.xml",
            "-f", "xml",
            "-r", "/home/workspace/pmd-report.xml"
        };
        PMD.main(pmdArgs);
    }
}

It uses the same options as described in PMD CLI reference.

Programmatically, variant 1

This is very similar:

import net.sourceforge.pmd.PMD;
import net.sourceforge.pmd.PMDConfiguration;

public class PmdExample {

    public static void main(String[] args) {
        PMDConfiguration configuration = new PMDConfiguration();
        configuration.setInputPaths("/home/workspace/src/main/java/code");
        configuration.setRuleSets("rulesets/java/quickstart.xml");
        configuration.setReportFormat("xml");
        configuration.setReportFile("/home/workspace/pmd-report.xml");

        PMD.doPMD(configuration);
    }
}

Programmatically, variant 2

This gives you more control over which files are processed, but is also more complicated.
You can also provide your own listeners and renderers.

First we create a PMDConfiguration. This is currently the only way to specify a ruleset:

PMDConfiguration configuration = new PMDConfiguration();
configuration.setMinimumPriority(RulePriority.MEDIUM);
configuration.setRuleSets("rulesets/java/quickstart.xml");

In order to support type resolution, PMD needs to have access to the compiled classes and dependencies
as well. This is called "auxclasspath" and is also configured here.
Note: you can specify multiple class paths separated by : on Unix-systems or ; under Windows.
```
configuration.prependClasspath("/home/workspace/target/classes:/home/.m2/repository/my/dependency.jar");
```
Then we need a ruleset factory. This is created using the configuration, taking the minimum priority into
account:
```
RuleSetFactory ruleSetFactory = RulesetsFactoryUtils.createFactory(configuration);
```

PMD operates on a list of DataSource. You can assemble a own list of FileDataSource, e.g.

List<DataSource> files = Arrays.asList(new FileDataSource(new File("/path/to/src/MyClass.java")));

For reporting, you can use a built-in renderer, e.g. XMLRenderer. Note, that you must manually initialize
the renderer by setting a suitable Writer and calling start(). After the PMD run, you need to call
end() and flush(). Then your writer should have received all output.
```
StringWriter rendererOutput = new StringWriter();
Renderer xmlRenderer = new XMLRenderer("UTF-8");
xmlRenderer.setWriter(rendererOutput);
xmlRenderer.start();
```
Create a RuleContext. This is the context instance, that is available then in the rule implementations.
Note: when running in multi-threaded mode (which is the default), the rule context instance is cloned for
each thread.
```
RuleContext ctx = new RuleContext();
```
Optionally register a report listener. This allows you to react immediately on found violations. You could also
use such a listener to implement your own renderer. The listener must implement the interface
ThreadSafeReportListener and can be registered via ctx.getReport().addListener(...).
```
ctx.getReport().addListener(new ThreadSafeReportListener() {
    public void ruleViolationAdded(RuleViolation ruleViolation) {
    }
    public void metricAdded(Metric metric) {
    }
```
Now, all the preparations are done, and PMD can be executed. This is done by calling
PMD.processFiles(...). This method call takes the configuration, the ruleset factory, the files
to process, the rule context and the list of renderers. Provide an empty list, if you don't want to use
any renderer. Note: The auxclasspath needs to be closed explicitly. Otherwise the class or jar files may
remain open and file resources are leaked.
```
try {
    PMD.processFiles(configuration, ruleSetFactory, files, ctx,
            Collections.singletonList(renderer));
} finally {
    ClassLoader auxiliaryClassLoader = configuration.getClassLoader();
    if (auxiliaryClassLoader instanceof ClasspathClassLoader) {
        ((ClasspathClassLoader) auxiliaryClassLoader).close();
    }
}
```

After the call, you need to finish the renderer via end() and flush().
Then you can check the rendered output.

renderer.end();
renderer.flush();
System.out.println("Rendered Report:");
System.out.println(rendererOutput.toString());

Here is a complete example:

import java.io.IOException;
import java.io.StringWriter;
import java.io.Writer;
import java.nio.file.FileSystems;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.PathMatcher;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import net.sourceforge.pmd.PMD;
import net.sourceforge.pmd.PMDConfiguration;
import net.sourceforge.pmd.RuleContext;
import net.sourceforge.pmd.RulePriority;
import net.sourceforge.pmd.RuleSetFactory;
import net.sourceforge.pmd.RuleViolation;
import net.sourceforge.pmd.RulesetsFactoryUtils;
import net.sourceforge.pmd.ThreadSafeReportListener;
import net.sourceforge.pmd.renderers.Renderer;
import net.sourceforge.pmd.renderers.XMLRenderer;
import net.sourceforge.pmd.stat.Metric;
import net.sourceforge.pmd.util.ClasspathClassLoader;
import net.sourceforge.pmd.util.datasource.DataSource;
import net.sourceforge.pmd.util.datasource.FileDataSource;

public class PmdExample2 {

    public static void main(String[] args) throws IOException {
        PMDConfiguration configuration = new PMDConfiguration();
        configuration.setMinimumPriority(RulePriority.MEDIUM);
        configuration.setRuleSets("rulesets/java/quickstart.xml");
        configuration.prependClasspath("/home/workspace/target/classes");
        RuleSetFactory ruleSetFactory = RulesetsFactoryUtils.createFactory(configuration);

        List<DataSource> files = determineFiles("/home/workspace/src/main/java/code");

        Writer rendererOutput = new StringWriter();
        Renderer renderer = createRenderer(rendererOutput);
        renderer.start();

        RuleContext ctx = new RuleContext();

        ctx.getReport().addListener(createReportListener()); // alternative way to collect violations

        try {
            PMD.processFiles(configuration, ruleSetFactory, files, ctx,
                Collections.singletonList(renderer));
        } finally {
            ClassLoader auxiliaryClassLoader = configuration.getClassLoader();
            if (auxiliaryClassLoader instanceof ClasspathClassLoader) {
                ((ClasspathClassLoader) auxiliaryClassLoader).close();
            }
        }

        renderer.end();
        renderer.flush();
        System.out.println("Rendered Report:");
        System.out.println(rendererOutput.toString());
    }

    private static ThreadSafeReportListener createReportListener() {
        return new ThreadSafeReportListener() {
            @Override
            public void ruleViolationAdded(RuleViolation ruleViolation) {
                System.out.printf("%-20s:%d %s%n", ruleViolation.getFilename(),
                        ruleViolation.getBeginLine(), ruleViolation.getDescription());
            }

            @Override
            public void metricAdded(Metric metric) {
                // ignored
            }
        };
    }

    private static Renderer createRenderer(Writer writer) {
        XMLRenderer xml = new XMLRenderer("UTF-8");
        xml.setWriter(writer);
        return xml;
    }

    private static List<DataSource> determineFiles(String basePath) throws IOException {
        Path dirPath = FileSystems.getDefault().getPath(basePath);
        PathMatcher matcher = FileSystems.getDefault().getPathMatcher("glob:*.java");

        List<DataSource> files = new ArrayList<>();

        Files.walkFileTree(dirPath, new SimpleFileVisitor<Path>() {
            @Override
            public FileVisitResult visitFile(Path path, BasicFileAttributes attrs) throws IOException {
                if (matcher.matches(path.getFileName())) {
                    System.out.printf("Using %s%n", path);
                    files.add(new FileDataSource(path.toFile()));
                } else {
                    System.out.printf("Ignoring %s%n", path);
                }
                return super.visitFile(path, attrs);
            }
        });
        System.out.printf("Analyzing %d files in %s%n", files.size(), basePath);
        return files;
    }
}

Refs pmd#2274

ghost · 2020-02-13T10:10:47Z

	1 Message
📖	No java rules are changed!

Generated by 🚫 Danger

oowekyala

Nice!

Refs #2283

adangel added 2 commits February 13, 2020 10:53

[doc] Add simple gradle documentation

fce8f76

[doc] Add PMD java api documentation

2e6ada8

Refs pmd#2274

adangel mentioned this pull request Feb 13, 2020

[doc] Java API documentation for PMD #2274

Closed

adangel added this to the 6.22.0 milestone Feb 13, 2020

oowekyala approved these changes Feb 14, 2020

View reviewed changes

oowekyala added a commit that referenced this pull request Feb 14, 2020

Merge branch 'docs-java-api'

e3e469c

Refs #2283

oowekyala merged commit 2e6ada8 into pmd:master Feb 14, 2020

adangel deleted the docs-java-api branch February 15, 2020 17:17

adangel mentioned this pull request Feb 24, 2020

[java] Typeresolution not working - missing auxclasspath #2311

Closed

oowekyala mentioned this pull request May 20, 2020

[doc] Documentations improvements tracker #1139

Closed

13 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[doc] Provide documentation for gradle integration and plain java API integration#2283

[doc] Provide documentation for gradle integration and plain java API integration#2283
oowekyala merged 2 commits into
pmd:masterfrom
adangel:docs-java-api

adangel commented Feb 13, 2020

Uh oh!

ghost commented Feb 13, 2020

Uh oh!

oowekyala left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

adangel commented Feb 13, 2020

Dependencies

Command line interface

Programmatically, variant 1

Programmatically, variant 2

Uh oh!

ghost commented Feb 13, 2020

Uh oh!

oowekyala left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants