Table Of ContentOctober 2009
Edition 0.8.1
September 2009
Edition 0.8 Editor: Send Feedback to:
Tim O’Brien
book@sonatype.com
Authors:
Contributing Authors:
Tim O’Brien
Dan Fabulich
Jason van Zyl
Eric Redmond
Brian Fox
Bruce Snyder
John Casey
Larry Shatzer
Juven Xu
Thomas Locher
Sonatype Maven Training
With Sonatype training, you will learn the know-how and best practices directly from
Maven and Nexus experts. Our training materials were developed by well-known
members of the Maven community.
MVN-101 Maven Mechanics
An online instructor-led course of two half-day sessions, ideal for programmers who
work with Maven projects and need to understand how to work with an existing
Maven build. This class is also appropriate for Maven users who are interested in Maven
MVN-201 Development Infrastructure Design
An online instructor-led course of two half-day sessions, ideal for Development Infra-
structure Engineers who are responsible for maintaining enterprise development infra-
structure.
http://www.sonatype.com/training
Copyright ...................................................................................................................... xi
1. Creative Commons ............................................................................................. xi
1.1. Creative Commons BY-NC-ND 3.0 US License ............................................ xii
Foreword: 0.8.1 ............................................................................................................ xix
1. Revision History ............................................................................................... xix
1.1. Changes in Edition 0.8.1 .......................................................................... xix
1.2. Changes in Edition 0.8 ............................................................................ xix
1.3. Changes in Edition 0.7.3 .......................................................................... xxi
1.4. Changes in Edition 0.7.2 ......................................................................... xxii
1.5. Changes in Edition 0.7.1 ......................................................................... xxv
1.6. Changes in Edition 0.7 ........................................................................... xxvi
1.7. Changes in Edition 0.6 ........................................................................... xxx
1.8. Changes in Edition 0.5 ........................................................................... xxx
1.9. Changes in Edition 0.4 ........................................................................... xxxi
Preface .................................................................................................................... xxxiii
1. How to Use this Book .................................................................................... xxxiii
2. Your Feedback .............................................................................................. xxxiv
3. Font Conventions ........................................................................................... xxxiv
4. Maven Writing Conventions ............................................................................ xxxiv
5. Acknowledgements ......................................................................................... xxxv
1. Introducing Apache Maven ........................................................................................... 1
1.1. Maven... What is it? .......................................................................................... 1
1.2. Convention Over Configuration ........................................................................... 1
1.. A Common Interface ........................................................................................... 2
1.4. Universal Reuse through Maven Plugins ............................................................... 3
1.5. Conceptual Model of a "Project" .......................................................................... 4
1.6. Is Maven an alternative to XYZ? ......................................................................... 5
1.. Comparing Maven with Ant ................................................................................. 5
2. Installing Maven ......................................................................................................... 9
2.1. Verify your Java Installation ............................................................................... 9
2.2. Downloading Maven .......................................................................................... 9
2.3. Installing Maven ............................................................................................. 10
2.3.1. Installing Maven on Mac OSX ................................................................ 10
2.3.2. Installing Maven on Microsoft Windows ................................................... 11
2.3.3. Installing Maven on Linux ...................................................................... 11
2.3.4. Installing Maven on FreeBSD or OpenBSD ............................................... 12
2.4. Testing a Maven Installation .............................................................................. 12
2.5. Maven Installation Details ................................................................................. 12
2.5.1. User-specific Configuration and Repository ............................................... 13
2.5.2. Upgrading a Maven Installation ............................................................... 13
2.5.3. Upgrading from Maven 1.x to Maven 2.x .................................................. 14
2.6. Uninstalling Maven .......................................................................................... 14
2.7. Getting Help with Maven .................................................................................. 15
2.8. About the Apache Software License ................................................................... 15
I. Maven by Example ..................................................................................................... 17
A Simple Maven Project ......................................................................................... 19
1. Introduction .............................................................................................. 19
1.1. Downloading this Chapter's Example .................................................. 19
2. Creating a Simple Project ............................................................................ 19
3. Building a Simple Project ............................................................................ 22
4. Simple Project Object Model ....................................................................... 22
5. Core Concepts ........................................................................................... 24
5.1. Maven Plugins and Goals ................................................................. 24
5.2. Maven Lifecycle ............................................................................. 26
5.3. Maven Coordinates .......................................................................... 29
5.4. Maven Repositories ......................................................................... 31
5.5. Maven's Dependency Management ..................................................... 33
5.6. Site Generation and Reporting ........................................................... 35
6. Summary .................................................................................................. 35
4. Customizing a Maven Project ............................................................................... 37
4.1. Introduction ............................................................................................ 37
4.1.1. Downloading this Chapter's Example ................................................ 37
4.2. Defining the Simple Weather Project .......................................................... 37
4.2.1. Yahoo! Weather RSS ..................................................................... 38
4.3. Creating the Simple Weather Project ........................................................... 38
4.4. Customize Project Information ................................................................... 40
4.5. Add New Dependencies ............................................................................ 41
4.6. Simple Weather Source Code .................................................................... 42
4.7. Add Resources ........................................................................................ 48
4.8. Running the Simple Weather Program ......................................................... 49
4.8.1. The Maven Exec Plugin ................................................................. 50
4.8.2. Exploring Your Project Dependencies ............................................... 50
4.9. Writing Unit Tests ................................................................................... 52
4.10. Adding Test-scoped Dependencies ............................................................ 54
4.11. Adding Unit Test Resources .................................................................... 55
4.12. Executing Unit Tests .............................................................................. 57
4.12.1. Ignoring Test Failures .................................................................. 58
4.12.2. Skipping Unit Tests ..................................................................... 59
4.13. Building a Packaged Command Line Application ......................................... 60
4.13.1. Attaching the Assembly Goal to the Package Phase ............................ 61
5. A Simple Web Application .................................................................................. 63
5.1. Introduction ............................................................................................ 63
5.1.1. Downloading this Chapter's Example ................................................ 63
5.2. Defining the Simple Web Application ......................................................... 63
5.3. Creating the Simple Web Project ................................................................ 63
5.4. Configuring the Jetty Plugin ...................................................................... 66
iv
5.5. Adding a Simple Servlet ........................................................................... 67
5.6. Adding J2EE Dependencies ....................................................................... 69
5.7. Conclusion ............................................................................................. 71
6. A Multi-module Project ...................................................................................... 73
6.1. Introduction ............................................................................................ 73
6.1.1. Downloading this Chapter's Example ................................................ 73
6.2. The Simple Parent Project ......................................................................... 73
6.3. The Simple Weather Module ..................................................................... 75
6.4. The Simple Web Application Module .......................................................... 77
6.5. Building the Multimodule Project ............................................................... 79
6.6. Running the Web Application .................................................................... 80
7. Multi-module Enterprise Project ........................................................................... 83
7.1. Introduction ............................................................................................ 83
7.1.1. Downloading this Chapter's Example ................................................ 83
7.1.2. Multi-module Enterprise Project ...................................................... 83
7.1.3. Technology Used in this Example .................................................... 85
7.2. The Simple Parent Project ......................................................................... 86
7.3. The Simple Model Module ........................................................................ 87
7.4. The Simple Weather Module ..................................................................... 91
7.5. The Simple Persist Module ....................................................................... 95
7.6. The Simple Web Application Module ........................................................ 101
7.7. Running the Web Application .................................................................. 111
7.8. The Simple Command Module ................................................................. 112
7.9. Running the Simple Command ................................................................. 118
7.10. Conclusion .......................................................................................... 120
7.10.1. Programming to Interface Projects ................................................ 121
8. Optimizing and Refactoring POMs ...................................................................... 123
8.1. Introduction .......................................................................................... 123
8.2. POM Cleanup ....................................................................................... 124
8.3. Optimizing Dependencies ........................................................................ 124
8.4. Optimizing Plugins ................................................................................ 128
8.5. Optimizing with the Maven Dependency Plugin ........................................... 129
8.6. Final POMs .......................................................................................... 133
8.7. Conclusion ........................................................................................... 140
II. Maven Reference ..................................................................................................... 141
9. The Project Object Model .................................................................................. 143
9.1. Introduction .......................................................................................... 143
9.2. The POM ............................................................................................. 143
9.2.. The Super POM ........................................................................... 145
9.2.2. The Simplest POM ...................................................................... 148
9.2.3. The Effective POM ...................................................................... 149
9.2.4. Real POMs ................................................................................ 149
9.3. POM Syntax ......................................................................................... 150
v
9.3.1. Project Versions .......................................................................... 150
9.3.2. Property References ..................................................................... 151
9.4. Project Dependencies .............................................................................. 153
9.4.1. Dependency Scope ...................................................................... 154
9.4.2. Optional Dependencies ................................................................. 154
9.4.3. Dependency Version Ranges ......................................................... 156
9.4.4. Transitive Dependencies ............................................................... 157
9.4.5. Conflict Resolution ...................................................................... 158
9.4.6. Dependency Management ............................................................. 160
9.5. Project Relationships .............................................................................. 162
9.5.1. More on Coordinates .................................................................... 162
9.5.2. Project Inheritance ....................................................................... 163
9.6. POM Best Practices ............................................................................... 165
9.6.1. Grouping Dependencies ................................................................ 165
9.6.2. Multi-module vs. Inheritance ......................................................... 167
10. The Build Lifecycle ........................................................................................ 173
10.1. Introduction ......................................................................................... 173
10.1.1. Clean Lifecycle (clean) ............................................................... 173
10.1.2. Default Lifecycle (default) ........................................................... 176
10.1.3. Site Lifecycle (site) .................................................................... 177
10.2. Package-specific Lifecycles .................................................................... 178
10.2.1. JAR ......................................................................................... 178
10.2.2. POM ....................................................................................... 179
10.2.3. Maven Plugin ............................................................................ 179
10.2.4. EJB ......................................................................................... 179
10.2.5. WAR ....................................................................................... 180
10.2.6. EAR ........................................................................................ 180
10.2.7. Other Packaging Types ............................................................... 181
10.3. Common Lifecycle Goals ...................................................................... 182
10.3.1. Process Resources ...................................................................... 182
10.3.2. Compile ................................................................................... 185
10.3.3. Process Test Resources ............................................................... 187
10.3.4. Test Compile ............................................................................ 187
10.3.5. Test ......................................................................................... 187
10.3.6. Install ...................................................................................... 188
10.3.7. Deploy ..................................................................................... 188
11. Build Profiles ................................................................................................. 191
11.1. What Are They For? ............................................................................. 191
11.1.1. What is Build Portability ............................................................. 191
11.1.2. Selecting an Appropriate Level of Portability .................................. 192
11.2. Portability through Maven Profiles .......................................................... 193
11.2.1. Overriding a Project Object Model ................................................ 195
11.3. Profile Activation ................................................................................. 196
vi
11.3.1. Activation Configuration ............................................................. 197
11.3.2. Activation by the Absence of a Property ........................................ 199
11.4. Listing Active Profiles .......................................................................... 199
11.5. Tips and Tricks .................................................................................... 200
11.5.1. Common Environments ............................................................... 200
11.5.2. Protecting Secrets ...................................................................... 202
11.5.3. Platform Classifiers .................................................................... 203
11.6. Summary ............................................................................................ 205
12. Running Maven .............................................................................................. 207
12.1. Maven Command Line Options .............................................................. 207
12.1.. Defining Properties ...................................................................... 207
12.1.. Getting Help ............................................................................... 207
12.1.3. Using Build Profiles ................................................................... 209
12.1.4. Displaying Version Information .................................................... 209
12.1.. Running in Offline Mode .............................................................. 209
12.1.6. Using a Custom POM or Custom Settings File ................................ 209
12.1.. Encrypting Passwords .................................................................. 210
12.1.8. Dealing with Failure ................................................................... 210
12.1.9. Controlling Maven's Verbosity ..................................................... 210
12.1.. Running Maven in Batch Mode ...................................................... 211
12.1.11. Downloading and Verifying Dependencies .................................... 211
12.1.12. Controlling Plugin Updates ........................................................ 212
12.1.. Non-recursive Builds .................................................................... 212
12.2. Using Advanced Reactor Options ............................................................ 213
12.2.1. Advanced Reaction Options Example Project .................................. 213
12.2.2. Resuming Builds ....................................................................... 215
12.2.3. Specifying a Subset of Projects .................................................... 215
12.2.4. Making a Subset of Projects ........................................................ 215
12.2.5. Making Project Dependents ......................................................... 216
12.2.6. Resuming a "make" build ............................................................ 216
12.3. Using the Maven Help Plugin ................................................................. 217
12.3.1. Describing a Maven Plugin .......................................................... 217
13. Maven Configuration ....................................................................................... 221
13.1. Configuring Maven Plugins .................................................................... 221
13.1.1. Plugin Configuration Parameters ................................................... 221
13.1.2. Adding Plugin Dependencies ....................................................... 224
13.1.3. Setting Global Plugin Parameters .................................................. 225
13.1.4. Setting Execution Specific Parameters ........................................... 225
13.1.5. Setting Default Command Line Execution Parameters ....................... 226
13.1.6. Setting Parameters for Goals Bound to Default Lifecycle ................... 226
14. Maven Assemblies .......................................................................................... 229
14.1. Introduction ......................................................................................... 229
14.2. Assembly Basics .................................................................................. 229
vii
14.2.1. Predefined Assembly Descriptors .................................................. 230
14.2.2. Building an Assembly ................................................................ 231
14.2.3. Assemblies as Dependencies ........................................................ 233
14.2.4. Assembling Assemblies via Assembly Dependencies ........................ 234
14.3. Overview of the Assembly Descriptor ...................................................... 238
14.4. The Assembly Descriptor ...................................................................... 239
14.4.1. Property References in Assembly Descriptors .................................. 239
14.4.2. Required Assembly Information ................................................... 239
14.5. Controlling the Contents of an Assembly .................................................. 240
14.5.1. Files Section .......................................................................... 241
14.5.2. FileSets Section ..................................................................... 242
14.5.3. Default Exclusion Patterns for fileSets ....................................... 244
14.5.4. dependencySets Section ........................................................... 245
14.5.5. moduleSets Sections ................................................................ 254
14.5.6. Repositories Section ................................................................... 260
14.5.7. Managing the Assembly’s Root Directory ....................................... 261
14.5.8. componentDescriptors and containerDescriptorHandlers .... 262
14.6. Best Practices ...................................................................................... 262
14.6.1. Standard, Reusable Assembly Descriptors ....................................... 263
14.6.2. Distribution (Aggregating) Assemblies ........................................... 266
14.7. Summary ............................................................................................ 270
15. Properties and Resource Filtering ...................................................................... 271
15.1. Introduction ......................................................................................... 271
15.2. Maven Properties ................................................................................. 271
15.2.1. Maven Project Properties ............................................................ 272
15.2.2. Maven Settings Properties ........................................................... 273
15.2.3. Environment Variable Properties .................................................. 274
15.2.4. Java System Properties ............................................................... 274
15.2.5. User-defined Properties ............................................................... 275
15.3. Resource Filtering ................................................................................ 276
16. Site Generation .............................................................................................. 281
16.1. Introduction ......................................................................................... 281
16.2. Building a Project Site with Maven ......................................................... 281
16.3. Customizing the Site Descriptor .............................................................. 283
16.3.1. Customizing the Header Graphics ................................................. 284
16.3.2. Customizing the Navigation Menu ................................................ 285
16.4. Site Directory Structure ......................................................................... 286
16.5. Writing Project Documentation ............................................................... 287
16.5.1. APT Example ........................................................................... 287
16.5.2. FML Example ........................................................................... 288
16.6. Deploying Your Project Website ............................................................. 289
16.6.1. Configuring Server Authentication ................................................ 289
16.6.2. Configuring File and Directory Modes ........................................... 290
viii
Description:O’Brien T., Casey J., Fox B. Maven: The Definitive Guide. - O'Reilly, 2009 - 426p.Edition 0.8Contents1. Introducing Apache Maven2. Installing Maven3. Building a Simple Project4. Customizing a Maven Project5. A Simple Web Application6. A Multi-module Project7. Multi-module Enterprise Project8. Opti