Maven2 Introduction part 1: the Coordinate System

Maven is gaining traction as the premiere form of Java code organization and managing builds. The entire world won't convert overnight, but adoption is likely to steadily increase once more people get over the learning curve and conceptual difference with ant scripts, the previous prevailing model of build management. In this article I'm going to try to take a bit of the steepness off of the learning curve for you.

The big sell for Maven is the dependency management and the coherence it brings to both your individual projects, and your code development overall. And by dependency management, I mostly mean where and which jar files you use. For ant users reading this, this is a way more than what the "depends" attribute of an ant target gets you. It's a way of:

• Avoiding confusion between different versions of the same jars


• Maintaining only one copy of the same jar on your computer (instead of having one copy for each of your projects that use it)


• Having a mechanism that retrieves jars (and making sure it is the right version as well) from the internet for you without you having to think about where it should be stored

Maven does this my having a highly structured approach to dependencies, and importantly, the adherence to this framework by the community who uses Maven. In this part of the article I'll start by covering the cornerstone of the Maven approach, the "Coordinate System," then we'll move on to Maven repositories.

The Coordinate System: groupId, artifactId and version

At the core of Maven 2 is its method of identifying resources (mostly jar files) by a strictly followed practice of file and directory naming. The goal is similar to that of XML namespaces and the java packaging conventions: to define items as distinct points in space according to a unversally followed set of conventions. It's simply these four identifiers:

• groupId: usually a reversed domain name such as com.lowagie.


• artifactId: a common name for the resource, such as itext.


• version: a version indicator such as 1.4. Numbers and decimals are typical, but not required, values for the version.


• packaging: the type of end product which could be ear or war, but is most often jar (and therefore the default, so packaging need not be specified)

(A side note about the groupId: there are many jars out there that do not use their organization's reverse domain name. In fact, they comprise some of the most widely used jars out there: log4j, jdom, ant, and xalan to name a few. All they use for their groupId is their simple well-known name (log4j, jdom, ant, and xalan for the examples just mentioned), and their artifactId is the same. These famous jars just happen to have been on the scene during an earlier version of Maven before the convention of using reversed domain names took hold; they held on to their old coordinate locations instead of updating.)

1. Here is the location of a jar file named itest-1.4.jar in a proper Maven repository. The initial part is chosen by the individual user (c:/.m2/repository) but everything following that is dictated by the coordinate system:
   
   c:/.m2/repository/com/lowagie/itext/1.4/itext-1.4.jar
   


2. In the same directory as itest-1.4.jar, you will find the file itest-1.4.pom. This is an XML file containing the following:
   
   

   
   <project >
   
   <modelVersion>4.0.0</modelVersion>
   
   <groupId>com.lowagie</groupId>
   
   <artifactId>itext</artifactId>
   
   <packaging>jar</packaging>
   
   <version>1.4</version>
   
   </project>
   
   

   
   
   


3. In the project's root directory, you will find a file called pom.xml, and that file will contain the same lines as above, but wrapped inside a <dependency> element:
   
   

   
   <dependency >
   
   <modelVersion>4.0.0</modelVersion>
   
   <groupId>com.lowagie</groupId>
   
   <artifactId>itext</artifactId>
   
   <packaging>jar</packaging>
   
   <version>1.4</version>
   
   </dependency>
   
   

   
   
   


4. Retrieval of resources over the internet is integral to maven. A jar can be referred to by its URL on a known repository. The first part of the URL is specific to the repository, whereas the rest follows the file structure of the coordinate system. Here is a URL for the location of a jar at the well-known repository ibiblio:
   http://mirrors.ibiblio.org/pub/mirrors/maven2/com/lowagie/itext/1.4/itext-1.4.jar
   


5. Now here is a Maven command line statement. It's purpose is to install a jar in a repository, but don't worry about that right now; just notice how the coordinate system manifests itself on a typical command line statement.
   

   
   mvn install:install-file -DgroupId=com.lowagie \
   
   -DartifactId=itext \
   
   -Dversion=1.4 \
   
   -Dpackaging=jar \
   
   -Dfile=itext-1.4.jar
   

   
   
6. Occasionally a point in space is referenced with a single line of text, using the format
   
   groupId:artifactId:packaging:version, as in:
   
   com.lowagie:itext:jar:1.4
   

These 5 situations show you most of the ways in which jars are referenced in the Maven world. There is a maddening consistency and pervasiveness to the Coordinate System throughout Maven. The more you learn about Maven, the more you discover you've already learned it.