Comprehensive Maven Tutorial: Installation, Configuration, Lifecycle, Dependencies, and Eclipse Integration

Preface

All of my projects currently use Maven, but I never had time to study it; this article records my learning and organization of Maven concepts.

1. Why use a build tool like Maven?

1.1 A project is an engineering unit

When a project becomes large, it is better to split it into multiple Maven modules, each represented by its own project, which facilitates division of labor and collaboration.

1.2 Managing JAR dependencies

Without Maven, the same JAR must be manually copied into each project's lib directory, leading to repetitive work. Maven stores JARs in a local repository and allows projects to reference them without copying.

1.3 Consistent acquisition of JARs

Maven provides a uniform way to download JARs from remote repositories, eliminating the need to manually download them from various websites.

1.4 Version inconsistency risk

Different projects may use different versions of the same JAR, causing runtime errors. Maven ensures that all projects use the same version from the repository.

1.5 Transitive dependencies

If a JAR depends on other JARs, Maven automatically resolves and adds those dependencies, saving time and reducing learning overhead.

2. What is Maven?

2.1 Definition

Maven is an automation build tool for the Java platform. Its evolution can be seen as make → Ant → Maven → Gradle .

2.2 Build concept

Build means compiling a dynamic web project and deploying the compiled result to a server.

编译：java源文件[.java] → 编译 → Class文件[.class]
部署：将编译后的文件部署到Servlet容器中

2.3 Build phases

The main phases are clean, compile, test‑compile, test, package, install, and deploy, each performing specific tasks such as cleaning old files, compiling source code, running tests, packaging JAR/WAR files, and publishing to repositories.

3. Installing Maven

3.1 Verify JAVA_HOME

Ensure the JAVA_HOME environment variable is set.

3.2 Download and extract Maven

Place the extracted Maven directory in a path without Chinese characters or spaces.

3.3 Configure environment variables

Add M2_HOME pointing to the Maven root directory and append %M2_HOME%\bin to the PATH variable.

3.4 Verify installation

Run mvn -v to display the Maven version and confirm the setup.

4. First Maven project

4.1 Directory structure

The conventional Maven layout is:

project-root/
├─ src/
│  ├─ main/java/          (source code)
│  ├─ main/resources/     (configuration files)
│  └─ test/               (test code)
└─ pom.xml                (project descriptor)

4.2 Sample source file

Create src/main/java/com/hzg/maven/Hello.java with the following content:

package com.hzg.maven;
public class Hello {
    public String sayHello(String name) {
        return "Hello " + name + "!";
    }
}

4.3 Sample pom.xml

<?xml version="1.0" ?>
<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.hzg.maven</groupId>
    <artifactId>Hello</artifactId>
    <version>0.0.1‑SNAPSHOT</version>
    <name>Hello</name>
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

4.4 Common Maven commands

mvn clean – clean old build files. mvn compile – compile main sources. mvn test‑compile – compile test sources. mvn test – run unit tests. mvn package – create JAR/WAR. mvn install – install the artifact into the local repository.

5. Repository and coordinates

5.1 pom.xml

The pom.xml (Project Object Model) is Maven’s core configuration file where all build settings, dependencies, plugins, and metadata are defined.

5.2 Coordinates

A Maven artifact is uniquely identified by three coordinates: <groupId> , <artifactId> , and <version> . The repository path follows the pattern groupId/artifactId/version/artifactId-version.jar .

5.3 Repository types

Local repository resides at %USERPROFILE%\.m2\repository . Remote repositories include private Nexus servers and the public Central Repository.

6. Dependency management

6.1 Resolution process

Maven first looks for a dependency in the local repository; if missing, it downloads it from the remote repository and caches it locally.

6.2 Scope

Dependency scopes control where a JAR is available:

compile – default, available in all phases.

provided – needed for compilation but supplied by the runtime container.

runtime – required only at execution time (e.g., JDBC drivers).

test – only for test compilation and execution.

system – similar to provided but requires an explicit path; Maven does not search the repository.

6.3 Transitive dependencies

Dependencies of a dependency are automatically included unless their scope prevents transitivity.

7. Maven lifecycle

7.1 Clean lifecycle

pre‑clean → clean → post‑clean.

7.2 Default lifecycle

validate, generate‑sources, process‑sources, generate‑resources, process‑resources, compile, process‑classes, test‑compile, test, package, verify, install, deploy.

7.3 Site lifecycle

pre‑site → site → post‑site → site‑deploy.

8. Using Maven in Eclipse

8.1 Configuration

Open Window → Preferences → Maven → Installations and add the extracted Maven directory. Then set the user settings file ( settings.xml ) under Window → Preferences → Maven → User Settings to configure the local repository path.

8.2 Creating a Maven Web project

Use File → New → Maven Project , select a web archetype, and follow the wizard. After creation, adjust the JDK version, project facets (e.g., Dynamic Web Module 3.1, Java 1.8), and add required libraries such as Tomcat.

9. Advanced Maven features

9.1 Dependency transitivity

When WebMavenDemo depends on JavaMavenService1 , which in turn depends on JavaMavenService2 , Maven automatically includes JavaMavenService2 ’s JARs in the final build.

9.2 Version conflict resolution

Shortest path wins: the version from the nearest dependency is used. If paths are equal, the version declared first in the pom.xml wins. Centralized version management can be achieved with <properties> and placeholders like ${spring.version} .

10. Build configuration

<build>
    <finalName>WebMavenDemo</finalName>
    <resources>
        <resource>
            <directory>src/main/java</directory>
            <includes><include>**/*.xml</include></includes>
            <excludes><exclude>**/*.txt</exclude><exclude>**/*.doc</exclude></excludes>
        </resource>
    </resources>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>2.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <version>2.1</version>
            <configuration>
                <warName>WebMavenDemo1</warName>
            </configuration>
        </plugin>
    </plugins>
</build>

Conclusion

After configuring the build, running mvn package generates the expected JAR/WAR files in the target directory. The article ends with two recommended Maven repository websites: mvnrepository.com and maven.aliyun.com .