------
 Customizing the Maven 2 Checkstyle Plugin
 ------

Customizing the Maven 2 Checkstyle Plugin

* Use a custom Checkstyle checker configuration.

  A custom {{{http://checkstyle.sourceforge.net/config.html#Checker}Checker configuration xml file}} can be defined and then referenced via a URL, File, or build classpath resource reference.

  To reference the a custom Checkstyle Checker configuration, use the <<configLocation>> parameter.

-------------------
  <project>
      ...
      <reporting>
          <plugins>
              <plugin>
                  <groupId>org.apache.maven.plugins</groupId>
                  <artifactId>maven-checkstyle-plugin</artifactId>
                  <configuration>
                      <configLocation>checkstyle.xml</configLocation>
                  </configuration>
              </plugin>
          </plugins>
      </reporting>
      ...
  </project>
-------------------

  This example causes the Maven 2 Checkstyle plugin to check for a File named <<checkstyle.xml>> or a resource named <<checkstyle.xml>> within the compile scope of the dependencies or build extensions classpath.

  There are 4 predefined Checkstyle configuration definitions that ship with the Maven 2 Checkstyle Plugin, the Sun Microsystems Definition is selected by default.

  * <<config/sun_checks.xml>> - Sun Microsystems Definition (default).

  * <<config/maven_checks.xml>> - Maven Development Definitions.

  * <<config/turbine_checks.xml>> - Turbine Development Definitions.

  * <<config/avalon_checks.xml>> - Avalon Development Definitions.



* Use custom Checkstyle property expansion definitions.

  A custom {{{http://checkstyle.sourceforge.net/config.html#Properties}property expansion definitions}} for the Checker can be defined.

  Checkstyle uses the property expansion mechanism to allow injection of specific values into a pre-defined Checker configuration.  Using property expansion alone is an insufficient means to customize the checks performed by Checkstyle.

  Example: <<checkstyle.xml>> - only checks the package name in use to ensure that it conforms to the desired scheme, but allows for users of this Checker to specify their own projectname.

-------------------
<?xml version="1.0" ?>

<!DOCTYPE module PUBLIC
  "-//Puppy Crawl//DTD Check Configuration 1.2//EN"
  "http://www.puppycrawl.com/dtds/configuration_1_2.dtd">

<module name="Checker">
    <module name="TreeWalker">
        <module name="PackageName">
            <property name="format"
                value="com\.example\.${projectname}(\.[a-z][a-zA-Z0-9]+)*$"/>
        </module>
    </module>
</module>
-------------------

  Example: <<pom.xml>> - Specifies the <<projectname>> property expansion that Checkstyle will use when encountering such a variable in the above Checker configuration.

-------------------
  <project>
      ...
      <reporting>
          <plugins>
              <plugin>
                  <groupId>org.apache.maven.plugins</groupId>
                  <artifactId>maven-checkstyle-plugin</artifactId>
                  <configuration>
                      <configLocation>checkstyle.xml</configLocation>
                      <propertyExpansion>
                        projectname=whizbang
                      </propertyExpansion>
                  </configuration>
              </plugin>
          </plugins>
      </reporting>
      ...
  </project>
-------------------

  The property expansion information can also come from a location using the <<propertiesLocation>> parameter, which can point to a URL, File, or build classpath resource reference.

* Using a Suppressions filter.

  Checkstyle allows the definition of a list of files and their line ranges that should be suppressed from reporting any violations (known as a {{{http://checkstyle.sourceforge.net/config.html#Filters}supressions filter}} ).

  Example: <<checkstyle-suppressions.xml>>

-------------------
<?xml version="1.0"?>

<!DOCTYPE suppressions PUBLIC
    "-//Puppy Crawl//DTD Suppressions 1.0//EN"
    "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd">

<suppressions>
    <suppress checks="JavadocStyleCheck"
              files="GeneratedObject.java"
              lines="50-9999"/>
    <suppress checks="MagicNumberCheck"
              files="LegacyDatasetConvertor.java"
              lines="221,250-295"/>
</suppressions>
-------------------

  Example: <<pom.xml>> - Specifies the suppressions filter that Checkstyle should use.

-------------------
  <project>
      ...
      <reporting>
          <plugins>
              <plugin>
                  <groupId>org.apache.maven.plugins</groupId>
                  <artifactId>maven-checkstyle-plugin</artifactId>
                  <configuration>
                      <configLocation>checkstyle.xml</configLocation>
                      <suppressionsLocation>checkstyle-suppressions.xml</suppressionsLocation>
                  </configuration>
              </plugin>
          </plugins>
      </reporting>
      ...
  </project>
-------------------

* Use a custom developed Checkstyle Check modules.

  For the really adventurous, custom Checkstyle checks can be used with the Maven 2 Checkstyle Plugin.

  The plugin provides the ability to define the {{{http://checkstyle.sourceforge.net/config.html#Packages}package names definition}} required to reference your custom check modules.

  TIP: Create a maven project that produces a jar file of your custom checks, and then include it in your projects using the maven build extension in the pom.xml to avoid them being included in the compile or package phases of your project.

  Example: <<mycompany-checkstyle-checks-1.0.jar>>.

-------------------
$ jar -tvf mycompany-checkstyle-checks-1.0.jar
     0 Tue Nov 29 13:13:14 EST 2005 META-INF/
   401 Tue Nov 29 13:13:12 EST 2005 META-INF/MANIFEST.MF
     0 Tue Nov 29 13:13:12 EST 2005 META-INF/maven/
     0 Tue Nov 29 13:13:14 EST 2005 META-INF/maven/com.mycompany/
     0 Tue Nov 29 13:13:14 EST 2005 META-INF/maven/com.mycompany/mycompany-checkstyle-checks/
  8489 Tue Nov 29 13:13:14 EST 2005 META-INF/maven/com.mycompany/mycompany-checkstyle-checks/pom.xml
   151 Tue Nov 29 13:13:14 EST 2005 META-INF/maven/com.mycompany/mycompany-checkstyle-checks/pom.properties
     0 Tue Nov 29 13:13:14 EST 2005 com/
     0 Tue Nov 29 13:13:14 EST 2005 com/mycompany/
     0 Tue Nov 29 13:13:14 EST 2005 com/mycompany/checkstyle/
  1252 Tue Nov 29 13:13:14 EST 2005 com/mycompany/checkstyle/packagenames.xml
 12939 Tue Nov 29 13:13:14 EST 2005 com/mycompany/checkstyle/PurityCheck.class
-------------------

  Example: <<checkstyle.xml>>

-------------------
<?xml version="1.0" ?>

<!DOCTYPE module PUBLIC
  "-//Puppy Crawl//DTD Check Configuration 1.2//EN"
  "http://www.puppycrawl.com/dtds/configuration_1_2.dtd">

<module name="Checker">
    <module name="TreeWalker">
        <module name="PurityTest"/>
    </module>
</module>
-------------------


  Example: <<pom.xml>>

-------------------
  <project>
      ...
      <reporting>
          <plugins>
              <plugin>
                  <groupId>org.apache.maven.plugins</groupId>
                  <artifactId>maven-checkstyle-plugin</artifactId>
                  <configuration>
                      <configLocation>checkstyle.xml</configLocation>
                      <packageNamesLocation>com/mycompany/checkstyle/packagenames.xml</packageNamesLocation>
                  </configuration>
              </plugin>
          </plugins>
      </reporting>
      ...
      <build>
          <extensions>
              <extension>
                  <groupId>com.mycompany</groupId>
                  <artifactId>mycompany-checkstyle-checks</artifactId>
                  <version>1.0</version>
              </extension>
          </extensions>
      </build>
  </project>
-------------------