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.23.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.23.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.23.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.23.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.23.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.23.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.23.0</version>
  <configuration>
    <configFile>${project.basedir}/eclipse-formatter-config.xml</configFile>
  </configuration>
</plugin>

The plugin overrides the compiler version in the configFile with the value of 1.8 by default, but will use the value of the maven.compiler.source property for the compilerCompliance and compilerSource values, and the value of the maven.compiler.target property for the compilerTargetPlatform value, if those properties are set in your Maven environment.

These parameters are useful to avoid updating the configFile to keep the compiler version in sync with the pom. This example shows how to set these parameters directly in the plugin configuration, rather than rely on the default behavior:

<plugin>
  <groupId>net.revelc.code.formatter</groupId>
  <artifactId>formatter-maven-plugin</artifactId>
  <version>2.23.0</version>
  <configuration>
    <configFile>${project.basedir}/eclipse-formatter-config.xml</configFile>
    <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.

The following configuration will bind the plugin to execute the format goal in the default lifecycle phase of process-sources. Try it using mvn process-sources.

<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.23.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.

The following configuration will bind the plugin to execute the format goal in the default lifecycle phase of process-sources.

<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.23.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). Try it using mvn process-sources.

<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>0.0.1</version>
            </dependency>
          </dependencies>
        </plugin>
      </plugins>
    </pluginManagement>
</project>