In my projects, I’ve always been the one who took care of infrastructure, standardization and quality assurance from the development perspective. The funny thing is that I’m no admin and no QA guy, so most of it wasn’t even my job. In this article, I’m going to list a few things that in my opinion as a software developer are essential to a professional software project.

What you need is no secret: If you read a few books and follow some technology blogs you know the bits and pieces. I’ll list a few things from a Java/Maven perspective, so some of this may or may not apply to other platforms.

First of all define a common coding style. I shouldn’t even have to mention this, but there will be chaos and conflict among developers if you don’t have it. Just use Sun’s Code Conventions, make some exceptions like “maximum line length is 120 characters” or “no tabs allowed” and you’re halfway done. Provide a bit of example code (one class, one page of paper) and put it up on a wall. This style guide should include rules for things like logging and exception handling strategies as well. Too few developers are even aware that you need a strategy here, so write it down! Don’t forget to define package namespaces for your project.

For Java projects provide organization-wide Maven archetypes that give you a solid basis for your project. Use existing open source ones to get you started! The effort for this pays off with each new project in reduced setup costs. But wait, each of your projects is different? Oh please, then adjust your build scripts. That’s no excuse to start from zero each time!

On a related note, invest in a proper internal Maven repository setup. Maybe use a stripped down version of Atlassian’s setup. You don’t want your builds to break just because some external repository isn’t available. Define rules who may deploy what to your repository. I’ve seen a lot of chaos here, so remind people to actually think before deploying stuff and breaking builds.

Get yourself a proper bug tracker and define how you’re going to use it. It doesn’t have to be fancy, a Trac installation will do in most cases and it will give you a wiki for your technical documentation, too. Do you just track issues or also tasks for developers? What’s the workflow? Who may open a ticket, who may close it? What amount of testing is required?

For god’s sake, define rules for working with your revision control system. How often should developers check in? How should a commit message look? How does your release process look like? When do you create a branch, how are releases tagged etc. Read up on the features of your system, branching may no longer hurt. Move on if you’re still using CVS.

A professional software project needs continuous integration. Period. Set it up (I recommend Hudson), define the proper reports and actually read them. It’s crucial to check test coverage and other metrics right from the beginning. If you add reports later, you will typically get warnings for every other line of source code. Nobody will read those reports anymore and it’s too much work to clean up the code.

Provide developers with a proper workstation setup that corresponds to the platform you’re targeting. Yes, it’s a good idea if everyone on the project used the same JVM and application server versions. If that’s what your production environment uses, even better! It might improve the chance that things actually work. Just saying.

I’m barely scratching the surface here, but it’s enough for one article already. For many of the points above you can find articles on the web (check my blog’s best practices category, for example). And still, it’s frustrating how little many software companies invest in those bare essentials.

Most people eventually get it that building release artifacts using their IDEs is not the way to nirvana. Builds have to stay stable and reproducible between IDE revisions, and being able to execute them in a command line environment or especially continuous integration servers is key to agile development.

Fortunately, there are open source build tools for Java. Less fortunately, they’re not quite perfect. Let’s see what we’ve got.

The Sorry State of Affairs

There’s Ant, the undying classic, but pretty much in maintenance mode, I understand. Ant-based build systems usually start small and innocent but quickly turn into a tangled mess. Every Ant script is a unique piece of modern art that has to be deciphered on its own. They are the cockroaches of Java development, and I guess we’ll have to deal with them again in 30 years when we’ll be porting ancient Java applications to the next big platform.

Maven 2 promises relief and introduces convention over configuration, dependency management, lifecycle support and a few other things that aren’t strictly relevant for a build system. Great concepts, but the actual implementation makes you want to cry. The state of documentation is poor, the XML syntax is unnecessarily bulky, and trivial one-off tasks aren’t possible without a proper plugin (go and write one if you’re feeling brave). Not to mention that stunts like multi-module projects are necessary to build a simple EAR file. And no, Eclipse doesn’t like them either.

Despite all its shortcomings, a lot of people including me tried hard to love Maven, but it’s not easy.

The Winds of Change

Where does that leave us?

I don’t have much hope for Ant. It is what it is and lacks too many things a build system needs, most importantly built-in conventions and higher level abstractions. Granted, there’s Ivy, a pretty nice dependency manager that adds a couple of interesting features, but that’s about it (Ivy looks heavily inspired by Maven, but it’s funny how they changed all the terminology).

Maven 2’s future looks a little bit brighter since it seems the project is opening up to common sense, which maybe be a direct effect of recent discussions and probably Don Brown’s patches. For example, the XML syntax in 2.1.0 will be much more concise and there are fixed default plugin versions in 2.0.9 so that it’s easier to have reproducible builds. Unfortunately, the public repository is a swamp of misplaced software and crappy metadata, so there may be no alternative to setting up a local repository.

At the moment, I’m taking a closer look at Buildr, a ruby-based build system for Java that’s currently under incubation at the ASF. Apparently they’re creating a better Maven, taking the proven concepts but none of its implementation. The jury’s still out on whether the average coder will be able to create effective, maintainable build scripts, but we’ll see. Having to learn Ruby may be a problem to some and an incentive to others.

So?

Poor build systems and development environments in general are a barrier for new project members and a frequent cause for frustration. I’ve worked on projects where all you had to do was to check something out from Subversion, type "mvn package" and you were ready to go. For other projects (both commercial and open source!) you needed a specialist’s support, a couple of days time and a lot of hand-holding to actually build the product and run it locally.

Unfortunately, only few development shops realize that a decent development environment is an asset and invest in their build infrastructure. A good project setup takes time, and if there’s no time or budget available, your build tool of choice won’t do any wonders on its own.

A while ago I posted an article that showed how to generate a database schema from JPA annotations. Since I didn’t get the hibernate3 maven plugin working back then I used the antrun plugin as a workaround. Thanks to the help of a reader the plugin works now, so an update is in order.

[Update 2009-06-01: The plugin is now available in version 2.2 from the central maven repository, so I removed the plugin repository configuration. I also switched from annotationconfiguration to jpaconfiguration.]

Since the last article the scenario hasn’t changed: I want to generate DDL scripts for creating a database schema from JPA annotations. The created schema can then be tweaked as necessary and used in the production environment. Like the old antrun solution, the maven plugin uses the ant task from Hibernate Tools, so the resulting schema is the same.

This is how it works. Edit your pom.xml and add the plugin configuration:

<build>
  <plugins>
    <!-- other plugins ... -->
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>hibernate3-maven-plugin</artifactId>
      <version>2.2</version>
      <executions>
        <execution>
          <phase>process-classes</phase>
          <goals>
            <goal>hbm2ddl</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <components>
          <component>
            <name>hbm2ddl</name>
            <implementation>jpaconfiguration</implementation>
          </component>
        </components>
        <componentProperties>
          <persistenceunit>Default</persistenceunit>
          <outputfilename>schema.ddl</outputfilename>
          <drop>false</drop>
          <create>true</create>
          <export>false</export>
          <format>true</format>
        </componentProperties>
      </configuration>
    </plugin>
  <plugins>
</build>

Don’t forget to set the persistence unit to whatever you declared in persistence.xml.

Schema creation is executed in the process-classes phase, so you’ll find the schema in target/hibernate3/sql/schema.ddl after running mvn package (or any later phase). An alternative is to remove the <executions> element and to run the hbm2ddl goal from the command line:

  mvn hibernate3:hbm2ddl

The plugin offers a lot more than just schema creation. See the plugin documentation for more information.

Setting up a Java EE application is no trivial task. Dependency management, building, and deployment can get pretty complex and require a thorough understanding of deployment descriptors, jars, ears and other artifacts.

In this article, I’m going to present a truly minimal maven-based setup for the JBoss Application Server (tested with jboss-4.0.5.GA), providing a solid base for further work. The project is an EJB3 demo application which uses JPA to access a database and makes the data available via a remote session bean interface. The application will be deployed in an ear file which contains the required dependencies (unless they are already provided by JBoss).

First of all, download the application and extract it. In the root directory, there’s a pom.xml file (the POM) which defines the top-level project. Each of the subdirectories (ear, ejb, and client) is a maven project itself with a pom.xml on its own. Apart from some basic values, the top-level POM specifies its sub-modules and gives a list of dependencies for the project. The dependency list is just a declaration, its purpose is to let the other POMs reference dependencies without having to specify the version number.

The ejb module is the heart of the application. It contains the server side source code, which is the data source layer (DAOs), JPA Entities, and a remote facade (in this case: a stateless session bean). The ejb module creates two jar files: One containing all the code, and the other one with all the interfaces and data transfer objects relevant for remote clients (the client-jar).

The ear module contains no source code, its purpose is to configure the deployment descriptor (application.xml) and to package the ejb module’s jar file and all the dependencies into a single ear file, ready for deployment into the jboss application server. You’ll find the created file in ear/target.

The client module implements a simple client application which accesses the server via its remote facade. It can be run from the command line or from within eclipse.

To build the project, run mvn install from the command line. If you want to import the project into eclipse, execute mvn eclipse:eclipse to generate the required .project and .classpath files. From within the IDE, choose File/Import, General/Existing Projects into Workspace, browse to the project’s base directory and hit Finish.

Update: I updated the demo application to version 0.2. The new version removes an unused import script that caused confusion and the documentation notes where the JBoss dependencies are coming from.

When using an ordinary jar library, IDEs like Eclipse’s JDE don’t have enough information to display inline javadocs for referenced classes. You have to manually direct Eclipse to the library’s source code to take advantage of inline documentation. Maven’s source plugin provides a convenient solution to this problem. When building the library, the plugin creates a source jar containing the package’s source code. This source package can be installed or deployed into your repository. Maven’s eclipse plugin then adds the source package to the generated .classpath file.

This is how it works. Before installing or deploying your library, run the source plugin:

  mvn source:jar

Your next install or deploy call will take care of the rest. In the dependent project (the one using your library), run the eclipse plugin:

  mvn eclipse:eclipse

After refreshing the project in eclipse, you should now have access to inline documentation.

If you don’t want to run source:jar each time, you can attach the call to the build lifecycle’s package phase:

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

After running mvn package, there should be a source package in your target directory.

Java’s persistence API (JPA) makes object-relational mapping very convenient. Using Hibernate, tables and sequences are generated automatically which speeds up development significantly. However, in production systems automatic schema creation isn’t desired. In many cases you would want to tune the schema a bit, like adding an index for speeding up common access paths, renaming constraints and the like. Additionally, an application should run with as little DB privileges as possible, so it is possible that CREATE TABLE is simply not permitted.

[UPDATE: See this article for a pure maven solution.]

The usual approach is to create a DDL script containing the required CREATE commands and execute it on the database before deploying the application. Unfortunately, this is a large task if you have many entities and with foreign key constraints, the order of commands matters. So it would be nice if we could generate a working DDL script from our JPA annotations that can be adjusted manually.

Using Hibernate and the hibernatetool Ant task, this is possible. In the following example, I’ll show how to configure a Maven project which used the antrun plugin to execute hibernatetool from within Maven.

First of all, we have to attach the antrun plugin to Maven’s lifecycle. Add the following to your pom.xml:

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-antrun-plugin</artifactId>
        <executions>
          <execution>
            <id>process-classes</id>
            <phase>process-classes</phase>
            <configuration>
              <tasks>
                <ant antfile="src/main/ant/build.xml" inheritRefs="true">
                  <target name="schemaexport"/>
                </ant>
              </tasks>
            </configuration>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-tools</artifactId>
            <version>3.2.0.beta9a</version>
          </dependency>
          <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-entitymanager</artifactId>
            <version>3.2.1.ga</version>
          </dependency>
          <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>1.2.14</version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>

The plugin configuration references an external build.xml file which contains the hibernatetool invocations. Create a directory src/main/ant and add the following build.xml file:

<?xml version="1.0" encoding="UTF-8"?>

<project>

    <!--
          Generate DDL files for schema creation.
    -->
    <target name="schemaexport">

        <taskdef name="hibernatetool"
                 classname="org.hibernate.tool.ant.HibernateToolTask"/>

        <hibernatetool destdir="target">

            <classpath refid="maven.compile.classpath"/>

            <!-- Use JPA annotations, as opposed to Hibernate's hbm
                 files. If there are multiple persistence units, specify
                 the correct one using the  "persistenceunit" attribute.
            -->
            <jpaconfiguration />

            <!-- Write all CREATE statements to a file. -->
            <hbm2ddl drop="false" create="true" export="false"
                     outputfilename="schema-create.ddl"
                     delimiter=";" format="true"/>

            <!-- Write all DROP statements to a different file. -->
            <hbm2ddl drop="true" create="false" export="false"
                     outputfilename="schema-drop.ddl"
                     delimiter=";" format="true"/>

        </hibernatetool>

    </target>

</project>

Now you can run mvn generate-classes and you will find two DDL files in the target directory: One for creating and one for dropping all tables.

Java projects, especially when it comes to web or EJB applications, tend to get pretty complex. Setting up such a project is a non-trivial task because of the many conventions you have to follow to make your application deployable. The maven project management tool provides a mechanism to setup a project quickly using its archetype concept.

An archetype is a template which creates a skeleton project for you that already knows which dependencies to download and how to build a deployable package. All you have to do is to adjust the maven configuration file (pom.xml) to your needs and fill in code.

When I wanted to play with Seam, all I had to do was to locate a proper archetype and run the following command (all on one line):

mvn archetype:create
  -DarchetypeGroupId=org.apache.maven.archetypes
  -DarchetypeArtifactId=softeu-archetype-seam-simple
  -DgroupId=de.mafr.seam
  -DartifactId=Seam-Demo
  -DremoteRepositories=http://maven.softeu.cz

A directory Seam-Demo is created which contains a skeleton project. You can create a deployable WAR-File from it using mvn package.