<?xml version="1.0" encoding="UTF-8"?>

<document xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <head>
    <title>Property Types</title>
    <script type="text/javascript"
            src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/>
    <script type="text/javascript" src="js/anchors.js"/>
    <script type="text/javascript" src="js/google-analytics.js"/>
    <link rel="icon" href="images/favicon.png" type="image/x-icon" />
    <link rel="shortcut icon" href="images/favicon.ico" type="image/ico" />
  </head>

  <body>
    <section name="Content">
      <macro name="toc">
        <param name="fromDepth" value="1"/>
        <param name="toDepth" value="1"/>
      </macro>
    </section>

    <section name="Overview">
    <p>
      Checkstyle is configured using properties, which are string
      representations. This document describes how these string
      representations are mapped to typed properties.
    </p>
    </section>

    <section name="integer">
      <p>
        This type represents an integer. The string representation is
        parsed using the <code>java.lang.Integer</code> class.
      </p>
    </section>

    <section name="string">
      <p>
        This type represents a string. The literal string representation
        is used.
      </p>
    </section>

    <section name="boolean">
      <p>
        This type represents a boolean. The default value is <code>false</code>.
        The following string representations will map to <code>true</code>:
      </p>

      <ul>
        <li><code>yes</code></li>
        <li><code>true</code></li>
        <li><code>on</code></li>
      </ul>

      <p>Anything else will map to <code>false</code>.</p>
    </section>

    <section name="stringSet">
      <p>
        This type represents a set of strings. The string representation
        is parsed as a set of comma (',') separated strings.
      </p>
      <p>
        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:
      </p>
      <source>
&lt;property name=&quot;tokens&quot; value=&quot;DIV_ASSIGN,PLUS_ASSIGN&quot;/&gt;
      </source>
      <p>can instead be expressed as:</p>
      <source>
&lt;property name=&quot;tokens&quot; value=&quot;DIV_ASSIGN&quot;/&gt;
&lt;property name=&quot;tokens&quot; value=&quot;PLUS_ASSIGN&quot;/&gt;
      </source>
    </section>

    <section name="intSet">
      <p>
        This type represents a set of integers. The string representation
        is parsed as a set of comma (',') separated integers that are parsed
        using the <code>java.lang.Integer</code> class.
      </p>
      <p>
        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:
      </p>
      <source>
&lt;property name=&quot;tokens&quot; value=&quot;42,666&quot;/&gt;
      </source>
      <p>can instead be expressed as:</p>
      <source>
&lt;property name=&quot;tokens&quot; value=&quot;42&quot;/&gt;
&lt;property name=&quot;tokens&quot; value=&quot;666&quot;/&gt;
      </source>
    </section>

    <section name="regexp">
      <p>
        This type represents a regular expression. The string representation is parsed using
        <a href="https://docs.oracle.com/javase/7/docs/api/index.html?java/util/regex/package-summary.html">
        java.util.regex package</a>.
      </p>
    </section>

    <section name="uri">
      <p>
        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, 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.
      </p>
    </section>

    <section name="file">
      <p>
        This type represents a local file. Unlike the <a href="#uri">uri</a> 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.
      </p>
    </section>

    <section name="lineSeparator">
      <p>
        This type represents the policy for line returns. The
        following table describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="line separator options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>
          <tr>
            <td><code>crlf</code></td>
            <td>Windows-style</td>
          </tr>
          <tr>
            <td><code>cr</code></td>
            <td>Mac-style</td>
          </tr>
          <tr>
            <td><code>lf</code></td>
            <td>Unix-style</td>
          </tr>
          <tr>
            <td><code>lf_cr_crlf</code></td>
            <td>lf, cr or crlf</td>
          </tr>
          <tr>
            <td><code>system</code></td>
            <td>system default</td>
          </tr>
        </table>
      </div>
    </section>

    <section name="parenPad">
      <p>
        This type represents the policy for padding with white space. The
        following table describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="padding options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>
          <tr>
            <td><code>nospace</code></td>
            <td>
              Do not pad. For example, <code>method(a, b);</code>
            </td>
          </tr>
          <tr>
            <td><code>space</code></td>
            <td>
              Ensure padding. For example,
              <code>method( a, b );</code>
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section name="wrapOp">
      <p>
        This type represents the policy for wrapping lines.
        The following table describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="wrap options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>
          <tr>
            <td><code>nl</code></td>
            <td>
              The token must be on a new line. For example:
              <div class="wrapper">
                <pre>
    someVariable = aBigVariableNameToMakeThings + "this may work"
                   + lookVeryInteresting;
                </pre>
              </div>
            </td>
          </tr>
          <tr>
            <td><code>eol</code></td>
            <td>
              The token must be at the end of the line. For example:
              <div class="wrapper">
                <pre>
    someVariable = aBigVariableNameToMakeThings + "this may work" +
                   lookVeryInteresting;
                </pre>
              </div>
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section name="block">
      <p>
        This type represents the policy for checking block statements. The
        following table describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="block options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>
          <tr>
            <td><code>text</code></td>
            <td>
              Require that there is some text in the block. For example:
              <div class="wrapper">
                <pre>
    catch (Exception ex) {
        // This is a bad coding practice
    }
                </pre>
              </div>
            </td>
          </tr>
          <tr>
            <td><code>statement</code></td>
            <td>
              Require that there is a statement in the block. For example:
              <div class="wrapper">
                <pre>
    finally {
        lock.release();
    }
                </pre>
              </div>
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section name="lcurly">
      <p>
        This type represents the policy for checking the placement of a
        left curly brace (<code>'{'</code>). The following table
        describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="left curly options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>

          <tr>
            <td><code>eol</code></td>
            <td>
              The brace must always be on the end of the line. For example:#
              <div class="wrapper">
                <pre>
    if (condition) {
        ...
                </pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>nl</code></td>
            <td>
              The brace must always be on a new line. For example:
              <div class="wrapper">
                <pre>
    if (condition)
    {
        ...
                </pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>nlow</code></td>
            <td>
              If the statement/expression/declaration connected to the brace spans multiple lines,
              then apply <code>nl</code> rule. Otherwise apply the <code>eol</code> rule.
              <code>nlow</code> is a mnemonic for "new line on wrap".
              For the example above Checkstyle will enforce:
              <div class="wrapper">
                <pre>
    if (condition) {
        ...
                </pre>
             </div>
              But for a statement spanning multiple lines, Checkstyle will
              enforce:
              <div class="wrapper">
                <pre>
    if (condition1 &amp;&amp; condition2 &amp;&amp;
        condition3 &amp;&amp; condition4)
    {
        ...
                </pre>
              </div>
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section name="rcurly">
      <p>
        This type represents the policy for checking the placement of a
        right curly brace (<code>'}'</code>) in blocks but not blocks of expressions.
        For right curly brace of expression blocks please follow issue
        <a href="https://github.com/checkstyle/checkstyle/issues/5945">#5945</a>. The following
        table describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="right curly options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>

          <tr>
            <td><code>alone</code></td>
            <td>
              The brace must be alone on the line. For example:
              <div class="wrapper">
                <pre>
    try {
        ...
    <b>}</b>
    finally {
        ...
    <b>}</b>
                </pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>alone_or_singleline</code></td>
            <td>
                    The brace must be alone on the line, yet
                    single-line format of block is allowed.
                    For example:
              <div class="wrapper">
                <pre>
    // Brace is alone on the line
    try {
        ...
    <b>}</b>
    finally {
        ...
    <b>}</b>

    // Single-line format of block
    public long getId() { return id; <b>}</b>
                </pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>same</code></td>
            <td>
              Works like <code>alone_or_singleline</code> 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.

              <p>Examples:</p>

              <div class="wrapper">
                <pre>
    public long getId() {return id;<b>}</b> // this is OK, it is single line

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

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

    // if-else blocks
    if (a &#62; 0) {
       ...
    <b>}</b> else { // this is OK
       ...
    }

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

    if (a &#62; 0) {
       ...
    <b>}</b> 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() {
                  ...
       <b>}</b> // this is OK, should be alone as next part of a multi-block statement is absent
    <b>}</b>); // this case is out of scope of RightCurly Check (see issue #5945)

    if (a &#62; 0) { ... <b>}</b> // OK, single-line multi-block statement
    if (a &#62; 0) { ... } else { ... <b>}</b> // OK, single-line multi-block statement
    if (a &#62; 0) {
        ...
    } else { ... <b>}</b> // OK, single-line multi-block statement
                </pre>
              </div>
            </td>
          </tr>

        </table>
      </div>
    </section>

    <section name="scope">
      <p>This type represents a Java scope. Checks use this to determine which
      methods/fields/classes will be examined by it's logic. The valid options are:</p>

      <ul>
        <li><code>nothing</code></li>
        <li><code>public</code></li>
        <li><code>protected</code></li>
        <li><code>package</code></li>
        <li><code>private</code></li>
        <li><code>anoninner</code></li>
      </ul>

      <p>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 <code>public</code> means only
      items with <code>public</code> modifiers are checked. Specifying <code>protected</code>
      means only <code>public</code> and <code>protected</code> modifiers are checked.
      If you wish to only validate items with <code>private</code> 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 <code>package</code>.
      </p>
    </section>

    <section name="access_modifiers">
      <p>This type represents Java access modifiers.</p>

      <ul>
        <li><code>public</code></li>
        <li><code>protected</code></li>
        <li><code>package</code></li>
        <li><code>private</code></li>
      </ul>
    </section>

    <section name="severity">
      <p>
        This type represents the severity level of a check violation. The
        valid options are:
      </p>

      <ul>
        <li><code>ignore</code></li>
        <li><code>info</code></li>
        <li><code>warning</code></li>
        <li><code>error</code></li>
      </ul>
    </section>

    <section name="importOrder">
      <p>
        This type represents the policy for checking imports order.
        The following table describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="import order options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>

          <tr>
            <td><code>top</code></td>
            <td>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:
              <div class="wrapper">
                <pre>
    import static a.b.C.*;
    import static x.y.Z.*;

    import a.b.D;
    import x.y.Z;</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>above</code></td>
            <td>All static imports are above the local group. For example:
              <div class="wrapper">
                <pre>
    import static a.b.C.*;
    import a.b.D;

    import static x.y.Z.*;
    import x.y.Z;</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>inflow</code></td>
            <td>All static imports are processed like non static
                imports. For example:
              <div class="wrapper">
                <pre>
    import static a.b.C.*;
    import a.b.D;

    import x.y.Z;
    import static x.y.Z.*;</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>under</code></td>
            <td>All static imports are under the local group. For example:
              <div class="wrapper">
                <pre>
    import a.b.D;
    import static a.b.C.*;

    import x.y.Z;
    import static x.y.Z.*;</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>bottom</code></td>
            <td>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:
              <div class="wrapper">
                <pre>
    import a.b.D;
    import x.y.Z;

    import static a.b.C.*;
    import static x.y.Z.*;</pre>
              </div>
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section name="elementStyle">
      <p>
        This type represents the policy for the styles for defining
        elements in an annotation. The following table
        describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="elementStyle options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>

          <tr>
            <td><code>expanded</code></td>
            <td>
              The expanded version is sometimes referred to as "named parameters"
              in other languages.
              Example:
              <div class="wrapper">
                <pre>@SuppressWarnings(value={"unchecked","unused",})</pre>
              </div>
              Example of violation:
              <div class="wrapper">
                <pre>@SuppressWarnings({"unchecked","unused",})</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>compact</code></td>
            <td>
              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:
              <div class="wrapper">
                <pre>
                @SuppressWarnings({"unchecked","unused",})
                @SuppressWarnings("unchecked")
                </pre>
              </div>
              Example of violation:
              <div class="wrapper">
                <pre>
                @SuppressWarnings(value = {"unchecked","unused",})
                @SuppressWarnings(value = "unchecked")
                </pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>compact_no_array</code></td>
            <td>
              It is similar to the <code>compact</code> style but
              single value arrays are flagged. With annotations a single value
              array does not need to be placed in an array initializer.
              Example:
              <div class="wrapper">
                <pre>
              @SuppressWarnings("unchecked")
              @MyAnnotation(someArray = "some value")
                </pre>
              </div>
              Example of violation:
              <div class="wrapper">
                <pre>
              @SuppressWarnings({"unchecked"})
              @MyAnnotation(someArray = {"some value"})
                </pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>ignore</code></td>
            <td>
              Anything goes.
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section name="closingParens">
      <p>
        This type represents the policy for the styles for the ending
        parenthesis. The following table describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="closingParens options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>

          <tr>
            <td><code>always</code></td>
            <td>
              Example:
              <div class="wrapper">
                <pre>@Deprecated()</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>never</code></td>
            <td>
              Example:
              <div class="wrapper">
                <pre>@Deprecated</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>ignore</code></td>
            <td>
              Anything goes.
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section name="trailingArrayComma">
      <p>
        This type represents the policy for the styles for the trailing
        array comma. The following table describes the valid options:
      </p>

        <div class="wrapper">
        <table summary="trailingArrayComma options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>

          <tr>
            <td><code>always</code></td>
            <td>
              Example:
              <div class="wrapper">
                <pre>@SuppressWarnings(value={"unchecked","unused",})</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>never</code></td>
            <td>
              Example:
              <div class="wrapper">
                <pre>@SuppressWarnings(value={"unchecked","unused"})</pre>
              </div>
            </td>
          </tr>

          <tr>
            <td><code>ignore</code></td>
            <td>
              Anything goes.
            </td>
          </tr>
        </table>
      </div>
    </section>

    <section name="javadocContentLocation">
      <p>
        This type represents policy on placement of the Javadoc content.
        The following table describes the valid options:
      </p>

      <div class="wrapper">
        <table summary="javadocContentLocation options">
          <tr>
            <td>Option</td>
            <td>Definition</td>
          </tr>

          <tr>
            <td><code>FIRST_LINE</code></td>
            <td>
              Represents the policy for Javadoc content starts from the same line
              as <code>/**</code>.
              Example:
              <div class="wrapper">
                <pre>
            &#47;** Summary text.
              * More details.
              *&#47;
            public void method();
                </pre>
              </div>
              This style is also known as "scala" style.
            </td>
          </tr>

          <tr>
            <td><code>SECOND_LINE</code></td>
            <td>
              Represents the policy for Javadoc content starts from the next line
              after <code>/**</code>.
              Example:
              <div class="wrapper">
                <pre>
              &#47;**
              * Summary text.
              * More details.
              *&#47;
              public void method();
                </pre>
              </div>
              This style is common to java projects.
            </td>
          </tr>

        </table>
      </div>
    </section>
  </body>
</document>
