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 otherwise 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 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 this hands on approach, 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. Initially I would test transitions using command line program mvn.

Install Maven 2 for your OS and set MVN_HOME, as well as create .m2 directory in your home(working) directory. 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 bellow 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:

(a) Where to begin?

For simpler projects one can simply start with converting project.xml to pom.xml (after saving all the project Maven1 build files into maven1 subdirectory.

For more complex projects the rule of thumb is to produce one artifact (JAR, WAR, etc.) per Maven project file. That means that it is prudent to create a maven2 (or m2) directory
where all the existing code is copied and than rearranged into several subprojects (modules). A parent pom.xml and subproject pom.xml files are than created and each module built separately. I will give an example later in section ... When you are finished with migration you can easily remove the old Maven 1 build.

In the m2 directory, you will need to create a parent POM. You will use the parent POM to store the common configuration settings that apply to all of the child modules. For example, each module will inherit the following values (settings) from the parent POM.
? groupId: this setting indicates your area of influence, company, department, project, etc., and it should mimic standard package naming conventions (for GLAST this is just 'glast' , but in general it will be com.yourcompany.projectname). Maven 2 will than install the files under _{/.m2/repository/glast or (}/.m2/repository/com/yourcompany/projectname)
? artifactId: the setting specifies the name of this module (for example, org-glast-groupmanager). The convention here at GLAST is that all the top projects should be prefixed with org-glast-
? version: this setting should always represent the next release version number appended with - SNAPSHOT - that is, the version you are developing in order to release. During the release process, Maven will convert to the definitive, non-snapshot version for a short period of time, in order to tag the release in your SCM.
? packaging: the jar, war, and ear values should be obvious to you (a pom value means
that this project is used for metadata only - when it is a parent project of several subprojects)

In this parent POM you can also add dependencies such as JUnit, which will be used for testing in every module, thereby eliminating the requirement to specify the dependency repeatedly across multiple modules.

The other possible addition to the parent POM files is specifying build properties that are common to all the modules, for example JDK settings, etc. This will be described later.

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 rename 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 the org-glast-groupmanager project. Mappings between project.xml and pom.xml elements:

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

-->


<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">

  	<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:${maven.username}@glast   java.slac.stanford.edu:/cvs/java:${pom.artifactId}  <!-- to be verified -->
                </developerConnection>
         </scm>
         <dependencies>
		<!-- dependencies here -->
		<dependency>
      			<groupId>tomcat</groupId>
      			<artifactId>servlet-api</artifactId>
      			<version>5.0.18</version>
    		</dependency>
		<!-- ... -->
		<!-- 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> <!-- should have been resources -->
			<includes>
	  			<include>META-INF/*.tld</include>
			</includes>
      		</resource>
    </resources>
  </build>
</project>

4. profiles.xml file

If we run mvn install target with this POM file, it will still not build completely as we need to locate dependencies that are not found in the parent POM central repositories (modules and plugins): http://repo1.maven.org/maven2

Maven 2 profile files

Profiles are Maven 2 way of letting you create environmental variations in the build life cycle to accommodate things like building on different platforms, building with different JVMs, testing with different databases, or referencing the local file system. Typically, you try to encapsulate as much as possible in the POM to ensure that builds are portable, but sometimes you simply have to take into consideration variation across systems and this is why profiles were introduced in Maven 2.

Profiles modify the POM at build time, and are meant to be used in complementary sets to give equivalent-but-different parameters for a set of target environments (providing, for example, the path of the application server root in the development, testing, and production environments).

As such, profiles can easily lead to differing build results from different members of your team. However, used properly, you can still preserve build portability with profiles. You can define profiles in one of the following three places:

? The Maven 2 settings file (typically <your -home-directory>/.m2/settings.xml)
? A file in the the same directory as the POM, called profiles.xml
? The POM itself

In terms of which profile takes precedence, the local-most profile wins. So, POM-specified profiles override those in profiles.xml, and profiles.xml overrides those in settings.xml. This is a pattern that is repeated throughout Maven 2, that local always wins, because it is assumed to be a modification of a more general case. settings.xml profiles have the potential to affect all builds, so they're sort of a "global" location for profiles. profiles.xml allows you to augment a single project's build without altering the POM.
And the POM-based profiles are preferred, since these profiles are portable (they will be distributed to the repository on deploy, and are available for subsequent builds originating from the repository or as transitive dependencies).

Because of the portability implications, any files which are not distributed to the repository are NOT allowed to change the fundamental build in any way. Therefore, the profiles specified in profiles.xml and settings.xml are only allowed to define:

? repositories
? pluginRepositories
? properties

Everything else must be specified in a POM profile, or in the POM itself, or not at all. For example, if you had a profile in settings.xml that was able to inject a new dependency, and the project you were working on actually did depend on that settings-injected dependency in order to run, then once that project is deployed to the repository it will never fully resolve its dependencies transitively when asked to do so. That's because it left one of its dependencies sitting in a profile inside your settings.xml file.

For example, GLAST specific m2 repository should be specified in profiles.xml file (thus allowing developers outside GLAST to refer to some other repositories), and developer specific m2 repository (if the developer keeps its own repository) can be specified in settings.xml file.

(c) Profile file structure

You can define the following elements in the POM profile:

? repositories
? pluginRepositories
? dependencies
? plugins
? properties (not actually available in the main POM, but used behind the scenes)
? modules
? reporting
? dependencyManagement
? distributionManagement

A subset of the build element, which consists of:

? defaultGoal
? resources
? testResources
? finalName

(d) Activating profiles

Since you build profiles for specific tasks (like debug build or test build), you need to have mechanism to identify and activate the profiles in different situations.

There are several ways that you can activate profiles:

1. Profiles can be specified explicitly using the mvn - P command line option. This option takes an argument that contains a comma-delimited list of profile-ids. When this option is specified, no profiles other than those specified in the option argument will be activated.

For example:

mvn -Pprofile1,profile2 install

2. Profiles can be activated in the Maven settings, via the activeProfiles section. This section takes a list of activeProfile elements, each containing a profile-id. Note that you must have defined the profiles in your settings.xml file as well. For example:

<settings>
[...]
<profiles>
<profile>
<id>profile1</id>
[...]
</profile>
</profiles>
<activeProfiles>
<activeProfile>profile1</activeProfile>
</activeProfiles>
[...]
</settings>

3. Profiles can be triggered automatically based on the detected state of the build environment. These activators are specified via an activation section in the profile itself. Currently, this detection is limited to prefix-matching of the JDK version, the presence of a system property, or the value of a system property. Here are some examples:

3.1.

<profile>
<id>profile1</id>
[...]
<activation>
<jdk>1.4</jdk>
</activation>
 </profile>

This activator will trigger the profile when the JDK's version starts with "1.4" (e.g., "1.4.0_08", "1.4.2_07", "1.4").

3.2

<profile>
<id>profile1</id>
[...]
<activation>
<property>
<name>debug</name>
</property>
</activation>
</profile>

This will activate the profile when the system property "debug" is specified with any value.
         3.3 

<profile>
<id>profile1</id>
[...]
<activation>
<property>
<name>environment</name>
<value>test</value>
</property>
</activation>
</profile>

This last example will activate the profile when the system property "environment" is specified with the value "test".


h3. (e)	profiles.xml  file for org-glast-groupmanager

Based on the general discussion above of profiles, I  have chosen initially the following profiles.xml file. 

Note: settings.xml file in my Maven2 repository directory (~igor/.m2) is just:

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

The profiles file will initially point to project specific repositories that are needed to complete the dependency resolution. In the transition period, when some of the files are in Maven 1 repositories (both GLAST and developer ) and only some of the files are in GLAST  Maven 2 respository:

 http://glast-ground.slac.stanford.edu/maven2/ or
/nfs/slac/g/glast/ground/maven2

we need to establish the set of repositories to follow the following path in the order of precedence:

1.	http://repo1.maven.org/maven2/ 
2.	any outside repositories not in maven2 repository above (like apache.org, sun.com, freehep.org)
3.	http://glast-ground.slac.stanford.edu/maven2/
4.	http://glast-ground-slac.stanford.edu/maven1/
5.	and only than developer specific repositories:
6.	~developer/.m2/repository
7.	~developer/.maven/repository

Note: as we download specific dependencies, extra dependencies might be downloaded, based on the dependencies specified in downloaded POM files.

The best practice is to define GLAST wide parent POM file, which will define GLAST specific repositories, settings, etc, which all the GLAST Java projects will use. Untils than I will assume that settings and properties in profile.xml will slowly migrate up the hieararchy to project POM files, up to its parent GLAST POM file.



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

h2. Appendix A

Here we give Maven 1.x files  for reference:

project.xml file:

<?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/$

</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>

<!-- more dependencies -->

<!- 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 file:

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 file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:j="jelly:core"
xmlns:u="jelly:util" default="war">
<goal name="webInstall">
<attainGoal name="tomcat:install"/>
</goal>
<goal name="webReload">
<attainGoal name="tomcat:remove"/>
<attainGoal name="tomcat:install"/>
</goal>
<goal name="webRemove">
<attainGoal name="tomcat:remove"/>
</goal>
<goal name="tomcat03Redeploy">
<u:properties file="$

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

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

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

build.properties file:

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

__ __

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