Maintaining Architectural Integrity

One of my first articles was about clean architecture (with an accompanying GitHub repo), and the sample application contained the following architectural diagram:

As you can see, in the above diagram, the web module communicates with the core module via the adapter. This effectively means that there is an architectural constraint where the web module should never be allowed to directly access the core.

Another constraint is that the configuration module can access any other module, but not the other way round (avoiding circular dependency). This particular constraint is taken care of by using modules, as no other module has the configuration module as a dependency. However, if your entire application was within a single module, then this constraint could be easily violated.

Violating Architectural Constraints

Due to transitive dependencies (web module includes the adapter and the adapter module includes the core) the web module can access core module classes, which is not what we want.

We can show this by creating a new class (called ViolatingClass) in the web module and creating a Customer (domain object in the core module) variable, and there would be no issue, thus quite easily violating the integrity of our chosen architecture.

package com.example.clean.app.web.controller;

import com.example.clean.app.core.domain.Customer;

public class ViolatingClass {
    // This should not be allowed as it violates our architecture,
    // where the web module should not be allowed to access the core,
    // but it is allowed due to transitive dependencies.
    private Customer customer;
}

Maintaining Integrity

One approach to preventing architectural violations is to use Checkstyle’s import-control to specify what is allowed or disallowed.

Creating Your Checkstyle Files

• Create a checkstyle folder at the root level of your project.

• Create a checkstyle.xml like below

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
        "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
        "http://checkstyle.sourceforge.net/dtds/configuration_1_3.dtd">

<module name="Checker">
    <module name="TreeWalker">
        <module name="ImportControl">
            <property name="file" value="checkstyle/import-control.xml"/>
        </module>
    </module>
</module>

• Create an import-control.xml like below

<?xml version="1.0"?>
<!DOCTYPE import-control PUBLIC
        "-//Puppy Crawl//DTD Import Control 1.4//EN"
        "http://checkstyle.sourceforge.net/dtds/import_control_1_4.dtd">

<import-control pkg="com.example.clean.app">
    <allow pkg=".*" regex="true"/>

    <subpackage name="adapter">
        <allow pkg=".*" regex="true"/>
        <disallow pkg="com.example.clean.app.configuration"/>
        <disallow pkg="com.example.clean.app.web"/>
    </subpackage>

    <subpackage name="configuration">
        <allow pkg=".*" regex="true"/>
    </subpackage>

    <subpackage name="core">
        <allow pkg=".*" regex="true"/>
        <disallow pkg="com.example.clean.app.adapter"/>
        <disallow pkg="com.example.clean.app.configuration"/>
        <disallow pkg="com.example.clean.app.data"/>
        <disallow pkg="com.example.clean.app.web"/>
    </subpackage>

    <subpackage name="data">
        <allow pkg=".*" regex="true"/>
        <disallow pkg="com.example.clean.app.configuration"/>
        <disallow pkg="com.example.clean.app.web"/>
    </subpackage>

    <subpackage name="web">
        <allow pkg=".*" regex="true"/>
        <disallow pkg="com.example.clean.app.configuration"/>
        <disallow pkg="com.example.clean.app.core"/>
    </subpackage>
</import-control>

So, what is happening here?

1. Line 6 specifies the starting package com.example.clean.app.

2. Line 7 allows everything before we start going through sub packages and limiting access.

3. Line 9 specifies the rules for the adapter module which allows access to everything except the configuration and web module.

4. Line 15 specifies the rules for the configuration module which is allowed access to everything.

5. Line 19 specifies the rules for the core module which is not allowed to access any other module as the intention is for other modules to depend on it.

6. Line 27 specifies the rules for the data module which allows access to everything except the configuration and web module.

7. Line 33 specifies the rules for the web module which allows access to everything except the configuration and core module.

Running Checkstyle via Gradle

To check that we now get an error (as our new ViolatingClass in the web module should not be allowed to access a core module class) when we try to build, we need to tell Gradle to run our checkstyle.

• First, apply the checkstyle plugin

apply plugin: 'checkstyle'

• Configure the checkstyle plugin

checkstyle {   
    configFile = new File("$rootDir/checkstyle/checkstyle.xml")   
    ignoreFailures = false   
    sourceSets = [sourceSets.main]
}

You can see this configuration in the accompanying Github repo in the build.gradle file.

Now build the project by running gradle clean build and  it should fail (specifying the path to the checkstyle html report) like below.

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':application:periphery:web:checkstyleMain'.
> Checkstyle rule violations were found. See the report at: ...

We now have a means of maintaining architectural integrity as part of our build process.

Checkstyle Inside an IDE

We can get feedback about violations even quicker by incorporating checkstyle into our IDE.

For IntelliJ:

1. Add the Checkstyle-IDEA plugin

2. Go to Settings > Other Settings > Checkstyle, add the checkstyle.xml file in your local workspace as a configuration file and enable it by ticking the checkbox.

3. Now go to ViolatingClass and you should see that the import statement is marked as red like below (if it's not you may have to change the Checkstyle version in IntelliJ to 8.8 in Settings > Other Settings > Checkstyle)

Pros and Cons of Using Checkstyle

Pros:

• Get immediate feedback in your IDE.

• Catch violations during your projects build step (e.g. during CI/CD in a pipeline).

• You can use regular expressions to reduce the amount of xml you have to write.

Cons

• In IntelliJ, I have to set the Checkstyle version to 8.8 for the IDE to recognise that there has been an import violation.

• Doesn’t catch violations if you use the entire package name when defining the variable (you are effectively avoiding importing the class). For example, if your ViolatingClass looked like below:

package com.example.clean.app.web.controller;

public class ViolatingClass {    
  private com.example.clean.app.core.domain.Customer customer;
}