The example in this section is a skeleton of a complex multimodule project that is used to illustrate the advanced reactor options. While it is possible to read this section without the example code, you might want to download the example code and follow along, experimenting with the various options as you learn how to use the advanced reactor options. This section’s example project may be downloaded with the book’s example code at:

http://www.sonatype.com/books/mvnref-book/mvnref-examples-0.9-project.zip

Unzip this archive in any directory, and then go to the ch-running/ directory. There you will see a directory named sample-parent/. All of the examples in this section will be executed from the examples/ch-running/sample-parent/ directory in the examples distribution. The sample-parent/ directory contains the multimodule project structure shown in Figure 6.1, “Directory Structure of Sample Multi-module Project”.

Figure 6.1. Directory Structure of Sample Multi-module Project

This project approximates the structure of a real-world enterprise project: the sample-model project contains a set of foundational model objects used throughout the system, the sample-util project would contain utility code, the sample-persist project would contain logic that deals with persisting objects to a database, and the other projects would all be combined to produce the various GUI and Web-based interfaces that comprise a very complex system. Figure 6.2, “Dependencies within Sample Multi-module Project” captures the dependencies between each of these sample modules.

Figure 6.2. Dependencies within Sample Multi-module Project

If you go into the sample-parent/ project directory and run mvn clean, you will see that the Maven Reactor reads all of the project dependencies and comes up with the following build order for these projects as shown in Example 6.2, “Order of Project Builds in Maven Reactor”.

[INFO] Reactor build order: 
[INFO]   sample-parent
[INFO]   sample-model
[INFO]   sample-persist
[INFO]   sample-services
[INFO]   sample-util
[INFO]   sample-security
[INFO]   sample-admin-webapp
[INFO]   sample-webapp
[INFO]   sample-rest
[INFO]   sample-client-connector
[INFO]   sample-gui
[INFO]   sample-admin-gui

The -rf or --resume-from option can come in handy if you want to tell the Maven Reactor to resume a build from a particular project. This can be useful if you are working with a large multimodule project and you want to restart a build at a particular project in the Reactor without running through all of the projects that precede it in the build order.

Assume that you are working on the multi-module project with the build order shown in Example 6.2, “Order of Project Builds in Maven Reactor” and that your build ran successfully up until Maven encountered a failing unit test in sample-client-connector. With the -rf option, you can fix the unit test in simple-client-connector and then run mvn -rf sample-client-connect from the sample-parent/ directory to resume the build with the final three projects.

$ mvn --resume-from sample-client-connector install
[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   sample-client-connector
[INFO]   sample-gui
[INFO]   sample-admin-gui
...

The -pl or --projects option allows you to select a list of projects from a multimodule project. This option can be useful if you are working on a specific set of projects, and you'd rather not wait for a full build of a multi-module project during a development cycle.

Assume that you are working on the multi-module project with the build order shown in Example 6.2, “Order of Project Builds in Maven Reactor” and that you are a developer focused on the sample-rest and sample-client-connector projects. If you only wanted Maven to build the sample-rest and sample-client-connector project, you would use the following syntax from the sample-parent/ directory:

$ mvn --projects sample-client-connector,sample-rest install
[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   sample-rest
[INFO]   sample-client-connector

If you wanted to run a portion of the larger build, you would use the -pl or --projects option with the -am or --also-make option. When you specify a project with the -am option, Maven will build all of the projects that the specified project depends upon (either directly or indirectly). Maven will examine the list of projects and walk down the dependency tree, finding all of the projects that it needs to build.

If you are working on the multi-module project with the build order shown in Example 6.2, “Order of Project Builds in Maven Reactor” and you were only interested in working on the sample-services project, you would run mvn -pl simple-services -am to build only those projects

$ mvn --projects sample-services --also-make install
[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   sample-parent
[INFO]   sample-model
[INFO]   sample-persist
[INFO]   sample-services

While the -am command makes all of the projects required by a particular project in a multi-module build, the -amd or --also-make-dependents option configures Maven to build a project and any project that depends on that project. When using --also-make-dependents, Maven will examine all of the projects in our reactor to find projects that depend on a particular project. It will automatically build those projects and nothing else.

If you are working on the multi-module project with the build order shown in Example 6.2, “Order of Project Builds in Maven Reactor” and you wanted to make sure that your changes to sample-services did not introduce any errors into the projects that directly or indirectly depend on sample-services, you would run the following command:

$ mvn --projects sample-services --also-make-dependents install
[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   sample-services
[INFO]   sample-admin-webapp
[INFO]   sample-webapp
[INFO]   sample-rest

When using --also-make, Maven will execute a subset of the larger build as shown in Section 6.2.4, “Making a Subset of Projects”. Combining --project, --also-make, and --resume-from provides you with the ability to refine your build even further. The -rf or --resume-from resumes the build from a specific point in the Reactor build order.

$ mvn --projects sample-webapp --also-make \
      --resume-from sample-services install
[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   sample-services
[INFO]   sample-util
[INFO]   sample-security
[INFO]   sample-webapp

In this example, the build is resumed from sample-services which omits the sample-persist and sample-model projects from the build. If you are focused on individual components and you need to accelerate your build times, using these advanced reactor options together is a great way to skip portions of your large multi-module project build. The --resume-from argument also works with --also-make-dependents.