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.

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.

Maven manages two types of dependency repositories:

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

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

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.

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

-Dmaven.test.skip=true

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

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

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

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>

• 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.