Installing Maven on any platform is a straightforward task. At the time of writing this book, the latest version is 3.2.3, which is available to download from http://maven.apache.org/download.cgi. This version requires JDK 1.6.0 or above. You should keep a note of the Java requirement for version 3.2.3 if you are planning to upgrade from version 3.0.0 family or 3.1.0 family. Prior to Maven 3.2.1, the only requirement was JDK 1.5.0.

Apache Maven is an extremely lightweight distribution. It does not have any hard requirements in terms of memory, disk space, or CPU. Maven is built on top of Java and will work on any operating system that runs a Java Virtual Machine (JVM).

$ mvn –version

Once you have installed Maven in your system, the next step is to fine-tune it for optimal performance. By default, the maximum heap allocation is 256 - 512 MB (-Xms256m to -Xmx512m). This default limit does not work while building a large, complex Java project, and it is recommended that you have at least 1024 MB of maximum heap. If you encounter the java.lang.OutOfMemoryError error at any point during a Maven build, it is mostly due to the lack of memory. You can use the MAVEN_OPTS environment variable to set the maximum allowed heap size for Maven at a global level.

The following command will set the heap size in Linux. Make sure that the value set as the maximum heap size does not exceed your system memory of the machine that runs Maven.

$ export MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=128m"

If you are on Microsoft Windows, use the following command:

$ set MAVEN_OPTS=-Xmx1024m -XX:MaxPermSize=128m

Here -Xmx takes the maximum heap size and -XX:MaxPermSize takes the maximum PermGen size.

The most popular way of starting a Maven build is by using the mvn clean install command. This will build all the Maven modules under your project and install the artifacts to your local repository. For a simple project, the entire build process will take less than a minute. However, for a large project, to create an online build with a clean repository could even take more than 3 hours: this is not an exaggeration. If you look at the WSO2 Carbon complete code base, the complete build process takes more than four hours to run with all the test cases. During a long-running build process, it is extremely important that we monitor the build properly.

The following screenshot shows an overview of the JVisualVM tool running a Maven build:

The JVisualVM tool that comes with the JDK distribution can be used to monitor a running Maven build. First, we need to start the Maven build and then start JVisualVM using the following command:

$ jvisualvm

This command will start the JVisualVM tool. Once the tool gets started, select org.codehaus.plexus.classworlds.launcher.Launcher from the Applications tab to monitor the running Maven build. You can gather many important statistics using JVisualVM, and based on that you can optimize your system resources for an optimal Maven build.

The following screenshot shows JVisualVM statistics of a running Maven build:

For a developer, remote debugging is a must-have feature for any build system. Why do we need remote debugging for a build system? This is extremely useful when you run your tests through the build itself. If any of the tests fail during the build, you should be able to debug and pinpoint the problem. The following command will run Maven in the debugging mode:

$ mvn clean install -Dmaven.surefire.debug

When the build starts to execute tests, it will be paused to connect with an IDE. You can connect Eclipse, NetBeans, or your favorite IDE to port 5005 in order to start remote debugging. By default, Maven opens up port 5005 for remote debugging.

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Listening for transport dt_socket at address: 5005

The default listening port number can be changed by setting the value of address appropriately. When you set the value of the suspend variable to y, the Maven build will stop until an IDE gets connected to it. If you want the build to continue and connect the IDE later, then set the value to n. To get full control over the debugging options, you can use the following command:

$ mvn clean install -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent -Djava.compiler=NONE"

Convention over configuration is one of the main design philosophies behind Apache Maven. Let's go through a few examples.

A complete Maven project can be created using the following code snippet in pom.xml file:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.packt</groupId>
  <artifactId>sample-one</artifactId>
  <version>1.0.0</version>
</project>

<project xmlns=http://maven.apache.org/POM/4.0.0xmlns:xsi=………xsi:schemaLocation="…">

Copy the previous configuration element and create a pom.xml file out of it. Then, place it in a directory called chapter-01 and create the following child directories under it:

Now, you can place your Java code under chapter-01/src/main/java and test cases under chapter-01/src/test/java. Use the following command to run the Maven build:

$ mvn clean install

This little configuration is tied up with many conventions:

If someone needs to override the default, conventional behavior of Maven, that is possible too. The following sample pom.xml file shows how to override some of the preceding default values:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.packt</groupId>
  <artifactId>sample-one</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <build>
    <sourceDirectory>${basedir}/src/main/java</sourceDirectory>
    <testSourceDirectory>${basedir}/src/test/java
    </testSourceDirectory>
    <outputDirectory>${basedir}/target/classes
    </outputDirectory>
  </build>
</project>