traute

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

View the Project on GitHub harmonysoft-tech/traute

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:

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 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:

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 :wink:

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.