10 Effective Tips on Using Maven

Maven is — without a doubt — the most popular build automation tool for software projects in the Java ecosystem. It has long replaced Ant, thanks to an easier and declarative model for managing projects, providing dependency management and resolution, well-defined build phases such compile and test, and support for plugins that can do anything related to building, configuring, and deploying your code. It is estimated to be used by 60 percent of Java developers in 2018.

Over the years, a number of usage scenarios and commands turned out to be quite useful for me when working on Maven-based projects. Here are a few usage tips that help in using Maven more effectively. There are many more, and one can obviously learn something new every day for a specific use case, but these are the ones I think can be commonly applied. The focus here is on aspects like command line usage, troubleshooting a certain issue, or making repetitive tasks easier. Hence, you won’t find practices like using dependencyManagementto centralize dependencies, which are rather basic anyway and more used in initially composing a POM.

Friendly disclaimer: if you’re new to Maven or haven’t had enough experience using it, it’s better to set aside some time to learn about its basics, instead of trying to learn by way of tips and tricks.

1. Fetching a Project’s Dependency Tree

This one is a no-brainer, but it is key to resolving dependency-related issues, such as using the wrong versions. It is described in the dependency:tree goal of the maven-dependency-plugin. You can simply run the following command line to display a tree of all dependencies used in your current project (optionally use less to scroll through the result, assuming you’re working on a big enough project):

$ mvn dependency tree | less

Note that in IDEs like Eclipse, this hierarchy of dependencies can be visualized in the POM editor. For example, in Eclipse, it can be viewed on the “Dependency Hierarchy” tab of the POM editor.

2. Analyze Dependencies

It is good practice to declare in the POM only those dependencies that a project actually uses, and often, you want to explicitly declare dependencies your project uses even if they are transitively included. This makes the POM cleaner, just like it’s a good practice to remove unused imports and declare those for types you use in Java code.

To do that, either run the dependency:analyze goal as a standalone command:

$ mvn dependency:analyze

Whenever the plugin finds an unused dependency that is declared in the POM or a used dependency that is undeclared, a warning is shown in the output. If a build failure needs to be raised because of this, the paramater failOnWarning can be set to true:

$ mvn dependency:analyze -DfailOnWarning=true

Another way is to use the dependency:analyze-only goal, which does the same thing, but it should be used within the build lifecycle, i.e. it can be integrated into the project’s POM:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <id>analyze-deps</id>
            <goals>
                <goal>analyze-only</goal>
            </goals>
        </execution>
    </executions>
</plugin>

3. Skipping Tests During a Local Build

When building a project on a development machine, you may want to skip existing unit and integration tests, perhaps, because you want to build the code more quickly or because you don’t care about tests for the moment. Maybe you want to run tests only after you feel you have the first draft of your commit ready to be tested. Note that this should never be done on a CI/CD machine that builds and deploys to a production or a staging environment.

There are two options to consider:

1. Skipping the running of tests: You can do it with mvn package -DskipTests=true. Or, you can shorten the property to just -DskipTests.
2. Skipping the compilation and running of tests (not recommended): You can do it with mvn package -Dmaven.test.skip=true. You can shorten the property to just -Dmaven.test.skip.

The latter skips the entire testing related tasks (both compiling and running tests), so it may make the build slightly faster, but-DskipTests is recommended instead, because it allows you to detect changes that broke the tests at compile-time. This is often important, as discovering and fixing errors earlier may end up requiring a re-iteration on the changes in the main code, maybe to do some refactoring to make the code easier to test.

Consider running tests in parallel, as described in the Surefire plugin documentation. This is a much better, long-term solution, but the cost is that you should make sure parallel tests are independent and don’t cause concurrency issues, because they will share the same JVM process.

4. Debugging Unit Tests

The aforementioned properties are understood by the maven-surefire-plugin, which is responsible for running unit tests. This plugin is invoked during the test phase of the build lifecycle. Sometimes, you don’t want to debug a failing test in your IDE, because you’re like me and don’t always trust that the IDE is running the test with new changes. Sometimes, you have a command line window and just want to stick to it. In that case, pass a property to the plugin as follows:

$ mvn clean package -Dmaven.surefire.debug

This will cause the plugin to listen to a remote debugger on port 5005. Now, you can configure a remote debugging in your IDE to connect to the listening plugin and execute the tests in debug mode.

If you ever need to do the same with integration tests, just use the property -Dmaven.failsafe.debug instead. The name comes from the maven-failsafe-plugin, which is responsible for running integration tests.

5. Running a Specific Test

So, you debugged a failing test and fixed the failure, and now, you want to re-run it to make sure it is successful. To tell Surefire to only run that specific test, the test parameter can be passed on the command line:

$ mvn clean package -Dtest=MyTest

According to the documentation of the test goal of the Maven Surefire plugin, the test parameter can be used to further control the specific test methods to execute:

$ mvn clean package -Dtest=MyTest#testMethod

6. Resuming the Build From a Project

I was hesitating whether or not to include this one because it looked trivial, and Maven usually points it to the user upon a build failure, but I decided it’s still worth listing. Whenever an error occurs in a build and you fixed it and want to re-run the build, the option -rf, followed with a colon and the name of the failed module, can be used to resume the build from the failed module to avoid re-building already successfully built modules:

$ mvn clean install-rf :db-impl

7. Effective POM

Instead of navigating multiple POM files at different levels in your multi-module project and/or POM files defined in dependencies themselves in order to figure out what transitive dependencies are resolved or what plugin configuration is applied, a simple command can show the effective POM that consists of the entire configuration snapshot of the current POM, including inherited information from parent POMs such as properties, plugins, dependency information, and profiles.

$ mvn help:effective-pom | less

In Eclipse, it can be viewed by clicking on the bottom tab labeled “Effective POM” within the default POM editor.

8. Building Specific Modules and Their Dependencies

In the case of multi-module projects with many dependent modules, you may want to specify explicitly which modules to build and ignore the others. For example, you just want to build one or two modules you’re working on along with their dependencies, instead of building the whole list of modules. Instead of just doing mvn clean install from the aggregator POM, you can use the -pl command line option. For example, to build only module db-impl, you can execute the command:

$ mvn clean install-pl db-impl -am

The option -am, shorthand for --also-make, tells Maven to build the projects required by the list in -pl.

9. Configuring JVM Memory

Before building a project, Maven will analyze its hierarchy of modules to construct a graph of dependencies that specifies the order of building these individual modules. Sometimes this analysis step can require more memory than the default allocated to the JVM process of Maven, hence causing a Java heap space error. To configure these memory settings, the MAVEN_OPTS environment variable can be set:

$ exportMAVEN_OPTS=-Xms256m -Xmx1024m

10. Debugging a Maven Plugin

Since Maven has a rich plugin ecosystem and it is easy to develop a custom plugin, it is likely to be in a situation where a developer needs to debug a problem with such plugins. Given the source code of your plugin is imported into your IDE, you can run Maven in debug mode using the mvnDebug executable (e.g. mvnDebug clean install), and Maven will wait for a remote debugger in the IDE to attach on port 8000.

Conclusion

Knowing how a build tool like Maven works is essential to making the most of it, but there are some use cases that often repeat themselves where it’s worth remembering these quick solutions. If you have any other tips, feel free to let us know in the comments below!