How dependency management works?

During the Ice Age, when java developers had to use external libraries in their java project like OkHttp it was necessary to download each dependency jar. The project folder structure was like this:

1
lib/
2
├─ okhttp.jar
3
├─ jackson.jar
4
src/
5
├─ AnotherClass.java
6
├─ Main.java

To build this project it was necessary to pass all .jar files to javac compiler

javac -cp "lib/*" -d out $(find src -name "*.java")

Although this makes you feel like a hacker, it’s very annoying because:

• Developers could have different environments (the find command I used here wouldn’t work on Windows, for example)
• Updating dependencies required manual search and download (again)
• Unless your team was well organized, you needed to figure out on your own which .jar version was the correct
• Multiple libraries required different versions of the same dependency

and more…

With Maven it’s as simple as:

1. Search for you dependency on Maven Repository, choose a version.
2. For example, in the JavaFX dependency page, you will see something like this:

1
<!-- https://mvnrepository.com/artifact/org.openjfx/javafx-graphics -->
2
<dependency>
3
    <groupId>org.openjfx</groupId>
4
    <artifactId>javafx-graphics</artifactId>
5
    <version>21.0.1</version>
6
</dependency>

3. Copy this inside of a <dependencies> tag inside your pom.xml file (will talk about this file more in The POM configuration file section)

1
<project>
2
    <dependencies>
3
        <dependency>
4
            <groupId>org.openjfx</groupId>
5
            <artifactId>javafx-graphics</artifactId>
6
            <version>21.0.1</version>
7
        </dependency>
8
    </dependencies>
9
</project>

4. Now, just run dependency:resolve and Maven will download all dependencies :)

~/
$ ls
Main.java pom.xml

~/
$ mvn dependency:resolve

Where are my JARs?

After Maven downloads each dependency defined in your POM file, it will cache in the local repository, which is just a folder in your computer.

cd ~/.m2/repository  # Local repository
cd ~/.m2/repository/org/openjfx/javafx-graphics/21.0.2/ #  Location of the JavaFX jar I showed in this example

Maven Lifecycles

Maven has very useful commands like:

# compiles the app (no shit?)
mvn compile

# Remove build artifacts
mvn clean

# Compile your app and move it to the local repository, making it available for other local projects
mvn install

These commands like compile, validate, clear are all called lifecyle phases. Maven divides these phases between three lifecycles: default, clean and site.

For example, the default cycle is composed with around 23+ phases. Here is the first 7:

When running any phase, all phases before of it will also be executed. E.g. If you run mvn compile it will run validate, initialize, generate-sources, process-sources etc… until process-resources, finishing with the compile phase.

The POM configuration file

POM (Project Object Model) is the configuration file Maven uses to understand your project structure, which dependencies to download, how to build the code, etc. The POM file is written in XML. It’s like a JSON but with more capabilities and the usage of tags with attributes (like HTML).

1
<exampleTag>
2
  <dataContainer>
3
    <value key="identifier"/>
4
  </dataContainer>
5
</exampleTag>

Project Info

The root element of every Maven POM is the <project> tag, containing XML attributes that allow your code editor and Maven to validate the file against an official schema.

• The xmlns attribute defines the default namespace for the whole xml file (so Maven knows which tag to use as a starting point)
• The remaining xmlns:xsi and xsi:schemaLocation are attributes used to define the schema we’re using. It’s helpful because our code editors and Maven can validate the xml before everything.

There is also another tags inside the project, providing information about the project.

1
<project xmlns="http://maven.apache.org/POM/4.0.0"
2
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4

5
    <!-- POM model version  -->
6
    <modelVersion>4.0.0</modelVersion>
7

8
    <!-- Group identifier for the project.
9
         Typically, uses the reversed domain name of the organization.
10
         Used to group related projects under the same namespace. -->
11
    <groupId>com.joseiedo</groupId>
12

13
    <!-- Unique name of this artifact within the group.
14
         Convention for public artifacts: lowercase letters, digits, hyphens. -->
15
    <artifactId>maven-in-a-nutshell</artifactId>
16

17
    <!-- Version of the produced artifact.
18
         Usually follows Semantic Versioning 2.0.0.
19
         “-ALPHA” indicates a pre-release. -->
20
    <version>1.0.0-ALPHA</version>
21

22
</project>

Now, if you want, you can check if the configuration is valid by running mvn validate in the same directory.

~/
$ ls
pom.xml

~/
$ mvn validate
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< com.joseiedo:maven-in-a-nutshell >------------------
[INFO] Building maven-in-a-nutshell 1.0.0-ALPHA
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.032 s
[INFO] Finished at: 2025-11-14T21:48:32-03:00
[INFO] ------------------------------------------------------------------------

Build properties

Here is where things get fun! Building a java application using javac is really boring for big projects, although you can simplify with bash, it’s still a pain in the ass to do this for every project.

With Maven, we just need to provide the source directory in the pom.xml!

1. Create a Main.java file in the same folder of your pom.xml with the following code:

1
public class Main {
2

3
    public static void main(String[] args) {
4
        System.out.println("Olá");
5
    }
6
}

2. Now, update your pom.xml adding the build information

1
<project>
4 collapsed lines
2
    <modelVersion>4.0.0</modelVersion>
3
    <groupId>com.joseiedo</groupId>
4
    <artifactId>maven-in-a-nutshell</artifactId>
5
    <version>1.0.0-ALPHA</version>
6

7
    <build>
8
        <!-- The default is src/main/java but let's change for this example ;) -->
9
        <sourceDirectory>.</sourceDirectory>
10
    </build>
11
</project>

3. Run mvn compile and see your compiled code inside the target folder!

~/
$ ls
Main.java pom.xml

27 collapsed lines
~/
$ mvn compile
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< com.joseiedo:maven-in-a-nutshell >------------------
[INFO] Building maven-in-a-nutshell 1.0.0-ALPHA
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ maven-in-a-nutshell ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory /Users/iedo/Study/maven/src/main/resources
[INFO]
[INFO] --- compiler:3.13.0:compile (default-compile) @ maven-in-a-nutshell ---
[INFO] Recompiling the module because of changed source code.
[WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
[INFO] Compiling 1 source file with javac [debug target 1.8] to target/classes
[WARNING] bootstrap class path not set in conjunction with -source 8
[WARNING] source value 8 is obsolete and will be removed in a future release
[WARNING] target value 8 is obsolete and will be removed in a future release
[WARNING] To suppress warnings about obsolete options, use -Xlint:-options.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.306 s
[INFO] Finished at: 2025-11-14T22:08:15-03:00
[INFO] ------------------------------------------------------------------------

~/
$ ls
Main.java pom.xml   target

Under the hood, maven use one of its plugins to run javac automatically passing diverse values that can also be configured in this POM (like source and target) respectively defining java version for source code and artifact.

Build plugins

Frameworks like Quarkus and Spring has their own build plugins to make your life easier, and you can use them in your project. Here is an example using spring-maven-plugin:

1
<project>
2
    <!--- omitted details -->
3
  <build>
4
    <plugins>
5
      <plugin>
6
        <groupId>org.springframework.boot</groupId>
7
        <artifactId>spring-boot-maven-plugin</artifactId>
8
      </plugin>
9
    </plugins>
10
  </build>
11
</project>

This plugin gives you commands like mvn springboot:run that executes your Spring backend and others that make building a Jar file easier.

Maven multi-module

I like multi-module architecture, and it’s very common to see big open source projects using it because of the flexibility you can achieve. I made an example for Quarkus, and it’s available on GitHub.

So, here is the walkthrough!

1. Define a parent pom.xml
2. Add a pom.xml for each module you have. At this point the folder structure should be like this:

1
.
2
├── moduleA/
3
│   └── pom.xml
4
├── moduleB/
5
│   └── pom.xml
6
├── moduleC/
7
│   └── pom.xml
8
└── pom.xml <- parent

3. In the parent pom.xml, declare your modules

1
<project xmlns="http://maven.apache.org/POM/4.0.0"
2
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4
    <modelVersion>4.0.0</modelVersion>
5

6
    <!-- Every module must have this POM as the "parent" -->
7
    <groupId>com.joseiedo</groupId>
8
    <artifactId>parent</artifactId>
9
    <version>1.0.0-ALPHA</version>
10

11
    <modules>
12
        <!-- The artifactId of each module pom.xml should be here -->
13
        <module>module-a</module>
14
        <module>module-b</module>
15
        <module>module-c</module>
16
    </modules>
17

18
    <!-- Parent POMs must have packaging = POM -->
19
    <packaging>pom</packaging>
20

21
</project>

4. In every module add the parent pom.xml

1
<project xmlns="http://maven.apache.org/POM/4.0.0"
2
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4

5
  <modelVersion>4.0.0</modelVersion>
6
    <artifactId>module-a</artifactId>
7
  <version>1.0.0-ALPHA</version>
8

9
  <parent>
10
    <groupId>com.joseiedo</groupId>
11
    <artifactId>parent</artifactId>
12
    <version>1.0.0-ALPHA</version>
13
  </parent>
14
</project>

5. If you have a module depending on another, just add it as a dependency:

1
<project xmlns="http://maven.apache.org/POM/4.0.0"
2
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4

5
  <modelVersion>4.0.0</modelVersion>
6
    <artifactId>module-b</artifactId>
7
  <version>1.0.0-ALPHA</version>
8

9
    <!-- ... -->
10

11
  <dependencies>
12
    <dependency>
13
      <groupId>com.joseiedo</groupId>
14
      <artifactId>module-a</artifactId>
15
    </dependency>
16
  </dependencies>
17
</project>

Maven treats every project/module as a package, so if you have modules depending on each other, run mvn install in the dependency project to compile and be placed in your local repository, being available to the modules depending on it.

mvn quarkus:dev -pl module-a
mvn install -pl module-b

It’s useful to have a parent pom.xml because:

1. You can run build and other commands like mvn install in the root of the project, and all modules will run the command.
2. You store common dependencies versions through <dependencyManagement> tag, also adding build plugins to all modules at the same time and all modules will inherit it, without making you update the used versions everywhere.

Going forward from here

There is a lot of properties I didn’t cover here but at this point I think it would be only me being a proxy for the documentation but writing with my words… For a full list of the possible properties you can use in your pom.xml, go for the documentation, write PoCs and test on your own, this is the best way to learn.

Other tools like gradle follows the same principle (changing the way to config and having bonus features), but the overall knowledge is reusable, so I think it’s worth to learn a bit about it.

So… bye and see you in the next post.