February 23, 2016

Just Enough Maven Part 1

If anything you do involves the JVM in any way, sooner or later, it's helpful to know a little about Apache Maven.

I've been using Maven for a long time now. But I can still remember it being daunting when I first decided to buckle down and learn it years ago.

Is Maven Worth Learning?

Spending the time and effort to learn Maven has been worth it for me without a doubt. When I first learned, it took me about 2-4 weeks to really understand the tool. Since then, I can say that it's easily given back 10 times of that initial investment (and most likely closer to 100 times).

I've inherited dozens of older java code bases at work. Each of these projects was originally created using a slightly different set of build tools.

A few years ago, I started the habit of ignoring whatever hodgepodge of build scripts came along with these legacy projects. Instead of struggling for days to figure out how to compile the thing, I just spend an hour converting it to maven. "Mavenizing" these projects has saved me months of banging my head against the wall.

Even the simple act of reorganizing code to conform to maven conventions brings instant, measurable benefits. Anyone who is given the responsibility of maintaining a maven project instantly knows how to build and run it. No more looking for jars, and reading readme files.

I know it can be a pain, but it's definitely worth putting in the effort to learn it. Maven is used by nearly every large java project out there. And almost every other tool and IDE in the java ecosystem is compatible with Maven.

Over the next few weeks, I plan to write several posts which I hope will help you to learn just enough maven to become productive as quickly as possible without getting stressed out. I'll try to keep each post short and focused on one small topic at a time.

Maven Haters

You might have stumbled over blog posts of people swearing never to use maven again. To be honest, I can relate with most of them!

I have a love/hate relationship. Maven is not always the easiest thing to work with. It's not much fun editing XML. The obscure error messages can still drive me insane. Maven is extremely opinionated about how you organize your files and has strict conventions about how to build a project. And, let's face it, it can be frustratingly difficult to get maven to perform stupid simple tasks.

Of course Maven is not the best tool for everything. And yeah, ideally I wish it was designed a bit differently. It be great if it were turing complete, and more composable, had better startup time and better documentation, etc, etc. But at the end of the day, Maven is actually pretty good at what it was built for.

When used as intended, it resolves dependencies, compiles java, packages jars and wars, deploys to servers, and runs tests consistently. And it's used everywhere. And it's supported by everything. So, in my opinion, it's not useful to fight it and complain about it. If you can't beat 'em, join 'em!

Also, I think one explanation for a lot of the Maven hatred is due to the fact that Maven sits right in the center of your java development environment. Because Maven is the entry point to nearly ever part of the java development process, it's an easy target for people to complain about and to blame all their problems on.

You don't have to love it, but learning about it won't hurt you, I promise.

Finding Maven Bliss

So, if you buy into my reasons for learning Maven, here's how I suggest going about it.

First of all, step back and invest the time to learn how to do basic tasks without maven (and without an IDE) first. Learn the basics, then learn how maven performs each.

I'll go into more detail in the next post, but here's a checklist for the basic tasks I think you need to learn how to do before using maven.

Start with a very basic "Hello World" java project and make sure you understand how to do each of these tasks first. Don't worry, each of these should be very easy to learn fairly quickly:

  1. Learn how to compile your project using the java and javac commands from the command line.
  2. Understand how to download jar file and figure out where to put it so you can use that library from your project.
  3. Figure out how to manually package your class files into a jar (or if you're doing web development, into a war file)
  4. Figure out how to run your program. If it's a console or desktop app, then figure out how to run it manually as an executable jar. If it's a webapp, get comfortable deploying the war to jetty or tomcat.

Do you really know how to do the tasks above? Be honest!

What's the command line flag to the java command to include a third party jar on the classpath?

When do you need to include the the META-INF and WEB-INF directories inside a war or jar?

If you don't the answers, then you might need to do a quick refresher.


Here are two more items you might need to brush up on before Maven.

  1. Understand how to use JUnit to write very simple tests
  2. Understand the basics of how version control works from the command line.

Learning Maven

Ok, once you're comfortable with the basics of how to build and deploy java projects, here's how I suggest you tackle learning maven. I suggest breaking your study into 4 topics:

  1. What is Maven exactly, anyhow? (Teaser: fundamentally, the core maven code really has nothing to do with building java projects at all!)
  2. How does Maven handle dependencies? (understanding snapshots, transitive dependencies, and maven repositories will save you a lot of grey hair)
  3. What's are the phases of the Maven Build Life Cycle? And how do you hook into the standard phases to perform custom tasks?
  4. What's the basic structure of the pom.xml?

I'll try to dedicate at least a full blog post to each of these topics.

Once you have a good understanding of these 4 concepts, I think you'll be a lot less stressed about using Maven. It should become much easier to figure out how to solve the more specific, esoteric maven related problems that you're probably currently pulling your hair out trying to solve (and that probably lead you to this article in the first place!).

Also, after being armed with solid grasp of maven fundamentals, you'll be able to more learn more easily about how to use other build tools like boot and Leinigen.

Stay tuned for more!

Tags: tools software java maven