This chapter will introduce Apache Maven. If you are an advanced Maven user, you can simply jump into the next chapter. Even for an advanced user, it is highly recommended that you at least brush through this chapter, as it will be helpful to make sure that we are on the same page as we proceed.
In this chapter, we will be discussing about the following topics:
Installing and configuring Maven on Ubuntu, Mac OS X, and Microsoft Windows
IDE integration
Tips and tricks to use Maven effectively
Apache Maven is popular as a build tool. However, in reality, it goes beyond being just a build tool. It provides a comprehensive build management platform. Prior to Maven, developers had to spend a lot of time in building a build system. There was no common interface. It differed from project to project—each time a developer moved from one project to another, there was a learning curve. Maven filled this gap by introducing a common interface. It ended the era of "the build engineer."
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).
Installing Maven on Ubuntu just needs a single-line command. Proceed with the following steps:
Run the following
apt-getcommand in the command prompt; you need to have thesudoprivileges to execute this:$ sudo apt-get install mavenThe installation takes a few minutes to complete. Upon the completion of the installation, you can run the following command to verify the installation:
$ mvn -versionYou should get an output similar to the following one if Apache Maven has been installed successfully:
$ mvn -version Apache Maven 3.2.3 Maven home: /usr/share/maven Java version: 1.7.0_60, vendor: Oracle Corporation Java home: /usr/lib/jvm/java-7-oracle/jre Default locale: en_US, platform encoding: UTF-8 OS name: "linux", version: "3.13.0-24-generic", arch: "amd64", family: "unix"
Maven is installed under the
/usr/share/mavendirectory. To check the directory structure behind the Maven installation directory, use the following command:$ ls /usr/share/maven bin boot conf lib man
Maven configuration files can be found under the
/etc/mavendirectory using the following command:$ ls /etc/maven m2.conf settings.xml
If you don't want to work with the apt-get command, there is another way of installing Maven under any Unix-based operating system. We will discuss this in the next section. Since Mac OS X has a kernel built on top of the Unix kernel, installing Maven on Mac OS X would be the same as installing it on any Unix-based operating system.
Most of the OS X distributions prior to OS X Mavericks had Apache Maven preinstalled. To verify that you've got Maven installed in your system, try out the following command:
$ mvn –version
If it does not result in a version, this means you do not have Apache Maven installed.
The following steps will guide you through the Maven installation process:
First, we need to download the latest version of Maven. Throughout this book, we will use Maven 3.2.3, which is the latest version at the time of writing this book. The Maven 3.2.3 ZIP distribution can be downloaded from http://maven.apache.org/download.cgi.
Unzip the downloaded ZIP file and extract it to
/usr/share/javadirectory. You need to have thesudoprivileges to execute the following command:$ sudo unzip apache-maven-3.2.3-bin.zip -d /usr/share/java/If you already have Maven installed in your system, use the following command to unlink:
$ sudo unlink /usr/share/mavenUse the following command to create a symlink to the latest Maven distribution, which you just unzipped. You need to have the
sudoprivileges to execute the following command:$ sudo ln -s /usr/share/java/apache-maven-3.2.3 /usr/share/mavenVerify the Maven installation with the following command:
$ mvn -version Apache Maven 3.2.3 (33f8c3e1027c3ddde99d3cdebad2656a31e8fdf4; 2014-08-12T02:28:10+05:30) Maven home: /usr/share/maven Java version: 1.6.0_65, vendor: Apple Inc. Java home: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home Default locale: en_US, platform encoding: MacRoman OS name: "mac os x", version: "10.8.5", arch: "x86_64", family: "mac"
Note
Maven can also be installed on Mac OS X with Homebrew. Check out the video at this link, https://www.youtube.com/watch?v=xTzLGcqUf8k, which explains the installation process in detail.
First, we need to download the latest version of Maven. The Apache Maven 3.2.3 ZIP distribution can be downloaded from http://maven.apache.org/download.cgi. Next, perform the following steps:
Unzip the downloaded ZIP file and extract it to
C:\Program Files\ASFfolder.Set the
M2_HOMEenvironment variable and point it toC:\Program Files\ASF\apache-maven-3.2.3.Verify the Maven installation with the following command on the command prompt:
mvn –versionNote
To learn how to set the environment variables on Microsoft Windows, you can refer http://www.computerhope.com/issues/ch000549.htm.
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.
Note
Maven runs as a Java process on JVM. As Java proceeds with a build, it keeps on creating Java objects. These objects are stored in the memory allocated to Maven. This area of memory where Java objects are stored is known as heap. Heap is created at the JVM start, and it increases as more and more objects are created up to the defined maximum limit. The -Xms JVM flag is used to instruct JVM the minimum value it should set at the time it creates the heap. The -Xmx JVM flag sets the maximum heap size.
Permanent Generation (PermGen) is an area of memory managed by JVM, which stores the internal representations of Java classes. The maximum size of PermGen can be set by the -XX:MaxPermSize JVM flag.
To learn about the Maven OutOfMemoryError error, check out the information at this link: https://cwiki.apache.org/confluence/display/MAVEN/OutOfMemoryError.
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.
Note
WSO2 Carbon is a framework that is written on top of OSGi to build servers. All WSO2 products, which are 100 percent open source and released under Apache 2.0 license, are built on top of WSO2 Carbon. WSO2 Carbon code base is available at https://svn.wso2.org/repos/wso2/carbon/.
The following screenshot shows an overview of the JVisualVM tool running a Maven build:
Note
JVisualVM is a Java virtual machine monitoring, troubleshooting, and profiling tool. To learn more about it, refer http://docs.oracle.com/javase/6/docs/technotes/tools/share/jvisualvm.html.
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>
Tip
Downloading the example code
You can download the example code files from your account at http://www.packtpub.com for all the Packt Publishing books you have purchased. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
Note
The Maven POM file starts with the <project> element. Always define the <project/> element with the corresponding schema. Some tools can't validate the file without it.
<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:
chapter-01/src/main/javachapter-01/src/test/java
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:
The Java source code is available at
{base-dir}/src/main/javaTest cases are available at
{base-dir}/src/test/javaA JAR file type of artifact is produced
Compiled class files are copied into
{base-dir}/target/classesThe final artifact is copied into
{base-dir}/targetThe link http://repo.maven.apache.org/maven2is used as the repository
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>Most of the hardcore developers never want to leave their IDE. Not just coding, building, deploying, and testing, they would be happy to do everything (if possible) from the IDE itself. Most popular IDEs have support for Maven integration and they have developed their own plugins to support Maven.
NetBeans 6.7 or newer ships with inbuilt Maven integration, while NetBeans 7.0 and newer versions bundle a complete copy of Maven 3 and run it for builds just like you would from the command line. For Version 6.9 or older, you have to download a Maven build and configure the IDE to run that. More information corresponding to Maven and NetBeans integration is available at http://wiki.netbeans.org/MavenBestPractices.
IntelliJ IDEA has inbuilt support for Maven; hence, you don't need to perform any additional steps to install it. More information corresponding to Maven and IntelliJ IDEA integration is available at http://wiki.jetbrains.net/intellij/Creating_and_importing_Maven_projects.
The M2Eclipse project provides first class Maven support through the Eclipse IDE. More information corresponding to Maven and Eclipse integration is available at https://www.eclipse.org/m2e/.
Note
The book Maven for Eclipse, Packt Publishing, discusses Maven and Eclipse integration in detail (https://www.packtpub.com/application-development/maven-eclipse).
If everything works fine, we don't have to worry about troubleshooting. However, most of the time this is not the case. A Maven build could fail for many reasons—some are under your control, while others are beyond your control. Knowing proper troubleshooting tips helps you pinpoint the exact problem. The following sections list out some of the commonly used troubleshooting tips. We will expand the list as we proceed in this book.
Once Maven debug level logging is enabled, it will print all the actions it takes during the build process. To enable debug level logging, use the following command:
$ mvn clean install –X
If you find any issues with any dependencies in your Maven project, the first step is to build a dependency tree. This shows where each dependency comes from. To build the dependency tree, run the following command against your project POM file:
$ mvn dependency:tree
The following result shows the truncated output of the previous command executed against the Apache Rampart project:
[INFO] -------------------------------------------------------------- [INFO] Building Rampart - Trust 1.6.1-wso2v12 [INFO] -------------------------------------------------------------- [INFO] [INFO] --- maven-dependency-plugin:2.1:tree (default-cli) @ rampart-trust --- [INFO] org.apache.rampart:rampart-trust:jar:1.6.1-wso2v12 [INFO] +- org.apache.rampart:rampart-policy:jar:1.6.1-wso2v12:compile [INFO] +- org.apache.axis2:axis2-kernel:jar:1.6.1-wso2v10:compile [INFO] | +- org.apache.ws.commons.axiom:axiom-api:jar:1.2.11-wso2v4:compile (version managed from 1.2.11) [INFO] | | \- jaxen:jaxen:jar:1.1.1:compile [INFO] | +- org.apache.ws.commons.axiom:axiom-impl:jar:1.2.11-wso2v4:compile (version managed from 1.2.11) [INFO] | +- org.apache.geronimo.specs:geronimo-ws-metadata_2.0_spec:jar:1.1.2:compile [INFO] | +- org.apache.geronimo.specs:geronimo-jta_1.1_spec:jar:1.1:compile [INFO] | +- javax.servlet:servlet-api:jar:2.3:compile [INFO] | +- commons-httpclient:commons-httpclient:jar:3.1:compile [INFO] | | \- commons-codec:commons-codec:jar:1.2:compile [INFO] | +- commons-fileupload:commons-fileupload:jar:1.2:compile
If you have multiple JDKs installed in your system, you may wonder what is being used by Maven. The following command will display all the environment variables and system properties set for a given Maven project:
$ mvn help:system
The following result is the truncated output of the previous command:
========================Platform Properties Details================== ===================================================================== System Properties ===================================================================== java.runtime.name=Java(TM) SE Runtime Environment sun.boot.library.path=/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Libraries java.vm.version=20.65-b04-462 awt.nativeDoubleBuffering=true gopherProxySet=false mrj.build=11M4609 java.vm.vendor=Apple Inc. java.vendor.url=http://www.apple.com/ guice.disable.misplaced.annotation.check=true path.separator=: java.vm.name=Java HotSpot(TM) 64-Bit Server VM file.encoding.pkg=sun.io sun.java.launcher=SUN_STANDARD user.country=US sun.os.patch.level=unknown ======================================================== Environment Variables ========================================================= JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home HOME=/Users/prabath TERM_SESSION_ID=9E4F0D49-180D-45F6-B6FB-DFA2DCBF4B77 M2_HOME=/usr/share/maven/maven-3.2.3/ COMMAND_MODE=unix2003 Apple_PubSub_Socket_Render=/tmp/launch-w7NZbG/Render LOGNAME=prabath USER=prabath
Maven uses default values for the configuration parameters when those are not overridden at the project level configuration. This is exactly what we discussed under the convention over configuration section. If we take the same sample POM file we used before in this chapter, we can see how the effective POM file would look using the following command.
$ mvn help:effective-pom
This is also the best way to see what default values are being used by Maven. More details about the effective-pom command are discussed in Chapter 2, Demystifying Project Object Model.
The following command lists all the JAR files and directories in the build classpath:
$ mvn dependency:build-classpath
The following result shows the truncated output of the previous command, executed against the Apache Rampart project:
[INFO] -------------------------------------------------------------- [INFO] Building Rampart - Trust 1.6.1-wso2v12 [INFO] -------------------------------------------------------------- [INFO] [INFO] --- maven-dependency-plugin:2.1:build-classpath (default-cli) @ rampart-trust --- [INFO] Dependencies classpath: /Users/prabath/.m2/repository/bouncycastle/bcprov-jdk14/140/bcprov-jdk14-140.jar:/Users/prabath/.m2/repository/commons-cli/commons-cli/1.0/commons-cli-1.0.jar:/Users/prabath/.m2/repository/commons-codec/commons-codec/1.2/commons-codec-1.2.jar:/Users/prabath/.m2/repository/commons-collections/commons-collections/3.1/commons-collections-3.1.jar
This chapter focused on building a basic foundation of Maven to bring all the readers to a common ground. We discussed the basic steps to install and configure Maven in Ubuntu, Mac OS X, and Microsoft Windows operating systems. Then, we covered some of the common, useful Maven tips and tricks. As we proceed with the book, some of the concepts that we touched on in this chapter will be discussed in detail later.
In the next chapter, we will discuss Maven Project Object Model (POM) in detail.
