Parent POM file

When we deal with hundreds of Maven modules, we need to structure the project to avoid any redundancies or any duplicate configurations. If not, it will lead to a huge maintenance nightmare. Let's have a look at some popular open source projects.

The WSO2 Carbon Turing branch, which is available at https://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/, has more than 1000 Maven modules. Anyone who downloads the source code from the root should be able to build the complete source, with all components. The pom.xml file at the root acts as a module-aggregating POM. It defines all Maven modules that need to be built under the <modules> element. Each module element defines the relative path (from the root POM file) to the corresponding Maven module. There needs to be another POM file under the defined relative path. The root POM in the WSO2 Carbon Turing project only acts as an aggregator module. It does not build any parent-child relationships with other Maven modules. The following code snippet shows the module configuration in the root pom.xml file

<modules>
  <module>parent</module>
  <module>dependencies</module>
  <module>service-stubs</module>
  <module>components</module>
  <module>platform-integration/clarity-framework</module>
  <module>features</module>
  <module>samples/shopping-cart</module>
  <module>samples/shopping-cart-global</module>
</modules>

Now, let's have a look at the POM file inside the parent module. This POM file defines plugin repositories, a distribution repository, plugins, and a set of properties. This does not have any dependencies, and this is the POM file that acts as the parent for other Maven submodules. The parent POM file has the following coordinates:

<groupId>org.wso2.carbon</groupId>
<artifactId>platform-parent</artifactId>
<version>4.2.0</version>
<packaging>pom</packaging>

If you look at the POM file inside the components module, it refers parent/pom.xml as the parent Maven module. The value of the relativePath element, by default, refers to the pom.xml file one level above, that is, ../pom.xml. However, in this case, it is not the parent POM file; hence, the value of the element must be overridden and set to ../parent/pom.xml, as shown here:

<groupId>org.wso2.carbon</groupId>
<artifactId>carbon-components</artifactId>
<version>4.2.0</version>
<parent>
  <groupId>org.wso2.carbon</groupId>
  <artifactId>platform-parent</artifactId>
  <version>4.2.0</version>
  <relativePath>../parent/pom.xml</relativePath>
</parent>

If you go inside the components module and run mvn help:effective-pom, you will notice that the effective POM aggregates both the configurations defined in parent/pom.xml and components/pom.xml. Parent POM files help to propagate common configuration elements to the downstream Maven modules, and it can go up to many levels. The components/pom.xml file acts as a parent POM file for Maven modules below that. For example, let's have a look at the following components/identity/pom.xml file. It has a reference to the components/pom.xml file as its parent. Note that here we do not need to use the relativePath element, as the corresponding parent POM is at the default location:

<groupId>org.wso2.carbon</groupId>
<artifactId>identity</artifactId>
<version>4.2.0</version>
<parent>
  <groupId>org.wso2.carbon</groupId>
  <artifactId>carbon-components</artifactId>
  <version>4.2.0</version>
</parent>