If you have worked on an ide like eclipse you might have already thought the structure created by Maven is different from how eclipse structures a project. If you directly import the maven created structure into eclipse you might see that eclipse identifies the project as disoriented and shows up compilation issues. No worries, there is a eclipse plugin for maven that comes to rescue. Issue the following command.

c:\helloworld\>mvn eclipse:eclipse

Eclipse workspace needs two important files that determines the project information and the classpath information. These information are stored in the files .project and .classpath respectively. The eclipse plugin modifies these files exactly what is needed in order for eclipse to understand the maven structure. Once you execute the above command, you can use eclipse to point to the directory to load the workspace. You can look at guide to using eclipse with maven for more information.

Maven helps in bringing discipline in the way the code is organized and structured and also helps in automating it. Suppose a new developer joins in the team, all you have to do is setup maven on the developer’s machine, pull down the current source that includes the pom from a version control system, apply the eclipse plugin and the developer is all set to start writing code. What’s more he/she can run maven to package it and deploy it locally and test it too. Thus everyone follows the automated process and the code and structure is standard across the team.

What we saw in this six part series on “Mavenizing your project” was a kick off to Maven. Maven can do a lot more stuff like site generation, code metric collection etc with the help of external plugins. Click here for a list of plugins available for Maven2.

Before you can start reading this part, kindly go through part 1 of Mavenizing your project. Just like rails, maven can help you in creating the initial structure of your project. Use the archetype plugin and it can create the initial project structure. The following command creates a HelloWorld project.

mvn archetype:create -DgroupId=com.compassites -DartifactId=helloworld

The archetype plugin has only one goal create and is used to create containers basically project templates. The second argument is a parameter (-D represents that we are going to supply a property) what the groupId would be and the third represents the artifactId.

Maven follows a file structure that has become the defacto and has been followed by the apache open source projects. You can look at the maven standard directory layout here. Although you could create your own structure, it is not recommended. When something has been tested and proven why not use it as it is rather than trying to define one on our own.

If you take a look at the files that Maven has created, you can see a pom.xml in the root of helloworld folder. If you look at the src\main\java you can see that Maven has by default create a java file called App.java which is basically a HelloWorld program. Note that it has already packaged it under com.compassites. Also you will find under src/test/main the junit test case. So by default we have the HelloWorld application without any effort. Lets try few more goals. Get into the helloworld folder where your pom is located. The following command compiles the java source.

mvn compile

and the following command runs the unit test.

mvn test

Now lets try packaging it. Note that like in Ant, the interdependent goals are executed automatically. The below command compiles, runs the test case and also creates the jar package.

mvn package

You can see that a file named HelloWorld-1.0-SNAPSHOT.jar has been created. As we said earlier a SNAPSHOT is a development version of the artifact. The version tag in the pom can be modified to reflect the version needed in case if it is a release build. OK now what if there are other projects which are dependent on this artifact?

mvn install

The above command will package the helloworld project and also create an artifact and store it in the local cache. Check it out in your user directory under .m2/repository/com.compassites/helloworld…

If any other project is depedent on the helloworld artifact, add the dependency in the project’s pom and maven picks it up from the local repository.

The archetype:create goal by default creates an artifact that can packaged into a jar. The below command helps in creating a war artifact.

mvn archetype:create archetype:create -DgroupId=com.compassites
-DartifactId=helloworld -DarchetypeArtifactId=maven-archetype-webapp

There was one extra parameter there, which just says that we want a web application templage. Explore the structure that maven creates.

Maven handles transitive dependency through the POM of the dependent artifact. If you go to the ibiblio directory of Hibernate 3, http://www.ibiblio.org/maven2/org/hibernate/hibernate/3.1.3/ you can see that there is a hibernate-3.1.3.pom. Click on that and you can see the POM for the Hibernate artifact. You can clearly see all the artifacts that Hibernate is dependent upon from the dependencies section. So once you include Hibernate as a dependency to your project, Maven also gets all the necessary dependencies of Hibernate as well. It simplifies your job, and all you need to tell Maven is what are the artifacts your project is dependent upon.

We saw two important areas of Maven, POM and the repository where artifacts are stored in the remote as well as where Maven caches it locally (your user directory). There is a third important aspect of Maven, the plugins. In fact the artifact repository and the POM is put to use only with the help of plugins. You can relate the work of a plugin to that of a target in Ant. So are plugins special programs in Maven. Not really, they are also artifacts that reside in the ibiblio maven repository. The ant task equivalent in maven is a goal.

OK at this point if you want to test out the commands and samples that will come up, you need to download and install Maven2. To execute maven you need to specify at least one goal. For example to celan the previous build output directories, issue the following command.

c:/>mvn clean:clean

The first clean is the plugin name and the second clean is the goal name. Clean is a basic build lifecycle goal and hence the plugin prefix is optional. Meaning the following command has the same effect as the above.

c:/>mvn clean

The list of basic build lifecycle goals can be found here. A plugin is like any other artifact except that apart from a POM it also has an XML file called plugin.xml. The plugin.xml file contains all the goals that the plugin can perform. Open the maven-clean-plugin-2.1.jar in Winzip, extract and view the plugin.xml and study it. If you want to know more about creating plugins you can go through it here.

The best part of Maven is handling dependency. That too in a J2EE project, you know you are dependent on so many other frameworks and each of them bring their own dependencies. It becomes your responsibility to solve this dependency at every enviornment your application is going to sit, including the development desktop. You mention the project dependencies in Maven and it picked up exactly only those dependencies until Maven2. Maven2 not just picked up the dependencies you mentioned but also the dependencies the dependent is dependent on. Wait I know that was a bit confusing. Lets take an example and understand it. Say in your project you are using Hibernate. Hibernate is dependent on few other frameworks, for example Apache Commons Logging. Prior to Maven2, you need to know all of the Hibernate dependencies and add them to the project dependencies section of the POM. In Maven2 it is all taken care of, it catches the chain of dependencies and makes sure all of the dependencies are added. Not only that, it can also be instructed to look for cyclic dependencies.

So where does Maven pick up these dependencies. We saw in our Ant example, that we had to create a separate directory to store our dependendant libraries, in this case just the JUnit. When you are dealing with Maven, you don’t need to bother about where to get and put the dependencies. Once you mention the artifact that you are dependent on Maven picks the artifact from a global repository called ibiblio. ibiblio is a public library where you can find artifacts on any area not just technology. Maven has its own area to store all the Java/J2EE artifacts. How is it stored and how Maven retrieves it after you have mentioned your dependencies is the next question. We saw how an artifact is represented in the previous post. Take a look at the dependencies section of HelloWorld POM from the previous post. Here is the snippet.

  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>3.8.2</version>
    <scope>test</scope>
  </dependency>

The URL where Maven looks for the jar is by this convention, http://www.ibiblio.org/maven2/
<groupId>/<artifactId>/<version>/<artifactId>-<version>.<extension> So in the above case, the URL would be http://www.ibiblio.org/maven2/junit/junit/3.8.2/junit-3.8.2.jar. Click on that link and you will be prompted to download JUnit jar.

So where does all the dependencies get downloaded? Maven caches all the jars to your home directory (in case of Windows, generally its c:\documents and settings\<user name>\.m2\repository). So the next time when you run maven, if there is already a dependency available locally it will not try to retrieve it again from ibiblio.

First let us go through some basics of Maven. When I say Maven in this post as well as the coming ones, I am referring to Maven2 the latest release. As told in my introduction post, Maven works on what is called as a Project Object Model (POM). Basically a POM is an XML structure and contains information about your project. And what information does it contain? Below is the list of top level sections in a POM.

• project information - Basic information like what artifact this project is (jar, war), what is the default package structure (eg.: com.compassites), description of the project etc.
• organization - Describes the organization’s details
• developers - Who are the developers involved in this project and what role they play.
• dependencies - what are the artifacts this project is dependent on (components, 3rd party jars etc)
• repositories - where the application dependencies (components, 3rd party jars, etc.) are available. Multiple repositories could be configured.
• pluginRepositories - where the plugins are available. Plugins help in managing specific tasks. For example a jira plugin for maven can help in retrieving all the bugs currently reported from jira.
• build - everything about the build like where to output, where are the resources etc.
• reporting - where will the project report be stored
• profiles - contains specific instructions for specific build type. For example what should Maven do if it is a production release or a customer release.

While a project can have all those sections, it is not mandatory and the POM can be relatively simple too. View this POM for a HelloWorld application. Note that we used the word artifact a lot of times. An artifact is a distribution ready package that can be used by any other artifact. An artifact is of the form,<artifactId>-<version>.<extension>

example, junit-3.8.2.jar

We will see how Maven retrieves the dependent artifacts in the next post.

The key advantage as you might have seen from Ruby on Rails and Capistrano is the standard being enforced by the framework. For example in Rails you want to create a HelloWorld web application, the first step in creating the entire project structure is to just issue the below command in the shell prompt.

c:\>rails HelloWorld

Rails creates a complete project structure in MVC architecture style and with all the necessary configuration file templates. You just have to start coding and every developer is forced to follow that structure and place their code in appropriate layer (Model, View or Controller). On one side it might look like the framework is in control and you are not, but look at it this way. If the structure that the framework provides, by default confirms to the industry standard architecture model and enforces best practices by default then why worry about being in control?

Now on the Java/J2EE world this has been missing and usually it is a chaos when multiple developers follow their own structure and packaging conventions. While this is difficult to monitor and manage, it can be streamlined and enforced from the beginning with the help of a tool like Maven.  Lets look at how to mavenize your project in the coming posts.

Build automation with Rails is the sweetest and the easiest thing on earth. OK I shouldn’t call it build automation rather deployment automation. As far as Rails is concerned your source is your build. Makes life simple, you don’t need to bother about two different structures. More than that, the structure is enforced and you dont need to worry about each and every developer creating their own structure and packaging as in Java.
Rake is a build language developed on Ruby. Its purpose is to automate the build process similar to Ant. Read Martin Fowlder’s “Using the Rake build language” for more details. Capistrano adds additional tasks that rake can execute to deploy a rails application. Assuming that you have installed ruby and rails, create a HelloWorld rails application. Following are the quick steps to automating your HelloWorld Rails application.

• Step 1 - Install Capistrano

c:\>gem install capistrano

• Step 2 - Apply capistrano to your application. Assuming its a HelloWorld application in rails issue the following command.
  

  c:\HelloWorld\>cap --aply-to c:\HelloWorld HelloWorld

  The arguments after the –aply-to in the above command are the path to the application and the application name. Once you execute the above command, Capistrano adds a file called capistrano.rake under the lib folder. This file contains all the tasks necessary for deployment.

• Step 3 - Edit deploy.rb file under the config folder and add the following lines

# Set the application name
set :application, “HelloWorld”
# Specify the source control repository location, say Subversion
set :repository, “http://compassites-server1:9000/repository/HelloWorld/trunk”
# Set the roles and which server would play that role. In our case, lets say all of them are the same unix box
role :app, “compassites-server1.compassites.net”
role :web, “compassites-server1.compassites.net”
role :db, “compassites-server1.compassites.net”
# Set the absolute path of the server. Assuming you are running your application using Apache web server.
set :deploy_to, “/apache2/htdocs/HelloWorld”

• Step 4 - Setup the folders. Rake deploys the application with the release date and version number as folder under the folder called release. This helps in rolling back the application to the previous release easily if need be. It also creates a current folder which is a sym link to the current release. The apache configuration refers to this directory to serve the application. To set up these directories, execute the following command.
  

  rake remote:exec ACTION=setup

  The above command will request for user name/password in the server and create and copy necessary files.

• Step 5 - Add task to restar the web server. Assuming that you have configured the apache to run your application, you just have to tell rake to restart the web server after the deployment happens. So override the default restart task in the deploy.rb file like below.
  

  task :restart, :roles => :app do
sudo “apachectl graceful”
end

• Step 6 - You are all set. Execute the below command
  

  c:\HelloWorld\>rake deploy

  The above command downloads the latest code from the repository under the date-revision number folder under release folder, sets the current folder link to point to this folder, runs the unit tests and restarts the server.

You can find detailed explanation and advanced setup information in the capistrano manual.

What we saw in the previous posts was a build script for simple HelloWorld application. What about creating an Ant script for a web application? It is fairly simple if you understand the basics. More than ant script you need to understand the following.

Enterprise Archive (ear) structure
Web application deployment descriptor
Application deployment descriptor

The best way to understand the structure is to first build an ear file or a war file with the help of an ide like MyEclipse or NetBeans and then extract it and study its structure. Next is to understand the deployment descriptors which are key in making your application work. The application server uses this information to load and execute your application into appropriate containers. Once you understand and know your web application’s structure and the deployment descriptiors then it is really simple to create an ant script to build it. You can find the next step of automating a HelloWorld web application build and deploying it to JBoss here.