Transitioning from Maven 1 to Maven 2 Hands on Tutorial

Transitioning from Maven 1 to Maven 2 project management

Igor Pavlin
Version 0.1
Date: December 1, 2007

This is a "hands on tutorial" for transitioning from Maven 1 to Maven 2 project management. It could be easily a large book, but I will try to keep things short and simple. If you do not understand something please refer to the mentioned literature or feel free to ask me.

For the purposes of this document I will be strict about names Maven 1.x and Maven 2.x, but later we should assume that unless oterhwise specified, when we say maven it will mean Maven 2.x.

The reader is assumed to be completely familiar with Maven 1, and not so much with Maven 2. I recommend reading at least the User documentation at http://maven.apache.org/.
I found book: Better Builds with Maven by Vincent Massol et al. (there is an electronic version available), very valuable. Published by DevZuz Library Press, April 2007.

In hands on approache, I will convert one of the GLAST projects org-glast-groupmanager, that was built with Maven 1, into a Maven 2 project. I will also assume that NetBeans 6.0 is used for building the project using Netbeans Maven 2 plugin. However, initially I will test transitions using command line mvn.

Install Maven 2 for your OS. Link is: http://maven.apache.org/

In Appendix One, I list typical GLAST Maven 1 project files and give a log of a successful 'maven' (Maven 1.x) run.

I will concentrate only on the significant changes when transitioning from Maven 1 to Maven 2. The changes will be presented in tabular forms bellow.

1. Default Directory Structure:

The default directory structure is strongly encouraged, as this leads to better project management. Most of the time you do not need to change the Maven 1 directory
structure, as it usually follows the recommended default structure for Maven 2.

The default directory structure is actually defined in the Maven 2 "Super POM" file, which all Maven 2 POM objects inherit from. Here is the GLAST directory structure for Maven 2 projects:

artifactId/    project directory
|-- .cvsignore    contains files that are local to build: target, profiles.xml, etc
|-- pom.xml    POM
|-- profiles.xml    local, user and project dependent profile definitions; this should not be version controlled
|-- LICENSE.txt    license of the project
|-- README.txt    welcome to the reader
|-- src/    original src material; this should be version controlled
|   |-- main/    the original material for the artifact
|   |   |-- java/    root of main Java source; wil be compiled into target/classes
|   |   |-- resources/    main Java resources; will be copied into target/classes
|   |   |-- webapp/
|   |       |-- WEB-INF/
|   |       |   `-- web.xml
|   |       `-- index.jsp    web application with standard web application structure
|   |   |-- assembly/
|   |       `-- dep.xml    assembly descriptor for maven-assembly-plugin
|   |   |-- filters/    resource filter properties files for main Java resources
|   |   |-- config/    configuration files for the artifact
|   |   |-- bash/
|   |   |-- groovy/
|   |   |-- prolog/
|   |   `-- sql/    sources in other technologies for the artifact
|   |-- site/    project documentation in different formats; mvn site will produce a project website in target/site based on this material and structure (Doxia)
|   |   |-- apt/
|   |   |   |-- format.apt
|   |   |   `-- index.apt    documentation in APT format (wiki-like HTML generation)
|   |   |-- fml/
|   |   |   `-- faq.fml    documentation in FML format (XML based FAQ format)
|   |   |-- resources/
|   |   |   |-- css/
|   |   |   |-- img/
|   |   |   `-- js/    site resources; will be copied into target/site as-is
|   |   |-- site.xml    site descriptor: description of site structure; this will generate menus
|   |   `-- xdoc/
|   |       `-- xdoc.xml    documentation in Xdoc format (XML based HTML generation; maven 1 legacy)
|   `-- test/    original material to test the artifact
|       |-- java/    root of Java source for testing the artifact; usually JUnit test classes; will be compiled into target/test-classes
|       |-- resources/    resources for testing the artifact; will be copied into target/test-classes
|       |-- filters/    resource filter properties files for resources for testing the artifact
|       |-- perl/
|       |-- haskell/
|       `-- python/    sources in other technologies for testing the artifact
`-- target/    generated material; this should not be under version control
    |-- artifactId-version.jar    generated artifact
    |-- classes/    result of compilation of src/main/java and copy of src/main/resources
    |-- exported-pom.xml    consolidated POM
    |-- javadoc/    javadoc of src/main/java
    |-- site/    project site generated by mvn site
    |-- surefire-reports/    test reports
    |-- test-classes/    result of compilation of src/test/java and copy of src/test/resources
    `-- announcement/
            `-- announcement.vm    org.codehaus.mojo:changelog-maven-plugin generates announcement mail here

2. Maven 2 project file pom.xml

The most reliable way to convert from project.xml to pom.xml is to follow the respective XML schema:
1. http://maven.apache.org/maven-v3_0_0.xsd for Maven 1.1.
2. http://maven.apache.org/maven-v4_0_0.xsd for Maven 2.0.

Note: The simplest thing to do in transition from Maven 1 to Maven 2 project building is to convert project.xml file into pom.xml file first. However, there are slight differences that need to be addressed and they are presented in the table bellow. I recommend creating subdirectories in the project directory called maven1 and maven2, where project files from both versions are kept (under the version control), until you are comfortable that your project is fully converted to a Maven 2 project.

You can start by moving project.xml to pom.xml, change pomVersion to modelVersion in the table bellow and than follow some of the mappings (bold letters denote elements that need to be changed. The following table resulted from conversion of project.xml in pom.xml of org-glast-groupmanager.

Mappings between project.xml and pom.xml project elements:

Maven 1.x Maven 2.x Description
<project>

    <project 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/maven-v4_0_0.xsd">    Keep more extended version of project, so you can visit the schema and validate document
<pomVersion>3.0.0</pomVersion>
    <modelVersion>4.0.0</modelVersion>
    Differentiates between different versions of POM objects
<groupId>    <groupId>    Stays the same
<artifactId>     <artifactId>    Stays the same
<currentVersion>    <version>    Same meaning
<shortDescription>     <description>    Same meaning
<package>    Not used, JavaDoc is done differently in Maven 2    The Java package name of the project. This value is used when generating JavaDoc.
<siteAddress>    Not used, hostname is part of url element    The hostname of the web server that hosts the project's web site. This is used when the web site is deployed.
<siteDirectory>    Not used, directory part of url
<repository>    Should be nested into <repositories> element
<developerConnection>    Should be moved to <scm> element for defining connection to SCM (Source Control Management) for developers.    SCM connection for developers
<reports> (and <report>*)    Delete, it is deprecated in Maven 2.
<properties>    If used inside <dependency> delete the element, instead use <scope>, <version>,<type> as described in http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html    Dependency properties
<url>    If used inside <dependency>, delete it.
<sourceDirectory>    Used inside <build>, no need to specify, if the default src directory is used.
<resource>, <directory>    Used inside <resources>, no need to specify,
If the default resources directory is used.

3. File after substitutions:

(Note: This file will still not work, as we need to specify some other Maven 2 properties, like local, GLAST and global repositories, etc.)

<?xml version="1.0" encoding="UTF-8"?>
<!--

Maven 2 is shortly identified as maven. If we want to give a reference to Maven 1.0.2 we will call Maven 1.

This POM extends SuperPOM, which means that the following elements are already defined:
maven central repository (http://repo1.maven.org/maven2)
maven plugin repository (http://repo1.maven.org/maven2)

default build directories:
target
target/classes
target/test-classes
target/site
src/main/java
src/test/java
src/main/scripts
src/main/resources
src/test/resources

as well as default profiles:
release-profile

and default plugins:

maven-source-plugin
maven-javadoc-plugin
maven-deploy-plugin

-->

<modelVersion>4.0.0</modelVersion>
<artifactId>org-glast-groupmanager</artifactId>
<groupId>glast</groupId>
<version>1.6-SNAPSHOT</version>
<description>Glast Group Manager</description>
<url>http://glast-ground.slac.stanford.edu/GroupManager/</url>
<name>Glast Group Manager</name>
<inceptionYear>2005</inceptionYear>
<repositories>
     <!--- Not yet defined ->
</repositories>
<scm>
    <developerConnection>
      scm:cvs:ext:$

Unknown macro: {maven.username}

@glast java.slac.stanford.edu:/cvs/java:$

Unknown macro: {pom.artifactId}

</developerConnection>
</scm>
<dependencies>
    <dependency>
      <groupId>tomcat</groupId>
      <artifactId>servlet-api</artifactId>
      <version>5.0.18</version>
    </dependency>
    <dependency>
      <groupId>tomcat</groupId>
      <artifactId>jsp-api</artifactId>
      <version>5.0.18</version>
    </dependency>
    <dependency>
      <groupId>jstl</groupId>
      <artifactId>jstl</artifactId>
      <version>1.1.2</version>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>taglibs</groupId>
      <artifactId>standard</artifactId>
      <version>1.1.2</version>
      <type>war</type>
    </dependency>
    <!--more dependencies here ->
    <!- Needed by cruisecontrol ->
    <dependency>
      <groupId>maven</groupId>
      <artifactId>maven-scm-plugin</artifactId>
      <version>1.5</version>
      <type>plugin</type>
    </dependency>
</dependencies>
<build>
    <resources>
      <resource>
    <directory>src/main/resource</directory>
    <includes>
    <include>META-INF/*.tld</include>
    </includes>
      </resource>
    </resources>
</build>
</project>

4.    Profiles.xml file
     Todo
3.    Maven 2 repositories.
Todo
4.    Web application deployments on tomcat servers
            Todo
5.    Using inheritance for POM objects
      Todo

Appendix A
project.xml
<?xml version="1.0" encoding="UTF-8"?>
<project>
   <pomVersion>3</pomVersion>
   <artifactId>org-glast-groupmanager</artifactId>
   <groupId>glast</groupId>
   <currentVersion>1.6-SNAPSHOT</currentVersion>
   <shortDescription>Glast Group Manager</shortDescription>
   <url>http://glast-ground.slac.stanford.edu/GroupManager/</url>
   <name>Glast Group Manager</name>
   <package>org.glast.groupmanager</package>
   <inceptionYear>2005</inceptionYear>
   <siteAddress>glast-java.slac.stanford.edu</siteAddress>
   <siteDirectory>/nfs/slac/g/glast/ground/docs/$

</siteDirectory>
   <reports>
      <report>maven-jdepend-plugin</report>
      <report>maven-changes-plugin</report>
      <report>maven-changelog-plugin</report>
      <report>maven-developer-activity-plugin</report>
      <report>maven-file-activity-plugin</report>
      <report>maven-javadoc-plugin</report>
      <report>maven-jxr-plugin</report>
      <report>maven-junit-report-plugin</report>
      <report>maven-linkcheck-plugin</report>
      <report>maven-tasklist-plugin</report>
      <report>taglib</report>
</reports>
   <repository>
      <developerConnection>
scm:cvs:ext:$

@glast-java.slac.stanford.edu:/cvs/java:$

Unknown macro: {pom.artifactId}

</developerConnection>
<url>http://www-glast.stanford.edu/cgi-bin/viewcvs/$

/?root=java</url>
   </repository>
   <dependencies>
      <dependency>
         <groupId>tomcat</groupId>
         <artifactId>servlet-api</artifactId>
         <version>5.0.18</version>
      </dependency>
      <dependency>
         <groupId>tomcat</groupId>
         <artifactId>jsp-api</artifactId>
         <version>5.0.18</version>
      </dependency>
      <dependency>
         <groupId>jstl</groupId>
         <artifactId>jstl</artifactId>
         <version>1.1.2</version>
         <properties>
            <war.bundle>true</war.bundle>
         </properties>
      </dependency>
      <dependency>
         <groupId>taglibs</groupId>
         <artifactId>standard</artifactId>
         <version>1.1.2</version>
         <properties>
            <war.bundle>true</war.bundle>
         </properties>
      </dependency>
      <dependency>
         <groupId>displaytag</groupId>
         <artifactId>displaytag</artifactId>
         <version>1.0</version>
         <url>http://displaytag.sourceforge.net/</url>
         <properties>
            <war.bundle>true</war.bundle>
         </properties>
      </dependency>
      <dependency>
         <groupId>commons-lang</groupId>
         <artifactId>commons-lang</artifactId>
         <version>2.0</version>
         <properties>
            <war.bundle>true</war.bundle>
         </properties>
      </dependency>
      <dependency>
         <groupId>commons-beanutils</groupId>
         <artifactId>commons-beanutils</artifactId>
         <version>1.7.0</version>
         <properties>
            <war.bundle>true</war.bundle>
         </properties>
      </dependency>
      <dependency>
         <groupId>commons-collections</groupId>
         <artifactId>commons-collections</artifactId>
         <version>3.1</version>
         <properties>
            <war.bundle>true</war.bundle>
         </properties>
      </dependency>
      <dependency>
         <groupId>codeczar-tomcat</groupId>
         <artifactId>maven-tomcat-plugin</artifactId>
         <version>1.1</version>
         <type>plugin</type>
         <properties>
            <comment>Compile time only</comment>
         </properties>
      </dependency>
      <dependency>
         <groupId>cas</groupId>
         <artifactId>casclient</artifactId>
         <version>2.1.1</version>
         <url>http://tp.its.yale.edu/tiki/tiki-index.php?page=CentralAuthenticationService</url>
         <properties>
            <war.bundle>true</war.bundle>
         </properties>
      </dependency>
      <dependency>
         <groupId>oracle</groupId>
         <artifactId>ojdbc</artifactId>
         <version>1.4</version>
         <jar>ojdbc14.jar</jar>
      </dependency>
      <dependency>
         <groupId>opensymphony</groupId>
         <artifactId>sitemesh</artifactId>
         <version>2.2.1</version>
         <type>jar</type>
         <properties>
            <war.bundle>true</war.bundle>
         </properties>
      </dependency>
      <!- Needed by cruisecontrol ->
      <dependency>
         <groupId>maven</groupId>
         <artifactId>maven-scm-plugin</artifactId>
         <version>1.5</version>
         <type>plugin</type>
         <url>http://www.ibiblio.org/maven/maven/plugins/</url>
      </dependency>
   </dependencies>
   <build>
      <sourceDirectory>src/main/java</sourceDirectory>
      <resources>
         <resource>
            <directory>src/main/resource</directory>
            <includes>
               <include>META-INF/*.tld</include>
            </includes>
         </resource>
      </resources>
   </build>
</project>

project.properties:

maven.repo.remote=http://mirrors.ibiblio.org/pub/mirrors/maven,http://java.freehep.org/maven,http://glast-ground.slac.stanford.edu/maven
maven.war.src=src/webapp
maven.tomcat.war.context=/GroupManager
maven.war.final.name=GroupManager.war
maven.tomcat.precompile=false
maven.repo.list=glast
maven.repo.glast=scpexe://glast-java.slac.stanford.edu
maven.repo.glast.directory=/nfs/slac/g/glast/ground/maven
maven.site.deploy.method=ssh
maven.compile.target=1.5
maven.compile.source=1.5
taglib.src.dir=src/main/resource/META-INF

maven.xml:

<?xml version="1.0" encoding="UTF-8"?>

<goal name="tomcat03Redeploy">
<u:properties file="$

Unknown macro: {user.home}

/tomcat03.properties" />
        <attainGoal name="clean"/>
        <attainGoal name="tomcat:remove"/>
        <attainGoal name="tomcat:deploy"/>
    </goal>

    <goal name="tomcat03Deploy">
        <u:properties file="$

/tomcat03.properties" />
        <attainGoal name="clean"/>
        <attainGoal name="tomcat:deploy"/>
    </goal>

    <goal name="tomcat01Redeploy">
        <u:properties file="$

Unknown macro: {user.home}

/tomcat01.properties" />
        <attainGoal name="clean"/>
        <attainGoal name="tomcat:remove"/>
        <attainGoal name="tomcat:deploy"/>
    </goal>

    <goal name="tomcat01Deploy">
        <u:properties file="$

/tomcat01.properties" />
        <attainGoal name="clean"/>
        <attainGoal name="tomcat:deploy"/>
    </goal>
</project>

build.properties:

maven.netbeans.exec.run=webReload
maven.netbeans.exec.build=war:war

tomcat01.properties:
maven.repo.remote = http://mirrors.ibiblio.org/pub/mirrors/maven,http://java.freehep.org/maven,http://glast-ground.slac.stanford.edu/maven,http://www.codeczar.com/maven
maven.tomcat.host=glast-tomcat01.slac.stanford.edu
maven.tomcat.port=8080
maven.tomcat.username=glast
maven.tomcat.password=...
maven.tomcat.precompile=false
maven.compile.compilerargs=-Xlint:unchecked
maven.tomcat.war.context=/dp2
maven.war.src=src/main/webapp
maven.war.final.name=dp2.war

and this is a log file produced by running command line maven:

__ __
| \/ |_ _Apache_ ___
| |\/| / _` \ V / -_) ' \ ~ intelligent projects ~
|| |_,|_/__|||_| v. 1.0.2

build:start:

war:init:

war:war-resources:
    [mkdir] Created dir: /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager
    [mkdir] Created dir: /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF
    [copy] Copying 15 files to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF

java:prepare-filesystem:
[mkdir] Created dir: /Users/igor/work/java/glast/org-glast-groupmanager/target/classes

java:compile:
[echo] Compiling to /Users/igor/work/java/glast/org-glast-groupmanager/target/classes
[javac] Compiling 6 source files to /Users/igor/work/java/glast/org-glast-groupmanager/target/classes

java:jar-resources:
Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/classes

test:prepare-filesystem:
[mkdir] Created dir: /Users/igor/work/java/glast/org-glast-groupmanager/target/test-classes
[mkdir] Created dir: /Users/igor/work/java/glast/org-glast-groupmanager/target/test-reports

test:test-resources:

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

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

war:webapp:
    [echo] Assembling webapp org-glast-groupmanager
    [mkdir] Created dir: /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [mkdir] Created dir: /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/tld
    [mkdir] Created dir: /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/classes
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 1 file to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/lib
    [copy] Copying 11 files to /Users/igor/work/java/glast/org-glast-groupmanager/target/org-glast-groupmanager/WEB-INF/classes

war:war:
[echo] Building WAR org-glast-groupmanager
[jar] Building jar: /Users/igor/work/java/glast/org-glast-groupmanager/target/GroupManager.war
BUILD SUCCESSFUL
Total time: 4 seconds
Finished at: Thu Nov 29 15:59:57 PST 2007

Child pages

Transitioning from Maven 1 to Maven 2 Hands on Tutorial