Introduction

Maven is a tool for the management and construction of software projects, especially for those based on Java. Maven has similar goals to make and ant, but with greater emphasis on the configuration by convention.

Maven is hosted by the Apache Software Foundation, and can be found at: http://maven.apache.org.

The main goals of Maven are:

Setting up a Maven project is done through the pom.xml file, which describes the main properties of the project and its dependencies with other modules and external components, as well as the Maven configuration to be applied. On the Maven website there is a reference guide on the pom.xml file format

Following the philosophy of configuration by convention, Maven defines a standard project structure:

project
|-- pom.xml
`-- src
    |-- main
    |   |-- java
    |   `-- resources
    |                   
    `-- test
        |-- java
        `-- resources

If we follow this structure (but if it is different, it can be configured) with a basic configuration, we can perform the typical tasks of any Java project, already predefined in Maven:

Each task is determined by a Maven objective, with its name passed as a parameter. Example:

mvn install

There are two main versions of Maven: 1.0 and 2.0. The latter version is used in gvSIG.

Maven plugins

The functionality provided by Maven consists of a number of plugins that can be registered and configured for each project via the pom.xml.

The most commonly used plugins are registered and configured by default. If we use a different one for our project, or need to adapt the configuration of any existing ones, we can access the Maven plugins page.

For each plugin there is a user guide and documentation on the different parameters that are accepted by the plugin.

The Maven plugin page also provides links to other repositories of available plugins, mainly on codehaus.org and code.google.com.

Local and remote repositories

Maven manages two types of dependency repositories:

Local repository

Local disk location where Maven stores downloaded dependencies, so that they do not have to be downloaded every time. The structure corresponds to one folder per groupId (if the groupID contains points, a subfolder will be created for each element), a folder with the name of the artifactId and finally, a folder with the version.

The downloaded dependencies are stored in the folder of the version. For example, see the following dependency in a pom.xml:

<dependency>
    <groupId>org.gvsig</groupId>
        <artifactId>org.gvsig.tools</artifactId>
        <version>2.0-SNAPSHOT</version>
</dependency>

This will be stored in the local Maven repository with the path:

MAVEN_REPO/org/gvsig/org.gvsig.tools/2.0-SNAPSHOT/org.gvsig.tools-2.0-SNAPSHOT.jar

The files stored by Maven in the local repository can be of type:

When specifying a dependency for our project, Maven will by default download only the .jar file with the compiled classes. However, we can specify that the .jar with the source code and / or the javadoc must be downloaded as well.

Remote repositories

Remote repositories are dependency servers where Maven will look when it cannot find a dependency in the local repository.

Common remote repositories that can be accessed via standard protocols are HTTP/S, FTP, SSH, etc.

The Maven project itself has a dependency repository, accessible by HTTP, which is configured by default. In the pom.xml files you can add other external repositories, or repositories of your own project. For example, gvSIG has its own repository, which is registered by default for the gvSIG projects, in addition to the official repositories.

The gvSIG repository is currently accessible through HTTP as read-only, and through SCP in editing mode. This repository contains mainly the files that are generated by the gvSIG projects, as well as any external dependencies that are not available in the official repository.

Common tasks

The Maven Getting Started Guide describes the common tasks, among which:


Lessons learned

Disable unit tests

To launch Maven in a project and generate jars without launching the unit tests, add the following parameter:

-Dmaven.test.skip=true

Disable the updating of SNAPSHOT dependencies

When offline, or when you want to disable the updating of SNAPSHOT dependencies, add the -o parameter.

Debug unit tests

Sometimes we may need to debug the unit tests of a project, launched by Maven.

To do this, there is a parameter that causes Maven to wait for a remote debug connection on port 5005, before launching each test:

mvn -Dmaven.surefire.debug test

More information can be found in the documentation of the Maven debugging tests plugin

Memory usage

It is possible that for some of the tasks Maven launches, such as the compilation of Java classes, or the generation of Javadoc, the default memory settings will not be enough.

If this happens, an OutOfMemoryError message will appear in the console. We can increase the maximum memory allocation of the JVM by defining the MAVEN_OPTS variable that allows us to pass parameters to the JVM that launches Maven. For example:

Linux:

export MAVEN_OPTS=-Xmx256M

Windows:

set MAVEN_OPTS=-Xmx256M

When there is not enough space for the loading of classes (PermGenSpace), this will produce an error like:

[INFO] Compilation failure
Failure executing javac, but could not parse the error:

The system is out of resources.
Consult the following stack trace for details.
java.lang.OutOfMemoryError: PermGen space
      at java.lang.ClassLoader.defineClass1(Native Method)
      at java.lang.ClassLoader.defineClass(ClassLoader.java:621)

In this case, we will need to increase the PermGen space with the -XX:MaxPermSize parameter. For example:

Linux:

export MAVEN_OPTS=-Xmx256M -XX:MaxPermSize=64m

Windows:

set MAVEN_OPTS=-Xmx256M -XX:MaxPermSize=64m

Use Maven through a proxy

If you access the Internet through a proxy, you will need to configure Maven to download dependencies through this proxy, following the Configuring a proxy instructions at the Maven page.

Basically, this consists of including the corresponding configuration in the .m2/settings.xml file:

<?xml version="1.0" encoding="UTF-8"?>

<settings 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/settings-1.0.0.xsd">

   ...

    <proxies>
        <proxy>
            <active>true</active>
            <protocol>http</protocol>
            <host>proxy.somewhere.com</host>
            <port>8080</port>
            <username>proxyuser</username>
            <password>somepassword</password>
            <nonProxyHosts>www.google.com|*.somewhere.com</nonProxyHosts>
        </proxy>
    </proxies>
</settings>

Available Maven resources