Java Practices->Using Maven for builds

Using Maven for builds

Maven is a widely-used tool for building Java projects.

For those familiar with the basics of Maven, here are some reminders regarding its use.

Running maven from the command line

After downloading Maven, you'll usually want to adjust your environment variables:

set JAVA_HOME to a local JDK, for example set JAVA_HOME=C:\jdk1.8.0
append the maven/bin directory to the PATH

The default Maven repository for downloaded jars and build artifacts has this default location:

${user.home}/.m2/repository

Common command lines

Examples:

mvn validate - sanity-check for the pom.xml file. (Each project has a pom.xml file that controls the behaviour of Maven.)
mvn compile
mvn test
mvn package
mvn install

mvn dependency:analyze is a good sanity check. It detects 2 kinds of error:

kruft: jars that are not really used
finds jars that are needed, but aren't explicit dependencies (and should be). In this case, the jars come via transitive fetching. A needs C, but gets C only because B depends on it. If B changes in the future, and no longer needs C, then A breaks because C wasn't an explicit dependency.

Some common options for commands:

-Dmaven.test.skip=true don't run the unit tests
-Pdev run with a specific profile; profiles often carry data specific to a target environment
-X verbose
-q quiet
-l where to put the output log file
-f a custom name for the pom.xml file
-e verbose error reporting

In general, a Maven command has this form:

mvn [options] [goal(s)] [phase(s)]

Archetype

An archetype is a canned template for a project structure, for example a jar or war. You typically start a new project by running a command like this to generate an 'archetypal' or standard directory structure:

A simple jar app:

>mvn archetype:generate -DartifactId=my-app -DgroupId=com.mycompany.app 
   -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

A web app:

>mvn archetype:generate -DartifactId=my-web-app -DgroupId=com.mycompany.app 
  -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false

For the web-app archetype, the tree looks like this after you have also run mvn install:

├───src
│ └───main
│ ├───resources
│ └───webapp
│ └───WEB-INF
└───target
 ├───classes
 ├───maven-archiver
 └───my-web-app
 ├───META-INF
 └───WEB-INF
 └───classes

Packaging: Lifecycle, Phase, and Goal

Packaging: 'LP(P:)G'
   1x Lifecycle
       Nx Phase
          Nx(plugin:)Goal

Packaging settings:

jar (the default)
pom
war
ear
rar
par
ejb
maven-plugin

There are 3 lifecycles. Here they are, listed with their phases:

clean: pre-clean, clean, post-clean
default: validate, initialize, generate-sources, process-sources, generate-resources, process-resources, compile, process-classes, generate-test-sources, process-test-sources, generate-test-resources, process-test-resources, test-compile, process-test-classes, test, prepare-package, package, pre-integration-test, integration-test, post-integration-test, verify, install, deploy
site: pre-site, site, post-site, site-deploy

The phases in a lifecycle are ordered and cumulative: a later phase includes all earlier ones. For example, invoking mvn install will always cause all preceding phases in that lifecycle to be executed as well. Typical invocations of Maven specify 1..N phases. For example, mvn clean install invokes 2 phases from 2 independent lifecycles.

Each phase, in turn, has N plugin:goal's (much like an Ant target). Each goal is implemented by a plugin. You customize the behavior of a plugin by adding a <plugin> entry in the pom.xml.

Some important phases:

validate - validate the project is correct and all necessary information is available
compile - compile the source code
test - run the unit tests
package - create the build target (a jar, for example)
install - put the build target into your local Maven repository

Resource-Filters

(Filter is actually a bad name; these refer to find-and-replace operations on special place-holder text in text files.)

In the resources directory, files can have place-holder references of the form ${blah}. Values for those references are defined in:

pom.xml profile settings (likely the most common location)
as pom.xml properties, as in ${project.name}, for instance
main/filters/blah.properties
a System property
settings.xml, a Maven config file, as in ${settings.blah}
environment settings, as in ${env.blah}

During the build, there is a maven phase (process-resources) which finds resource files and does a find-and-replace on all such ${blah} placeholder strings. In the pom.xml, you need to turn this mechanism on explicitly, like so:

<build>
 <resources>
  <resource>
   <directory>src/main/resources</directory>
   <filtering>true</filtering>
   </resource>
 </resources>
</build>

Maven coordinates

Maven uses the (rather silly) term of coordinates to refer to their conventional names for build artifacts: the who-what-when information.

Example: myorg.myproj:abc-web:1.1.0

The colon acts as a separator. The 3 basic items are, in order:

groupId who made this
artifactId what is its name - avoid dots in this part
version major.minor.increment.qualifier: 3.2.9, 3.2-beta

Maven defines conventional version strings that it's able to parse (examples above). The qualifier is simply plain text. The other items are numeric. Following this convention is highly recommended. A version of SNAPSHOT has specific meaning to Maven: the build is a development build, not a release build.

There are variations in the version string, having these items appearing before the version:

packaging
classifier (for example jdk18)

Layout

Maven projects have a conventional layout (a directory tree). A starter-version of that layout is generated when you start a project using a Maven archetype. The project layout can be altered, but in practice that's probably rarely done. When you deviate from the defaults, it requires more work to keep Maven functioning properly.

Names of tests

By default, in the test directory, Maven recognizes the following kinds of class names as unit tests:

**/*Test.java
**/Test*.java
**/*TestCase.java

The idea is that it won't treat any other classes as tests. This let you place helper or utility classes beside your test classes.

Resource locations

main/resources items are put into the root of the jar
test/resources can be accessed in tests, as if they're in the root of the class path

Artifact names

You should avoid using dots in the artifactId, because it may lead to problems.

Version numbers

See above for details on version numbers. Note as well that in the pom.xml, a standard version number, appearing as just 3.2, acts as advice to Maven. Maven will try to use that version, as your preferred version, but it may, if needed, use a different version instead. You alter this behaviour, and hard-code to a precise version, by decorating the version with a special syntax, for example [3.2].

Versions have a special syntax:

3.2 - my preferred version, but Maven may need to use some other version
[3.2] - this exact version only
(1.2, 3.2) - in this range (exclude the ends)
[1.2,3.2] - in this range (include the ends)

Dependencies

If you declare a dependency on X, and X depends on Y, Maven will automagically fetch Y for you. A version is always needed. If it's not explicit, it's taken from somewhere:

defined by some other dependency
defined by another pom.xml

The scope of a dependency defines the contexts in which it's needed:

compile (the default; all cases; propagated to child projects)
runtime (run and test, but not compile)
test (tests only)
provided (compile and test, but not run). For example, the servlet API jars are provided by the container, so they don't need to be included in the war.

Jars not available in a remote Maven repository

In this case, you need to put the jar manually into the local repository, using a command similar to:

>mvn install:install-file -Dfile=non-maven-proj.jar 
 -DgroupId=some.group -DartifactId=non-maven-proj -Dversion=1 -Dpackaging=jar

Sharing POMs

There are 3 ways to share the content of a pom.xml:

dependencies. For example, you can define a project that consists of nothing but shared dependencies, and then point your own project to it.
super-pom
aggregator-and-module

Be aware of sloppy terms when reading docs about these ideas: the terms parent and child are used, but they should be avoided, because they mean different things according to who's talking. Your thinking will be clear if you stick to these terms instead:

pom and its super-pom
an aggregator-project and its N module-projects

Inheritance from super-pom (Project Inheritance):

one pom extends another, by including a <parent>, and pointing to a super-pom
a super-pom is always present by default (Maven has a built-in super-pom)
a pom gets most, but not all, of what's in its super-pom
a pom has only 1 super-pom
the super-pom must set its packaging to pom

Aggregation: point to child-modules (Project Aggregation):

the aggregator-pom sets its packaging to pom
the aggregator-pom adds modules, pointing to N module-projects
there are no changes to the module's pom
the ordering of modules in the aggregator-pom isn't significant; if child A depends on child B, then Maven will figure it out
any Maven commands on the aggregator-project are passed on to the module-projects

It's legal to combine the above two styles:

your-pom has a super-pom
the super-pom has your-pom as one of its modules

Be careful: whether or not something is inherited is tricky! You should verify the behaviour if there's any doubt.

The effective-pom:

is a merge of your-pom + all of its super-poms (up the tree, 1 at a time)
mvn help:effective-pom is the command that shows the effective-pom

Dependency vs Dependency Management

The difference between these 2 is with respect to poms that point to a super-pom. Let's say that your-pom points to a super-pom, via the usual parent tag.

If the super-pom has a regular dependency, then your-pom gets that dependency, no matter what.
If the super-pom has the jar as a dependencyManagement item, then your-pom gets it only if your-pom explicitly declares it as a dependency. Furthermore, if your-pom's dependency leaves out version/scope for the item, then it gets the super-pom's version/scope.

Profiles

Some projects use profiles to customize the build for different environments. One of the main things to customize are database settings.

each profile must have an id
an example of using a profile id in a production build: mvn -Pproduction clean install
profiles can override just about any setting in the pom.xml
any property settings defined in a <profile> tag are visible during resource-filtering, so that placeholder strings ${blah} in resource files can be replaced with real values defined by the current profile.

Example of the syntax:

<profile>
 <id>production</id>
 <properties>
   <db.driverClass>oracle.jdbc.driver.OracleDriver</db.driverClass>
   <db.connectionURL>jdbc:oracle:thin:@10.0.1.14:1521:APPS</db.connectionURL>
   <db.username>productionuser</db.username>
   <db.password>productionpassword</db.password>
 </properties>
</profile>

Practices to consider

don't leave out the version of a dependency, since it will default to the latest version, which will change over time
use dependencyManagement to centralize versions among modules
avoid duplication by centralizing in a super-pom
do your best to avoid repeating things
consider using the enforcer plugin
consider using the Maven release plugin
in pluginManagement, consider defining explicitly all versions of all plugins, so you don't get clobbered by plugin upgrades (similar behaviour as for dependencyManagement)