Basic individual project build and deployment

Maven is a build system that was created to reduce the redundancy that developers found when using Ant. It uses Ant tasks and allows developers to port Ant tasks to Maven, but not by using the same build files. Luckily, this allowed us to simultaneously maintain the Ant build structure in our projects and move to Maven. Maven's default build file is named 'project.xml' and corresponds roughly to Ant's build.xml. Similarly, Ant tasks are called goals in Maven. The goal scheme, which I'll describe in more detail later, is pretty easy to use and extend once you have an understanding of it. Goals are contained within plugins, which is a jar file that Maven can download, install, and run when it is called for. Goals can also be contained within a file named 'maven.xml' which is scripted in a language called 'Jelly'.

The most fundamental task that a user would want to use Maven for is to build a jar file from a java project. The only requirement to be able to do that (besides the normal java source files) is to have a simple project.xml file at the base of the project structure. Using our typical project structure, I'll use Projects/Framework as an example of a basic project. The following is the most rudimentary build file you can have to allow Maven to successfully build a project:

<project>
<artifactId>framework</artifactId>
<currentVersion>1.26</currentVersion>
<build>
<sourceDirectory>src</sourceDirectory>
</build>
</project>

In this example, we are just defining the ${artifactId}, which is the output name of the jar file (among other things), the version, and the source directory. Maven uses defaults for values that are not defined if it can. Here is a listing of most of the main Maven properties.

NOTE: Maven uses an xml scripting language called Jelly for extending it's functionality. The variable, or property, notation is ${var name} and will be used throughout these documents. If you're wondering why the xml element named artifactId is also using the Jelly notation, it's because it can be referenced from within Jelly scripts as well, although the real variable name would be ${pom.artifactId}. Pom stands for Project Object Model, which is the project.xml file.

A full listing of elements recognized in the project.xml file is here.

Project resources to include in jar files

Using the above project.xml file, Maven looks for the source files in a directory called 'src'. If there are other types of files that should be included in the output jar file, there would be other element definitions required within the '<build>' element tags for those types of files and their locations such as resources:

<build>
    <resources>
      <resource>
        <directory>${basedir}/src</directory>
        <includes>
          <include>org/concord/domain/ui/images/**</include>
        </includes>
      </resource>
    </resources>
</build>

The above code-snippet is from the Projects/Domain project and tells Maven to include anything in '${basedir}/src' directory that matches the pattern 'org/concord/domain/ui/images/**'. Obviously, that pattern will only match something in the matching path, but coding it this way puts it in the jar file with the path prepended, whereas, if the '<directory>' tag was '${basedir}/src/org/concord/domain/ui/images', the path in the jar file would only be the file name or directory path below the resource directory.

Running Maven

So, this is the directory structure:

Image of framework project directory structure

As you can see from the project structure, the Ant build.xml and Maven project.xml exist together in the top of the project, known as the ${basedir} property in Maven, without interfering with each other. This allows users to continue building using Ant or Maven, whichever they prefer.

Once the project.xml file is in the ${basedir}, we can run the command needed to generate the jar file:

maven jar

Of course, this assumes your installation of Maven is working. The 'jar' argument tells Maven which goal to run, in this case, the jar goal of the jar plugin. If there was another goal of the jar plugin to run, it would need to be explicitly named, such as jar:snapshot. The 'jar' goal just happens to be the default goal of the jar plugin, so it doesn't need to be qualified, although it could have been (jar:jar). Use the command 'maven -g' to see a listing of all installed Maven goals. To see a list of released plugins and their associated goals and properties, look here.

The 'jar' goal will do a couple of things by default that a developer will usually find acceptable and won't need to change as is the case with many Maven plugins. This is the typical output from the jar goal:

eblack@ubuntu:/tmp/Projects/Framework $ maven jar
__ __
| \/ |__ _Apache__ ___
| |\/| / _` \ V / -_) ' \ ~ intelligent projects ~
|_| |_\__,_|\_/\___|_||_| v. 1.0.2

build:start:

java:prepare-filesystem:
    [mkdir] Created dir: /tmp/Projects/Framework/target/classes

java:compile:
    [echo] Compiling to /tmp/Projects/Framework/target/classes
    [echo]
==========================================================

NOTE: Targeting JVM 1.4, classes
will not run on earlier JVMs

==========================================================

    [javac] Compiling 83 source files to /tmp/Projects/Framework/target/classes

java:jar-resources:

test:prepare-filesystem:
    [mkdir] Created dir: /tmp/Projects/Framework/target/test-classes
    [mkdir] Created dir: /tmp/Projects/Framework/target/test-reports

test:test-resources:

test:compile:
    [echo] No test source files to compile.

test:test:
    [echo] No tests to run.

jar:jar:
    [jar] Building jar: /tmp/Projects/Framework/target/framework-1.26.jar
BUILD SUCCESSFUL
Total time: 5 seconds
Finished at: Tue Mar 22 17:10:59 EST 2005

eblack@ubuntu:/tmp/Projects/Framework $

The listing shows that a directory path is created, called 'target/classes'. This is the ${maven.build.dest} property. The 'target' directory itself is the ${maven.build.dir} and is used for the top directory of a number of derived actions. As you can see at the end of the above listing, it is also the default location for the output jar file.

The naming of the output jar file follows the Maven convention; artifactId-version.extension. The version will be taken from the <currentVersion> element in the project.xml file or can be set to SNAPSHOT by running the 'jar:snapshot' goal. The extension is automatically set to 'jar' when using the jar plugin and it's goals.

Local deployment of artifacts

Unless your output jar file is a runnable application, chances are you'll want to be able to use it by other projects. To do that, you'll need to install the jar file somewhere other Maven projects can find it. There are a number of ways to make your jar files accessible to other Maven projects, but in this section we'll only describe how to make it available on your local system (see Repository building for more advanced deployment).

NOTE: Maven calls the location of deployed artifacts a repository. There are two types of repositories: local and remote. Remote repositories exist on a server somewhere (we have one at http://source.concord.org) as would most organizations for internal development and deployment. Maven maintains the central repository for Maven at http://www.ibiblio.org/maven for any publicly available plugins. That is the default server that a Maven build will attempt to deploy to or retrieve artifacts from. Local repositories are located in '${user.home}/.maven', also referred to as '${maven.home.local}', in the 'repository' directory (which also has a property associated with it called ${maven.repo.local}).

The command for deploying an artifact locally is:

maven jar:install

If the jar is not already created, it will be built, then deployed to the local repository where it can be referenced by other projects if they call it as a dependency.