Checkstyle rule for "@annotations must be on separate line"

Question

I am trying to create a rule for checkstyle, that will prevent writing inline annotations usage, like this:

@Entity MyClass someEntity;
@Foo(a="B") public void bar(Baz baz) {
}

but will not prevent thinks like that:

public void bar(@Param Baz baz) {
}

Is there any way to achieve that?

Answer 1

Most of this answer was inspired by Checkstyle's "Writing Checks" article. Most of the work is done in AnnotationSameLineCheck.

AnnotationSameLineCheck.java

This Java file was inspired by the "Visitor In Action" section of the "Writing Checks" article.

getDefaultTokens defines which parts (a.k.a. tokens) of a Java file we're interested in. Out first one might think that we'd be interested in TokenTypes.ANNOTATION, but this is not the case. We're not interested in TokenTypes.ANNOTATION because we don't want to inspect all annotations; we actually want to disregard TokenTypes.PARAMETER_DEF.

What are we interested in then? We're actually interested in those parts of a Java file that can be annotated (i.e., the class definition TokenTypes.CLASS_DEF, method definitions TokenTypes.METHOD_DEF, etc.). Conveniently, Checkstyle's API has a method that can tell us if a token is annotated. That method isAnnotationUtility.containsAnnotation, which is used in visitToken.

The algorithm used to determine if an annotation is on the same line as other parts of a Java file is as follows:

1. Determine if a particular token contains an annotation. If not, do nothing.
2. Find the annotation token.
3. Find the token before the annotation token.
4. Find the token after the annotation token.
5. If the annotation token is on the same line as the previous token, log an error.
6. If the annotation token is on the same line as the next token, log an error.

This algorithm is found in visitToken.

package example;

import com.puppycrawl.tools.checkstyle.api.AnnotationUtility;
import com.puppycrawl.tools.checkstyle.api.Check;
import com.puppycrawl.tools.checkstyle.api.DetailAST;
import com.puppycrawl.tools.checkstyle.api.TokenTypes;

public class AnnotationSameLineCheck extends Check {
    @Override
    public int[] getDefaultTokens() {
        // PACKAGE_DEF and PARAMETER_DEF were left out of the list
        return new int[] { TokenTypes.ANNOTATION_DEF, //
                TokenTypes.ANNOTATION_FIELD_DEF, //
                TokenTypes.CLASS_DEF, //
                TokenTypes.CTOR_DEF, //
                TokenTypes.ENUM_DEF, //
                TokenTypes.ENUM_CONSTANT_DEF, //
                TokenTypes.INTERFACE_DEF, //
                TokenTypes.METHOD_DEF, //
                TokenTypes.VARIABLE_DEF };
    }

    @Override
    public void visitToken(DetailAST ast) {
        if (AnnotationUtility.containsAnnotation(ast)) {
            final DetailAST holder = AnnotationUtility.getAnnotationHolder(ast);
            final DetailAST annotation = getAnnotationAst(holder);
            final DetailAST prev = getPreviousSibling(annotation, holder, ast);
            final DetailAST next = getNextSibling(annotation, holder, ast);
            if (isPreviousSiblingOnSameLine(prev, annotation) || //
                    isNextSiblingOnSameLine(annotation, next)) {
                log(annotation.getLineNo(), //
                        annotation.getColumnNo(), //
                        "Annotations must exist on their own line");
            }
        }
    }

    private static boolean isPreviousSiblingOnSameLine(DetailAST prev, DetailAST annotation) {
        if (prev == null) {
            return false;
        } else if (prev.getLastChild() == null) {
            return prev.getLineNo() == annotation.getLineNo();
        }
        return prev.getLastChild().getLineNo() == annotation.getLineNo();
    }

    private static boolean isNextSiblingOnSameLine(DetailAST annotation, DetailAST next) {
        if (next == null) {
            return false;
        }
        return annotation.getLineNo() == next.getLineNo();
    }

    private static DetailAST getAnnotationAst(DetailAST aHolderAst) {
        if (aHolderAst.getType() == TokenTypes.ANNOTATIONS) {
            return aHolderAst;
        } else if (aHolderAst.getType() == TokenTypes.MODIFIERS) {
            return aHolderAst.findFirstToken(TokenTypes.ANNOTATION);
        }
        throw new AssertionError("aHolder must be one of TokenTypes.ANNOTATIONS or TokenTypes.MODIFIERS but was " + aHolderAst);
    }

    private static DetailAST getPreviousSibling(DetailAST annotation, DetailAST holder, DetailAST ast) {
        if (annotation.getPreviousSibling() != null) {
            return annotation.getPreviousSibling();
        } else if (holder.getPreviousSibling() != null) {
            return holder.getPreviousSibling();
        }
        return ast.getPreviousSibling();
    }

    private static DetailAST getNextSibling(DetailAST annotation, DetailAST holder, DetailAST ast) {
        if (annotation.getNextSibling() != null) {
            return annotation.getNextSibling();
        } else if (holder.getNextSibling() != null) {
            return holder.getNextSibling();
        }
        return ast.getNextSibling();
    }
}

checks.xml

This XML file was inspired by the "Integrate Your Check" section of the "Writing Checks" article. It is used by Checkstyle to specify which checks to perform on a set of Java files. Note that AnnotationSameLineCheck is fully qualified (i.e., its package is specified in the name). checks.xml is mentioned in the build.xml file.

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
          "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
          "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
<module name="Checker">
    <module name="TreeWalker">
        <module name="example.AnnotationSameLineCheck"/>
    </module>
</module>

build.xml

This Ant build file was inspired by Checkstyle's "Ant Task" article. Using Ant is only one way to execute Checkstyle. Using the command line is another option.

<project default="example">
    <taskdef resource="checkstyletask.properties" classpath="target/classes:lib/checkstyle-5.5-all.jar" />
    <target name="example">
        <checkstyle config="checks.xml">
            <fileset dir="src/main/java" includes="**/AnnotatedClass.java" />
            <formatter type="plain" />
        </checkstyle>
    </target>
</project>

AnnotationClass.java

One can use the following class to test AnnotationSameLineCheck. It is mentioned in the build.xml file. Note the testing of interface, class, enum, member-variable, method, parameter, and local-variable declarations.

package example;
    @Deprecated
class CorrectClassDefA {}

@Deprecated class IncorrectClassDefA {}

abstract
@Deprecated
class CorrectClassDefB {}

abstract @SuppressWarnings(value = "unused") class IncorrectClassDefB0 {}

abstract
    @Deprecated class IncorrectClassDefB1 {}

abstract@Deprecated
class IncorrectClassDefB2 {}

@Deprecated abstract class IncorrectClassDefB3 {}

@Deprecated
abstract class CorrectClassDefB4 {}

@SuppressWarnings(value = "unused")
interface CorrectInterfaceDefA {}

@Deprecated interface IncorrectInterfaceDefA {}

abstract
@Deprecated
interface CorrectInterfaceDefB {}

abstract @Deprecated interface IncorrectInterfaceDefB0 {}

abstract
@Deprecated interface IncorrectInterfaceDefB1 {}

abstract @SuppressWarnings(value = "unused")
interface IncorrectInterfaceDefB2 {}

@SuppressWarnings(value = "unused") abstract interface IncorrectInterfaceDefB3 {}

@SuppressWarnings(value = "unused")
abstract 
interface CorrectInterfaceDefB4 {}

@Deprecated
enum CorrectEnumA {
    @SuppressWarnings(value = "unused")
    CORRECT,
    @Deprecated INCORRECT }

@Deprecated enum 
IncorrectEnumA {
@Deprecated
    CORRECT,
    @SuppressWarnings(value = "unused") INCORRECT }


public class AnnotatedClass { @Deprecated // incorrect
    public AnnotatedClass() {}

    @Deprecated
    AnnotatedClass(int correct) {}

    public
    @SuppressWarnings(value = "unused")
    AnnotatedClass(boolean correct, boolean correct0) {}

    @SuppressWarnings(value = "unused")
    AnnotatedClass(int correct, int correct0, int correct1) {}

    public @SuppressWarnings(value = "unused")
    AnnotatedClass(@Deprecated int bad, int bad0, int bad1, int bad2) {}

    @SuppressWarnings(value = "unused") AnnotatedClass(@Deprecated int bad, int bad0, int bad1, int bad2, int bad3) {}

    @Deprecated private int incorrectB;

    transient @Deprecated 
    private int incorrectC;

    transient
    @Deprecated 
    private 
    int correctD;

    private
    @SuppressWarnings(value = "unused")
    Object correctA; @SuppressWarnings(value = "dog")
     public void incorrectA(final Object baz) {
    }

    public void correctB(@SuppressWarnings(value = "dog") final Object good) {
        @Deprecated
        int correctA;

        final @Deprecated int incorrectB;

        final
        @Deprecated
        Object
        correctC;
    }

    @SuppressWarnings(value = "dog") public 
    void incorrectC(final Object bad) {
    }

    public
    @SuppressWarnings(value = "dog") void incorrectD(final Object bad) {
    }
}