Creating Custom PMD Rules with Java and XPath

1. Preparation

Download the latest PMD version (5.4.1) from the official site pmd.github.io , extracting pmd-bin-5.4.1.zip and pmd-src-5.4.1.zip . The binary package contains executable tools, while the source package provides the library code.

2. Directory Overview

pmd-bin-5.4.1 (executable version)

bin designer.bat – GUI tool that converts Java source to an AST. bgastviewer.bat – Similar GUI tool. cpd.bat – Command‑line duplicate‑code detector. cpdgui.bat – GUI version of the duplicate‑code detector. pmd.bat – Windows entry point for PMD. run.sh – Linux entry point for PMD.

lib – Contains all dependent JARs, including third‑party and language modules.

pmd-src-5.4.1 (source version)

pmd-core – Core execution scheduler.

pmd-java – Java language detection module, with sub‑directories such as grammar , rulesets , and various rule categories (e.g., basic , codesize ).

pmd-java8 – Support for Java 8.

pmd-javascript, pmd-jsp – Modules for other languages.

3. Idea for a Custom Rule

Define the rule you want to enforce.

List all code patterns that would violate the rule.

Use designer.bat to view the AST of those patterns.

Write rule code that captures the distinguishing AST features.

Create an XML rule file describing the rule.

Run PMD against sample code to verify the rule triggers correctly.

Example Rule: While Loops Must Use Braces

The rule checks that a WhileStatement node contains a Block child; if only a Statement is present, the rule reports a violation.

Step 1 – Identify the Desired Rule

Enforce that every while loop is surrounded by braces to avoid confusing code structure.

Step 2 – List Violating Code Patterns

Provide examples of while loops without braces (illustrated with images in the original article).

Step 3 – Analyze AST with designer.bat

Run designer.bat (found in pmd-bin-5.4.1/bin ) and paste the source code to view its AST. The relevant node is WhileStatement , which shows different child structures depending on the presence of braces.

Step 4 – Write Java Rule Code

Create a new Java class extending net.sourceforge.pmd.lang.java.rule.AbstractJavaRule . The rule traverses the AST, locates ASTWhileStatement nodes, checks the second child for an ASTBlock , and calls addViolation(data, node) when a block is missing.

Step 5 – Create the XML Rule File

Place the rule definition in a custom XML file (e.g., mycustomrules.xml ) with elements such as name , message , class , description , and example . The class can reside in any package, e.g., com.yourcompany.util.pmd .

Step 6 – Build and Run

Re‑package the modified pmd-java module with mvn clean package , replace the original JAR in pmd-bin-5.4.1/lib , and execute PMD: pmd.bat -d c:\path\to\my\src -f xml -R c:\path\to\mycustomrules.xml The output will show any violations of the custom rule.

4. Using XPath to Write the Same Rule

PMD also supports XPath rules. The same “while loop must use braces” rule can be expressed as: //WhileStatement[not(Statement/Block)] Create an XML rule file containing this expression; no Java code is required. The designer tool can generate the XML automatically.

After pointing PMD to the new XML file and running the scan, the rule works as expected.

Tip: Use the designer’s “Create rule XML” action to quickly generate the rule file, remembering to set the language="java" attribute manually if needed.

This article provides a quick start for custom PMD rule creation; a future article will cover more complex rule development.