traute

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

View the Project on GitHub

Table of Contents

1. License

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

2. Overview

Traute can be used in Ant by putting its Javac plugin’s *.jar into compiler’s classpath and specifying necessary javac options.

3. Sample

ivy.xml

<dependencies>
    <dependency org="tech.harmonysoft" name="traute-javac" rev="1.1.8"/>
    <!-- ... -->
</dependencies>

build.xml

<target name="compile">
    <ivy:cachepath pathid="lib.path.id"/>
    <javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
        <compilerarg value="-Xplugin:Traute"/>
    </javac>
</target>

A complete standalone sample project can be found here.

4. Options

Any Traute Javac Plugin setting can be provided to the Ant’s <javac> task through the <compilerarg> element.

4.1. NotNull Annotations

NotNull annotations to use are defined through the traute.annotations.not.null option (multiple annotations might be specified separated by the colon (:)):

<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
    <compilerarg value="-Xplugin:Traute"/>
    <!-- Add null-checks only for method parameters/return values marked by @my.company.NotNull -->
    <compilerarg value="-Atraute.annotations.not.null=my.company.NotNull"/>
</javac>

More details on that can be found here.

4.2. NotNullByDefault Annotations

NotNullByDefault annotations to use are defined through the traute.annotations.not.null.by.default. option prefix followed by the instrumentation type:

<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
    <compilerarg value="-Xplugin:Traute"/>
    <!-- Use my.custom.NotNullByDefault for method parameters -->
    <compilerarg value="-Atraute.annotations.not.null.by.default.parameter=my.custom.NotNullByDefault"/>
</javac>

More details on that can be found here.

4.3. Nullable Annotations

Nullable annotations to use are defined through the traute.annotations.nullable option (multiple annotations might be specified separated by :):

<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
    <compilerarg value="-Xplugin:Traute"/>
    <!-- Do not generate null-checks for method parameters/return values marked by @my.company.Nullable -->
    <compilerarg value="-Atraute.annotations.not.null=my.company.Nullable"/>
</javac>

More details on that can be found here.

4.4. Instrumentation Types

Instrumentations types to use are defined through the traute.instrumentations option:

<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
    <compilerarg value="-Xplugin:Traute"/>
    <!-- Add checks only for method parameters (do not add check for return values) -->
    <compilerarg value="-Atraute.instrumentations=parameter"/>
</javac>

More details on that can be found here.

4.5. Exception to Throw

Custom exception class to throw from failed null-checks is defined through the traute.exception. option prefix followed by the instrumentation type:

<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
    <compilerarg value="-Xplugin:Traute"/>
    <!-- Throw a IllegalArgumentException when a null is given to a method parameter marked by @NotNull -->
    <compilerarg value="-Atraute.exception.parameter=IllegalArgumentException"/>
    <!-- Throw a IllegalStateException when a null is given from a method marked by @NotNull -->
    <compilerarg value="-Atraute.exception.return=IllegalStateException"/>
</javac>

More details on that can be found here.

4.6. Exception Text

Custom exception text to use in exceptions thrown from failed null-checks is defined through the traute.failure.text. option prefix followed by the instrumentation type:

<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
    <compilerarg value="-Xplugin:Traute"/>
    <!-- Use exception message like 'MyArg must not be null' for a method parameter names 'myArg' -->
    <compilerarg value="-Atraute.failure.text.parameter=${capitalize(PARAMETER_NAME)} must not be null"/>
</javac>

More details on that can be found here.

4.7. Logging

Logging verbosity is defined through the traute.log.verbose option:

<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
    <compilerarg value="-Xplugin:Traute"/>
    <!-- Use verbose logging -->
    <compilerarg value="-Atraute.log.verbose=true"/>
</javac>

More details on that can be found here.

4.8. Log Location

Plugin’s log file is defined through the traute.log.file option:

<javac srcdir="${src.dir}" destdir="${build.dir}" classpathref="lib.path.id" debug="true">
    <compilerarg value="-Xplugin:Traute"/>
    <!-- Instruct the plugin to write its logs to the /home/me/traute.log -->
    <compilerarg value="-Atraute.log.file=/home/me/traute.log"/>
</javac>

More details on that can be found here.