Learn the most important things about Maven

Maven is one of the most popular build management tools for Java developers. Made by Apache, it helps you have a clear overview of a project while also delivering an easy way for teams to collaborate on the same code.

By the end of this article you’ll know the most important things about the pom.xml file that governs Maven, as well as its components like plugins, dependencies, and the build lifecycle.

Why use Maven? 🤔

While learning to program in Java, you’ll soon encounter situations in which the standard classes aren’t useful and you have to get another library to reach your goals.

This can be a pretty simple experience if you’re the only person working on the source code. However, once you start having more people collaborate, or your dependencies rely on other dependencies (transitive), your project structure will start looking cluttered.

Enter Maven: the Apache tool holds all of your project’s information in a special file called pom.xml which is short for Project Object Model.

In this simple XML file, you can fill in information about your project, such as its name, its version, and so on. But, most importantly, you also fill in the dependencies, which are the external libraries that your project needs to run as intended.

It also helps enforce best practices for developers and an easy for follow cycle for building and deploying your project. You’ll see the importance of these things as we delve into the examples but, first, we need to set everything up.

Setting up Maven 🔧

Installing JDK

While it may be obvious, you must first have a valid Java Development Kit (JDK) version installed on your system. You can download it from the official Oracle website. JDK 11 is the latest version but the most used currently is JDK 8. Pick whichever you want.

Once you finish installing JDK, you need to set a special variable called JAVA_HOME. You can do this by running the following commands, replacing PATH_TO_YOUR_JDK_INSTALL_FOLDER with your actual path, for example C:\Program Files\Java\jdk1.8.0_101 on Windows or Java/jdk1.8.0_101 on Linux/Mac:

  • On Windows by:
    • Opening the Start menu
    • Typing cmd.exe
    • Right-clicking on the displayed file and choosing Run as Administrator
    • In the new console window, type: SET JAVA_HOME="PATH_TO_YOUR_JDK_INSTALL_FOLDER"
  • On Mac/Linux by opening a terminal window and typing the following lines:
    • JAVA_HOME=$HOME/PATH_TO_YOUR_JDK_INSTALL_FOLDER
    • export JAVA_HOME

Installing Apache

After completing these steps, it’s time to actually download Maven from the official website. In case you get confused by all the different links, just download the Binary zip archive option. Extract the archive with a tool like 7zip.

Once this is done, we need to add the bin folder from the Maven directory to our system’s PATH variable. You can do this by running the following commands, replacing PATH_TO_YOUR_MAVEN_FOLDER with your actual path, for example C:\Program Files\apache-maven-3.6.0\bin on Windows or opt/apache-maven-3.6.0/bin on Linux/Mac:

  • On Windows by:
    • Opening the Start menu
    • Typing Environment and selecting the option to Edit System Variables
    • A new window should appear with options for Performance, User Profiles, and so on. Press the button marked Environment Variables
    • In this new window, in the System Variables section, select the Path variable and press Edit.
    • Depending on the Windows version, you’ll see a long list of paths separated by semi-colon (;) or a table with the values on each row.
    • Add the PATH_TO_YOUR_MAVEN_FOLDER at the end of the list or on a new row and hit OK.
    • It should look like this, on Windows 10
Learn how to add a new system variable in Windows 10
Learn how to add a new system variable in Windows 10
  • On Mac/Linux by opening a terminal window and typing the following command: export PATH=/PATH_TO_YOUR_MAVEN_FOLDER:$PATH

Once you have completed this, open a new terminal window and type mvn -v. You should get a message about your Maven installation and the Java version it found on your computer, such as:

Apache Maven 3.5.0 (ff8f5e7444045639af65f6095c62210b5713f426; 2017-04-03T22:39:06+03:00)
Maven home: C:\Program Files\apache-maven-3.5.0\bin\..
Java version: 1.8.0_121, vendor: Oracle Corporation
Java home: C:\Program Files\Java\jdk1.8.0_121\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"

Depending on your own system, additional configuration may be needed to set up a proxy server, for example. You can find additional help on the official website.

Creating your first Maven project 🚀

Once you have valid installations of Java and Maven, you can create your first project straight from the command line interface (CLI) which is supplied by your system’s terminal application (Command Prompt for Windows, Bash or Terminal for Unix-based systems).

Simply create a new folder that will house the project and in it, open a new terminal window. Type mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

There are a lot of parameters present here but we’ll get to them in a future guide. What’s important is that the process will take a bit of time but, at the end of it, you should have a new folder called my-app which houses a folder called src, which includes more folders, and a pom.xml file. In the src/main/java directory you will find the packages containing project source code, while in src/test/java you will find the code for the tests that reference the project source code.

This file and folder structure represents the standard project structure, a best practice for Java developers that is enforced by Maven. As you can see, Maven is already helping us by already creating this for us.

Explaining the pom.xml 🔎

The basic pom.xml file contains four main sections. First, let’s see the whole file and then go through it portion by portion.

<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.7</maven.compiler.source>
    <maven.compiler.target>1.7</maven.compiler.target>
  </properties>
 
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.12</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

The first main section contains the project and modelVersion tags, these contain XML-specific information, so you won’t be modifying them in day-to-day work.

  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0-SNAPSHOT</version>

This is the section relevant to your project, it contains the groupId and artifactIdyou specific in the lenghty command we typed in the terminal. The version tag is automatically generated, unless you specify otherwise. Generally, for in-development projects, you use the word SNAPSHOT attached to the end, while for fully-functioning versions, you use RELEASE. This helps with versioning your project and lets others know what they can expect from it.

  <properties>
    <maven.compiler.source>1.7</maven.compiler.source>
    <maven.compiler.target>1.7</maven.compiler.target>
  </properties>

This section basically tells Maven what Java version code you are writing and for what Java version you want the code to be compiled. maven.compiler.source contains the version of Java language you are using, while maven.compiler.target says you will compile the code for Java 1.7. This helps Maven highlight compile errors that derive from, for example, writing code with Java 8-specific features that needs to be compiled for Java 7.

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.12</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

Finally, and the section where you will probably spend the most time, we have the dependencies group. Here, you will declare your dependencies, with each one going into a separate dependency tag.

Every dependency needs to have a groupId, a artifactId and a version which are used to uniquely identify the external library in the Maven repository. You can also specify a scope like test, compile, runtime, etc. This basically tells Maven where you want the dependency to be available. For example, the jUnit dependency listed above has a scope of test, meaning it will only be available for use in classes found in src/test/java.

Conclusion 🏁

This concludes this not-so-brief introduction to Maven. You’ve managed to learn how the Apache tool is used by Java developers and testers, how it can be installed alongside Java on your system, how it can be accessed from the command-line interface (CLI) and what are the most important sections of its pom.xml file.

Stay tuned for more great articles about this essential tool in the future.

Leave a Reply

Your email address will not be published. Required fields are marked *