The most important part of a maven-project is its project object model – pom.xml. As discussed in the introduction, maven follows conventions over configurations. Therefore, we need to follow a standard for project folder structure. We will now understand maven by creating a simple maven project, but before that let us understand a few basic concepts.

Every project is uniquely identified by groupId, artifactId & version, and this is also known as project coordinates.


Naming conventions on groupId, artifactId, & version

Just like java, maven has an official recommendation on naming conventions. Maven does not enforce these rules, but I advise to follow as far as possible. There are a few legacy projects that do not follow this convention.

  • groupId – groupId uniquely identifies a project across all other projects. A group ID should follow Java’s package name rules. This means it starts with a reversed domain name, org.apache.commons, com.jstobigdata.docker and so on.

    For a multi-module project, you need to create subgroups. e.g org.apache.maven, org.apache.maven.plugins, and org.apache.maven.reporting.
  • artifactId – artifactId is the name of the jar without version. When you create it, you can choose whatever name you want with lowercase letters and no strange symbols. If it’s a third party jar, you have to take the name of the jar as it’s distributed. e.g. log4j, spring-web etc.
  • version – To distribute a project, use any typical version with numbers and dots (1.0, 1.1, 1.0.1, …). Don’t use dates as they are usually associated with SNAPSHOT (nightly) builds. Examples, 1.1.3, hibernate uses 6.0.17.Final.

Like mentioned before, you will always come across projects that don’t follow the conventions like Log4j, uses <groupId>log4j</groupId>. But Log4j2 follows the right conventions, it uses <groupId>org.apache.logging.log4j</groupId>.

What is maven archetype?

After pom.xml, maven archetype is another most important concept of maven. An archetype is a Maven project templating toolkit. Think of archetypes as a template for creating a project structure and they include best practices.

There are several official archetypes and many more from the communities. For example, use maven-archetype-webapp for generating a web-app. Similarly, use maven-archetype-plugin for creating custom plugins and maven-archetype-simple for scaffolding a simple Java application.

You can run the following from terminal to list the available maven archetypes. It shows me 1388 archetypes when I created this tutorial.

mvn archetype:generate

Create a simple maven project

Create a folder using mkdir maven-tutorial, enter inside the directory cd maven-tutorial, then run the following command to create a simple java application. Will use the simple-example project to understand the basics.

mvn -B archetype:generate -DgroupId=com.jstobigdata.maventutorial \
  -DartifactId=simple-example \
  -Dpackage=com.jstobigdata.maventutorial \
  • The above command creates a simple maven project inside the root directory named simple-example. -B create the project in a batch (non-interactive) mode.
  • Open the simple-example directory in your IDE (Visual Studio Code), and open the pom.xml file. Try to relate it to what we have discussed in the introduction section. pom.xml will always be residing in ${basedir}.
  • ${basedir}/src/main/java is the directory where source code will reside and similarly, ${basedir}/src/test/java is the place where the test code goes.
  • Run mvn compile to compile the code. Basically converts the .java to .class.
mvn compile
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building simple-example 1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ simple-example ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory /Users/bikramkundu/jstobigdata/awesome-maven-examples/simple-example/src/main/resources
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ simple-example ---
[INFO] Changes detected - recompiling the module!
[WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
[INFO] Compiling 1 source file to /Users/bikramkundu/jstobigdata/awesome-maven-examples/simple-example/target/classes
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.176 s
[INFO] Finished at: 2019-07-25T08:41:36+05:30
[INFO] Final Memory: 15M/299M
[INFO] ------------------------------------------------------------------------
  • Now, run mvn test and comment below the output you get. This command is used to run the test cases, specifically for Unit test cases.
  • There are several other commands like install, clean etc, I will cover them in maven Lifecycle section.
  • Now execute mvn package to create a runnable java jar in the /target and as you can see simple-example-1.0-SNAPSHOT.jar gets created in the target directory.

Till now, we have only looked into the basics and how to create a project from archetype. In the later part of the tutorial, you will learn the core concepts of maven.