Maven

Goals

Use Maven to compile a Java project.
Run a program that from .class files output by Maven.
Use Maven to package a Java project.
Run a program from a JAR file packaged by Maven.
Generate Javadoc documentation via a Maven plugin.

Concepts

bound
classpath
coordinates (Maven)
convention over configuration
declarative
goal
imperative
JAR file
life cycle
Maven
plugin
Project Object Model (POM)
project root directory
semantic versioning
snapshot version

Preview

pom.xml

<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.example</groupId>
  <artifactId>helloworld</artifactId>
  <version>1.0</version>

  <name>Hello World Program</name>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
  </properties>
</project>

cd helloworld
mvn clean package
java -classpath target/helloworld-1.0.jar com.example.HelloWorld

Preparation

Download and install Maven.
1. Make sure your JAVA_HOME environment variable is set.
2. Make sure your M2_HOME environment variable is set.
3. Make sure that the Maven …/bin subdirectory is in your system PATH environment variable.

7-Zip application listed in the Resources, which you may already be using to submit your homework, can also open the .zip and .tar.gz files downloaded from the Maven site.

You can verify you have correctly installed Maven by entering the following; you should have at least version 3.3.1 (preferably version 3.6.0 or higher):

mvn --version

Lesson

Apache Maven is a popular tool used to compile, test, package, and deploy (collectively called “to build” or “the build”) Java projects. Rather than seek out javac to compile your programs, you'll ask Maven to do it. Once you start working with multiple classes (and using third-party libraries, which you'll learn about another day), you'll appreciate handing the build off to Maven rather than invoking javac on each file in your source code.

Project Object Model (POM)

The Maven build configuration for a project is stored in the Project Object Model (POM), which is described in a pom.xml file in the root directory of your project. the POM is stored in a simple XML format, the most basic of which looks like this:

pom.xml

<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.example</groupId>
  <artifactId>helloworld</artifactId>
  <version>1.0</version>

  <name>Hello World Program</name>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
  </properties>
</project>

The project.build.sourceEncoding value of UTF-8 is very important, so that Maven will support extended characters and accent marks correctly in your source file. You will learn more about character encodings in a future lesson.

But by default Maven compiles the source code using rules for Java 1.5. For this course it is essential that you set the maven.compiler.source and maven.compiler.target properties in order for the compiler to recognize the and allow the features available in Java 11.

Project Coordinates

Your project is identified by coordinates. The coordinates are extremely important. They make up the basis for identifying components or artifacts in Maven, allowing you to easily use your project with other libraries. There are three minimum coordinates your project must have: groupId, artifactId, and version.

Coordinate	Description
`groupId`	Some identifier for the individual, company, or organization releasing the application or library. Usually this is the same as the Java package or relevant part of the package identifier.
`artifactId`	Something to identify the program or library. Should be lowercase letters, with the hyphen character `-` allowed.
`version`	Something to identify the version of your program. Usually a sequence of number separated by dots, such as `2.0.1`.

In documentation the coordinates are usually written together separated by colon characters, e.g. com.example:helloworld:1.0.

Unless you intend to release your project as several different modules (a topic discussed in an upcoming lesson), you don't need to include the project identifier as part of the groupId. That is you can simply use com.example:helloworld:1.0; there is no need for com.example.helloworld:helloworld:1.0.

Many projects today are using semantic versioning. A semantic version is the standard version number format x.x.x you've often seen, except that rules are included that describe what the version numbers indicate relating to forwards and backwards compatibility when new versions of a program or library are released. See Semantic Versioning 2.0.0 for more details.

Once your project is given a set of coordinates, the code for those coordinates never change! That means that if you release your program as version 2.1.3 and you later modify your program, you must change the version number! Otherwise, your Maven installation (or your customers' installation) may see that the version of Maven has not changed, and assume that the program has not changed either. Maven might then completely ignore all your program's improvements!

Snapshot Versions

Maven provides an option for programs that are still in flux and would otherwise need to generate a new version number several times a day. If your program is under construction and not yet ready for public release, you can add a -SNAPSHOT to the end of your version coordinate, such as 2.0.1-SNAPSHOT. This let's Maven know not to expect the features of this version to be completely fixed, and not to use any older, cached version of the snapshot when performing builds. You can keep this snapshot version until you are ready for the final release—just don't forget to remove the -SNAPSHOT before you publish your final product!

Project Directory Structure

Maven expects your project to be stored in a certain standard directory layout, starting at the top-level project root directory you initially created. There are several directories Maven recognizes for different functions; for now, these are all you need to know. Note that although the source code hierarchy merely moves two levels down, the root directory of the project stays the same. See Introduction to the Standard Directory Layout for more details.

pom.xml Maven POM

src/main/java

Main source code root directory.

e.g. src/main/java/com/example/HelloWorld.java

When it compiles your project, Maven will produce .class files, which it places in the target/classes/ directory subtree:

`target/`	Output root directory, containing package archives. (See Packaging below.) e.g. `target/helloworld-1.0.jar`
`target/classes`	Receives an accumulation of compiled classes and copied/filtered resources. e.g. `target/classes/com/example/HelloWorld.class`

target/

Output root directory, containing package archives. (See Packaging below.)

e.g. target/helloworld-1.0.jar

target/classes

Receives an accumulation of compiled classes and copied/filtered resources.

e.g. target/classes/com/example/HelloWorld.class

Note how this is different than the result of running javac! You are accustomed to javac placing your .class files in the same directory as your .java files. By placing the object code in a separate location than your source code, it helps you manage your source code better; as well as bundle and distribute the build artifacts separate from the source code.

Maven Life Cycle

When Maven goes about its work, it goes through several stages called phases in the life cycle of the build. (Maven prefers the single word “lifecycle”.) There are many phases to the default life cycle; here are the only ones you need to know right now:

validate
initialize
compile
test
package
…

Building with Maven

The following instructions work both on Linux and on Windows.

Compiling

When you invoke Maven indicating a particular phase, Maven will execute all phases up to and including the indicated phase. For example, the following command will cause Maven first to validate your project, initialize some settings, and only then compile your source files. You can later ask Maven to perform special actions during those or other phases.

cd helloworld
mvn compile

Don't forget that the output files (such as .class files) produced by the build will usually be placed in the target/ directory subtree.

Adding clean to any Maven invocation will cause Maven first to clean the artifacts from any previous build. For example, mvn clean compile will cause Maven first to erase the .class files and other files in the target/ directory before compiling.

cd helloworld
mvn clean compile

If you just want to clean up your project (while still keeping the source files, of course), you can always invoke mvn clean by itself, without specifying a life cycle phase.

Running Your Program from Maven

You can also run your program directly from Maven. You will need to specify the main class of your file, just as you would with java.

cd helloworld
mvn exec:java -Dexec.mainClass="com.example.HelloWorld"

If you want to pass arguments to your program (which you will learn about in future lessons), you must add -Dexec.args="arguments" to the command, where arguments are the particular command-line arguments you desire.

Running Your Program from Class Files

Remember from an earlier lesson that you ran your program by invoking java from the root directory of your project. Because Maven places the .class files relative to the the target/classes/ directory, not relative your project root directory, you'll first need to change to that directory before you can run your program.

cd helloworld/target/classes
java com.example.HelloWorld

Another option is to use the java -classpath or -cp option to set the Java classpath, which is (naturally) the path to the location for finding class files.

cd helloworld
java -classpath target/classes com.example.HelloWorld

Testing

Maven knows how to run tests as well. Currently you probably don't have any tests to run; if you did you could enter the following command to have Maven test your program. Maven would also compile your program if needed, because the test phase comes after the compile phase in the Maven life cycle.

cd helloworld
mvn test

Packaging

Maven also knows how to package your .class files in an archive for distributing to others. Most projects consist of more than one class, and distributing multiple .class files separately would be unwieldy. The most common archive format for distributing Java programs is the JAR file, which is essentially a Zip file with a .jar extension. This is the type of archive Maven produces by default when it packages your project output.

To package your project, issue the following command to Maven.

cd helloworld
mvn package

Remember that Maven executes every phase in the life cycle from the beginning, up to and including the phase you indicate. So before packaging your project, Maven will first validate, initialize, and if needed compile your project. If you would like Maven to first clean up your project output directory, you can add the clean command, as indicated above.

This time, along with the .class file(s) placed in the target/classes/ directory, Maven creates a JAR file containing these files and places it in the target/ directory. Thus the project defined by the example POM above will result in the JAR file target/helloworld-1.0.jar when Maven packages the project.

Running Your Program from a JAR File

Besides running your program from one or more .class files as you've have been doing up till now, you can also run a program from a JAR file package. In fact this is the way Java applications are usually run, as Java programs are typically distributed via JAR files instead of individual .class files. You'll soon see that Maven coupled with JAR files allows easy integration of an application JAR, the library JARs it depends on, their JAR dependencies, and so on.

Running a Java program from a JAR file works similar to running a Java program from a set of .class files, except that you'll indicate the -classpath to the JAR instead of the .class file output root directory.

cd helloworld
java -classpath target/helloworld-1.0.jar com.example.HelloWorld

Plugins

All the actions Maven takes, including compiling your program and executing it from within Maven, are controlled by plugins. One action you might want to take is to generate Javadoc documentation as you have been doing manually using the javadoc tool. There exists an Apache Maven Javadoc Plugin that will generate Javadoc documentation for you. By specifying the plugin in the POM and invoking it though Maven, it will already know where your classes are located. Plugins are specified in the <build> section of your POM.

Specifying the Maven Javadoc Plugin.

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.0.1</version>
      </plugin>
    </plugins>
  </build>

Notice that to identify the Maven Javadoc Plugin you had to indicate its coordinates, just as you identified the coordinates of your program. The latest available version of the Javadoc plugin as of this writing uses the coordinates org.apache.maven.plugins:maven-javadoc-plugin:3.0.1.

After adding the plugin to the POM, you need to invoke a goal of the plugin. The Maven Javadoc Plugin has several goals. The first one you will want to try is the javadoc goal. You can invoke it through Maven itself on the command line, specifying the plugin name and then the goal, separated by a colon : character.

cd helloworld
mvn javadoc:javadoc

The Maven Javadoc Plugin will generate documentation as if you had used the javadoc tool manually; you do not need to specify any packages or output directory. By default the plugin will place the documentation in the target/site/apidocs directory.

If you want a plugin to run automatically as part of a build, you will need to specify a goal in the <executions> section of the plugin. Most of the time a goal is already associated with or bound to one of the existing Maven life cycle phases by default. The jar goal of the Apache Maven Javadoc Plugin, for example, is already bound to the Maven package phase. Simply by indicating the jar goal as an <execution>, the plugin will create a JAR file containing the Javadoc documentation every time Maven performs the package phase!

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.0.1</version>
        <executions>
          <execution>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

cd helloworld
mvn package

The plugin will generate a file target/helloworld-1.0-javadoc.jar file containing the documentation. As part of this process, the unpackaged Javadoc HTML documentation will be placed in target/apidocs/. If a goal is not bound to a phase by default (which should be indicated in its documentation), you will need to specify the Maven phase in which you want the execution to occur. See How to attach a maven plugin to a phase by default? to learn how.

There are many ways plugins can be configured, mostly in the plugin's <configuration> section. The Apache Maven Compiler Plugin is one plugin that is already configured for every POM. It uses the maven.compiler.source and maven.compiler.target properties you specified above. Rather than using these properties, you could configure the plugin directly by first listing it in your <plugins> section, and then providing appropriate configuration properties. The following configuration is equivalent to providing the source and target properties; it represents an alternate way to indicate the compiler version. The latest available version of the compiler plugin as of this writing uses the coordinates org.apache.maven.plugins:maven-compiler-plugin:3.8.0.

  <build>
    <plugins>
      <plugin>
        …
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.0</version>
        <configuration>
          <source>11</source>
          <target>11</target>
        </configuration>
      </plugin>
    </plugins>
  </build>

See Guide to Configuring Plug-ins for more extensive information.

If you specify an explicit Maven Compiler Plugin version of 3.6.0 or later, you can use the new <release> configuration setting to indicate both the source and target Java version at the same time.

  <build>
    <plugins>
      …
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.0</version>
        <configuration>
          <release>11</release>
        </configuration>
      </plugin>
    </plugins>
  </build>

These later versions of the Maven Compiler Plugin also allow you to specify the release as a property, using maven.compiler.release.

  …
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>11</maven.compiler.release>
  </properties>
  …
  <build>
    <plugins>
      …
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.0</version>
      </plugin>
    </plugins>
  </build>

The maven.compiler.release property and <release> setting are not available on the older version of the Maven Compiler Plugin currently bundled with Maven; you'll have to indicate the plugin version manually as shown.

Review

Summary

Maven standard project directory layout.

`pom.xml`	Maven POM
`src/main/java`	Main source code root directory.
`target/`	Output root directory, containing package archives.
`target/classes`	Receives an accumulation of compiled classes and copied/filtered resources.

Maven life cycle.

validate
initialize
compile
test
package
…

Gotchas

A Maven project must have a file named pom.xml located in the root directory of the project. If the POM is named anything else, or located in another directory, Maven will not build the project.
Don't forget to remove the -SNAPSHOT before final release of your program!
The output of a Maven build is usually found in the target/ directory subtree. Your .class files will not be placed in the same directory as your .java files!
If you don't set the Java version in your POM, the maven-compiler-plugin will default to assuming your .java files are written in Java 1.5, which can generate some very perplexing errors.

In the Real World

Most java programs and libraries are distributed via JAR files. You will seldom if ever work directly with .class files; most of the time Maven and/or your Integrated Development Environment (IDE) will take care of them for you.

Think About It

Are you sure this is the final release of your project? If you're not positive, leave the -SNAPSHOT at the end of the version until you're sure. Otherwise, you'll have to increment the version number if you make any further changes before release.

Self Evaluation

What are Maven “coordinates”?
What is a Maven “snapshot version”?
How might you view the contents of a JAR file?
If you enter mvn compile on the command line, what other life cycle phases will Maven execute? What about mvn package? What about mvn validate?

Task

Convert the “Hello World” program you wrote in a previous homework to match the conventions expected by Maven. Be able to clean and package your program using Maven; as well as run your program from the resulting JAR file.

Create a compressed archive of your entire project and send it to your teacher.

Maven

Goals

Concepts

Preview

Preparation

Lesson

Project Object Model (POM)

Project Coordinates

Snapshot Versions

Project Directory Structure

Maven Life Cycle

Building with Maven

Compiling

Running Your Program from Maven

Running Your Program from Class Files

Testing

Packaging

Running Your Program from a JAR File

Plugins

Review

Summary

Gotchas

In the Real World

Think About It

Self Evaluation

Task

See Also

References

Resources