Over a million developers have joined DZone.

Enforce Software Design With Checkstyle and QDox

DZone's Guide to

Enforce Software Design With Checkstyle and QDox

To ensure maintainability, focus on your software's design. And to lend a hand, Checkstyle and QDox can make sure your code follows your constraints.

· Java Zone
Free Resource

Just released, a free O’Reilly book on Reactive Microsystems: The Evolution of Microservices at Scale. Brought to you in partnership with Lightbend.

Developers care about the code they write. They build tools that enforce spaces instead of tabs, forbid 1-letter identifiers and ensure that every class and method has Javadoc comments. One example of such a tool is Checkstyle.

But usually, it’s not code style violations that make code hard to read and maintain. More often, it is higher level code organization (software design) – all the decisions made about classes, their responsibilities, connections between them, etc.

Tools like Checkstyle surprisingly won’t help you to avoid making your view layer go directly to the database. In this post, I want to show how to implement this kind of design constraint by building a custom Checkstyle check.

Problem Definition

Let’s consider a naive example – a Spring web application where you have controllers, services, and repositories. Let’s pretend that, as the architect, you believe that controllers should only talk to services, and services should talk to repositories. You consider controllers talking directly to repositories a bad design and want to entirely forbid this:

package me.loki2302.spring;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

public class HelloController {
  private PersonRepository personRepository;

  public String hello() {
    return String.format(
      "There are %d persons in the repository", 

When you run the build, you want it to fail with a clear message saying that having a reference to PersonRepository in HelloController is a bad idea.


Checkstyle’s code analysis capabilities are quite low-level. When you build your own check, Checkstyle gives you an AST and it’s up to you to understand what it describes. While AST is one of the central concepts in compiler design, it only describes the words code consists of, not the code’s semantics.

We are interested in semantics. We don’t want to operate on AST level and instead of looking at the code, we want to look at what this code describes. QDox is a great library that reads Java code and builds a model of all packages, classes, methods and links between them. It doesn’t analyze method bodies, though (if it’s a showstopper, take a look at Spoon – a more powerful alternative to QDox).

To solve the problem, we’ll make Checkstyle and QDox work together:

  • We’ll create a SpringAppDesignCheck – a custom Checkstyle check that will connect our code analysis with Checkstyle. Its only goal is going to be CodeModel initialization and querying.
  • We’ll create a CodeModel – a service that uses QDox models to understand the code structure. Its only goal is going to be to provide a collection of DesignViolation objects for every file we validate.

SpringAppDesignCheck: A Custom Checkstyle Check

Let’s first take a look at SpringAppDesignCheck and its 2 methods: beginProcessing() and processFiltered().

The beginProcessing() method gets called once per build. This method is a good place to perform initialization. In our case, we’ll construct the JavaProjectBuilder and the CodeModel:

public class SpringAppDesignCheck extends AbstractFileSetCheck {
    public void beginProcessing(String charset) {
        JavaProjectBuilder jpb = new JavaProjectBuilder();
        codeModel = new CodeModel(jpb);

What we do is, we just load the entire codebase from the very beginning.

The second method, processFiltered(), gets called once per source file and is supposed to emit errors (if any) for this specific file. In our case, we ask codeModel object to give us all the error descriptors and then just format and log them (logging is how Checkstyle expects you to report the errors):

    protected void processFiltered(File file, List < String > lines) {
        List < DesignViolation > designViolations =
        for (DesignViolation designViolation: designViolations) {
            String message = String.format(
                "%s is a controller and references %s via field %s",
            log(designViolation.lineNumber, message);

CodeModel: A Code Analyzer Built Around QDox

Now, let’s take a look at CodeModel. Its only responsibility is to provide a collection of DesignViolation objects for a given source code file. Every DesignViolation is a descriptor of which controller class has a reference to which repository class in what field.

public class CodeModel {
    private final JavaProjectBuilder javaProjectBuilder;

    public CodeModel(JavaProjectBuilder javaProjectBuilder) {
        this.javaProjectBuilder = javaProjectBuilder;

    public List < DesignViolation > getDesignViolations(File file) {
        List < JavaClass > classes = getControllerClasses(file);

        List < DesignViolation > designViolations = new ArrayList < > ();
        for (JavaClass controllerClass: classes) {
            List < JavaField > fieldsOfTypeJpaRepository =

            List < DesignViolation > thisControllerViolations =
                .map(field - > new DesignViolation(
                    field.getLineNumber() + 1,

        return designViolations;

The algorithm is quite straightforward:

  • For every controller class
  • Get all fields of type JpaRepository
  • And for every such field record the error

How do we find all controller classes? We just look for all classes annotated with @RestController:

    private List < JavaClass > getControllerClasses(File file) {
        return javaProjectBuilder.getClasses().stream()
            .filter(c - > file.equals(getJavaClassSource(c)))

    private static boolean isRestController(JavaClass javaClass) {
        final String REST_CONTROLLER_CLASS_NAME =
        return javaClass.getAnnotations().stream()
            .map(a - > a.getType())
            .anyMatch(c - > c.isA(REST_CONTROLLER_CLASS_NAME));

How do we find all class fields of type JpaRepository? We just look for all fields of type JpaRepository:

    private List < JavaField > getJpaRepositoryFields(JavaClass javaClass) {
        final String JPA_REPOSITORY_CLASS_NAME =
        return javaClass.getFields().stream()
            .filter(f - > f.getType().isA(JPA_REPOSITORY_CLASS_NAME))

Thanks to QDox’s intuitive API, the hardest part of our solution, code analysis, looks very straightforward.


Now, if we enable our check in checkstyle.xml:

<?xml version="1.0" encoding="UTF-8"?>
<module name="Checker">
    <module name="me.loki2302.SpringAppDesignCheck">
        <property name="fileExtensions" value="java" />
        <property name="sourceRoot" value="src/main/java" />
        <property name="severity" value="error" />

The build will fail with this error:

[ant:checkstyle] [ERROR] /home/loki2302/checkstyle-experiment/
HelloController is a controller and references me.loki2302.spring.
PersonRepository via field personRepository [SpringAppDesign]

If you jump to the top of the page, you’ll see that HelloController.java line 10 is exactly where the violation is: private PersonRepository personRepository;


Software exists in time, so maintainability is one of the defining factors of software quality. Clear and logical design is a key to good maintainability. While it’s a responsibility of every developer to keep the system balanced as it evolves, some of the design validations are easy to automate and minimize the risk of the human factor.

There’s a self-sufficient demo project in this GitHub repository: Make sure to take a look.

Strategies and techniques for building scalable and resilient microservices to refactor a monolithic application step-by-step, a free O'Reilly book. Brought to you in partnership with Lightbend.

static code analysis ,checkstyle ,java ,code quality ,tutorial

Published at DZone with permission of Andrey Agibalov. See the original article here.

Opinions expressed by DZone contributors are their own.


Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.


{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}