Setup

Setup

I’m assuming you have the following ready.

• Java 8
• Maven
• a text editor or IDE you’re comfortable with

I’m running the command-line commands in a Unix-like environment – give or take some minor adjustments this tutorial should also work on Windows.

Get the code

Clone this repository and check out the initial commit. I have tagged it as initial.

git clone https://github.com/glts/safer-spring-petclinic.git
git checkout initial

This is our codebase. Now is a good time to check if we’re starting out all green. Before we do, let’s make a first commit e7ab16a and upgrade to Java 8.

In the project root, run the install Maven goal to see if the build is fine. (This compiles the production and test source, runs the tests, bundles up the WAR artefact, and installs it in the local Maven repository.)

mvn install

This can take quite a while the first time, because all the project’s dependencies need to be downloaded. At some point you should see the ‘BUILD SUCCESS’ message.

Then start the web server:

mvn tomcat7:run

Open a browser at http://localhost:9966/petclinic/. This is the Pet Clinic.

You can browse around a little to get familiar with the app. (‘Franklin’ is a name you can enter on the ‘Find Owners’ page.) Hit Control-C to stop the web server when you’re done.

JSR 305 annotations

The annotations @Nullable and @NonNull are provided by the Checker Framework in the package org.checkerframework.checker.nullness.qual. However, I am going to use the equivalent annotations from the JSR 305 effort. JSR 305, ‘Annotations for Software Defect Detection’, was an attempt to standardise annotations like @Nullable. Unfortunately, this effort fizzled out. Still, it is the closest thing to a standard that we have today. (The official repository is at https://code.google.com/p/jsr-305/.)

The JSR 305 annotations have a nicer package name (javax.annotation) than the ones from the Checker Framework, but bear in my mind that they are less powerful. Only the Checker Framework annotations can be applied to the use of a type. The following, ‘a non-null List of nullable Strings’ cannot be expressed with the JSR 305 annotations.

private @NonNull List<@Nullable String> list;

Anyway, I’m adding the relevant JAR in the <dependencies> section in the POM in my second commit 7d039ae. If you use the Checker Framework annotations substitute the appropriate dependency instead:

<dependency>
  <groupId>org.checkerframework</groupId>
  <artifactId>checker-qual</artifactId>
  <version>1.9.8</version>
</dependency>

The checker profile

The next step is to integrate the Checker Framework into our build, and activate the Nullness Checker.

I think it is best to keep this stuff separate from the original build, so I will create a separate Maven profile for compiling with the Checker Framework.

Keeping the Checker Framework compilation separate makes sense for a number of reasons. First, the class files that the compiler produces when an annotation processor like the Nullness Checker is attached are different from the class files output without annotation processing. This may not be an issue depending on your situation – but with annotation-heavy frameworks like Spring and Hibernate there is a risk of unwanted interaction. Second, annotation processing slows the build down.

Here is the checker profile. You can see in my third commit 71fe129 that I’ve added it at the bottom of the Maven POM, right above the final <url> tag.

<profiles>
  <profile>
    <id>checker</id>
    <dependencies>
      <dependency>
        <groupId>org.checkerframework</groupId>
        <artifactId>checker</artifactId>
        <version>1.9.8</version>
        <scope>provided</scope>
      </dependency>
      <dependency>
        <groupId>org.checkerframework</groupId>
        <artifactId>jdk8</artifactId>
        <version>1.9.8</version>
        <scope>provided</scope>
      </dependency>
    </dependencies>
    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-dependency-plugin</artifactId>
          <executions>
            <execution>
              <goals>
                <goal>properties</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.3</version>
          <configuration>
            <source>${java.version}</source>
            <target>${java.version}</target>
            <annotationProcessors>
              <annotationProcessor>org.checkerframework.checker.nullness.NullnessChecker</annotationProcessor>
            </annotationProcessors>
            <compilerArgs>
              <arg>-Xbootclasspath/p:${org.checkerframework:jdk8:jar}</arg>
            </compilerArgs>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

All this does is define a new profile checker, add two Checker Framework dependencies, and activate the NullnessChecker annotation processor during compilation.

The dependencies are declared with provided scope, meaning that they won’t be bundled with the final WAR artefact. We want to use them during compilation only.

The Checker Framework comes with an annotated JDK 8, and we’re putting it on the classpath for the annotation processor. The annotated JDK contains the method signatures in the JDK, annotated as appropriate with @Nullable and @NonNull. The annotated JDK isn’t strictly necessary but it does help reduce false positives.

With that set up, the checker profile is ready and can be activated with the -P flag.

Kick off the build with mvn -Pchecker compile and turn the page.