dgroup / arch4u-pmd

Linting rules for Java frameworks like Spring, Quarkus, Jackson, SLF4J, etc., to avoid known problems in REST API, logging, observability, performance, and general best practices.

• Overview
• How to use?
  • Maven (pom.xml)
  • Gradle (build.gradle)
  • Include arch4u-pmd rules into your existing custom ruleset
  • Exclude particular rule
  • Reconfigure a rule
  • Exclude particular folder from inspection
• How to contribute?
• Contributors

Overview

arch4u-pmd is a library with pmd rules that bring new regulations related to known problems in REST API, logging, monitoring, etc., including reconfigured default pmd rules to decrease false-positive violations during usage of well-known frameworks like Spring, Quarkus, etc.

In addition to our custom/reconfigured rules we are using the latest stable pmd-java version which is 6.55.0 with more than 320+ rules with default configuration.

Legend:

• ✅ included in arch4u-ruleset.xml
• ⌛ planned for review considering framework(s) architecture
• 🌵 temporary disabled or reconfigured in arch4u-ruleset.xml
• ❌ disabled/not planned in arch4u-ruleset.xml

PMD rule	Provider	Status	Spring	Quarkus
UseExistingMediaTypeConstant	arch4u-pmd:0.1.0	✅	✅	⌛
UseOpenApiInRestEndpoints	arch4u-pmd:0.1.0	✅	✅	⌛
RestEndpointsWithoutExposedMetrics	arch4u-pmd:0.1.0	✅	✅	⌛
UseConstantAsMetricName	arch4u-pmd:0.1.0	✅	✅	⌛
NoMandatoryConstructorInExceptionClass	arch4u-pmd:0.1.0	✅	✅	⌛
AvoidUsingObjectMapperAsALocalVariable	arch4u-pmd:0.1.0	✅	✅	⌛
AvoidMdcOutsideTryStatement	arch4u-pmd:0.1.0	✅	✅	⌛
PotentiallyThreadLocalPollutionByMdc	arch4u-pmd:0.1.0	✅	✅	⌛
GuardLogStatement	pmd-java:6.44.0	❌	❌	❌
JUnitAssertionsShouldIncludeMessage	pmd-java:6.44.0	🌵	⌛	⌛
UnusedPrivateMethod	pmd-java:6.44.0	🌵	⌛	⌛
AtLeastOneConstructor	pmd-java:6.44.0	🌵	✅	⌛
OnlyOneReturn	pmd-java:6.44.0	🌵	⌛	⌛
CommentRequired	pmd-java:6.44.0	🌵	⌛	⌛
AvoidCatchingGenericException	pmd-java:6.44.0	⌛	⌛	⌛
CouplingBetweenObjects	pmd-java:6.44.0	🌵	⌛	⌛
LawOfDemeter	pmd-java:6.44.0	❌	❌	❌
LoosePackageCoupling	pmd-java:6.44.0	⌛	⌛	⌛
SignatureDeclareThrowsException	pmd-java:6.44.0	⌛	⌛	⌛
TooManyFields	pmd-java:6.44.0	🌵	⌛	⌛
TooManyMethods	pmd-java:6.44.0	🌵	⌛	⌛
UseObjectForClearerAPI	pmd-java:6.44.0	❌	❌	❌
AtLeastOneConstructor	pmd-java:6.44.0	❌	❌	❌
UseUtilityClass	pmd-java:6.44.0	🌵	✅	⌛
ShortClassName	pmd-java:6.44.0	🌵	✅	✅
ImmutableField	pmd-java:6.44.0	🌵	✅	✅
LongVariable	pmd-java:6.44.0	🌵	✅	✅

How to use?

Maven (pom.xml)

...
<build>
 <plugins>
   ...
   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-pmd-plugin</artifactId>
     <version>3.15.0</version>
     <executions>
       <execution>
         <phase>test</phase>
         <goals>
           <goal>check</goal>
         </goals>
       </execution>
     </executions>
     <configuration>
       <printFailingErrors>true</printFailingErrors>
       <rulesets>
         ...
         <ruleset>io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml</ruleset>
         ...
       </rulesets>
       <excludeRoots>
         <excludeRoot>target/generated-sources/</excludeRoot>
       </excludeRoots>
     </configuration>
     <dependencies>
       <!-- Latest arch4u-rules -->
       <dependency>
         <groupId>io.github.dgroup</groupId>
         <artifactId>arch4u-pmd</artifactId>
         <version>${version}</version>
       </dependency>
     </dependencies>
   </plugin>
   ...
 </plugins>
</build>
 ...

Gradle (build.gradle)

apply plugin: 'pmd'

dependencies {
   ...
   pmd "io.github.dgroup:arch4u-pmd:${version}"    // use latest arch4u-pmd rules version
   pmd "commons-io:commons-io:2.11.0"              // required dependency by pmd engine
   ...
}

pmd {
   consoleOutput = true
   ruleSetFiles = files("io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml")
   ruleSets = []                                   // Keep it as is, workaround for pmd
}

Include arch4u-pmd rules into your existing custom ruleset

0. Don't forget to add rules to classpath in Maven/Gradle pmd plugin (see lines above)
1. Let's assume that you already have pmd rules defined in your-pmd-ruleset.xml
2. Add line <rule ref="io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml"/> to your-pmd-ruleset.xml

   <?xml version="1.0"?>
   <ruleset name="pmd ruleset with your rules"
     xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
    
     ...
     <rule ref="io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml"/>
     ...
   
   </ruleset>

Exclude particular rule

<?xml version="1.0"?>
<ruleset name="pmd ruleset with your rules">
  ...
  <rule ref="io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml">
    <exclude name="UseExistingMediaTypeConstant"/>
  </rule>
  ...
</ruleset>

Reconfigure a rule

<?xml version="1.0"?>
<ruleset name="pmd ruleset with your rules">
  ...
  <!-- 1. Exclude rule with default configuration  -->
  <rule ref="io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml">
    <exclude name="UseExistingMediaTypeConstant"/>
  </rule>
  <!-- 2. Reconfigure rule with expected property -->
  <rule name="UseExistingMediaTypeConstant"
        language="java"
        externalInfoUrl="https://github.com/dgroup/arch4u-pmd/discussions/43"
        message="Use existing MediaType constant instead of string literal: https://github.com/dgroup/arch4u-pmd/discussions/43"
        class="io.github.dgroup.arch4u.pmd.UseExistingConstant">
    <priority>3</priority>
    <properties>
      <!-- 3. Set the 'regexPattern' considering your needs -->
      <property name="regexPattern" description="Regular expression of prohibited string"
                value="(^|\s)(application\/(json|xml|atom\+xml|x-www-form-urlencoded|octet-stream|svg\+xml|xhtml\+xml)|(multipart\/form-data)|(text\/(html|xml|plain)))(\s|$)"/>
    </properties>
  </rule>
  ...
</ruleset>

Exclude particular folder from inspection

<?xml version="1.0"?>
<ruleset name="pmd ruleset with your rules">
  ...
  <!-- Exclude target folder that may contain generated sources -->
  <exclude-pattern>.*/target/generated-sources/.*</exclude-pattern>
  <exclude-pattern>.*/build/generated-sources/.*</exclude-pattern>
  <!-- Exclude test folder -->
  <exclude-pattern>.*/src/test/java/org/tbd/tbd/tbd/.*</exclude-pattern>
  ...
</ruleset>

How to contribute?

1. Pull requests are welcome! Don't forget to add your name to contribution section and run this, beforehand:

   mvn -Pqulice clean install

2. Everyone interacting in this project’s codebases, issue trackers, chat rooms is expected to follow the code of conduct.
3. Latest maven coordinates here:

   <dependency>
       <groupId>io.github.dgroup</groupId>
       <artifactId>arch4u-pmd</artifactId>
       <version>${version}</version>
   </dependency>

4. Download pmd rule designer
   • https://pmd.github.io/latest/pmd_userdocs_extending_designer_reference.html

Contributors

• dgroup as Yurii Dubinka ([email protected])
• dykov as Oleksii Dykov ([email protected])
• smithros as Rostyslav Koval ([email protected])