Maven Cheatsheet

Maven is a project management tool for Java projects based on the concept of a project object model (POM). It can manage a project’s build, reporting, testing, and documentation.

Maven can do the following things

• Manage dependencies
• Compile source code
• Deploy source code
• Run tests
• Can generate documentation from JavaDoc
• Create reports like unit test coverage

Maven’s purpose is to:

• Easy to use. It hides away a lot of details making it easy to learn, use and share.
• Provide a uniform dependency management and build system. This results that dependencies pulled or builds created are the same across your computer, someone else’s computer, on a CICD server, or any other server.
• Encourage better development practices. This includes things like project layout, unit test management, etc.
• Have project information that can be easily understood and can also be generated from source code. All the information is contained in the POM like dependencies, unit test reports, etc.

Creating a project

Use the maven archetypes feature to create a project having default project structure and settings.

Example:

Use the command to create a project: mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

You executed the Maven goal archetype:generate, and pass in various parameters to that goal. The prefix archetype is the plugin that provides the goal. This archetype:generate goal created a simple project based upon a maven-archetype-quickstart archetype. Suffice it to say for now that a plugin is a collection of goals with a general common purpose.

The standard project structure is:

my-app
|-- pom.xml
`-- src
    |-- main
    |   `-- java
    |       `-- com
    |           `-- mycompany
    |               `-- app
    |                   `-- App.java
    `-- test
        `-- java
            `-- com
                `-- mycompany
                    `-- app
                        `-- AppTest.java

The POM is:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
 
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0-SNAPSHOT</version>
 
  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
 
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.12</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

Build the Project using mvn package

The command line will print out various actions, and end with the following:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.953 s
[INFO] Finished at: 2019-11-24T13:05:10+01:00
[INFO] ------------------------------------------------------------------------

Unlike the first command executed (archetype:generate), the second is simply a single word - package. Rather than a goal, this is a phase. A phase is a step in the build lifecycle, which is an ordered sequence of phases. When a phase is given, Maven executes every phase in the sequence up to and including the one defined. For example, if you execute the compile phase, the phases that get executed are:

1. validate
2. generate-sources
3. process-sources
4. generate-resources
5. process-resources
6. compile

You may test the newly compiled and packaged JAR with the following command:

java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App

Which will print the quintessential:

Hello World!

Maven Phases

Although hardly a comprehensive list, these are the most common default lifecycle phases executed.

• validate: validate that the project is correct and all necessary information is available
• compile: compile the source code of the project
• test: test the compiled source code using a suitable unit testing framework. These tests should not require the code to be packaged or deployed
• package: take the compiled code and package it in its distributable format, such as a JAR.
• integration-test: process and deploy the package if necessary into an environment where integration tests can be run
• verify: run any checks to verify the package is valid and meets quality criteria
• install: install the package into the local repository, for use as a dependency in other projects locally
• deploy: done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.

There are two other Maven lifecycles of note beyond the default list above. They are

• clean: cleans up artifacts created by prior builds
• site: generates site documentation for this project

Phases are mapped to underlying goals. The specific goals executed per phase are dependent upon the packaging type of the project. For example, package executes jar:jar if the project type is a JAR and war:war if the project type is - you guessed it - a WAR. An interesting thing to note is that phases and goals may be executed in sequence. mvn clean dependency:copy-dependencies package This command will clean the project, copy dependencies, and package the project (executing all phases up to package, of course).

Generating the Site

mvn site

This phase generates a site based upon information on the project’s pom. You can look at the documentation generated under target/site.

Standard Directory Layout

At the top level, files descriptive of the project: a pom.xml file. In addition, there are textual documents meant for the user to be able to read immediately upon receiving the source: README.txt, LICENSE.txt, etc.

There are just two subdirectories of this structure: src and target. The only other directories that would be expected here are metadata like CVS, .git or .svn, and any subprojects in a multiproject build (each of which would be laid out as above).

The target directory is used to house all output of the build.

The src directory contains all of the source material for building the project, its site, and so on. It contains a subdirectory for each type: main for the main build artifact, test for the unit test code and resources, site, and so on.

Within artifact producing source directories (ie. main and test), there is one directory for the language java (under which the normal package hierarchy exists), and one for resources (the structure which is copied to the target classpath given the default resource definition).

Cheatsheet

• Get Maven version: mvn --version
• Compile the project: mvn compile
• Compile and run tests: mvn test
• Compile tests but not execute them: mvn test-compile
• Compile and create an artifact (JAR/WAR/EAR): mvn package
• Install the JAR to the local repository: mvn install
• Generate a website: mvn site
• Clean previous build results: mvn clean

References

• https://maven.apache.org/
• https://maven.apache.org/guides/getting-started/index.html
• https://maven.apache.org/pom.html
• https://maven.apache.org/settings.html
• https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html