com.puppycrawl.tools.checkstyle.checks.annotation

Class AnnotationUseStyleCheck

java.lang.Object

com.puppycrawl.tools.checkstyle.api.AutomaticBean

com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

com.puppycrawl.tools.checkstyle.api.Check

com.puppycrawl.tools.checkstyle.checks.annotation.AnnotationUseStyleCheck

All Implemented Interfaces:

Configurable, Contextualizable

public final class AnnotationUseStyleCheck
extends Check

This check controls the style with the usage of annotations.

Annotations have three element styles starting with the least verbose.

• COMPACT_NO_ARRAY
• COMPACT
• EXPANDED

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 valuess.

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 ClosingParans 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, sections 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>
 

Author:

Travis Schneeberger

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AnnotationUseStyleCheck.ClosingParens Defines the two styles for defining elements in an annotation.
static class	AnnotationUseStyleCheck.ElementStyle Defines the styles for defining elements in an annotation.
static class	AnnotationUseStyleCheck.TrailingArrayComma Defines the two styles for defining elements in an annotation.

Field Summary

Fields

Modifier and Type	Field and Description
static String	MSG_KEY_ANNOTATION_INCORRECT_STYLE A key is pointing to the warning message text in "messages.properties" file.
static String	MSG_KEY_ANNOTATION_PARENS_MISSING A key is pointing to the warning message text in "messages.properties" file.
static String	MSG_KEY_ANNOTATION_PARENS_PRESENT A key is pointing to the warning message text in "messages.properties" file.
static String	MSG_KEY_ANNOTATION_TRAILING_COMMA_MISSING A key is pointing to the warning message text in "messages.properties" file.
static String	MSG_KEY_ANNOTATION_TRAILING_COMMA_PRESENT A key is pointing to the warning message text in "messages.properties" file.

Constructor Summary

Constructors

Constructor and Description
AnnotationUseStyleCheck()

Method Summary

Methods

Modifier and Type	Method and Description
int[]	getAcceptableTokens() The configurable token set.
int[]	getDefaultTokens() Returns the default token a check is interested in.
int[]	getRequiredTokens() The tokens that this check must be registered for.
void	setClosingParens(String parens) Sets the ClosingParens from a string.
void	setElementStyle(String style) Sets the ElementStyle from a string.
void	setTrailingArrayComma(String comma) Sets the TrailingArrayComma from a string.
void	visitToken(DetailAST ast) Called to process a token.

Methods inherited from class com.puppycrawl.tools.checkstyle.api.Check

beginTree, destroy, finishTree, getClassLoader, getFileContents, getLine, getLines, getTabWidth, getTokenNames, init, isCommentNodesRequired, leaveToken, log, log, setClassLoader, setFileContents, setMessages, setTabWidth, setTokens

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, log, setId, setSeverity

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

configure, contextualize, finishLocalSetup, getConfiguration, setupChild

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MSG_KEY_ANNOTATION_INCORRECT_STYLE

public static final 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 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 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 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 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

Constructor Detail

AnnotationUseStyleCheck

public AnnotationUseStyleCheck()

Method Detail

setElementStyle

public void setElementStyle(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(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(String parens)

Sets the ClosingParens from a string.

Parameters:

parens - string representation

Throws:

org.apache.commons.beanutils.ConversionException - if cannot convert string.

getDefaultTokens

public int[] getDefaultTokens()

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 Check

Returns:

the default tokens

See Also:

TokenTypes

getRequiredTokens

public int[] getRequiredTokens()

The tokens that this check must be registered for.

Overrides:

getRequiredTokens in class Check

Returns:

the token set this must be registered for.

See Also:

TokenTypes

getAcceptableTokens

public int[] getAcceptableTokens()

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.

Overrides:

getAcceptableTokens in class Check

Returns:

the token set this check is designed for.

See Also:

TokenTypes

visitToken

public void visitToken(DetailAST ast)

Called to process a token.

Overrides:

visitToken in class Check

Parameters:

ast - the token to process