Maven

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:

Facilitate the process of compilation and construction of the project.
Generate quality documentation for the project.
Provide development guidelines based on best practices.
To facilitate seamless migration to new features of Maven.

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:

Compilation of code.
Packaging in .jar, .war or .ear files.
Generation of javadoc and other reports.
Implementation of unit tests.
etc.

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:

pom.xml: the configuration and dependencies of the dependency. In this way, Maven will download the entire tree of dependencies that is needed at any given time so that we don?t have to specify the dependencies of a dependency of our project.
.jar file with compiled classes.
.jar file with source code.
.jar file with javadoc.
etc.

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:

Compile a project:
```
mvn compile
```
Generate the artifacts (usually .jar files) and install them in the local Maven repository so that they are available for the other projects. This in turn implies the compilation, generation of .jar files, launching of tests
```
mvn install
```
Upload a generated jar (or jars) to the Maven repository, to publish a binary for the other projects:
```
mvn deploy
```
This option will be used when we have finished a version of a project that we want to publish so that it is accessible for other developers.
Delete everything that is generated with Maven, within the project:
```
mvn clean
```
Launch the unit tests:
```
mvn test
```
NOTE: Keep in mind that it is the virtual machine through which Maven is invoked that will launch the unit tests. This implies that, in general, we have the same requirements as gvSIG itself, such as having the JAI installed. This must be taken into account, also because the unit tests will be launched when generating a build.

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

The Maven project website: is the place where we can get the latest versions of Maven, general documentation and main plugins, etc.
The dependency browser of the Maven project repository: this lets you search for artifacts from the Maven project repository that you may want to include as dependencies.
The Codehaus plugin repository: the Mojo project of Codehaus develops additional plugins for Maven.
The book Better Builds With Maven: the authors are some of the main developers of Maven, and we can download a free copy of the book after registration.
Maven: The Definitive Guide: another book about Maven, available for reading online or as a PDF download under a Commons license.