Table of Contents

• 1. License
• 2. Overview
• 3. Sample
• 4. Options
  • 4.1. NotNull Annotations
  • 4.2. NotNullByDefault Annotations
  • 4.3. Nullable Annotations
  • 4.4. Instrumentations Types
  • 4.5. Exception to Throw
  • 4.6. Exception Text
  • 4.7. Logging
  • 4.8. Log Location

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.10"/>
    <!-- ... -->
</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.