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

Class AnnotationUseStyleCheck

java.lang.Object

com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

com.puppycrawl.tools.checkstyle.api.AbstractCheck

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

All Implemented Interfaces:

Configurable, Contextualizable

public final class AnnotationUseStyleCheck
extends AbstractCheck

Checks the style of elements in annotations.

Annotations have three element styles starting with the least verbose.

• ElementStyleOption.COMPACT_NO_ARRAY
• ElementStyleOption.COMPACT
• ElementStyleOption.EXPANDED

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

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

Using the ElementStyleOption.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 ElementStyleOption.COMPACT_NO_ARRAY style is less verbose. It is similar to the ElementStyleOption.COMPACT style but single value arrays are flagged. With annotations a single value array does not need to be placed in an array initializer.

The ending parenthesis are optional when using annotations with no elements. To always require ending parenthesis use the ClosingParensOption.ALWAYS type. To never have ending parenthesis use the ClosingParensOption.NEVER type. To not enforce a closing parenthesis preference a ClosingParensOption.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 TrailingArrayCommaOption.ALWAYS type. To never have a trailing comma use the TrailingArrayCommaOption.NEVER type. To not enforce a trailing array comma preference a TrailingArrayCommaOption.IGNORE type is provided. Set this through the trailingArrayComma property.

By default, the ElementStyleOption is set to COMPACT_NO_ARRAY, the TrailingArrayCommaOption is set to NEVER, and the ClosingParensOption is set to NEVER.

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.

• Property closingParens - Define the policy for ending parenthesis. Type is com.puppycrawl.tools.checkstyle.checks.annotation.AnnotationUseStyleCheck$ClosingParensOption. Default value is never.
• Property elementStyle - Define the annotation element styles. Type is com.puppycrawl.tools.checkstyle.checks.annotation.AnnotationUseStyleCheck$ElementStyleOption. Default value is compact_no_array.
• Property trailingArrayComma - Define the policy for trailing comma in arrays. Type is com.puppycrawl.tools.checkstyle.checks.annotation.AnnotationUseStyleCheck$TrailingArrayCommaOption. Default value is never.

Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Violation Message Keys:

• annotation.incorrect.style
• annotation.parens.missing
• annotation.parens.present
• annotation.trailing.comma.missing
• annotation.trailing.comma.present

Since:

5.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AnnotationUseStyleCheck.ClosingParensOption	Defines the two styles for defining elements in an annotation.
static class	AnnotationUseStyleCheck.ElementStyleOption	Defines the styles for defining elements in an annotation.
static class	AnnotationUseStyleCheck.TrailingArrayCommaOption	Defines the two styles for defining elements in an annotation.

Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

AbstractAutomaticBean.OutputStreamOptions

Field Summary

Fields

Modifier and Type	Field	Description
private static String	ANNOTATION_ELEMENT_SINGLE_NAME	The element name used to receive special linguistic support for annotation use.
private AnnotationUseStyleCheck.ClosingParensOption	closingParens	Define the policy for ending parenthesis.
private AnnotationUseStyleCheck.ElementStyleOption	elementStyle	Define the annotation element styles.
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.
private AnnotationUseStyleCheck.TrailingArrayCommaOption	trailingArrayComma	Define the policy for trailing comma in arrays.

Constructor Summary

Constructors

Constructor	Description
AnnotationUseStyleCheck()

Method Summary

Modifier and Type	Method	Description
private void	checkCheckClosingParensOption(DetailAST ast)	Checks to see if the closing parenthesis are present if required or prohibited.
private void	checkCompactNoArrayStyle(DetailAST annotation)	Checks for compact no array style type violations.
private void	checkCompactStyle(DetailAST annotation)	Checks for compact style type violations.
private void	checkExpandedStyle(DetailAST annotation)	Checks for expanded style type violations.
private void	checkStyleType(DetailAST annotation)	Checks to see if the AnnotationElementStyleOption is correct.
private void	checkTrailingComma(DetailAST annotation)	Checks to see if the trailing comma is present if required or prohibited.
int[]	getAcceptableTokens()	The configurable token set.
int[]	getDefaultTokens()	Returns the default token a check is interested in.
private static <T extends Enum<T>> T	getOption(Class<T> enumClass, String value)	Retrieves an Enum type from a @{link String String}.
int[]	getRequiredTokens()	The tokens that this check must be registered for.
private static boolean	hasArguments(DetailAST annotation)	Checks that annotation has arguments.
private void	logCommaViolation(DetailAST ast)	Logs a trailing array comma violation if one exists.
void	setClosingParens(String parens)	Setter to define the policy for ending parenthesis.
void	setElementStyle(String style)	Setter to define the annotation element styles.
void	setTrailingArrayComma(String comma)	Setter to define the policy for trailing comma in arrays.
void	visitToken(DetailAST ast)	Called to process a token.

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

beginTree, clearViolations, destroy, finishTree, getFileContents, getFilePath, getLine, getLineCodePoints, getLines, getTabWidth, getTokenNames, getViolations, init, isCommentNodesRequired, leaveToken, log, log, log, setFileContents, setTabWidth, setTokens

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

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

Methods inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

configure, contextualize, 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

ANNOTATION_ELEMENT_SINGLE_NAME

private static final String ANNOTATION_ELEMENT_SINGLE_NAME

The element name used to receive special linguistic support for annotation use.

See Also:

Constant Field Values

elementStyle

private AnnotationUseStyleCheck.ElementStyleOption elementStyle

Define the annotation element styles.

trailingArrayComma

private AnnotationUseStyleCheck.TrailingArrayCommaOption trailingArrayComma

Define the policy for trailing comma in arrays.

closingParens

private AnnotationUseStyleCheck.ClosingParensOption closingParens

Define the policy for ending parenthesis.

Constructor Detail

AnnotationUseStyleCheck

public AnnotationUseStyleCheck()

Method Detail

setElementStyle

public void setElementStyle(String style)

Setter to define the annotation element styles.

Parameters:

style - string representation

Since:

5.0

setTrailingArrayComma

public void setTrailingArrayComma(String comma)

Setter to define the policy for trailing comma in arrays.

Parameters:

comma - string representation

Since:

5.0

setClosingParens

public void setClosingParens(String parens)

Setter to define the policy for ending parenthesis.

Parameters:

parens - string representation

Since:

5.0

getOption

private static <T extends Enum<T>> T getOption(Class<T> enumClass,
                                               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

Throws:

IllegalArgumentException - when unable to parse value

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

visitToken

public void visitToken(DetailAST ast)

Description copied from class: AbstractCheck

Called to process a token.

Overrides:

visitToken in class AbstractCheck

Parameters:

ast - the token to process

checkStyleType

private void checkStyleType(DetailAST annotation)

Checks to see if the AnnotationElementStyleOption is correct.

Parameters:

annotation - the annotation token

checkExpandedStyle

private void checkExpandedStyle(DetailAST annotation)

Checks for expanded style type violations.

Parameters:

annotation - the annotation token

hasArguments

private static boolean hasArguments(DetailAST annotation)

Checks that annotation has arguments.

Parameters:

annotation - to check

Returns:

true if annotation has arguments, false otherwise

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.

checkCheckClosingParensOption

private void checkCheckClosingParensOption(DetailAST ast)

Checks to see if the closing parenthesis are present if required or prohibited.

Parameters:

ast - the annotation token