Sonatype

Seperation of Concerns

A good practice to follow for maintaining system integrity, which is the the true role of an architect (don't let anyone tell you differently). Maven helps guide your project design into a good best-practice seperation of concerns (SoC).

More on Coordinates

We mentioned coordinates in Chapter 2. They are mentioned again here because of their central importance to Maven's ability to manage project relationships. Coordinates are Maven's way of tracking a specific project, like an address, but with a temporal aspect. More than pinpointing a specific project, Maven can pinpoint a specific project in time by its "version" element. Coordinates are used by dependency, plugin and extension elements, as well as for defining inheritence, and anywhere else the project or goal configuration may need to know information about including - or excluding - a specific project.

If we go up to the parent pom.xml file of the Killer App project you will see the coordinates peppered throughout the file. Most obvious is the project's own required coordinate definition:

<project>
  <groupId>com.training.killerapp</groupId>
  <artifactId>killerapp</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>
  ...
</project>

The version element is always required in some capacity. If not specifically specified where you see it, it is likely specified in a parent project, or some sort of management meta-element, or may be inferred through a plugin. The other element you will notice is the packaging element. This tells Maven that the artifact created by this project is a single file: the POM - albeit a possibly annotated version of it. The default packaging type is a jar, and so the default coordinate assumes this is the case.

Whereas the my-app project of the previous chapter had the coordinates mavenbook:my-app:jar:1.0-SNAPSHOT this project is represented as com.training.killerapp:killerapp:pom:1.0-SNAPSHOT.

How does Maven use these coordinates? In multiple ways. Firstly, it uses them to retrieve the specific projects from remote and local repositories. It also uses coordinates to decifer how project hierarchies fit together, and plugins use them for a wide array of things, such as the maven-war-plugin, that uses coordinates to decide what projects to package into the war.

If you have run mvn install on this project, you may wonder what it means to "install" a project. In Maven, installing a project means placing a copy of the project's POM and the generated artifact (in jar packaging type projects, the artifact is a JAR; in pom projects, the artifact is only the POM, etc.) to a local directory structure mirroring the groupId, artifactId and version of the coordinate. The default location for your local repository is .m2/repository under your base user directory (retrieved from Java's "user.home" property) represented as ${user.home}. Each artifact is under its groupId - with dot-notation seperated into directory hierarchy. This is similar to Java's packaging structure. The groupId is followed by the artifactId, followed by version. The POM file can be found under this directory, named as the artifactId-version.pom.

In general, the project's packaged artifact lives with its pom, resulting in the following two files (not including optional checksum files, like md5):

groupId/artifactId/version/artifactId-version.pom
groupId/artifactId/version/artifactId-version.packaging

For our example, the "killerapp" project you have installed above will reside under:

${user.home}/.m2/repository/com/training/killerapp/killerapp/1.0-SNAPSHOT/killerapp-1.0-SNAPSHOT.pom

Since it is a pom type project, the pom.xml file is its own artifact. The killerapp-api project, on the other hand, it a jar project, thus yeilding the following files installed into the local repository:

${user.home}/.m2/repository/com/training/killerapp/killerapp-api/1.0-SNAPSHOT/killerapp-api-1.0-SNAPSHOT.jar
${user.home}/.m2/repository/com/training/killerapp/killerapp-api/1.0-SNAPSHOT/killerapp-api-1.0-SNAPSHOT.pom

We cover local and remote repositories with more depth in Chapter 13. For now simply note the relationship between project coordinates and where they are installed.

Dependencies

The most immediately useful piece of Maven's project relationship mechanism is project dependencies. A dependency is any project that is required by this project to perform some function. That function could be compilation, testing or simply runtime.

Before Maven most build systems would require the build user to provide the dependencies of a project on their own. A common method of dealing with this problem was to check in required binaries to version control, which has problems of its own, wasting a significant amount of bandwidth and disk space. Typically you would want the jars to be contained by your tree so that they can be versioned along with it. This may mean that each development branch on a machine has a copy of those jars. It also means they are checked for diffs each time a commit is done. Since they rarely change, another common pattern is to locate the jars in a tree separate from the source. This works around the problems mentioned above, but now you lose reproducibility over time. Another common problem is that the jars aren't versioned in their file name so it's difficult to determine what versions are actually present. These /lib folders tend to become dumping grounds for jars over time that are difficult to keep in sync with the actual dependencies used.

Most of the projects in the killerapp have dependencies. The dependency list of the parent killerapp project is as follows:

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

Simple! This specifies the coordinates for a project that the killerapp depends upon, as well as the scope of the dependency. Notice that the packaging type is not specified. That is because, like the POM definition itself, the type defaults to "jar" when not specified. Note that junit is required for testing only. That means that for the project compilation or normal runtime, junit is not necessary. However, the project build will only succeed with junit available in the repository, since that would cause the test to fail. The valid scope types are:

• compile - this is the default scope, used if none is specified. Compile dependencies are available in all classpaths.
• provided - this is much like compile, but indicates you expect the JDK or a container to provide it. It is only available on the compilation classpath (not runtime), is not transitive, nor is it packaged.
• runtime - this scope indicates that the dependency is not required for compilation, but is for execution. It is in the runtime and test classpaths, but not the compile classpath.
• test - this scope indicates that the dependency is not required for normal use of the application, and is only available for the test compilation and execution phases.
• system - this scope is similar to provided except that you have to provide the JAR which contains it explicitly. The artifact is always available and is not looked up in a repository. If you declare the scope to be system you must also provide the systemPath element. Note that this scope is not recommended, and will likely be removed in future versions of Maven (it is always desired that libraries are in the Maven repository).

    <dependency>
      <groupId>com.training.killerapp</groupId>
      <artifactId>killerapp-core</artifactId>
      <version>${project.version}</version>
      <classifier>memory</classifier>
      <exclusions>
        <exclusion>
          <groupId>com.training.killerapp</groupId>
          <artifactId>killerapp-store-xstream</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

major.minor.bug_fix-qualifier-build_number

1.3.5-alpha-1

1.3.5-alpha-1-SNAPSHOT

    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>[3.8,4.0)</version>
      <scope>test</scope>
    </dependency>

Multi-module

Multi-module projects are pom type projects that contain a list of modules to build. Simple, elegant, and filled with vast potential, multi-module projects are always of packaging type "pom". This is because they do not (normally) produce artifacts of their own, but exist merely to group together other projects - and sometimes other multi-modules. The killerapp:killerapp:pom:1.0-SNAPSHOT project is a multi-module project since it contains a list of modules that can be managed as a group. We have already touched on the power of these projects when we ran "mvn install" under the base directory. When the Maven commandline printed out the following list:

[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO]   Killer App
[INFO]   Killer App Model
[INFO]   Killer App API
[INFO]   Killer App Stores
[INFO]   Killer App Memory Store
[INFO]   Killer App XStream Store
[INFO]   Killer App Core
[INFO]   Killer App Commandline Interface
[INFO]   Killer App Web WAR

It discovered the list because they were added as modules, and those modules were the names of directories immediately under the current POM ${basedir} (the current project's base directory). The Killer App Stores project is also a multi-module - manages Memory and XStream Stores.

Note that we call the projects under the multi-module projects "modules" and not "children" or "child projects". This is purposeful, so as not to confuse projects grouped by multi-module project with another type of project relationship: inheritence.

Inheritence

Under the killerapp-api project type the following command:

 mvn help:effective-pom

Comparing that pom.xml to the contents of the killerapp-api's pom.xml should yield surprising results. Mailing lists? JUnit and killerapp-model version in the dependency list? And other information we have not encountered before, such as the build element and child elements. Were did all of this data come from? Peeking at the parent killerapp project should yield some answers. The killerapp-model (and, indeed, all of the projects in the Killer App) inherit from the com.training.killerapp:killerapp project, declared in each POM via the parent element.

  <parent>
    <groupId>com.training.killerapp</groupId>
    <artifactId>killerapp</artifactId>
    <version>1.0-SNAPSHOT</version>
  </parent>

Remember above we mentioned that groupId/artifactId/versionId are required in some capacity? The killerapp-api POM does not specify a groupId or version. It inherits those values from the parent. Maven assumes that the parent is either installed into the local repository, or available in the parent directory (../pom.xml) of the current project. If neither is true (for example, some organizations prefer to put the parent project in its own directory) this default may be overridden via the relativePath - for example: ../parent-project/pom.xml.

• dependencies
• developers and contributors
• plugin lists
• reports lists
• plugin executions with matching ids
• plugin configuration

Oftentimes a set of projects will require similar values for the set. Just like the inheritence of any other object oriented system (of which Maven is one... it is the Project Object Model afterall) child projects will inherit many of a parent projects values.

The Ultimate Parent

All POMs ultimately inherit from the SuperPOM. The SuperPOM plays a similar role to Java's java.lang.Object class. It is a set of pre-defined values from which all other POMs minimally inherit. This is Convention over Configuration at work. Since there are several values required for proper POM operation, and most of these values are similar for many projects, they are set as the default values of all POMs. The specific values of the SuperPOM can be found in Appendix A. Some important values to note from the SuperPOM are under the "build" element.

The build element defines information directly concerning a project's build settings (as opposed to, say, the project's name - like "Killer App API"). Up until now we have built the projects without concern for how Maven knows where to look for a project's files, and how it knows where to build and place its artifact. This information is configurable by any Maven project, but inherits certain defaults from the Maven SuperPOM. Any directories which are not absolute (begins with a / in unix environment, a driver letter like C: in windows) are assumed to be relative to the project's base directory (or ${basedir}.

<project>
  ...
  <build>
    <!-- the base directory where build artifacts are placed -->
    <directory>target</directory>

    <!-- where compiled files are placed -->
    <outputDirectory>target/classes</outputDirectory>

    <!-- The name of the final artifact sans extension (or possible classifiers) -->
    <finalName>${artifactId}-${version}</finalName>

    <!-- where compiled test files are placed -->
    <testOutputDirectory>target/test-classes</testOutputDirectory>

    <!-- Where the Java source files are expected to be -->
    <sourceDirectory>src/main/java</sourceDirectory>

    <!-- Where non-Java script source files are expected to be -->
    <scriptSourceDirectory>src/main/scripts</scriptSourceDirectory>

    <!-- Where the test Java source files are expected to be -->
    <testSourceDirectory>src/test/java</testSourceDirectory>
    <resources>
      <resource>
        <!-- Where non-compiled files reside (such as .properties file). They are put into the outputDirectory -->
        <directory>src/main/resources</directory>
      </resource>
    </resources>
    <testResources>
      <testResource>
        <!-- Where non-compiled files reside. They are put into the testOutputDirectory -->
        <directory>src/test/resources</directory>
      </testResource>
    </testResources>
  </build>
  ...
</project>

There is more to being a parent than just defining defaults for all of its children to inherit. Sometimes the parent needs to be able to manage a child's settings if it requires them at all. Enter the dependencyManagement element.

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.training.killerapp</groupId>
        <artifactId>killerapp-model</artifactId>
        <version>${project.version}</version>
      </dependency>
      ...
    <dependencies>
  </dependencyManagement>

Multi-module versus Inheritance

To re-tread on the previous field, there is a difference between inheriting from a parent project, and being managed by an multi-module project. A parent project is one that passes its values to its children. This is different from a multi-module project, where it merely manages a group of other sub-project or module - however no values are actually passed to the modules it manages. Because of this disconnect - and it is commonly desired that a single project both manage a group of projects as well as set values they they can each utilize - a parent project will commonly contain its children as modules (such as killerapp and killerapp-stores). This is not to believe that inheritence and multi-modules are related - so do not be confused - they are merely complimentary - yet a best practice to follow for simplicity and cohesion (only one top-level "master" project).

All Together

Maven's goal is to make project management conceptually simpler. When we put the projects above together we get the following.

There are more complex pieces for certain, for example inheriting dependencies, or dependency scope. However, understanding the above graph will take you a long way to understanding Maven's project relationship combinations.

Comprehensive Overview

You can find more details about the POM 4.0.0 structure in Appendix 1.

Properties

Properties are an excellent way of helping to "future-proof" your POM - especially in combination with a Parent POM. Check out the Tips and Tricks section in Appendix 3: Properties: Synchronize versions/groups with an Inherited Property.

Dependency Groupers

This is a simple trick used to keep a set of dependencies grouped together. For example, the Microsoft SQLServer JDBC implementation which consists of three jars: msbase.jar, msutil.jar, and mssqlserver.jar. The following example assumes that you have a repository containing these jars, grouped under "com.microsoft":

<project>
  <groupId>com.mycompany</groupId>
  <artifactId>jdbc</artifactId>
  <version>1.0</version>
  <packaging>pom</packaging>
  <dependencies>
    <dependency>
      <groupId>com.microsoft</groupId>
      <artifactId>msbase</artifactId>
      <version>${msJdbcVersion}</version>
    </dependency>
    <dependency>
      <groupId>com.microsoft</groupId>
      <artifactId>msutil</artifactId>
      <version>${msJdbcVersion}</version>
    </dependency>
    <dependency>
      <groupId>com.microsoft</groupId>
      <artifactId>mssqlserver</artifactId>
      <version>${msJdbcVersion}</version>
    </dependency>
  </dependencies>
  <properties>
    <msJdbcVersion>(1.0,)</msJdbcVersion>
  </properties>
</project>

Install the above project - since it's packaging type is "pom" rather than something like "jar", this file alone is placed into the repository. You can now add this project as a dependency (do not forget to add the "pom" type) and all of it's dependencies will be added to your project - the power of transitive dependencies at work!

<project>
  <description>This is a project requiring JDBC</description>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>com.mycompany</groupId>
      <artifactId>jdbc</artifactId>
      <version>1.0</version>
      <type>pom</type>
    </dependency>
  </dependencies>
</project>

If you later decide to switch to a different JDBC driver, for example, JTDS, just replace the dependencies in the com.mycompany:jdbc project to use net.sourceforge.jtds:jtds and update the version. All of your dependant projects will use jtds if they decide to update to the newer version. It is an easy way to roll out mass changes without breaking anyone unexpectedly.

<project>
  <groupId>com.mycompany</groupId>
  <artifactId>jdbc</artifactId>
  <version>1.0</version>
  <packaging>pom</packaging>
  <dependencies>
    <dependency>
      <groupId>net.sourceforge.jtds</groupId>
      <artifactId>jtds</artifactId>
      <version>1.2</version>
    </dependency>
  </dependencies>
</project>