Maven Enforcer Custom Rule: Property Usage

Maven Enforcer Plugin is an extension to the (mostly) Java build tool Maven. The Enforcer plugin provides goals to control certain environmental constraints such as Maven version, JDK version and OS family along with many standard rules and also user created custom rules.

The rule propertyUsage is a custom rule to ensure that Java Properties files are in good order. It verifies the following:

• All properties which are defined in properties files, are also used in the source code.
• All properties used in the source code are also defined in properties files.
• No property is defined more than once in properties files.
• When used properties are extracted from the source code, a project policy can be forced via regexp:
  • on property name.
  • on how to access them (via Spring Placeholders, via getProperty, etc.).

Maven Enforcer Plugin

Maven Enforcer is an excellent tool to remove some uncertainty from your build — uncertainty caused mostly by human error.

Maven Enforcer operates by rules which are constraints set by set. A rule can be anything. It can force, for example, that certain Maven properties are set or that version strings adhere to a certain format. The rule dependencyConvergence ensure all dependencies converge to the same version and rule requireActiveProfile enforces that one or more profiles are active during build.

Maven Enforcer Plugin calls itself The Loving Iron Fist of Maven¹. It can be invoked at any stage of the build, though normally this happens at validate phase because most rules can be enforced before compilation. Most standard rules enforcer build time constraint, like OS or architecture, profiles, properties or external environment variables. It can be useful to invoke Maven Enforcer also in a later phase if one needs to check, for example, for existence of files.

The project Extra Enforcer Rules, maintained by MojoHaus, is a collection of some extra custom rules that can be handy in big projects. For example, requireEncoding enforcer the source files to use the same character encoding. Although UTF-8 is commonly the default character set nowadays, by accident a source file with some other encoding might slip into the project. Rule banCircularDependencies verifies that there are no circular dependecies in the project.

Property Usage

The custom rule propertyUsage can be used when there are many developers and the Java source code needs to be uniform and look the same in all parts of the project.

It often happens during development that different properties are defined and used, and then taken out of use but definition is forgotten; they get “left behind” in the resources/*.properties file. Or the opposite: a definition is missing in a subproject using the already introduced property. Not to mention that every developer has his or her own style to access properties: Spring Placeholder, getProperty() function, getProperty() with default value or some external library.

Rule propertyUsage is meant to solve these problems, and others. With the help of regular expressions one can define how properties are accessed in Java source code and how they should look — starting with capital letter or small letter, using camel case or dash, and so on.

Configuration

Let's look at an example configuration (in a pom.xml file):

...
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <dependencies>
        <dependency>
            <groupId>com.github.mikkoi.maven.enforcer.rule</groupId>
            <artifactId>property-usage-rule</artifactId>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <id>enforce-property-usage</id>
            <goals>
                <goal>enforce</goal>
            </goals>
            <configuration>
                <rules>
                    <useAllProperties implementation="com.github.mikkoi.maven.plugins.enforcer.rule.propertyusage.PropertyUsageRule">
                        <definitionsOnlyOnce>true</definitionsOnlyOnce>
                        <definedPropertiesAreUsed>true</definedPropertiesAreUsed>
                        <usedPropertiesAreDefined>false</usedPropertiesAreDefined>
                    </useAllProperties>
                </rules>
                <!-- Fail build if wrong encoding encountered. -->
                <fail>true</fail>
            </configuration>
        </execution>
    </executions>
</plugin>
...

Because this rule is not included in maven-enforcer-plugin jar, it needs to be specified as an extra dependency using <dependencies> element. Element <execution> does not need to have an <id> but it is useful if debugging is needed. The element <useAllProperties> inside <rules> could be named anything, but it is necessary to specify the implementing class with parameter implementation. Inside <useAllProperties> is the actual configuration with parameter names hopefully easy enough to understand without reading further documentation.

All configuration options on the rule's home pages.

References: