The rule designer

Installing, running, updating

The designer is part of PMD’s binary distributions. Toinstall a distribution, see thedocumentation page about installing PMD.

The designer still works with Java 8 from Oracle, which includes JavaFX. If you use this Java version, thenall is set. However, it is recommended to use OpenJDK along with OpenJFX. The recommended Java Runtime isJava 11 (or later) with OpenJFX 17 (or later).

You can get OpenJDK fromAdoptium,Azul,Microsoft,SAP,Amazon and other OpenJDK vendors.Note: Azul provides a JDK which includes JavaFX - this variant is currently not supported. You always needto install OpenJFX separately.

OpenJFX is available fromJavaFX download page.You need the SDK. Extract the zip file, and set theJAVAFX_HOME environment variable to the extracteddirectory. It should be the directory, that contain the sub-folder “lib” in it.

Example (for linux x64 only, with Java 21 and OpenJFX 21):

$mkdir$HOME/openjdk$cd$HOME/openjdk$wget https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.2%2B13/OpenJDK21U-jdk_x64_linux_hotspot_21.0.2_13.tar.gz$tarxfz OpenJDK21U-jdk_x64_linux_hotspot_21.0.2_13.tar.gz$exportJAVA_HOME=$HOME/openjdk/jdk-21.0.2+13$exportPATH=$JAVA_HOME/bin:$PATH$wget https://download2.gluonhq.com/openjfx/21.0.2/openjfx-21.0.2_linux-x64_bin-sdk.zip$unzip-q openjfx-21.0.2_linux-x64_bin-sdk.zip$exportJAVAFX_HOME=$HOME/openjdk/javafx-sdk-21.0.2

If the bin directory of your PMD distribution is on your shell’s path, then you can thenlaunch the app with

~ $pmd designer

C:\>pmd.bat designer

This is to allow easy updating, and let you choose the dependencies you’re interested in.The available language modules are those on the classpath of the app’s JVM. That’s why it’s recommended to use thestandard PMD startup scripts, which setups the classpath with the available PMD libraries.

Updating

The latest version of the designer currentlyworks with PMD 7.0.0 and above. You can simply replacepmd-designer-7.X.Y.jar with thelatest build in the installationfolder of your PMD distribution, and run it normally. Note that updating may cause some persisted stateto get lost, for example the code snippet.

Usage reference

The rule designer is both a tool to inspect the tree on which PMD rules run on, and to write XPath rulesin an integrated manner. This page describes the features that enable this.

AST inspection

You can enter source code in the middle zone.

• Make sure to select the correct language and version for your source code:
  • Language is set app-wide with the blue button in the menu-bar
  • If the language has several language versions, you can select a specific one with the choicebox just above the code area
• If the source is valid using this setting, the tree to the right will update to display the AST of the code
• When selecting a node, the left panel updates with information about a node

Selecting nodes

There are several ways to focus a node for inspection:

• From the tree view: just click on an item
  • Since 6.16.0, the tree view is also searchable: pressCtrl+F when it’s focused,or click on theSearch button and enter a search query. You can cycle through results withCtrl+Tab orCtrl+F3, and cycle back withCtrl+Shift+Tab orCtrl+Shift+F3.
• From the crumb bar: the crumb bar below the code area shows the ancestors of the currently selected node,and is empty if you have no selection:

• From the source code: maintainCtrl for a second until the code area becomes mostly blue.Then, each node you hover over on the code area will be selected automatically. Example:

Node inspection

The left panel displays the following information:

• XPath attributes: this basically are all the attributes available in XPath queries. Those attributes arewrappers around a Java getter, so you can obtain documentation on the relevant Javadoc (that’s not yetintegrated into the designer)
• Metrics: for nodes that support it, the values of metrics are displayed in this panel
• Scopes: This is java specific and displays some representation of the symbol table. You mostly don’t needit. If you select e.g. a variable id, its usages are already highlighted automatically without opening the panel:

XPath rule design

The bottom part of the UI is dedicated to designing XPath rules:

The center is an XPath expression. As you type it, the matched nodes are updated on the right, and highlightedon the code area. Autocompletion is available on some languages.

Note: you can keep several rules in the editor (there’s a tab for each of them).

Rule properties

Above the XPath expression area, the“Properties” button allows you todefine new properties for your prototype rule.You can also edit the existing properties.

When you click on it, a small popup appears:

The popup contains in the center a list of currently defined properties, displaying their name and expected type.

• Adding: the “Add property” button adds a row to the table
• Deleting: each item has a “Trash” button to delete the property
• Editing: each property can be further edited by clicking on the “Ellipsis” button on the right

Editing properties

The edit menu of a property looks like the following:

• You can edit the name, description, expected type, and default value of the property
• All this information is exported with the rule definition (seeExporting to an XML rule)
• The default value is used unless you’re editing a test case, and you set a custom value for the test case(seeTesting a rule)

Exporting to an XML rule

The littleexport icon next to the gear icon opens a menu to export your rule. This menu lets you fill-in themetadata necessary for an XPath rule to be included in a ruleset.

Testing a rule

PMD has its own XML format to describe rule tests and execute them using our test framework. The designer includesa test editor, which allows you to edit such files or create a new one directly as you edit the rule.This is what the panel left of the XPath expression area is for.

See alsothe test framework documentation.

Testing model

A rule test describes

• the configuration of the rule
• the source on which to run
• the expected violations
• a description (to name the test)

When executing a test, the rule is run on the source with the given configuration, then the violations it findsare compared to the expected ones.

Adding tests

Tests can be added in one of four ways:

• From an XML file: if you already have a test XML file for your tests, you can load all the tests it defines easily.

• From the current source: A new test case with a default configuration is created, with the source that iscurrently in the editor

• With an empty source: A new test case with a default configuration is created, with an empty source file.You must edit the source yourself then.

• From an existing test case: Each test case list item has a “Copy” button which duplicates the test and loadsthe new one.

Test status

In the designer, the test panel is a list of test cases. Their status (passing, failing, error, unknown) is color coded.

Loading a test case

Each test has a piece of source, which you can edit independently of the others, when the test isloaded in the editor. Additional rule configuration options can be chosen when the test is loaded.

Loading is done with theLoad button:

Only one test case may be loaded at a time. If the loaded test is unloaded, the editor reverts back to the stateit had before the first test case was loaded.

Editing a loaded test case

When a test is loaded,the source you edit in the code area is the source of the test. Changes are independentfrom other tests, and from the piece of source that was previously in the editor.

When a test is loaded, an additional toolbar shows up at the top of the code area:

Expected violations

The“Expected violations” button is used to add or edit the expected violations.

Initially the list of violations is empty. You can add violations bydragging and dropping nodes onto thebutton or its popup, from any control that displays nodes. For example:

Test case rule configuration

Rule properties can be configured for each test case independently using the“Property mapping” button. For example:

This configuration will be used when executing the test to check its status.

Exporting tests

When you’re done editing tests, it’s a good idea to save the test file to an XML file. Exporting is done usingthe“Export” button above the list of test cases:

Note that the exported file does not contain any information about the rule. The rule must be in a ruleset filesomewhere else.

If you want to use PMD’s test framework to use the test file in your build, please refer to the conventionsexplained inthe test framework documentation.