Function1

Each time you write a new Java portlet you may have noticed that there is definitely a set of common steps that need to be completed. For example, even though the functionality of portlets may be completely different, you can always be sure that you’ll have to do things like setting up a classpath, configuring an IDE, hunting around for third party dependencies, testing and debugging, deploying your code to a server, etc. As you may know, there are several software development tools available that claim to help reduce the amount of these tedious “housekeeping” tasks. These types of tools are generally referred to as “Build Systems”. And the number one Google result for “Build System” at the time of this writing is a solution called “Maven”.

If you peruse maven articles out in the blog-o-sphere, this is the message you’ll hear:

Using Maven will make you a better developer. Using Maven will make your organization more productive. Maven will solve your integration issues. Maven encourages unit testing. Maven will enforce DRY best practices and Convention over Configuration. Maven will save the rainforest and will give you thick, shiny, lustrous hair. Marcia, Marcia, Marcia! … Maven, Maven, Maven!

You (or your software dev team) might have already written quite a bit of java web apps and have managed to get by pretty well without Maven. You may have even written some killer java portal apps which your organization can’t live without.  

If you’re like me, you’re also probably a bit tired of learning scripting languages (ant, perl, make, bash, dos, ruby, on and on, and on). You’re probably hesitant to make the investment in learning another. Well, I hear you. I feel your pain. So, in this article, I’d like to give you some idea about what types of tedious tasks that Maven can help you eliminate (and by doing so, possibly save significant development cost). I also want to try to convince you that Maven is worth the effort. Stay tuned for later articles where I will dive deeper into the actual implementation details of how to best use Maven to manage your java projects.

So, to prove it to you that Maven is well worth the investment, I’ll walk you through a recent experience. As a new employee at Function1, I am very excited about the product suite currently in development. In particular, I wanted to help add some functionality to one of our new products named Formbuilder.

Remember Studio Server? You know, the one with the Tetris Easter Egg? Well, Formbuilder is everything Studio Server was, plus an easier to use interface and updated with the latest and greatest technologies. Formbuilder really makes it a no-brainer to create and administer surveys and polls. Formbuilder can be run as a standalone webapp inside any of the standard java web containers. It can also be installed to run as a portlet with tight integration with Web Center Interaction.

Here are the steps it took me (as a brand new F1 employee, totally unfamiliar with Formbuilder source code) to get to the point where I could compile and run Formbuilder in a development environment without Maven. Afterwards, I’ll compare how each step might have been accomplished using Maven. And you can be the judge ;-)

Formbuilder is a standard java web application. On the back end, it uses servlets to manage requests. The servlets talk to a service layer powered by hibernate that manages persisting and retrieving data to database. On the front end, it uses GWT and Ext-JS to provide the views. Administrators can create surveys (using a very slick and easy-to-use user interface, imo):

And, of course, Formbuilder also provides a page where you can complete and submit surveys:

When I first got a hold of the source code, I was really impressed how well everything was organized. The folder structure followed the normal java development best practices and coding conventions. There were no surprises from a software development point of view.  Even so, getting to the point where I could actually write code, was pretty slow going. If you’ve ever inherited a non-trivial java application to maintain, I’m sure you can relate. And in my experience, this “ramp up” time is generally accepted by most development teams as something that you “just have to roll up your sleeves and get done”. Here are the steps that were necessary for me to get from having zero knowlege of source code to where I was able to compile and run the Formbuilder application:

Check Out Source Code

The first step was to get the source code. A few emails and I had access to subversion and I was able to check out the latest and greatest using the svn command line tool.

Create Eclipse Project

Eclipse stores info about what it thinks are java projects under a file called “.project” and a folder named “.settings”. Since these had been checked into subversion, I was able to import the code directly into eclipse as an eclipse java project. Unfortunately, this only kinda-sorta worked. Since the eclipse project had been build on another machine, the Eclipse files contained hard coded paths. There were red X’s everywhere and Eclipse was not happy.

Resolved Dependencies

One of the biggest hassles working with Java is managing the thirdparty jars that each web app depends on. In this case, it was easy to see that all required jars were inside the war/WEB-INF/lib directory. However, I also noticed that all these jars had been checked into source control. For small to medium sized projects, checking jars into source control works ok. But, in my experience, as the source code grows so does the jar dependencies and pretty soon the number of jars becomes unmanageable. Checkouts from svn can quickly become excruciatingly slow. In this case, it wasn’t a big problem (but something to keep in mind for future maven articles :). I manually added each jar to the eclipse project’s build path and that made Eclipse a little happier, making a lot of the existing red X’s go away.

Compiling the UI Code

Google Web Toolkit (GWT) is a technology that allows you to write java and have it compiled into javascript. Formbuilder uses GWT to create some really slick web user interfaces. So, the next step was to download and install the Eclipse GWT plugin. This plugin handles all the configuration necessary to be able to “compile” gwt java code. After setting up the plugin, eclipse was 100% happy, all the compile errors (Red X’s) in eclipse were satisfied!

Build Database

So now it’s time to fire this bad boy up and try it out?! Oh right, I probably need to install a database. Some hunting and I found the hibernate.cfg.xml which contained the database credentials. I noticed there were 3 database flavor’s configured inside of the xml file. Two of the configurations were commented out. I learned that Formbuilder is compatible with serveral database vendors including MySql, Oracle, and Microsoft SQL Server. I chose to use MySql since it lends itself well for development. A few google searches later and I was able to use the mysql command line tool to create a new mysql database (and new mysql user) to match the credentials found in the hibernate config file. I then used the hibernate hbm2ddl tool to automatically generate the datbase schema based on annotations inside the source code. Very cool. Life was good.

Package

Okie-Dokie. Things are compiling. The database is created and is online. The next step is to build a war and then test. I found a helpful shell script (named deploy.sh) that bundled up all the compiled class files created by eclipse along with the WEB-INF directory (including all the jars) into a war file. I copied the war file into tomcat/webapps and pointed my browser to browse to http://localhost:8080/formbuilder and voila? Oh, Dag nabbit!

Runtime Error #1

From the stack trace, it looked like the servlet was not able to connect to the database. After some more hunting I found that there were several application properties files. One property file was used to build a war to run on a local development environment. Another properties file was used to build a war to run on a production server. The production properties file was “active” so I switched back to the local properties file. Ok, run deploy.sh again. Then copy the war over to tomcat/webapps again. Browse to the formbuilder page, and …. DOH!

Runtime Error #2

I was seeing the same database connection error. After some troubleshooting, this time it turned out to be that some of the values inside the properties files were overwriting some of the
values inside hibernate.cfg.xml. I could see that this was intentional. This way, the deploy.sh script could easily switch back and forth between building war for development vs a war for production. Run deploy.sh again, then copy the war over (…again!).

Runtime Errors #3-15

I was now able to connect to the database. But the next errors were several runtime ClassNotFound errors. Even though I had copied all jars over from WEB-INF/libs, it turned out that I needed to find and download a few extra from various web sites. It turned out that I was using a different version of Tomcat than other developers. So I ran the bash script to create the war (…again!). Then, I manually copied and pasted the war into tomcat/webapps (…again!).

Run!

Finally! Formbuilder was running inside tomcat. I was able to create and save a new survey successfully. All in all, it took probably close to 20 hrs to get to the point where I could start being productive and writing code.

Maven

Now, I’d like to describe the steps it took me to get up and running after I “mavenized” the formbuilder project. You ready for this?

c:\> mvn install

That’s it! No lie. That single command (1) resolves and downloads required thirdparty jars (2) compiles java to class files (3) compiles gwt java to javascript (4) generates the database schema (5) runs junit tests (6) creates a war (7) and actually starts an embedded tomcat server which runs the Formbuilder web app.

I’m convinced. So What Next?

None of the steps described above will come to a surprise to anyone who’s ever written a Java web application. It can be frustrating (and costly) to manually repeat the same housekeeping tasks over and over. Maven solves this problem by forcing you to organize all your Java projects exactly the same. It gives you a common set of commands for building Java applications. Think how great it would be to be able to run “mvn install” against any piece of source code that can be found in your organization and have it handle all the tediousness for you?! Automation is a beautiful thing.

Stay tuned for Part II where I’ll cover more on exactly which common development problems that Maven solves and specifics of how to configure Maven to do so.