2.3. Maven Essentials

This section provides a quick introduction to some essential Maven concepts, enabling you to understand the fundamental ideas of the Maven build system.

Maven defines a standard set of phases in the build lifecycle, where the precise sequence of phases depends on what type of package you are building. For example, a JAR package includes the phases (amongst others): compile, test, package, and install.

When running Maven, you normally specify the phase as an argument to the mvn command, in order to indicate how far you want the build to proceed. To get started, the following are the most commonly used Maven commands:

Example 2.1, “Standard Maven Directory Layout” shows the standard Maven directory layout. Most important is the Maven POM file, pom.xml, which configures the build for this Maven project.

ProjectDir/
    pom.xml
    src/
        main/
            java/
                ...
            resources/
                META-INF/
                    spring/
                        *.xml
                OSGI-INF/
                    blueprint/
                        *.xml
        test/
            java/
            resources/
    target/
        ...

The project's Java source files must be stored under ProjectDir/src/main/java/ and any resource files should be stored under ProjectDir/src/main/resources/. In particular, Spring XML files (matching the pattern *.xml) should be stored under the following directory:

ProjectDir/src/main/resources/META-INF/spring/

Blueprint XML files (matching the pattern *.xml) should be stored under the following directory:

ProjectDir/src/main/resources/OSGI-INF/blueprint/

An important principle of Maven is that of convention over configuration. What this means is that Maven's features and plug-ins are initialized with sensible default conventions, so that the basic functionality of Maven requires little or no configuration.

In particular, the location of the files within Maven's standard directory layout effectively determines how they are processed. For example, if you have a Maven project for building a JAR, all of the Java files under the src/main/java directory are automatically compiled and added to the JAR. All of the resource files under the src/main/resources directory are also added to the JAR.

Maven defines a variety of packaging types, which determine the basic build behavior. The most common packaging types are as follows:

The end product of a Maven build is a Maven artifact (for example, a JAR file). Maven artifacts are normally installed into a Maven repository, from where they can be accessed and used as building blocks for other Maven projects (by declaring them as dependencies).

Artifacts are uniquely identified by a tuple of Maven coordinates, usually consisting of groupId:artifactId:version. For example, when deploying a Maven artifact into the Red Hat JBoss Fuse container, you can reference it using a Maven URI of the form, mvn:groupId/artifactId/version.

For more details about Maven coordinates, see chapter "Building with Maven" in "Deploying into Apache Karaf".

The most common modification you will need to make to your project's POM file is adding or removing Maven dependencies. A dependency is simply a reference to a Maven artifact (typically a JAR file) that is needed to build and run your project. In fact, in the context of a Maven build, managing the collection of dependencies in the POM effectively takes the place of managing the collection of JAR files in a Classpath.

The following snippet from a POM file shows how to specify a dependency on the camel-blueprint artifact:

<project ...>
    ...
    <dependencies>
        <dependency>
            <groupId>org.apache.camel</groupId>
            <artifactId>camel-blueprint</artifactId>
            <version>2.17.0.redhat-630xxx</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    ...
</project>

The dependency element declares a dependency on the Maven artifact with coordinates org.apache.camel:camel-blueprint:6.3.0.redhat-xxx. You can add as many dependency elements as you like inside the dependencies element.

The scope element is optional and provides some additional information about when this dependency is needed. By default (with the scope element omitted), it is assumed that the dependency is needed at build time, at unit test time, and at run time. With scope set to the value, provided, the effect depends on what kind of artifact you are building:

To simplify the list of dependencies in your POM and to avoid having to list every single dependency explicitly, Maven employs a recursive algorithm to figure out the dependencies needed for your project.

For example, if your project, A, depends on B1 and B2; B1 depends on C1, C2, and C3; and B2 depends on D1 and D2; Maven will automatically pull in all of the explicitly and implicitly required dependencies at build time, constructing a classpath that includes the dependencies, B1, B2, C1, C2, C3, D1, and D2. Of these dependencies, only B1 and B2 appear explicitly in A's POM file. The rest of the dependencies—which are figured out by Maven—are known as transitive dependencies.

A Maven repository is a place where Maven can go to search for artifacts. Because Maven repositories can be anywhere—and that includes anywhere on the Internet—the Maven build system is inherently distributed. The following are the main categories of Maven repository:

For more details about Maven repositories, see chapter "Building with Maven" in "Deploying into Apache Karaf".

If you need to customise the remote repositories accessible to Maven, you must separately configure the build-time and runtime repository locations, as follows: