Creating a Maven webapp from scratch

Doing a little research for an article about “log4j”:http://logging.apache.org/log4j/ configuration in Java webapps, I decided to use “Maven”:http://maven.apache.org/ as a sidekick. “I already pointed out earlier”:http://blog.nofail.de/2010/01/buildr-the-build-system-that-doesnt-suck/ that my favourite build tool is “buildr”:http://buildr.apache.org/. The reason I chose Maven is that it has “archetypes”:http://maven.apache.org/guides/introduction/introduction-to-archetypes.html and that there is a deprecated guide for using such an archetype “to create a blank webapp”:http://maven.apache.org/guides/mini/guide-webapp.html that would be valuable for me.

h2. installing Maven on OS X

The Maven “documentation”:http://maven.apache.org/documentation in general and the “installation instructions”:http://maven.apache.org/download.html#Installation in particular *SUCK*. They lack essential information as most Java documentation does. So here is a step by step guide for OS X:

# go to the place you want to install Maven to
cd ~/Library
# download latest Maven version
curl -O http://apache.autinity.de/maven/binaries/apache-maven-2.2.1-bin.zip
# unzip the archive
unzip apache-maven-2.2.1-bin.zip
# add a symlink for convenience
ln -s apache-maven-2.2.1 maven
# add executables to the PATH
echo export PATH="~/Library/maven/bin":\$PATH >> ~/.profile

# open a new bash and check Maven is running
mvn --version
=> Apache Maven 2.2.1 (r801777; 2009-08-06 21:16:01+0200)

h2. creating the webapp

If Maven is running on the system, you can use the archetype to create a blank webapp:

# go to the workspace
cd ~/Documents/workspace/
# let Maven create a webapp
mvn archetype:generate \ 
   -DgroupId=de.nofail \
   -DartifactId=tomcat-logging \
   -Dversion=1.0.0-SNAPSHOT \
   -DarchetypeArtifactId=maven-archetype-webapp

This takes several minutes, as it requires a thousand some broken dependencies for whatever is necessary to create some files and folders! But after that, you have a fresh, apache conform webapp at hand:

# go to the webapp
cd tomcat-logging/
# let Maven create a distributable war
mvn clean package

This is very nice for a Java application! Zero configuration and you get a running webapp that you can start after another two thousand downloads instantly from the command line:

mvn jetty:run &
open http://localhost:8080/tomcat-logging/	

h2. all by myself

There is just one big problem with this so far: it won’t work bejond that! Maven lacks sensible defaults everywhere! Examples? Here you go:

h3. Java compiler

Maven uses Java 1.4 as the default compliance level for the Java compiler. So if you start adding some “Annotations”:http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html or “Generics”:http://java.sun.com/j2se/1.5.0/docs/guide/language/generics.html to your code, which are Java 1.5 features, your build will fail until configuring the compiler plugin properly:

	[...]
	
		
			[...]
			
				org.apache.maven.plugins
				maven-compiler-plugin
				2.0.2
				
					1.6
					1.6
				
			
			[...]
		
	
	[...]

This should be a top level configuration!

h3. Jetty plugin

Making changes to the code won’t change anything in the webapp run by the “Jetty plugin”:http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin. You need to configure the plugin in order to pick up changes. Since the plugin can not do any hot code replacement, it has to restart the context after every change. A no-go for most webapps:

	[...]
	
		
			[...]
			
				org.mortbay.jetty
				maven-jetty-plugin
				6.1.10
				
					10
				
			
			[...]
		
	
	[...]

Why is this soooo much XML?

h2. Eclipse integration

Maven has support for integrating a project into “Eclipse”:http://eclipse.org/ via the “Maven-Eclipse-Plugin”:http://maven.apache.org/plugins/maven-eclipse-plugin/:

# configure your workspace (do not use ~ to point to your home!)
mvn eclipse:configure-workspace -Declipse.workspace=../
# create Eclipse files
mvn eclipse:eclipse

These tasks add a M2_REPO classpath variable to your Eclipse environment that points to your local Maven repository and creates a _.project_ and _.classpath_ file from the existing pom. Just import the project with _Import > General > Existing Projects into Workspace_ and your done.

h3. better with Eclipse plugins

Since there are mature Eclipse plugins for Maven and Jetty, you should consider installing these from their update sites:

* “m2eclipse”:http://m2eclipse.sonatype.org/sites/m2e
* “run jetty run”:http://run-jetty-run.googlecode.com/svn/trunk/updatesite

It’s never easy doing stuff from scratch, but Maven should help flatten the rocky path to Java projects. Instead it piles up another Mount Everest of complexity to climb for a Java developer…

h2. additional information

Check out my github profile for “a working example project”:http://github.com/phoet/tomcat-logging that was created using these steps.

Maven – development for morons made easy!