Tips for using Maven2

A while ago I decided it was time to abandon the old familiar Ant build tool and try Maven. Everyone claims that Maven is much better than Ant so I thought lets give it a go. Unfortunately I found the documentation available on the net confusing and hard to follow.

Maybe it just me but its almost as if no-one could explain Maven in a short tutorial. The first thing that I found confusing is that it is difficult to tell when people are talking about Maven 1 or Maven 2. The differences between the two are so great that they might as well be different projects. To be clear these tips refer to maven 2.

1) Download maven 2 from the apache site and unzip it in your preferred location. I put mine in

"/home/<user>/applications"

2)There are a few variables that need to be set before you start using maven. You need to set your M2_REPO variable which tells maven where your local repos is. Also you need to define a M2_HOME variable which points to your maven installation and, of course update your path variable. On a Linux box you can do this by editing your /home/<user>/.bashrc file and adding the following lines.

PATH="$PATH:/home/<user>/applications/maven-2.0.4/bin"
M2_REPO="/home/<user>/.m2/"
M2_HOME="/home/<user>/applications/maven-2.0.4"
export M2_REPO
export M2_HOME
export PATH

You may need to create the local repository directory. This is usually /home/<user>/.m2/repository. Maven should create this for you automatically when you run it for the first time.


3) One thing to note is that if you are behind a windows (ntlm) firewall it is almost impossible to get maven to connect to external repositories to download dependencies. This seems to be a well kept secret for maven. No one mentions it and you can spend an in-ordinate amount of time edting setting.xml and pom.xml files etc in a vain attempt to get it to work.

You can get it working by installing ntlmaps and then setup your /etc/ntlmaps/server.cfg to point to the windows firewall and setup maven to use this pseudo ntlmaps as a proxy in /home/<user>/.m2/settings.xml. You do this by setting up the "proxies" element. Here is my complete settings.xml file

 

<settings>
<proxies>
<proxy>
<id>proxy1</id>
<active>true</active>
<protocol>http</protocol>
<host>127.0.0.1</host>
<username>username</username>
<password>password</password>
<port>5865</port>
</proxy>
</proxies>
</settings>

Don't forget to start ntlmaps by running "/etc/init.d/ntlmaps start". Now when I go "mvn package" I can download from behind windows firewalls. When I am not behind a windows firewall I have to rename my setting.xml file otherwise downloading doesn't work.

4)The quick and easy way to start using maven is to setup your project directory structure with it. Maven has built in templates for different types of project and third parties such as codehaus have additional plugins. There are different types of projects, like web application or portlets or third party ones for tapestry projects etc. You can view the built in archetypes at

http://mirrors.ibiblio.org/pub/mirrors/maven2/org/apache/maven/archetypes/.

You can also create your own archetypes which is quite handy for establishing a consistent structure across projects. The command to create your project has the following syntax
 

mvn archetype:create -DarchetypeArtifactId=archetypeArtifactId \
-DgroupId=newProjectGroupId \
-DartifactId=newProjectArtifactId


eg

mvn archetype:create -DgroupId=<package name> -DartifactId=<jar file name> DarchetypeArtifactId=maven-archetype-webapp

Note that groupId is simply the base package for your project and the artifactId is the name of the jar that will be generated for the project.

6) One the project has been create you can begin coding. If you using eclipse you can create .project and .classpath files by running mvn eclipse:eclipse. You also have to define a M2_REPO variable in eclipse to point to your repository.

"mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo"

You can also define a new classpath variable inside eclipse. From the menu bar, select Window > Preferences > Select Java > Build Path > Classpath Variables page. This variable should be called M2_HOME and point to your local maven repository ie. M2_HOME=/home/<user>/.m2/repository

7)To add dependencies to your project you can just edit your pom.xml file and add them under the dependencies element. eg
 

<dependency>
<groupId>velocity</groupId>
<artifactId>velocity</artifactId>
<version>1.4</version>
</dependency>


To get the correct groupId and artifactId I usually just go to "http://mvnrepository.com" and search for the jar there. They conveniently provide a pom snippet you can just copy and paste it into your pom.xml

8) To compile your project run

"mvn compile"


9) To clean your directory run

"mvn clean"


10) To run test run

"mvn test"

11) To build your project without running the unit test you can use the following command

"mvn -Dmaven.test.skip=true package"

12) To package your jar or war run maven package. If you have a jar and want to include 3rd party jars, ie. include your dependencies you need to make use of the maven-assembly plugin.