Creating an Organization POM

As previously mentioned in this chapter, consistency is important when setting up your build infrastructure. By declaring shared elements in a common parent POM, project inheritance can be used to assist in ensuring project consistency.

While project inheritance was limited by the extent of a developer’s checkout in Maven 1.0 – that is, the current project – Maven 2 now retrieves parent projects from the repository, so it’s possible to have one or more parents that define elements common to several projects. These parents (levels) may be used to define departments, or the organization as a whole.

As an example, consider the Maven project itself. It is a part of the Apache Software Foundation, and is a project that, itself, has a number of sub-projects (Maven, Maven SCM, Maven Continuum, etc.). As a result, there are three levels to consider when working with any individual module that makes up the Maven project. This project structure can be related to a company structure, wherein there’s the organization, its departments, and then the teams within those departments. Any number of levels (parents) can be used, depending on the information that needs to be shared.

To continue the Maven example, consider the POM for Maven SCM:

<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-parent</artifactId>
    <version>1</version>
  </parent>
  <groupId>org.apache.maven.scm</groupId>
  <artifactId>maven-scm</artifactId>
  <url>http://maven.apache.org/maven-scm/</url>
  [...]
  <modules>
    <module>maven-scm-api</module>
    <module>maven-scm-providers</module>
    [...]
  </modules>
</project>

If you were to review the entire POM, you’d find that there is very little deployment or repository-related information, as this is consistent information, which is shared across all Maven projects through inheritance.

You may have noticed the unusual version declaration for the parent project. Since the version of the POM usually bears no resemblance to the software, the easiest way to version a POM is through sequential numbering. Future versions of Maven plan to automate the numbering of these types of parent projects to make this easier.

It is important to recall, from section 3.7, that if your inherited projects reside in an internal repository, then that repository will need to be added to the settings.xml file in the shared installation (or in each developer’s home directory).

If you look at the Maven project’s parent POM, you’d see it looks like the following:

<project>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.apache</groupId>
    <artifactId>apache</artifactId>
    <version>1</version>
  </parent>
  <groupId>org.apache.maven</groupId>
  <artifactId>maven-parent</artifactId>
  <version>5</version>
  <url>http://maven.apache.org/</url>
  [...]
  <mailingLists>
    <mailingList>
      <name>Maven Announcements List</name>
      <post>announce@maven.apache.org</post>
      [...]
    </mailingList>
  </mailingLists>

  <developers>
    <developer>
    [...]
    </developer>
  </developers>
</project>

The Maven parent POM includes shared elements, such as the announcements mailing list and the list of developers that work across the whole project. Again, most of the elements are inherited from the organization-wide parent project, in this case the Apache Software Foundation:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.apache</groupId>
  <artifactId>apache</artifactId>
  <version>1</version>
  <organization>
    <name>Apache Software Foundation</name>
    <url>http://www.apache.org/</url>
  </organization>
  <url>http://www.apache.org/</url>
  [...]
  <repositories>
    <repository>
      <id>apache.snapshots</id>
      <name>Apache Snapshot Repository</name>
      <url>http://svn.apache.org/maven-snapshot-repository</url>
      <releases>
        <enabled>false</enabled>
      </releases>
    </repository>
  </repositories>
  [...]
  <distributionManagement>
    <repository>
      [...]
    </repository>
    <snapshotRepository>
      [...]
    </snapshotRepository>
  </distributionManagement>
</project>

The Maven project declares the elements that are common to all of its sub-projects – the snapshot repository (which will be discussed further in section 7.6), and the deployment locations.

An issue that can arise, when working with this type of hierarchy, is regarding the storage location of the source POM files. Source control management systems like CVS and SVN (with the traditional intervening trunk directory at the individual project level) do not make it easy to store and check out such a structure.

These parent POM files are likely to be updated on a different, and less frequent schedule than the projects themselves. For this reason, it is best to store the parent POM files in a separate area of the source control tree, where they can be checked out, modified, and deployed with their new version as appropriate. In fact, there is no best practice requirement to even store these files in your source control management system; you can retain the historical versions in the repository if it is backed up (in the future, the Maestro Repository Manager will allow POM updates from a Web interface).