Content

Overview

Checkstyle is configured using properties, which are string representations. This document describes how these string representations are mapped to typed properties.

boolean

This type represents a boolean. The following string representations will map to true:

  • yes
  • true
  • on

Anything else will map to false.

byte

This type represents a byte. The string representation is parsed using the java.lang.Byte class.

byte[]

This type represents a set of bytes. The string representation is parsed as a set of comma (',') separated bytes that are parsed using the java.lang.Byte class.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated byte values.

char

This type represents a char. The string representation is parsed using the java.lang.Character class.

char[]

This type represents a set of chars. The string representation is parsed as a set of comma (',') separated chars that are parsed using the java.lang.Character class.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated char values.

double

This type represents a double. The string representation is parsed using the java.lang.Double class.

double[]

This type represents a set of doubles. The string representation is parsed as a set of comma (',') separated doubles that are parsed using the java.lang.Double class.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated integers. For example, the following:

<property name="tokens" value="0.42,0.666"/>
      

can instead be expressed as:

<property name="tokens" value="0.42"/>
<property name="tokens" value="0.666"/>
      

float

This type represents a float. The string representation is parsed using the java.lang.Float class.

float[]

This type represents a set of floats. The string representation is parsed as a set of comma (',') separated floats that are parsed using the java.lang.Float class.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated float values.

int

This type represents an integer. The string representation is parsed using the java.lang.Integer class.

int[]

This type represents a set of integers. The string representation is parsed as a set of comma (',') separated integers that are parsed using the java.lang.Integer class.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated integers. For example, the following:

<property name="tokens" value="42,666"/>
      

can instead be expressed as:

<property name="tokens" value="42"/>
<property name="tokens" value="666"/>
      

long

This type represents a long. The string representation is parsed using the java.lang.Long class.

long[]

This type represents a set of longs. The string representation is parsed as a set of comma (',') separated longs that are parsed using the java.lang.Long class.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated long values.

short

This type represents a short. The string representation is parsed using the java.lang.Short class.

short[]

This type represents a set of shorts. The string representation is parsed as a set of comma (',') separated shorts that are parsed using the java.lang.Short class.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated short values.

AccessModifierOption[]

This type represents Java access modifiers.

  • public
  • protected
  • package
  • private

BlockOption

This type represents the policy for checking block statements. The following table describes the valid options:

Option Definition
text Require that there is some text in the block. For example:
    catch (Exception ex) {
        // This is a bad coding practice
    }
                
statement Require that there is a statement in the block. For example:
    finally {
        lock.release();
    }
                

ClosingParensOption

This type represents the policy for the styles for the ending parenthesis. The following table describes the valid options:

Option Definition
always Example:
@Deprecated()
never Example:
@Deprecated
ignore Anything goes.

ElementStyleOption

This type represents the policy for the styles for defining elements in an annotation. The following table describes the valid options:

Option Definition
expanded The expanded version is sometimes referred to as "named parameters" in other languages. Example:
@SuppressWarnings(value={"unchecked","unused",})
Example of violation:
@SuppressWarnings({"unchecked","unused",})
compact 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. Example:
                @SuppressWarnings({"unchecked","unused",})
                @SuppressWarnings("unchecked")
                
Example of violation:
                @SuppressWarnings(value = {"unchecked","unused",})
                @SuppressWarnings(value = "unchecked")
                
compact_no_array 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. Example:
              @SuppressWarnings("unchecked")
              @MyAnnotation(someArray = "some value")
                
Example of violation:
              @SuppressWarnings({"unchecked"})
              @MyAnnotation(someArray = {"some value"})
                
ignore Anything goes.

File

This type represents a local file. Unlike the uri type, which implies read only and not modifiable access to the resource, a property of this type indicates files whose contents can be modified by Checkstyle.

ImportOrderOption

This type represents the policy for checking imports order. The following table describes the valid options:

Option Definition
top All static imports are at the top. Groups for static import are defined by the property 'staticGroups'. The blank line between groups is driven by the property 'separatedStaticGroups'. For example:
    import static a.b.C.*;
    import static x.y.Z.*;

    import a.b.D;
    import x.y.Z;
above All static imports are above the local group. For example:
    import static a.b.C.*;
    import a.b.D;

    import static x.y.Z.*;
    import x.y.Z;
inflow All static imports are processed like non static imports. For example:
    import static a.b.C.*;
    import a.b.D;

    import x.y.Z;
    import static x.y.Z.*;
under All static imports are under the local group. For example:
    import a.b.D;
    import static a.b.C.*;

    import x.y.Z;
    import static x.y.Z.*;
bottom All static imports are at the bottom. Groups for static import are defined by the property 'staticGroups'. The blank line between groups is driven by the property 'separatedStaticGroups'. For example:
    import a.b.D;
    import x.y.Z;

    import static a.b.C.*;
    import static x.y.Z.*;

JavadocContentLocationOption

This type represents policy on placement of the Javadoc content. The following table describes the valid options:

Option Definition
FIRST_LINE Represents the policy for Javadoc content starts from the same line as /**. Example:
            /** Summary text.
              * More details.
              */
            public void method();
                
This style is also known as "scala" style.
SECOND_LINE Represents the policy for Javadoc content starts from the next line after /**. Example:
              /**
              * Summary text.
              * More details.
              */
              public void method();
                
This style is common to java projects.

LeftCurlyOption

This type represents the policy for checking the placement of a left curly brace ('{'). The following table describes the valid options:

Option Definition
eol The brace must always be on the end of the line. For example:#
    if (condition) {
        ...
                
nl The brace must always be on a new line. For example:
    if (condition)
    {
        ...
                
nlow If the statement/expression/declaration connected to the brace spans multiple lines, then apply nl rule. Otherwise, apply the eol rule. nlow is a mnemonic for "new line on wrap". For the example above Checkstyle will enforce:
    if (condition) {
        ...
                
But for a statement spanning multiple lines, Checkstyle will enforce:
    if (condition1 && condition2 &&
        condition3 && condition4)
    {
        ...
                

LineSeparatorOption

This type represents the policy for line returns. The following table describes the valid options:

Option Definition
crlf Windows-style
cr Mac-style
lf Unix-style
lf_cr_crlf lf, cr or crlf
system system default

PadOption

This type represents the policy for padding with white space. The following table describes the valid options:

Option Definition
nospace Do not pad. For example, method(a, b);
space Ensure padding. For example, method( a, b );

Pattern

This type represents a regular expression. The string representation is parsed using java.util.regex package.

Pattern[]

This type represents a set of patterns. The string representation is parsed as a set of comma (',') separated patterns.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated patterns. For example, the following:

<property name="patterns" value="^prefix*$, ^*suffix$"/>
      

can instead be expressed as:

<property name="patterns" value="^prefix*"/>
<property name="patterns" value="^*suffix$"/>
      

RightCurlyOption

This type represents the policy for checking the placement of a right curly brace ('}') in blocks but not blocks of expressions. For right curly brace of expression blocks please follow issue #5945. The following table describes the valid options:

Option Definition
alone The brace must be alone on the line. For example:
    try {
        ...
    }
    finally {
        ...
    }
                
alone_or_singleline The brace must be alone on the line, yet single-line format of block is allowed. For example:
    // Brace is alone on the line
    try {
        ...
    }
    finally {
        ...
    }

    // Single-line format of block
    public long getId() { return id; }
                
same Works like alone_or_singleline but the brace should be on the same line as the next part of a multi-block statement (one that directly contains multiple blocks: if/else-if/else or try/catch/finally). If no next part of a multi-block statement present, brace must be alone on line. It also allows single-line format of multi-block statements.

Examples:

    public long getId() {return id;} // this is OK, it is single-line

    // try-catch-finally blocks
    try {
        ...
    } catch (Exception ex) { // this is OK
        ...
    } finally { // this is OK
        ...
    }

    try {
        ...
    } // this is NOT OK, not on the same line as the next part of a multi-block statement
    catch (Exception ex) {
          ...
    } // this is NOT OK, not on the same line as the next part of a multi-block statement
    finally {
          ...
    }

    // if-else blocks
    if (a > 0) {
       ...
    } else { // this is OK
       ...
    }

    if (a > 0) {
       ...
    } // this is NOT OK, not on the same line as the next part of a multi-block statement
    else {
       ...
    }

    if (a > 0) {
       ...
    } int i = 5; // NOT OK, no next part of a multi-block statement, so should be alone

    Thread t = new Thread(new Runnable() {
       @Override
       public void run() {
                  ...
       } // this is OK, should be alone as next part of a multi-block statement is absent
    }); // this case is out of scope of RightCurly Check (see issue #5945)

    if (a > 0) { ... } // OK, single-line multi-block statement
    if (a > 0) { ... } else { ... } // OK, single-line multi-block statement
    if (a > 0) {
        ...
    } else { ... } // OK, single-line multi-block statement
                

Scope

This type represents a Java scope. Checks use this to determine which methods/fields/classes will be examined by its logic. The valid options are:

  • nothing
  • public
  • protected
  • package
  • private
  • anoninner

Using a specific scope means not only will that modifier be examined, but also all the modifiers listed above it in the previous list. Specifying public means only items with public modifiers are checked. Specifying protected means only public and protected modifiers are checked. If you wish to only validate items with private modifiers and ignore any others, then you must set the exclude scope property, if available, to the scope above it in the table. In this case you would exclude package.

SeverityLevel

This type represents the severity level of a module violation. The following table describes the valid options:

Option Definition CLI Ant task
ignore If a violation occurs, modules with this severity are ignored as if they never occurred. This severity can be used to disable a module in the configuration. Such violation not printed in output, however, depending on the setting of executeIgnoredModules when executed, the module may still run and if an exception occurs, the exception will turn into an error and act as one. Such violation not printed in output, however, depending on the setting of executeIgnoredModules when executed, the module may still run and if an exception occurs, the exception will turn into an error and act as one.
info If a violation occurs, modules with this severity are displayed as informational. Displays the violation, but not fail the execution. Displays the violation, but not fail the execution.
warning This severity behaves exactly the same as info in Checkstyle. It can be used to let user bring more attention to reviewers of such violations. Displays the violation, but not fail the execution. Displays the violation, might fail the execution.
maxWarnings can be used to pass the execution until a certain number of warnings are found.
error If a violation occurs, modules with this severity are displayed as error and should be considered as a failure. Displays the violation, fail the execution. Displays the violation, might fail the execution.
maxErrors can be used to pass the execution until a certain number of error are found.

String

This type represents a string. The literal string representation is used.

String[]

This type represents a set of strings. The string representation is parsed as a set of comma (',') separated strings. Extra spaces are allowed.

Alternatively, a property of this type can be supplied multiple times which is equivalent to a set of comma separated strings. For example, the following:

<property name="tokens" value="DIV_ASSIGN, PLUS_ASSIGN"/>
      

can instead be expressed as:

<property name="tokens" value="DIV_ASSIGN"/>
<property name="tokens" value="PLUS_ASSIGN"/>
      

TrailingArrayCommaOption

This type represents the policy for the styles for the trailing array comma. The following table describes the valid options:

Option Definition
always Example:
@SuppressWarnings(value={"unchecked","unused",})
never Example:
@SuppressWarnings(value={"unchecked","unused"})
ignore Anything goes.

URI

This type represents a URI. The string representation is parsed using a custom routine to analyze what type of URI the string is. It can be a URL, regular file, a file referenced using 'classpath:' protocol, or a resource path. It will try loading the path as a URL first, then as a file that must exist, and then finally as a resource on the classpath. Note that the pseudo URL `classpath:` specifies that the resource should be loaded from the class path, if it is not a local file.

WrapOption

This type represents the policy for wrapping lines. The following table describes the valid options:

Option Definition
nl The token must be on a new line. For example:
    someVariable = aBigVariableNameToMakeThings + "this may work"
                   + lookVeryInteresting;
                
eol The token must be at the end of the line. For example:
    someVariable = aBigVariableNameToMakeThings + "this may work" +
                   lookVeryInteresting;