Package com.puppycrawl.tools.checkstyle.checks.annotation

Class AnnotationUseStyleCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable
    public final class AnnotationUseStyleCheck
extends AbstractCheck
    This check controls the style with the usage of annotations.

    Annotations have three element styles starting with the least verbose.

    To not enforce an element style a IGNORE type is provided. The desired style can be set through the elementStyle property.

    Using the EXPANDED style is more verbose. The expanded version is sometimes referred to as "named parameters" in other languages.

    Using the COMPACT style is less verbose. This style can only be used when there is an element called 'value' which is either the sole element or all other elements have default values.

    Using the COMPACT_NO_ARRAY style is less verbose. It is similar to the COMPACT style but single value arrays are flagged. With annotations a single value array does not need to be placed in an array initializer. This style can only be used when there is an element called 'value' which is either the sole element or all other elements have default values.

    The ending parenthesis are optional when using annotations with no elements. To always require ending parenthesis use the ALWAYS type. To never have ending parenthesis use the NEVER type. To not enforce a closing parenthesis preference a IGNORE type is provided. Set this through the closingParens property.

    Annotations also allow you to specify arrays of elements in a standard format. As with normal arrays, a trailing comma is optional. To always require a trailing comma use the ALWAYS type. To never have a trailing comma use the NEVER type. To not enforce a trailing array comma preference a IGNORE type is provided. Set this through the trailingArrayComma property.

    By default the ElementStyle is set to EXPANDED, the TrailingArrayComma is set to NEVER, and the ClosingParens is set to ALWAYS.

    According to the JLS, it is legal to include a trailing comma in arrays used in annotations but Sun's Java 5 & 6 compilers will not compile with this syntax. This may in be a bug in Sun's compilers since eclipse 3.4's built-in compiler does allow this syntax as defined in the JLS. Note: this was tested with compilers included with JDK versions 1.5.0.17 and 1.6.0.11 and the compiler included with eclipse 3.4.1.

    See Java Language specification, §9.7.

    An example shown below is set to enforce an EXPANDED style, with a trailing array comma set to NEVER and always including the closing parenthesis. 

     <module name="AnnotationUseStyle">
    <property name="ElementStyle"
        value="EXPANDED"/>
    <property name="TrailingArrayComma"
        value="NEVER"/>
    <property name="ClosingParens"
        value="ALWAYS"/>
 </module>

    • Field Detail

      • MSG_KEY_ANNOTATION_INCORRECT_STYLE

        public static final java.lang.String MSG_KEY_ANNOTATION_INCORRECT_STYLE
        A key is pointing to the warning message text in "messages.properties" file.
        See Also:
        Constant Field Values

      • MSG_KEY_ANNOTATION_PARENS_MISSING

        public static final java.lang.String MSG_KEY_ANNOTATION_PARENS_MISSING
        A key is pointing to the warning message text in "messages.properties" file.
        See Also:
        Constant Field Values

      • MSG_KEY_ANNOTATION_PARENS_PRESENT

        public static final java.lang.String MSG_KEY_ANNOTATION_PARENS_PRESENT
        A key is pointing to the warning message text in "messages.properties" file.
        See Also:
        Constant Field Values

      • MSG_KEY_ANNOTATION_TRAILING_COMMA_MISSING

        public static final java.lang.String MSG_KEY_ANNOTATION_TRAILING_COMMA_MISSING
        A key is pointing to the warning message text in "messages.properties" file.
        See Also:
        Constant Field Values

      • MSG_KEY_ANNOTATION_TRAILING_COMMA_PRESENT

        public static final java.lang.String MSG_KEY_ANNOTATION_TRAILING_COMMA_PRESENT
        A key is pointing to the warning message text in "messages.properties" file.
        See Also:
        Constant Field Values

      • ANNOTATION_ELEMENT_SINGLE_NAME

        private static final java.lang.String ANNOTATION_ELEMENT_SINGLE_NAME
        The element name used to receive special linguistic support for annotation use.
        See Also:
        Constant Field Values

    • Constructor Detail

      • AnnotationUseStyleCheck

        public AnnotationUseStyleCheck()

    • Method Detail

      • setElementStyle

        public void setElementStyle​(java.lang.String style)
        Sets the ElementStyle from a string.
        Parameters:
        style - string representation
        Throws:
        org.apache.commons.beanutils.ConversionException - if cannot convert string.

      • setTrailingArrayComma

        public void setTrailingArrayComma​(java.lang.String comma)
        Sets the TrailingArrayComma from a string.
        Parameters:
        comma - string representation
        Throws:
        org.apache.commons.beanutils.ConversionException - if cannot convert string.

      • setClosingParens

        public void setClosingParens​(java.lang.String parens)
        Sets the ClosingParens from a string.
        Parameters:
        parens - string representation
        Throws:
        org.apache.commons.beanutils.ConversionException - if cannot convert string.

      • getOption

        private static <T extends java.lang.Enum<T>> T getOption​(java.lang.Class<T> enumClass,
                                                         java.lang.String value)
        Retrieves an Enum type from a @{link String String}.
        Type Parameters:
        T - the enum type
        Parameters:
        enumClass - the enum class
        value - the string representing the enum
        Returns:
        the enum type

      • getDefaultTokens

        public int[] getDefaultTokens()
        Description copied from class: AbstractCheck
        Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.
        Specified by:
        getDefaultTokens in class AbstractCheck
        Returns:
        the default tokens
        See Also:
        TokenTypes

      • getRequiredTokens

        public int[] getRequiredTokens()
        Description copied from class: AbstractCheck
        The tokens that this check must be registered for.
        Specified by:
        getRequiredTokens in class AbstractCheck
        Returns:
        the token set this must be registered for.
        See Also:
        TokenTypes

      • getAcceptableTokens

        public int[] getAcceptableTokens()
        Description copied from class: AbstractCheck
        The configurable token set. Used to protect Checks against malicious users who specify an unacceptable token set in the configuration file. The default implementation returns the check's default tokens.
        Specified by:
        getAcceptableTokens in class AbstractCheck
        Returns:
        the token set this check is designed for.
        See Also:
        TokenTypes

      • checkStyleType

        private void checkStyleType​(DetailAST annotation)
        Checks to see if the AnnotationElementStyle is correct.
        Parameters:
        annotation - the annotation token

      • checkExpandedStyle

        private void checkExpandedStyle​(DetailAST annotation)
        Checks for expanded style type violations.
        Parameters:
        annotation - the annotation token

      • checkCompactStyle

        private void checkCompactStyle​(DetailAST annotation)
        Checks for compact style type violations.
        Parameters:
        annotation - the annotation token

      • checkCompactNoArrayStyle

        private void checkCompactNoArrayStyle​(DetailAST annotation)
        Checks for compact no array style type violations.
        Parameters:
        annotation - the annotation token

      • checkTrailingComma

        private void checkTrailingComma​(DetailAST annotation)
        Checks to see if the trailing comma is present if required or prohibited.
        Parameters:
        annotation - the annotation token

      • logCommaViolation

        private void logCommaViolation​(DetailAST ast)
        Logs a trailing array comma violation if one exists.
        Parameters:
        ast - the array init ANNOTATION_ARRAY_INIT.

      • checkCheckClosingParens

        private void checkCheckClosingParens​(DetailAST ast)
        Checks to see if the closing parenthesis are present if required or prohibited.
        Parameters:
        ast - the annotation token