Section 3.1. Dividing and Conquering | Maven: A Developers Notebook (Developers Notebooks)

3.1. Dividing and Conquering

When developing object-oriented code, it is good practice to implement a separation-of-concerns strategy. In a complex software engineering effort, you manage complexity by organizing logic into components which are tightly focused (or concerned) with a specific part of a project or process. You can apply this same idea to a project's build. If you have a huge, multi-artifact project, having a big build with everything stuffed in is asking for maintenance hell. Fortunately, Maven is here to help us break down our project into subprojects.

3.1.1. How do I do that?

Let's take a web application example. Imagine a simple web application with a Servlet container showing the Quote of the Day (QOTD). Your first goal is to identify the different Maven subprojects you need to create to break such an application into distinct subprojects. The QOTD application uses Rome, a Really Simple Syndication (RSS) and Atom Utilities library, to parse a publicly available quote-of-the-day feed at http://www.quotationspage.com/data/qotd.rss.

Figure 3-1 illustrates the QOTD web application that has been separated into four interdependent modules. Each circle represents a separate Maven subproject which creates an artifact. Each arrow represents a dependency: the packager project depends on the web project, and the web project depends on the core project.

Figure 3-1. Maven subprojects for the QOTD web application

Here's a rundown of what each subproject contains:

core: The core subproject contains business logic for obtaining the quote of the day. Such logic is independent of any specific presentation layer, and core generates a JAR artifact named qotd-core-1.0.jar.
web: The web subproject contains all the classes for the QOTD web application. In this case, the web subproject is composed of servlets, JSP files, and HTML files. These classes depend on business logic from the core artifact to obtain quotes. The web subproject generates a WAR artifact named qotd-web-1.0.war.

Note: Break it up! Large projects are difficult to maintain. Do not hesitate to refactor your project into multiple subprojects.

acceptance: The acceptance subproject executes acceptance tests on the web application using HtmlUnit (http://htmlunit.sourceforge.net), which is a framework that extends JUnit to test web pages. To start your web application, you are going to use the Jetty plug-in, which uses the Jetty (http://jetty.mortbay.org) Servlet container. Thus, the acceptance subproject requires that both the core and web subprojects be built before its tests can be executed. Note that the acceptance subproject does not generate an artifact.
packager: packager generates a zip file containing the distribution of the web application project. The zip file contains the web application in a WAR file, and a README with installation instructions. In a real web application project, you could package a container so that the web application is a standalone application that can be executed as is by its users.

3.1.2. What about...

...having a single project with a single source directory? Why couldn't I just put the business logic and the packaging goals in the web project?

Note: A Maven project generates only one primary artifact.

You would soon find out that this is not possible with Maven if you wish to benefit from the existing plug-ins to the full extent. In Maven, the following rule applies: one build project must generate only one primary artifact (JAR, WAR, EAR, etc.)one project, one artifact. All the existing Maven plug-ins are built following this rule. Maven projects can generate multiple secondary artifacts such as JavaDoc files, sources packaged as zip files, and reports, but a single project can generate only a single primary artifact.

For example, the Java plug-in supports only a single source directory, so you wouldn't be able to elegantly use it for compiling sources located in different directories. The same applies for the Test plug-in, which can only execute unit tests located in a single source directory. Maven was designed with multiproject builds in mind, and for this reason you will find it impossible to create a monster "frankenproject" with a large, distributed source path.