Apache Maven Cookbook - Sample Chapter

28
Apache Maven Cookbook Raghuram Bharathan Quick answers to common problems Over 90 hands-on recipes to successfully build and automate development life cycle tasks following Maven conventions and best practices Free Sample

Transcript of Apache Maven Cookbook - Sample Chapter

Page 1: Apache Maven Cookbook - Sample Chapter

Apache Maven Cookbook

Raghuram Bharathan

Apache Maven Cookbook

What this book will do for you...

Install Apache Maven successfully on your preferred OS

Explore the various features of Apache Maven to build effi cient automation tools

Discover when and how to use the various Apache Maven plugins

Generate and publish your project documentation using Apache Maven

Analyze and control code quality and code coverage using Apache Maven

Build various types of Java projects as well as other binaries

Set up complex projects using the concept of inheritance

$ 49.99 US£ 32.99 UK

Prices do not include local sales tax or VAT where applicable

Inside the Cookbook... A straightforward and easy-to-follow format

A selection of the most important tasks and problems

Carefully organized instructions for solving the problem effi ciently

Clear explanations of what you did

Apply the solution to other situations

Quick answers to common problems

Apache Maven offers a comprehensive set of features to build, test, release, and deploy software projects and maintain enterprise development infrastructure.

This book is a hands-on guide that enables you to explore the vast potential of Apache Maven, the leading software build tool. You will start off by successfully installing Apache Maven on your favorite OS, and then you will create your fi rst working project. Furthermore, the book walks you through setting up and using Maven with popular Java Integrated Development Environments (IDEs) so you can exploit Maven features to build standard Java applications. Above all, you will also learn to create site reports and documentation for your project along with handling typical build requirements and other advanced Maven usages.

Raghuram

Bharathan

Apache M

aven Cookbook

Over 90 hands-on recipes to successfully build and automate development life cycle tasks following Maven conventions and best practices

P U B L I S H I N GP U B L I S H I N G

community experience dist i l ledP

UB

LIS

HIN

GP

UB

LIS

HIN

G

Visit www.PacktPub.com for books, eBooks, code, downloads, and PacktLib.

Free Sample

Page 2: Apache Maven Cookbook - Sample Chapter

In this package, you will find: The author biography

A preview chapter from the book, Chapter 1 'Getting Started'

A synopsis of the book’s content

More information on Apache Maven Cookbook

About the Author Raghuram Bharathan is a postgraduate in computer applications from the National

Institute of Technology, Trichy. In his career in the software industry, he has worked

with Hewlett-Packard, Cisco, and ThoughtWorks, among others. He is the cofounder of

Innoventes Technologies, a tech company involved in product engineering and providing

services in mobile and web applications.

He is experienced in enterprise web and mobile technologies and is well-versed in the

setting up, maintenance, and usage of various build automation tools, such as ANT,

Apache Maven, Gradle, and Buildr.

He has been using Apache Maven for more than 7 years in his projects and is one of the

top providers of answers for Maven in Stack Overflow.

Page 3: Apache Maven Cookbook - Sample Chapter

Apache Maven Cookbook Apache Maven Cookbook describes the features of Apache Maven through a series of

recipes. This book will help you understand what Apache Maven is and allow you to use

its features with the help of complete and working examples.

What This Book Covers Chapter 1, Getting Started, covers the installation of Apache Maven on Microsoft

Windows, Mac OS X, or Linux, as well as creating and building your first project with it.

The chapter also details the steps to install prerequisite software required for Maven.

Chapter 2, IDE Integration with Maven, focuses on configuring popular IDEs with the

help of Maven and running Maven projects in them. Eclipse, NetBeans, and IntelliJ

IDEA are the three IDEs covered in this chapter.

Chapter 3, Maven Lifecycle, covers the life cycle of Apache Maven and explores

the concept of phases and goals. It also describes how a user can use profiles to

customize builds.

Chapter 4, Essential Maven Plugins, describes the Maven plugins, which are essential to

build a project. For each plugin, the various configuration options are also explored.

Chapter 5, Dependency Management, explores the various types of Maven dependencies,

and delves into downloading and getting reports on them. It also talks about how to

handle network issues during a dependency download.

Chapter 6, Code Quality Plugins, covers the support provided for various code quality

tools, such as Checkstyle, PMD, FindBugs, and Sonar. The configuration options for

each plugin as well as generating reports are also explored.

Chapter 7, Reporting and Documentation, covers the reporting features of Maven. The

site plugins and the various reports supported by it are described in detail.

Chapter 8, Handling Typical Build Requirements, explores the features provided by

Maven to handle builds of selective sources and the inclusion of selected resources. It

also describes how to use the command line and help features of Maven along with

interfacing with software configuration management systems.

Chapter 9, Multi-module Projects, describes the support required to build large projects

with multiple modules. Maven support for aggregated builds and defining parent-child

relationships is also described here.

Page 4: Apache Maven Cookbook - Sample Chapter

Chapter 10, Java Development with Maven, describes the building of different types of

java artifacts like Jar, War and Ear. It also describes Maven support to run projects in

Jetty and Tomcat.

Chapter 11, Advanced Maven Usage, explores the advanced features of Maven, such as

creating distributions and enforcing rules. It also describes how to make a project release.

Page 5: Apache Maven Cookbook - Sample Chapter

1

1Getting Started

In this chapter, we will cover the basic tasks related to getting started with Apache Maven:

Installing Maven on Microsoft Windows

Installing Maven on Mac OS X

Installing Maven on Linux

Changing the JDK used by Maven

Creating a simple project with Maven

Building a simple project with Maven

Changing the location of the Maven repository

Running Maven behind an HTTP proxy server

Understanding the standard directory layout

IntroductionApache Maven is a popular tool for build automation, primarily Java projects. Maven addresses two aspects of building software. First, it describes how a software is built and, second, it describes its dependencies. It uses conventions for the build procedure. An XML fi le describes the software project being built, its dependencies on other external modules and components, the build order, directories, and required plugins. It comes with predefi ned targets to perform certain well-defi ned tasks, such as code compilation and its packaging. Maven dynamically downloads Java libraries and Maven plugins from one or more repositories, such as the Maven Central Repository, and stores them locally.

Ever since Maven 1.0 was released in 2004, it has gained popularity and is today the build tool for a large number of open source and commercial projects.

Page 6: Apache Maven Cookbook - Sample Chapter

Getting Started

2

If you are reading this book, then you are not here to understand why Maven is required. You are here to explore Maven and unleash the potential that it offers. The objective of this book is to make the reader aware of Maven's various features, which include installation, confi guration, and simple to complex usage by means of examples, illustrations, and working projects.

A brief comparison with other build automation toolsLet's briefl y discuss some build automation tools:

Make: If you are from the C programming world, chances are you have used Make. Makefi les are not platform-independent. They are not natively compatible with Windows. Thus, they are unsuited to build Java projects.

Ant: This is modeled after Make and has targets and dependencies. Each target has a set of tasks. Ant doesn't have any conventions. It is procedural and does not have the concept of a build lifecycle. Maven has conventions, is declarative, and has a lifecycle.

In this chapter, we will cover the basics of Maven—installing the software, verifying the installation, and creating, implementing, and building a simple Java project. We will also cover a few advanced items, such as changing the location of the repository or running Maven behind an HTTP proxy server as it could be relevant to those who have issues with the way Maven works by default.

Let us start by setting up Maven. We will cover how to do this on the three popular operating systems, namely Microsoft Windows, Mac OS X, and Linux.

Installing Maven on Microsoft WindowsAt the time of writing this book, Microsoft Windows 8.1 is the latest version of Microsoft Windows. While the screenshots and output will be for Microsoft Windows 8.1, the steps are similar for earlier (and possibly later) versions as well.

Getting readyAs Maven requires a Java platform, fi rst ensure that you have installed the Java environment on your system, Java Development Kit (JDK) specifi cally; Java Runtime Environment (JRE) is not suffi cient.

Page 7: Apache Maven Cookbook - Sample Chapter

Chapter 1

3

You can verify whether Java is installed on your system by opening Add or Remove Programs. If you see something similar to the following screenshot, JDK is installed on your system:

You can also verify the program folder structure from Microsoft Windows Explorer:

How to do it...Let's start installing Java and Maven by performing the following steps:

1. Set the variable JAVA_HOME to point to the Java installation that you want Maven to use; for example, you can do this by setting JAVA_HOME variable in the following way:

C:\projects\apache_maven_cookbook>set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_20

Page 8: Apache Maven Cookbook - Sample Chapter

Getting Started

4

Note that this setting will not be persisted once the command prompt is closed. To persist this, set Environment Variables... using the Control Panel option, as described later for the M2_HOME variable.

2. If JDK is not installed on your system, now is the time to download and install it from the Oracle Java SE download page at http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Once it is installed, ensure JAVA_HOME is set as described earlier.

Now that we have set up Java, let us download and set up Maven.

3. Go to http://maven.apache.org/ and click on the Download link.

4. The links to the latest stable versions of Maven are displayed.

5. The binaries are available in both, .zip and .tar.gz formats. Choose one of them.

6. Extract the downloaded binary to a folder you want Maven to reside in. In this case I have chosen C:\software.

It is best to avoid folders with spaces as some features of Maven or its plugins might not work.

7. Ensure the contents are similar to the following screenshot:

Page 9: Apache Maven Cookbook - Sample Chapter

Chapter 1

5

The preceding screenshot displays a list of directories contained in Maven.

Now let's briefl y discuss what these directories contain:

The bin folder contains the batch fi les and shell scripts to run Maven on various platforms.

The boot folder contains the jars required for Maven to start.

The conf folder contains the default settings.xml fi le used by Maven.

The lib folder contains the libraries used by Maven. It also contains an ext folder in which third-party extensions, which can extend or override the default Maven implementation, can be placed.

Now let us make sure we can run Maven from the command prompt by carrying out the following steps:

1. Open Control Panel:

Page 10: Apache Maven Cookbook - Sample Chapter

Getting Started

6

2. Choose Advanced system settings:

3. Click on Environment Variables.... Add the M2_HOME variable and set it to the folder where Maven was extracted.

4. Edit the PATH variable to include Maven's bin folder:

Page 11: Apache Maven Cookbook - Sample Chapter

Chapter 1

7

How it works...A Maven installation is essentially a set of JAR fi les, confi guration fi les, and a Microsoft Windows batch fi le, mvn.bat.

The mvn command essentially runs this batch fi le. It fi rst checks for JAVA_HOME. This fi le is present in the bin folder of the Maven installation and, hence, it needs to be in PATH.

If the batch fi le does not fi nd JAVA_HOME, it looks for Java in its PATH. This can lead to unexpected results, as typically the Java in PATH is usually the JRE and not the JDK.

The batch fi le then looks for M2_HOME, which is the location of the Maven installation. It does this so that it can load the libraries that are present.

Additionally, it also reads values specifi ed in MAVEN_OPTS. This variable allows you to run Maven with an additional heap size and other Java parameters.

Using the values for JAVA_HOME, M2_HOME, and Maven_OPTS, the batch fi le runs its main class org.codehaus.plexus.classworlds.launcher.Launcher.

There's more...Verify your Maven installation using the following steps:

1. Open a command prompt in Microsoft Windows and run the following command:

C:\software\apache-maven-cookbook>mvn -version

2. The following output should be displayed:

Apache Maven 3.2.5 (12a6b3acb947671f09b81f49094c53f426d8cea1; 2014-12-14T22:59:23+05:30)

Maven home: C:\software\apache-maven-3.2.5

Java version: 1.7.0_67, vendor: Oracle Corporation

Java home: C:\Program Files\Java\jdk1.7.0_67\jre

Default locale: en_IN, platform encoding: Cp1252

OS name: "windows 8.1", version: "6.3", arch: "amd64", family: "windows"

See also The Creating a simple project with Maven recipe in this chapter

Page 12: Apache Maven Cookbook - Sample Chapter

Getting Started

8

Installing Maven on Mac OS XLet us look at the steps to install Maven on Mac OS X. This applies to the latest version of Mac OS X, namely Yosemite.

Earlier, Apple provided Java for Mac, but stopped doing so from Java 7 onwards. Apple Java is not available on recent versions of Mac OS X.

Getting readyLet us check if the Java environment is available on your Mac:

1. Open the terminal and run the following command:

/usr/libexec/java_home -v 1.7

2. See if you get an output similar to the following:

/Library/Java/JavaVirtualMachines/jdk1.7.0_71.jdk/Contents/Home

3. Run the following command to check if you have Java 8:

/usr/libexec/java_home -v 1.8

4. This should give the following output if Java exists:

/Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home

As you can see, my system has both Java 1.7 and 1.8.

5. Set JAVA_HOME to the desired JDK. This can be done in two ways, depending on what you desire:

If this is for the duration of the session, run the following command:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home

If this is permanent, add the preceding line in .bash_profile in your HOME folder

Ensure you have the JDK installation and not JRE.

If Java is not present, download and install Java from the Oracle Java download page at http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Page 13: Apache Maven Cookbook - Sample Chapter

Chapter 1

9

Once installed, verify the Java installation by following the preceding steps.

Now, let us set up Maven on Mac OS X.

How to do it...Let's download Maven from its offi cial website by performing the following steps:

1. Go to http://maven.apache.org/ and click on the Download link. Links to the latest stable versions of Maven will be displayed.

2. The binaries are available in both .zip and .tar.gz formats. Choose one of them.

3. Extract the downloaded binary to the folder you want Maven to reside in. The typical location for the Mac is /usr/local folder.

4. You will need a super user (su) or administrator access to place the contents in the /usr/local folder. If you do not have access, you can place the contents in a subfolder of your HOME folder.

5. Ensure the contents are similar to the following output by executing the following command:

/usr/local/apache-maven-3.2.5$ ls -l

The output is shown as:

total 27

-rw-r--r-- 1 root wheel 17464 Aug 12 02:29 LICENSE

-rw-r--r-- 1 root wheel 182 Aug 12 02:29 NOTICE

-rw-r--r-- 1 root wheel 2508 Aug 12 02:26 README.txt

drwxr-xr-x 8 root wheel 4096 Aug 19 13:41 bin

drwxr-xr-x 3 root wheel 0 Aug 19 13:41 boot

drwxr-xr-x 4 root wheel 0 Oct 14 17:39 conf

drwxr-xr-x 67 root wheel 28672 Aug 19 13:41 lib

6. Set the M2_HOME variable as follows:

export M2_HOME=/usr/local/apache-maven-3.2.5

7. Update the PATH to include Maven's bin folder:

export PATH=$PATH:$M2_HOME/bin

Like JAVA_HOME, the preceding settings can be persisted by updating .bash_profile with the preceding lines.

Page 14: Apache Maven Cookbook - Sample Chapter

Getting Started

10

In the preceding steps, we discussed the steps to download Maven from its offi cial website. We will now discuss installing Maven using brew. Brew is a popular application on Mac OS X to install open source software. If you have brew installed on your Mac OS X, run the following command to install Maven:

brew install maven

The output for the preceding command will be displayed as shown in the following screenshot:

How it works...The Maven installation is essentially a set of JAR fi les, confi guration fi les, and a Mac OS X shell script, namely mvn.

The mvn command essentially runs this script. It fi rst checks for JAVA_HOME. This fi le is present in the bin folder of the Maven installation and, hence, it needs to be in PATH.

If the shell script does not fi nd JAVA_HOME, it looks for Java in its PATH. This can lead to unexpected results, as typically the Java in PATH is usually the JRE installation and not JDK.

The shell script then looks for M2_HOME, which is the location for the Maven installation. It does this so that it can load the libraries that are present.

Additionally, it also reads values specifi ed in MAVEN_OPTS. This variable allows you to run Maven with an additional heap size and other Java parameters.

Using the values for JAVA_HOME, M2_HOME, and MAVEN_OPTS, the shell script runs its main class org.codehaus.plexus.classworlds.launcher.Launcher.

There's more...Verify your Maven installation using the following steps:

1. Open a command prompt and run the following command:

mvn –version

Page 15: Apache Maven Cookbook - Sample Chapter

Chapter 1

11

2. The output for the preceding command should be displayed as shown in the following screenshot:

See also The Creating a simple project with Maven recipe in this chapter

Installing Maven on LinuxLet us look at the steps to install Maven on Linux.

While there are many fl avors of Linux (Ubuntu, Fedora, RHEL, SUSE, CentOS, and so on), the steps to set up Maven are similar.

Getting readyMaven needs Java, specifi cally the Java Development Kit (JDK). Using the following steps, let us check if it is installed in your Linux system, which is a bit tricky:

1. Open a terminal and run the following command:

java -version

2. See if you get an output similar to the following:

java version "1.7.0_65"

OpenJDK Runtime Environment (rhel-2.5.1.2.el6_5-x86_64 u65-b17)

The preceding output will still not tell you where your Java is installed, which is required to set JAVA_HOME. You can get this information by performing the next set of steps.

3. Check if javac works; it does only if JDK is installed, not JRE:

$ javac -version

The output for the preceding command is shown as:

javac 1.7.0_65

Page 16: Apache Maven Cookbook - Sample Chapter

Getting Started

12

4. Find the location of the javac command:

$ which javac

The output for the preceding command is shown as:

/usr/bin/javac

5. In the preceding output, javac is a symbolic link to the actual location of the fi le. Try to determine this location in the following way:

$ readlink /usr/bin/javac

The output for the preceding command is shown as:

/etc/alternatives/javac

6. By executing the preceding command, we again got the symbolic link. To get the path to the location of javac, we execute the following command again:

$ readlink /etc/alternatives/javac

The output for the preceding command is shown as:

/usr/lib/jvm/java-1.7.0-openjdk.x86_64/bin/javac

7. We have now located the folder where JDK is installed:

/usr/lib/jvm/java-1.7.0-openjdk.x86_64/

8. Set JAVA_HOME to the preceding folder. This can be done in two ways, depending on what you desire:

If it is for the duration of the session, run the following command:

export JAVA_HOME=/usr/lib/jvm/java-1.7.0-openjdk.x86_64/

If this is permanent, add the preceding line in .bash_profile in your HOME folder.

If Java is not present, download and install Java from the Oracle Java download page at http://www.oracle.com/technetwork/java/javase/downloads/index.html.

If you have an rpm-based Linux distribution, you can download and install rpm. Otherwise, you can download the .tar.gz format of the distribution and extract it to a folder of your choice.

In the earlier case, you know exactly where Java is installed and can set JAVA_HOME correspondingly. Once installed, verify the Java installation by following the preceding steps.

Now, let us set up Maven on Linux.

Page 17: Apache Maven Cookbook - Sample Chapter

Chapter 1

13

How to do it...To set up Maven on Linux, perform the following steps:

1. Go to http://maven.apache.org/ and click on the Download link. The links to latest stable versions of Maven will be displayed.

2. The binaries are available in both .zip and .tar.gz formats. For Mac OS X and Linux, the preferred download format is .tar.gz.

3. Extract the downloaded binary to a folder you want Maven to reside in. The typical location in Linux is the /usr/local folder.

You will need a super user (su) or administrator access to place contents in the /usr/local folder. If you do not have access, you can place this in a subfolder of your HOME folder.

4. Execute the following command, and ensure the contents of the apache-maven-3.2.5 folder are similar to the following output:

/usr/local/apache-maven-3.2.5$ ls -l

The output for the preceding command is shown as:

total 27

-rw-r--r-- 1 root root 17464 Aug 12 02:29 LICENSE

-rw-r--r-- 1 root root 182 Aug 12 02:29 NOTICE

-rw-r--r-- 1 root root 2508 Aug 12 02:26 README.txt

drwxr-xr-x 8 root root 4096 Aug 19 13:41 bin

drwxr-xr-x 3 root root 0 Aug 19 13:41 boot

drwxr-xr-x 4 root root 0 Oct 14 17:39 conf

drwxr-xr-x 67 root root 28672 Aug 19 13:41 lib

5. Set the M2_HOME variable as follows:

export M2_HOME=/usr/local/apache-maven-3.2.5

6. Update PATH to include Maven's bin folder:

export PATH=$PATH:$M2_HOME/bin

Like JAVA_HOME, the preceding settings can be persisted by updating .bash_profile.

Page 18: Apache Maven Cookbook - Sample Chapter

Getting Started

14

How it works...The Maven installation is essentially a set of JAR fi les, confi guration fi les, and a Linux shell script, namely mvn.

The mvn command essentially runs this script. It fi rst checks for JAVA_HOME. This fi le is present in the bin folder of the Maven installation and hence needs to be in PATH.

If the shell script does not fi nd JAVA_HOME, it looks for java in its PATH. This can lead to unexpected results, as typically, the Java in PATH is usually JRE and not JDK.

The shell script then looks for M2_HOME, which is the location of the Maven installation. It does this so that it can load the libraries that are present.

Additionally, it also reads values specifi ed in MAVEN_OPTS. This variable allows you to run Maven with an additional heap size and other Java parameters.

Using the values for JAVA_HOME, M2_HOME, and MAVEN_OPTS, the shell script runs its org.codehaus.plexus.classworlds.launcher.Launcher main class.

There's more...Using the following steps, let's confi rm that Maven has been set up correctly, by running a Maven command:

1. Open a command prompt and run the following command:

mvn –version

2. The following output should be displayed:

Apache Maven 3.2.5 (12a6b3acb947671f09b81f49094c53f426d8cea1; 2014-12-14T22:59:23+05:30)

Maven home: /usr/local/maven

Java version: 1.7.0_65, vendor: Oracle Corporation

Java home: /usr/lib/jvm/java-1.7.0-openjdk-1.7.0.65.x86_64/jre

Default locale: en_US, platform encoding: ANSI_X3.4-1968

OS name: "linux", version: "2.6.32-279.22.1.el6.x86_64", arch: "amd64", family: "unix"

If you get an error, recheck the installation steps and repeat them.

Page 19: Apache Maven Cookbook - Sample Chapter

Chapter 1

15

See also The Creating a simple project with Maven recipe in this chapter

Changing the JDK used by MavenIt is possible to have more than one version of JDK installed on your system. By following some simple steps, you can specify and/or change the JDK to be used by Maven.

How to do it...You will recall that, in the earlier section, we used Java SE 7. Let us now change to Java SE 8. To change the JDK version to Java SE 8 on Microsoft Windows, perform the following steps:

1. From the command prompt, run the following command:

set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_20

2. For Linux or Mac, the command will be:

export JAVA_HOME=<java-8-home-folder>

3. Now, run the following command to check the version of Maven installed:

mvn –version

4. To check the version of Maven installed on Microsoft Windows, run the following command from the command prompt. You should get the following output. The output will be similar for Linux and Mac:

C:\projects\apache-maven-cookbook>mvn -version

The output for the preceding command is shown as:

Apache Maven 3.2.5 (12a6b3acb947671f09b81f49094c53f426d8cea1; 2014-12-14T22:59:23+05:30)

Maven home: C:\software\apache-maven-3.2.5

Java version: 1.8.0_20, vendor: Oracle Corporation

Java home: C:\Program Files\Java\jdk1.8.0_20\jre

Default locale: en_IN, platform encoding: Cp1252

OS name: "windows 8.1", version: "6.3", arch: "amd64", family: "windows"

Page 20: Apache Maven Cookbook - Sample Chapter

Getting Started

16

How it works...Maven always uses the JDK specifi ed by JAVA_HOME, no matter how many JDK installations are available on the system. This allows the user the fl exibility to change JDKs as required or based on the project.

Hence, it is important to ensure JAVA_HOME is defi ned. In the absence of this variable, Maven attempts to detect the presence of Java from PATH. This is typically JRE and not JDK.

Creating a simple project with MavenNow that we have set up Maven on our favorite operating system and verifi ed that it works fi ne, it is time to create a simple Java project.

Maven makes it easy to bootstrap a new project by creating a bunch of fi les and folders following accepted conventions.

How to do it...Let's start creating the fi rst simple project using Maven, by performing the following steps:

1. Open a command prompt and change the directory to the folder in which you want to create your fi rst Maven project.

2. Run the following command:

mvn archetype:generate -DgroupId=com.packt.cookbook -DartifactId=simple-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

You can change the groupId and artifactId values in the preceding command as per your requirement.

3. You will see Maven downloading a bunch of fi les:

Downloading: https://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-clean-plugin/2.5/maven-clean-plugin-2.5.pom

Downloaded: https://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-clean-plugin/2.5/maven-clean-plugin-2.5.pom (4 KB at 1.4 KB/sec)

4. Then it will start generating sources:

[INFO] >>> maven-archetype-plugin:2.2:generate (default-cli) > generate-sources

@ standalone-pom >>>

Page 21: Apache Maven Cookbook - Sample Chapter

Chapter 1

17

5. When Maven has completed generating sources, it will create the project that we want:

[INFO] Using following parameters for creating project from Old (1.x) Archetype:maven-archetype-quickstart:1.0[INFO] ----------------------------------------------------------------------------[INFO] Parameter: groupId, Value: com.packt.cookbook[INFO] Parameter: packageName, Value: com.packt.cookbook[INFO] Parameter: package, Value: com.packt.cookbook[INFO] Parameter: artifactId, Value: simple-project[INFO] Parameter: basedir, Value: C:\projects\apache-maven-cookbook[INFO] Parameter: version, Value: 1.0-SNAPSHOT[INFO] project created from Old (1.x) Archetype in dir: C:\projects\apache-maven-cookbook\simple-project

Downloading the example code

You can download the example code fi les 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 fi les e-mailed directly to you.

How it works...Did you get an while error running the preceding command to create your simple project?

One possibility is that your Maven is behind an HTTP proxy server. If so, see the Running Maven behind an HTTP proxy server recipe in this chapter.

Let's look at the folder structure that is created:

Page 22: Apache Maven Cookbook - Sample Chapter

Getting Started

18

You will notice the following things:

The Maven project confi guration fi le pom.xml is created in the root of the simple-project folder. We will explore this fi le in detail in subsequent sections.

A bunch of folders are created:

src\main\java: This is for Java source files

src\test\java: This is for Java test source files

src\main\resources: This is for resource files for the project

src\test\resources: This is for resource files for the test

Within each of the preceding folders, a folder structure corresponding to the groupId (org.packt.cookbook) is created.

The following are essentially Maven conventions at work:

Maven expects all Java source fi les to reside in src\main\java

Similarly, it expects all Java test fi les to reside in src\test\java

It expects all project resources to reside in src\main\resources and test resources to reside in src\test\resources

It expects that source fi les will typically have the same package structure as the groupId parameter (though this is not mandatory)

Two sample classes, namely App.java and AppTest.java, are also created and it is not expected that they will be used beyond testing how Maven works

The mvn command that we used in the Creating a simple project with Maven recipe in this chapter, tries to invoke the generate goal of the archetype plugin with the specifi ed command-line parameters.

The default Maven installation has minimal features. All features of Maven are available as Maven plugins. When given a plugin name, Maven knows where to download it from and then run it.

In this case, Maven downloads the archetype plugin. This plugin, in turn, can depend on another plugin. In this case, the latter plugin gets downloaded. This happens in a recursive fashion and, at the end of the process, all the relevant plugins required to run the specifi ed command are downloaded.

These plugins are placed in your local repository, which is a location in your system. Once downloaded, these are never downloaded again unless deleted.

Page 23: Apache Maven Cookbook - Sample Chapter

Chapter 1

19

See also The Running Maven behind an HTTP proxy server recipe in this chapter

Building a simple project with MavenLet us now build the project that was created in the preceding section.

How to do it...To build the previously created simple project with Maven, perform the following steps:

1. Open the command prompt and run the following command, changing the directory to the folder the project was created:

mvn package

2. Observe the following things in the output:

Notice the following warning (we will see how to resolve this later in this book):

[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ simple-project ---

[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources,

i.e. build is platform dependent!

Check if the sources are compiled:

[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ simple-project

Check if the tests are run:

[INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ simple-project ---

[INFO] Surefire report directory: C:\projects\apache-maven-cookbook\simple-project\target\surefire-reports

-------------------------------------------------------

T E S T S

-------------------------------------------------------

Running com.packt.cookbook.AppTest

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.005 sec

3. A JAR fi le is now created.

Page 24: Apache Maven Cookbook - Sample Chapter

Getting Started

20

How it works...In the mvn package command, the package parameter is a phase in the build lifecycle. Maven has a default build lifecycle that has a number of phases. Each phase will execute every phase prior to it in order along with the specifi ed phase. In this case, the package phase executes in the following order:

Validate

Compile

Test

Package

The validate phase makes sure that the project (specifi cally the pom.xml fi le that describes the project) is in order and all the necessary information to run the project is available.

The compile phase compiles the sources.

The test phase compiles the test sources and then runs the test using a suitable test framework. In the earlier example, the JUnit framework is used to run the tests.

The package phase packages the artifacts to the format specifi ed in the pom.xml fi le.

Changing the location of the Maven repository

There are three types of Maven repositories:

Local: This is the repository in your computer fi lesystem Remote: This is the repository from where the required Maven fi les get downloaded Mirrors: These are repository managers, such as Nexus and Artifactory, that mirror

various repositories

You will have seen Maven downloading a number of fi les (called poms and jars). Let us see where they are located in your computer:

Go to your HOME folder (C:\Users\username) in the case of Microsoft Windows, /Users/username for Mac, and, /home/username (or a similar location) for Linux

You will notice the .m2 folder and within that, a subfolder called repository

Any folder that starts with a dot (.) is typically hidden from view. You will need to change your folder viewer settings to see it.

You will see a number of folders and fi les that are used by Maven

Page 25: Apache Maven Cookbook - Sample Chapter

Chapter 1

21

You may want to change this location for the following reasons:

You may want to conserve space in the C drive and store these folders and fi les in the D drive on Microsoft Windows.

You may want to take a back up of the contents. Backup software usually backs up contents in specifi c folders of the fi lesystem.

Your organization may have a policy for all users to store a local repository in the same folder.

How to do it...To change the location of the Maven repository, perform the following steps:

1. Create a fi le called settings.xml in the .m2 folder.

2. Add the following contents to the settings.xml fi le that you just created:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <localRepository>C:/software/maven</localRepository></settings>

Notice the highlighted part of the preceding code. We have changed the location of the repository contents to C:\software\maven. You can change it to any valid folder name.

3. Delete the repository subfolder and run the mvn package command again.

You will now notice that the repository folder is not created in the .m2 folder. Instead, it is created in C:\software\maven.

How it works...Maven determines the location of the local repository in the following way:

If settings.xml exists in the user's .m2 folder, which contains the <localRepository> tag, then Maven uses its contents to determine the location

If not, Maven will check if localRepository is explicitly defi ned in the default settings.xml, present in the conf folder of the Maven installation

If it is not present there, Maven will use the default value for the local repository, which is the user's .m2 folder

Page 26: Apache Maven Cookbook - Sample Chapter

Getting Started

22

Running Maven behind an HTTP proxy serverMost organizations do not allow devices in their network to access the Internet directly for security and other reasons. In such cases, typically, a proxy server comes into picture. The proxy server details are specifi ed in the browser or any other location where access to the Internet is required.

How to do it...Let's start running Maven behind an HTTP proxy server, by performing the following steps:

1. Create a settings.xml fi le in the .m2 folder in your HOME directory, if it does not exist already.

2. Add the following code within the settings tag:

<proxies> <proxy> <id>myproxy</id> <active>true</active> <protocol>http</protocol> <host>proxy.myorg.com</host> <port>8080</port> <username>proxyuser</username> <password>somepassword</password> <nonProxyHosts>*.myorg.com </nonProxyHosts> </proxy> </proxies>

If the proxy server does not need authentication, the username and password tags can be omitted.

The nonProxyHosts tag allows you to specify locations that can be accessed directly (for instance, your intranet). This can be skipped if not relevant.

How it works...Maven needs Internet access to download plugins and dependencies. When Maven runs, it reads the user's settings.xml fi le, if it exists. It checks for any active proxy settings and applies the same.

Maven uses the values in the proxy settings to download any artifacts from the repository. If there are no artifacts to be downloaded, then these values are not used.

Page 27: Apache Maven Cookbook - Sample Chapter

Chapter 1

23

The HTTP proxy server may work only in your organization's network. If you are running Maven from a different network, you may want to turn off the HTTP proxy server. This can be done by setting the active tag to false in the preceding code.

Understanding the standard directory layoutWhen we built our sample Java project earlier, we saw fi les being compiled, tests being run, and a JAR being generated. We do not know where these artifacts were created.

How to do it...Let's fi nd where the artifacts were created by performing the following steps:

1. Go to the folder that has the sample Maven project.

2. Open the target subfolder that was created:

How it works...When Maven runs, it puts all the contents that it generates into a separate folder. This is to distinguish it from any user-generated content. Let us examine the contents of this folder:

The classes folder: Compiled source fi les are placed in this folder. This folder will also contain resources, such as XML and property fi les that are part of the source, placed in src/main/resources.

The test-classes folder: Compiled test source fi les are available in this folder. In addition, it also contains test resources, which are fi les required for the purpose of testing, but not for running the project.

The surefire-reports folder: Test reports are separately placed in this folder. Typically, both XML and HTML report formats are available. The latter can be opened in the browser, while the former can be integrated with a code coverage tool.

The output .jar fi le: The generated project artifact is also present in this folder.

Two other folders—maven-archiver and maven-status—hold information used by Maven during the build.