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
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% 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 definitely many more, and one can obviously learn something new everyday for a specific use case, but these are the ones I think can be commonly applied. Note that 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
dependencyManagement to centralize dependencies, which are rather basic anyway and more used in initially composing a POM.
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 wrong versions. It is described in
dependency:tree goal of the
maven-dependency-plugin. You can simply run the below in a 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 a 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 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 a 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:
- skipping the running of tests
You can do it with
mvn package -DskipTests=true. You can shorten the property to just
- 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
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 more easier to test.
Bonus tip: 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, maybe 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.
Bonus tip: 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, in order 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
-am, shorthand for
--also-make, tells Maven to build also the projects required by the list in
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:
$ export MAVEN_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.
Knowing how a build tool like Maven works is essential in order to make the most of it, but there are some use cases that often repeat themselves where it’s worth remembering some quick solutions. If you have any other tips that are similar to the above, feel free to comment.Follow @MahmoudAnouti