Project Management, This Time With Maven

maven_logo

As we covered a recent post, Apache Ant is an excellent tool for building and deploying basic Java projects, and provides services to download and manage third-party packages.  Configuring Ant projects is a fairly manual process however, and it would be nice to have a tool that assisted with the setup of complex frameworks like Struts and Spring.  Gradle is the newest tool to perform this task, but Apache Maven is the go-to utility today.

The problem you’re trying to solve with Maven is not unlike that for Ant.  When your project is small, it’s relatively easy to build it at the command line or with static scripts.  As it grows however, it becomes more important to make the build process as efficient as possible; only recompiling those classes that have changed since the last build.  But more importantly, using 3rd-party libraries and frameworks require you to download and manage many additional archives and arrange them in specific ways in your project folder.  Maven helps with all these.

Installing Maven

Installing Maven on your development system is similar to most other Apache products.  Again we’ll cover the installation for Windows environments, but the process for other platforms is similar.  Begin by retrieving the latest Maven archive from the download site.  Find the latest binary .zip; version 3.3.1 at the time of this writing.

Be sure to also download the corresponding .asc signature file and validate the integrity of the binary package.

Unzip the package in a suitable location like c:\Maven.  Next you’ll need to set up a few environment variables:

C:\Maven>set MAVEN_HOME=C:\Maven\apache-maven-3.3.1
C:\Maven>set M2_HOME=%MAVEN_HOME%
C:\Maven>set PATH=%PATH%;%MAVEN_HOME%\bin

To make these permanent in Windows, right-click on Start -> System -> Advanced Settings -> Environment Variables, and add them to the ‘User Variables’ section.  Adjust the values for the specific location of your Maven files.

Your First Java Project

Let’s use maven to create a basic Java project. Begin by creating a folder to house your projects, and use the maven utility to generate all the necessary files.  Maven can generate a wide away of project types, or archetypes.

C:\Users\Lambert\Desktop> mkdir Projects
C:\Users\Lambert\Desktop> cd Projects

C:\Users\Lambert\Desktop\Projects>mvn archetype:generate -DgroupId=net.proloquor
.experimental -DartifactId=DateUtil -DarchetypeArtifactId=maven-archetype-quicks
tart -DinteractiveMode=false
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:2.3:generate (default-cli) > generate-sources
@ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:2.3:generate (default-cli) < generate-sources
@ standalone-pom <<<
[INFO]
[INFO] --- maven-archetype-plugin:2.3:generate (default-cli) @ standalone-pom --
-
[INFO] Generating project in Batch mode
[INFO] -------------------------------------------------------------------------
---
[INFO] Using following parameters for creating project from Old (1.x) Archetype:
 maven-archetype-quickstart:1.0
[INFO] -------------------------------------------------------------------------
---
[INFO] Parameter: basedir, Value: C:\Users\Lambert\Desktop\Projects
[INFO] Parameter: package, Value: net.proloquor.experimental
[INFO] Parameter: groupId, Value: net.proloquor.experimental
[INFO] Parameter: artifactId, Value: DateUtil
[INFO] Parameter: packageName, Value: net.proloquor.experimental
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] project created from Old (1.x) Archetype in dir: C:\Users\Lambert\Desktop
\Projects\DateUtil
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.984 s
[INFO] Finished at: 2015-04-29T23:24:12-04:00
[INFO] Final Memory: 13M/113M
[INFO] ------------------------------------------------------------------------
C:\Users\Lambert\Desktop\Projects>

The maven command you entered generated a lot of activity.  To understand what it did, let’s look at the command line parameters you entered.

  • groupId – This is the package in which your project resides
  • artifactId – This is the name of your project
  • archetypeArtifactId – This is the type of project you’d like to create

Maven will prompt you for version numbers and other information, unless you include the interactiveMode=false parameter, in which case it uses default values for each.

The maven-archetype-quickstart archetype is a basic java application with accompanying JUnit unit tests.  It arranges files according to a standard layout, such as:

quickstart_layout

Maven defines various life cycle phases in the development process.  For a list of those phases:

C:\Users\richard\Desktop\Projects\DateUtil>mvn
[...]
[ERROR] No goals have been specified for this build. You must specify a valid li
fecycle phase or a goal in the format <plugin-prefix>:<goal> or <plugin-group-id
>:<plugin-artifact-id>[:<plugin-version>]:<goal>. Available lifecycle phases are
: validate, initialize, generate-sources, process-sources, generate-resources, p
rocess-resources, compile, process-classes, generate-test-sources, process-test-
sources, generate-test-resources, process-test-resources, test-compile, process-
test-classes, test, prepare-package, package, pre-integration-test, integration-
test, post-integration-test, verify, install, deploy, pre-clean, clean, post-cle
an, pre-site, site, post-site, site-deploy.
[..]

mvn compile compiles the project, mvn test runs the unit tests, and mvn package creates a deployable jar file.  Running the main() method of a class in your project is a little more complicated

C:\Users\Lambert\Desktop\Projects\DateUtil>mvn exec:java -Dexec.mainClass="net.p
roloquor.experimental.App"
[...]
Downloaded: https://repo.maven.apache.org/maven2/org/apache/maven/maven-plugin-a
pi/2.2.1/maven-plugin-api-2.2.1.jar (13 KB at 8.8 KB/sec)
Downloaded: https://repo.maven.apache.org/maven2/org/sonatype/plexus/plexus-sec-
dispatcher/1.3/plexus-sec-dispatcher-1.3.jar (28 KB at 20.1 KB/sec)
Downloaded: https://repo.maven.apache.org/maven2/classworlds/classworlds/1.1/cla
ssworlds-1.1.jar (37 KB at 26.6 KB/sec)
Downloaded: https://repo.maven.apache.org/maven2/org/apache/commons/commons-exec
/1.3/commons-exec-1.3.jar (54 KB at 35.8 KB/sec)
Downloaded: https://repo.maven.apache.org/maven2/org/codehaus/plexus/plexus-util
s/3.0.20/plexus-utils-3.0.20.jar (238 KB at 155.1 KB/sec)
Hello World!
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 15.889 s
[INFO] Finished at: 2015-04-30T22:10:23-04:00
[INFO] Final Memory: 11M/66M
[INFO] ------------------------------------------------------------------------
C:\Users\Lambert\Desktop\Projects\DateUtil>

As you see, maven downloads a lot of packages from it’s central repository.  Apache keeps the latest copies of 100’s of libraries at repo.maven.apache.org.  Fortunately, when maven downloads a package from the central repository, it stores it in your local repository, or %USERPROFILE%\.m2\repository on your local machine.  Future maven runs pull from that location first.

pom.xml

All maven-based projects are managed by a Project Object Model, or pom.xml file.  The file contains information on many aspects of the project, most importantly the external packages on which the project depends.

pom.xml

We’ll talk more about the contents of this file later.

Using Maven with Eclipse

While maven comes with a powerful command line program, mvn, we typically want to work within an IDE like Eclipse.

Importing Maven Projects into an Eclipse Workspace

As we’ve learned, Eclipse projects require a few additional files to work in that environment: .classpath which is Eclipse’s way of storing references to external libraries, and .project which holds general configuration information.  To generate these files, go to the root directory of your maven project and run:

mvn eclipse:eclipse

Although it’s now suitable for Eclipse, your project still needs to be imported into a workspace.  Open Eclipse at our workspace and click on File -> Import… -> General -> Existing Projects into Workspace.  Select the root directory of your project, and and check the specific project, if there are more than one.

All your files will be copied into their own project in your workspace.  From this point, the files in your original folder are no longer needed, all further development is done from the workspace.

Creating New Maven Projects in Eclipse

What we really want to do however, is create new maven projects from within Eclipse.  For this, Eclipse provides an interface to the central repository through its project creation functions.  To beign, launch Eclipse and click File -> New -> Other … -> Maven -> Maven Project.  First, choose the archetypeArtifactId on which to base your new project.

archetype

Next, fill in the groupId (package) and artifactId (project name), along with any other maven parameters you need (you don’t need to specify interactiveMode here).  You can also specify a version string stored in the pom.xml file.

MavenProject

Once you click ‘Finish’, the project retrieves the necessary dependencies from from the central or local repositories and creates the project.  You can debug, run, and test your application as any other.  If you need to make a change to the projects configuration such as dependent external libraries, you can use the custom editor for the generated pom.xml file.

PomEditor

What’s Next?

We’ve shown that we can use maven to create and manage our Java projects.  This can be done using simple command line tools, or from within full-featured IDE’s like Eclipse.  We’ll use maven to build most of our more complex Proloquor.net projects.

Acknowledgements

Again, Yong Mook Kim writes an easy-to-follow blog on this and many other software development topics.  His articles on Maven were very helpful for this post.

Leave a Reply

Your email address will not be published. Required fields are marked *