Examples

Here are more examples of using the java formatter plugin.

For more details on these parameters, see the format goal

Setting Source Files

By default, the plugin formats all java source files in the src/main/java and src/test/java directories.
To format source files in other locations, use the directories parameter.
This example formats files in the java main source and generated sources directories:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.8.0</version>
  <configuration>
    <directories>
      <directory>${project.build.sourceDirectory}</directory>
      <directory>${project.build.directory}/generated-sources</directory>
    </directories>
  </configuration>
</plugin>

For more control in specifying the java source files to format, use the includes and excludes parameters.
These parameters are fileset patterns relative to all source directories, usually src/main/java and src/test/java.
This example only formats files in the include package, except for test classes and those in the exclude "special" subpackage:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.8.0</version>
  <configuration>
    <includes>
      <include>com/relativitas/maven/plugins/formatter/</include>
    </includes>
    <excludes>
      <exclude>com/relativitas/maven/plugins/formatter/special/</exclude>
      <exclude>**/*Test.java</exclude>
    </excludes>
  </configuration>
</plugin>

Setting Compiler Version

To specify the compiler version to use in formatting, use the compilerSource, compilerCompliance, and compilerTargetPlatform parameters.
By default, the plugin uses a version of 1.8 for all of these parameters.
This example uses 1.9 as the compiler version during formatting:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.8.0</version>
  <configuration>
    <compilerSource>1.9</compilerSource>
    <compilerCompliance>1.9</compilerCompliance>
    <compilerTargetPlatform>1.9</compilerTargetPlatform>
  </configuration>
</plugin>

These 3 parameters can also be set using the maven compiler plugin properties for source and target.

<properties>
  <maven.compiler.source>1.9</maven.compiler.source>
  <maven.compiler.target>1.9</maven.compiler.target>
</properties>

System Independent Line Endings

To specify the line ending to use in formatting, use the lineEnding parameter.
By default, the plugin uses the line ending of the current system.
This parameter allows using the existing line ending of files or a consistent line ending for all files, useful for large projects with developers using different operating systems.
This example specifies using the carriage-return and line-feed of DOS/Windows for the line ending during formatting:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.8.0</version>
  <configuration>
    <lineEnding>CRLF</lineEnding>
  </configuration>
</plugin>

For all possible values, see the lineEnding description on the format goal

Source File Encoding

To specify the encoding to use during formatting, use the encoding parameter.
By default, the plugin uses the project.build.sourceEncoding property if specified in the pom.
Otherwise, the file encoding of the current system will be used.
This example specifies using the UTF-8 encoding during formatting using the parameter:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.8.0</version>
  <configuration>
    <encoding>UTF-8</encoding>
  </configuration>
</plugin>

This example specifies also using the UTF-8 encoding during formatting but using the property:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.8.0</version>
</plugin>
...
<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

Custom Configuration File

By default, the plugin uses the Eclipse formatter settings and provides no additional preferences other than the compiler version.
To specify formatting preferences for the Eclipse code formatter, use the configFile parameter.
This parameter points to a file or classpath resource location for an Eclipse code formatter xml file.
To provide additional classpath resources to the plugin, add a dependency on a jar containing your formatter xml file.

A configFile can be created and exported in Eclipse as follows:

  • In Eclipse, go to Window > Preferences > Java > Code Style > Formatter
  • If you have a custom profile, select the profile and click on the Edit button
    • To create a custom profile, click the New button
    • Enter a name and select an existing profile to inherit settings from
    • Click Ok and set the profile settings
  • Click the Export button and save the file

This file should contain a profile of kind CodeFormatterProfile with org.eclipse.jdt.core.formatter settings:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<profiles version="11">
  <profile kind="CodeFormatterProfile" name="Custom Project Formatter" version="11">
    <setting id="org.eclipse.jdt.core.formatter.blank_lines_after_package" value="1"/>
    <setting id="org.eclipse.jdt.core.compiler.source" value="1.9"/>
    ...
  </profile>
</profiles>

This example uses a configuration file named eclipse-formatter-config.xml for formatting:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.8.0</version>
  <configuration>
    <configFile>${project.basedir}/eclipse-formatter-config.xml</configFile>
  </configuration>
</plugin>

By default, the plugin uses the compiler versions in the configFile instead of the compiler parameters.
To specify using the compiler parameters instead of those in the configFile, set the overrideConfigCompilerVersion parameter to true.

This parameter is useful to avoid updating the configFile to keep the compiler version in sync with the pom.
This example uses all settings except the compiler version defined in the configuration file named eclipse-formatter-config.xml and instead uses the compiler version specified in the parameters for formatting:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.8.0</version>
  <configuration>
    <configFile>${project.basedir}/eclipse-formatter-config.xml</configFile>
    <overrideConfigCompilerVersion>true</overrideConfigCompilerVersion>
    <compilerSource>1.9</compilerSource>
    <compilerCompliance>1.9</compilerCompliance>
    <compilerTargetPlatform>1.9</compilerTargetPlatform>
  </configuration>
</plugin>

Basic Configuration Using External Resource

This section describes configuring the plugin for use with the formatter
configuration file provided by another jar.

Assume that you are using an external build-tools jar, containing
a formatter file at eclipse/formatter.xml. Such a project could have
been built using a structure similar to the following:

com.example:build-tools
|-- pom.xml
`-- src
    `-- main
        `-- resources
            `-- eclipse
                `-- formatter.xml

You can then configure your project to use this formatter in this jar.
A separate artifact containing the formatter resource works well with
both single-module and multi-module projects:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>myproject</artifactId>
  <version>1.0</version>
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>net.revelc.code.formatter</groupId>
          <artifactId>formatter-maven-plugin</artifactId>
          <version>2.8.0</version>
          <dependencies>
            <dependency>
              <groupId>com.example</groupId>
              <artifactId>build-tools</artifactId>
              <version>1.0</version>
            </dependency>
          </dependencies>
        </plugin>
      </plugins>
    </pluginManagement>
    <plugins>
      <plugin>
        <groupId>net.revelc.code.formatter</groupId>
        <artifactId>formatter-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>format</goal>
            </goals>
            <configuration>
              <configFile>eclipse/formatter.xml</configFile>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Multimodule Configuration

If you do not wish to use an externally provided resource jar containing your
formatter configuration, you can create a multi-module project, with one module
depending on a sibling build-tools project.

For example:

com.example:multiproject
|-- pom.xml
|-- build-tools
|   `-- pom.xml
|   `-- src
|       `-- main
|           `-- resources
|               `-- eclipse
|                   `-- formatter.xml
|-- moduleA
|   `-- pom.xml
|-- moduleB
|   `-- pom.xml

In the multi-module parent POM

Provide some basic configuration, as desired in parent POM of the
multi-module project for the formatter plugin:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>multiproject</artifactId>
  <version>1.0</version>
  <packaging>pom</packaging>
  <name>Multiproject Parent</name>
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>net.revelc.code.formatter</groupId>
          <artifactId>formatter-maven-plugin</artifactId>
          <version>2.8.0</version>
        </plugin>
      </plugins>
    </pluginManagement>
    <plugins>
      <plugin>
        <groupId>net.revelc.code.formatter</groupId>
        <artifactId>formatter-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>format</goal>
            </goals>
            <configuration>
              <configFile>eclipse/formatter.xml</configFile>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  <modules>
    <module>build-tools</module>
    <module>moduleA</module>
    <module>moduleB</module>
  </modules>
</project>

In the sibling modules which use the formatter

Configure the non-build-tools modules to include their sibling build-tools
module when they run the formatter (moduleA shown here, for example):

<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>multiproject</artifactId>
    <version>1.0</version>
  </parent>
  <artifactId>moduleA</artifactId>
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>net.revelc.code.formatter</groupId>
          <artifactId>formatter-maven-plugin</artifactId>
          <dependencies>
            <dependency>
              <groupId>com.example</groupId>
              <artifactId>build-tools</artifactId>
              <version>${project.version}</version>
            </dependency>
          </dependencies>
        </plugin>
      </plugins>
    </pluginManagement>
</project>