/traute

Enhances java sources compilation in a way to insert null-checks into generated *.class files

Primary LanguageJavaMIT LicenseMIT

Build Status Maven Central

TL;DR

Traute is a javac plugin which makes bytecode for source code below

@NotNull
public Integer service(@NotNull Integer i) {
    return adjust(i);
}

look like if it's compiled from this:

@NotNull
public Integer service(@NotNull Integer i) {
    if (i == null) {
        throw new NullPointerException("Argument 'i' of type Integer (#0 out of 1, zero-based) is marked by @NotNull but got null for it");
    }
    Integer tmpVar1 = adjust(i);
    if (tmpVar1 == null) {
        throw new NullPointerException("Detected an attempt to return null from method MyClass.service() marked by @NotNull");
    }
    return tmpVar1;
}

Couple of notes:

  • this is default behavior, the plugin provides a number of configuration options like an ability to define exception to throw, customize its text etc
  • explicitly marking all target method parameters/return types by @NotNull might be tedious, so, the plugin can be configured to consider them to be not-null by default - see the NotNullByDefault and Nullable

Table of Contents

1. License

See the LICENSE file for license rights and limitations (MIT).

2. Rationale

Null references are considered to be one of the most expensive mistakes in IT design. It's not surprising that there are numerous efforts to solve it. Here are a couple of examples from the Java world:

  • Kotlin fights them at the language level

  • many tools try to report it as early as possible, for example, here IntelliJ IDEA warns us about a possible NPE:

  • production code often looks like below:

    import static com.google.common.base.Preconditions.checkNotNull;

...

public void service(Input input) {
  checkNotNull(input, "'input' argument must not be null");
  // Process the input
}

Kotlin really solves the problem but Java is still a very popular language, so, we have to deal with nullable values. Current tool allows to automate such 'enforce nullability contract' checks generation.

3. Alternatives

I found the only alternative which provides similar functionality - Project Lombok. Here are pros and cons for using it:

  • only lombok.NonNull annotation is supported - there might be problems with IDE highlighting possible NPEs in source code
  • the feature is implemented through a custom Annotaton Processing Tool, which means that there are two set of *.class files after the compilation - one from original code and another one with the tool-added instrumentations. Compiler plugin-based approach is more natural for such task as it's completely transparent for the further assembly construction
  • Lombok doesn't support NotNullByDefault
  • a solution offered by the current project works only for the javac8, Lombok might operate with javac6 and javac7 (as APT API is available starting from java6, however, I have not verified that)
  • Lombok is more mature and popular at the moment

4. Name Choice

I really like German - how it sounds, language rules, everything, so, wanted to use a german word.

Traute sounds nice and has a good meaning - Trust. Users trust the tool and the tool enforces trust in application 😉

5. Usage

5.1. Command Line

The core functionality is a Javac plugin which adds null-checks into the generated *.class files. It's possible to use the plugin directly from a command line, however, there are a number of adapters for popular build systems

5.2. Gradle

There is a dedicated Traute plugin for the Gradle build system

5.3. Maven

This page contains instructions on how to use Traute from Maven

5.4. Ant

This page contains instructions on how to use Traute from Ant

6. Releases

Release Notes

Javac Plugin

Gradle Plugin

You can also subscribe for the new versions notification through twitter and facebook.

7. How to Contribute

8. Contributors

9. Evolution

As the project is basically a Javac plugin and convenient build system-specific adapters to it, new features should be added to the core part. Please check the corresponding chapter.

10. Feedback

Please use any of the channels below to provide your feedback, it's really valuable for me:

11. Acknowledgments

JetBrains helps open source projects by offering free licenses to their awesome products.

yourkit

YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of YourKit Java Profiler and YourKit .NET Profiler, innovative and intelligent tools for profiling Java and .NET applications.

jprofiler

EJ Technologies supports open source projects by offering a JProfiler Java profiler license.