BeeWorks werkte in onderaanneming aan dit project. Jurgen tekende de globale architectuur en nam een groot deel van de ontwikkeling voor zijn rekening.

Deploying the plugin

The files that are generated by a project, be it a jar, a war or anything else, are called artifacts. The build file for our Hibernate Tools plugin creates a jar-file, which is the default for the Java plugin. Because other projects should be able to use this plugin, we will deploy it to an online repository. Now, Gradle can deploy the jar-file with an ivy.xml descriptor, or with a Maven POM file. For this experiment, we will use the Maven POM.

The project will be hosted on Google Code, so let’s use the google code subversion repository for uploading artifacts. The protocol we’ll use is WebDAV, as described here.

First of all, we need to add the plugin ‘maven’.

usePlugin 'maven'

This plugin adds an install task to the build, so running ‘gradle install’ puts the jar-file and the generated POM in the local Maven repository. Note that you should specify the group in the build file:

group = "org.meijiframework.gradle"

After verifying that the POM is in fact generated, and the artifact is properly installed in the local Maven repository, we can continue with the WebDAV repository upload. First, we add a dependency on the WebDAV wagon jar:

dependencies {
    archives "org.apache.maven.wagon:wagon-webdav:1.0-beta-2"
}

The archives configuration is the default dependency configuration for the artifact management tasks.
Now we can configure the maven deployer:

uploadArchives {
    repositories.mavenDeployer {
        name = 'googleCodeDeployer'
        repository(url: "dav:https://bzb-framework.googlecode.com/svn/maven-repository/") {
            authentication(userName: "Your.Name", password: "yourPassword")
        }
    }
}

This should be sufficient, and running ‘gradle upload’ should upload the snapshot of the Hibernate plugin to the maven repository on Google Code. With gradle 0.8 however, I got an exception. You can read all about it on the Gradle Jira, where I reported the bug (http://jira.codehaus.org/browse/GRADLE-729). Apparently there is a jar versioning problem, which can easily be solved by removing the file webdavlib-2.0.jar from $GRADLE_HOME/lib and replacing commons-httpclient-3.0.jar with commons-httpclient-2.0.2.

It’s not a good idea to put your username and password in the build file, so let’s try to externalize this. With Maven you would do this with the settings.xml file in the ~/.m2 folder, with gradle the solution is similar, but more concise: create a properties file gradle.properties in the ~/.gradle folder and add the googleCodeUser and googleCodePass properties. Then in the uploadArchives section of your build file, replace the authentication line with this:

            authentication(userName: googleCodeUser, password: googleCodePass)

Using the Hibernate plugin revisited

Remember in part 2 of this series, after we created the Hibernate Tools plugin for Gradle, we needed to add 2 dependencies to our model project: one for the plugin itself, with a file dependency and one for Hibernate EntityManager. Now that we have deployed the plugin on a Maven repository, we can simplify this. First we need to add a reference to our Maven repo to the build script, and then we can replace the file dependency with an artifact dependency and remove the Hibernate EntityManager dependency altogether, because now the transitive dependency mechanism is working. So the buildScript section now looks like this (supposing we deployed version 1.0.0 of our plugin):

buildscript {
    repositories {
        mavenCentral()
        mavenRepo urls: "http://repository.jboss.com/maven2"
       mavenRepo urls: "http://bzb-framework.googlecode.com/svn/maven-repository"
    }
    dependencies {
        classpath group: 'org.meijiframework.gradle', name: 'gradle-hibernate-tools', version: '1.0.0'
     }
}

usePlugin(org.meijiframework.gradle.plugins.HibernateToolsPlugin)

Multimodule build

First thing we need to do, is pull some build logic that could be useful in the other modules (midtier, ui, …) to the root build file of the MoneyPile project. This is where Gradle is very different from Maven: whereas Maven (2.x) uses inheritance for sharing common build logic, Gradle uses configuration injection. This is much more flexible. So, let’s see how we can make the MoneyPile build a multimodule build.

First we need to create a settings.gradle file in the root directory of our project. In this file, we specify which modules our project contains. At this point, there is only one module: model. So our settings.gradle file should currently look like this:

include "model"

Now we can create the root build.gradle file, in the same directory as the settings.gradle file. For multimodule builds, there are 2 very important clauses in Gradle: allprojects and subprojects. The allprojects clause will be executed for all modules, including the root, and the subprojects clause will only be executed for the submodules.

In the allprojects clause of MoneyPile, we can put the version and the Maven repository configuration.

allprojects {
    version = '1.0.0-SNAPSHOT'

    repositories {
        mavenCentral()
        mavenRepo urls: "http://repository.jboss.com/maven2"
    }
}

In the subprojects clause, we put the common stuff for all Java builds:

subprojects {
    usePlugin 'java'
    usePlugin 'project-reports'
    usePlugin 'eclipse'
    sourceCompatibility = 1.6

    manifest.mainAttributes(
        'Implementation-Title': 'BeeWorks MoneyPile',
        'Implementation-Version': version
    )

    task copyRuntimeDependencies(dependsOn: configurations.runtime.buildArtifacts, type: Copy) {
        into('build/output/lib')
        from configurations.runtime
        from configurations.runtime.allArtifacts*.file
    }
}

Now that this is in the root build file, we can clean up the build file of the model module. The only thing we need there is the name of the resulting jar-file, the dependencies and the Hibernate plugin configuration:

buildscript {
    repositories {
        mavenCentral()
        mavenRepo urls: "http://repository.jboss.com/maven2"
        mavenRepo urls: "http://bzb-framework.googlecode.com/svn/maven-repository"
    }
    dependencies {
        classpath group: 'org.meijiframework.gradle', name: 'gradle-hibernate-tools', version: '1.0.0'
    }
}

usePlugin(org.meijiframework.gradle.plugins.HibernateToolsPlugin)

schemaExport.dialects = 'org.hibernate.dialect.Oracle10gDialect, org.hibernate.dialect.MySQL5Dialect, org.hibernate.dialect.PostgreSQLDialect, org.hibernate.dialect.HSQLDialect'

jar.baseName = 'moneypile-model'

dependencies {
    compile group: 'org.slf4j', name: 'slf4j-log4j12', version: '1.5.2'
    compile group: 'log4j', name: 'log4j', version: '1.2.14'
    compile group: 'commons-logging', name: 'commons-logging', version: '1.1.1'
    compile group: 'org.hibernate', name: 'ejb3-persistence', version: '1.0.2.GA'
    compile group: 'org.hibernate', name: 'hibernate-annotations', version: '3.4.0.GA'
    compile group: 'org.hibernate', name: 'hibernate-commons-annotations', version: '3.3.0.ga'
    compile group: 'javax.validation', name: 'validation-api', version: '1.0.CR5'
    compile group: 'org.hibernate', name: 'hibernate-search', version: '3.1.0.GA'
    testCompile group: 'junit', name: 'junit', version: '4.4'
    testCompile group: 'org.hibernate', name: 'hibernate-validator', version: '4.0.0.CR1'
}

And that’s our multimodule build with 1 module! Now we can create the next module: midtier. This will contain the DAOs and services of the MoneyPile application. This is a very simple module, so all we have to add here are the dependencies and the name of the jar-file. We also want to specify that this module depends on the model module:

jar.baseName = 'moneypile-midtier'

dependencies {
     compile project(':model')
}

The webapp module has some more requirements: we would like to be able to run the webapp using a Jetty plugin. Just like Maven, Gradle has a plugin for this:

     usePlugin 'war'
     usePlugin 'jetty'

Now, we can run our webapp with the command ‘gradle jettyRun’.

Closing thoughts

Today, we learned how to deploy a custom gradle plugin to a repository, we touched the subject of multimodule builds, and added the Jetty plugin to our build, so we can run our webapp from the command line.

Note that Gradle offers a number of ways to handle multimodule builds. Coming from Maven, I’m used to using a build file for every module, but you can just as well put everything in the root build file. You can read all about this in the Gradle manual of course.

I’m still not 100% sure the configuration injection approach is the best one though. With Maven, I was able to create a company-wide parent pom that was inherited by all projects. That pom contained the locations of the Subversion repository, CI, Jira etc. With Gradle there does not seem to be an easy way to accomplish the same thing easily, unless you write a plugin. On the other hand, Gradle plugins are quite easy to write and much more powerful than their Maven counterparts. Still, composition of build files would be nice.

So, will I ditch Maven in favor of Gradle? For existing Maven projects, no. They work fine for now, and I don’t like fixing what isn’t broken. For future projects, I think I might. Unless Maven 3.0 completely blows me away Now that I’m hooked on Groovy and Grails, I might even try to contribute a Gradle plugin for Grails…

    def texify(String input) {
        return input.
            //replace all \ with {\textbackslash}
            replaceAll("\\\\" , "{\\\\textbackslash}").
            //put backslash before {, } $, %, _, & and #
            replaceAll('([{}\$%_&#])', '\\\\$1').
            //undo { and } for the {\textbackslash} occurrences
            replaceAll("\\\\\\{\\\\textbackslash\\\\\\}", "{\\\\textbackslash}").
            //replace ~ with \~{}
            replaceAll("~", "\\\\~{}").
            //put math mode around <, > and |
            replaceAll("([<>|])", '\\$$1\\$').
            //replace all ... with \ldots
            replaceAll("(^|[^.])\\.\\.\\.([^.])", '$1\\\\ldots$2').
            //fix double quotes
            replaceAll("(^|\\s)\\\"", '$1``').
            replaceAll("\\\"(\\W|\$)", '\'\'$1').
            //fix single quotes
            replaceAll("(^|\\s)'", '$1`').
            replaceAll("'(\\W|\$)", '\'$1')
    }

I based the regular expressions on this Perl script by Tristan Miller, and on the excellent LaTeX manual at the Ghent University LaTeX user group.

Het Edo Framework verwijst naar de Edo-periode (1603-1867) in de geschiedenis van Japan. Gedurende deze periode regeerde het Tokugawa shogunaat, dat in 1603 officieel werd gevestigd door Tokugawa Ieyasu. De naam Edo-periode wordt gebruikt omdat het shogunaat, en dus de macht, in Edo (het huidige Tokyo) gezeteld was. De Edo-periode bracht rust en stabiliteit in Japan, onder andere vanwege de strenge regels die werden opgesteld.

Our goal for today

For my old/current Java development framework, I have written a Maven plugin that takes the META-INF/persistence.xml of a JPA project, and uses Hibernate SchemaExport to generate 3 ddl-files for every database dialect you specify: drop-create, create and drop. By default, this is done for Oracle, MySQL, PostgreSQL and HSQL, but you can choose any of the dialects Hibernate offers. I know what you’re thinking: why didn’t you just use the hibernate3 plugin that’s available on Codehaus? Well, I haven’t checked lately, but when I created my framework, this plugin didn’t do what I wanted and it was still in the sandbox. Plus, I liked the challenge.

Now, how will we do this with Gradle? As far as I can tell, there are several options: Since Gradle offers first-class support for Ant build files and Ant tasks, we could use the Ant tasks that come with Hibernate Tools. But again, they don’t really do what I want: for one, you need to set the dialect in the persistence.xml file, and I don’t want that. All I want to put in there are the class names of my entities.

I’ve chosen to dive into the Gradle API and write a Gradle Task and a Plugin for this purpose. My knowledge of Groovy is still too limited, so I’ll write them in Java.

So let’s create a new project, called ‘gradle-hibernate-tools’. The Gradle build file looks a lot like the one we created yesterday:

usePlugin 'java'
usePlugin 'project-reports'
usePlugin 'eclipse'

defaultTasks 'clean', 'build'

sourceCompatibility = 1.6
version = '1.0.0-SNAPSHOT'
manifest.mainAttributes(
     'Implementation-Title': 'Hibernate tools plugin for Gradle',
     'Implementation-Version': version
)
jar.baseName = 'gradle-hibernate-tools'

repositories {
     mavenCentral()
     mavenRepo urls: "http://repository.jboss.com/maven2";
}

dependencies {
     compile group: 'org.slf4j', name: 'slf4j-api', version: '1.5.2'
     compile group: 'org.slf4j', name: 'slf4j-log4j12', version: '1.5.2'
     compile group: 'org.hibernate', name: 'ejb3-persistence', version: '1.0.2.GA'
     compile group: 'org.hibernate', name: 'hibernate-annotations', version: '3.4.0.GA'
     compile group: 'org.hibernate', name: 'hibernate', version: '3.2.1.ga'
     compile group: 'org.hibernate', name: 'hibernate-entitymanager', version: '3.4.0.GA'
     compile group: 'org.hibernate', name: 'hibernate-commons-annotations', version: '3.3.0.ga'
     compile group: 'org.hibernate', name: 'hibernate-tools', version: '3.2.4.GA'
     compile group: 'dom4j', name: 'dom4j', version: '1.6.1'
     compile group: 'org.codehaus.groovy', name: 'groovy-all', version: '1.6.4'
     compile files('lib/gradle-core-0.8.jar', 'lib/gradle-open-api-0.8.jar')
}

The only difference here is the manifest section, and a number of dependencies, specifically Groovy, Gradle and Hibernate Tools. You’ll notice that the gradle dependency is a file dependency to a jar-file I put in the project lib directory. The Gradle artifacts are not yet available on any Maven repository. This is something that should be fixed as soon as possible.

The Task

The next step is writing the Task that will perform the database schema export. Now, in the Gradle manual, there are chapters on writing custom tasks and custom plugins, but they don’t go into a lot of detail. The best way for now is diving into the Gradle source code, which is exactly what I did. Let’s take a look at the Task.

public class SchemaExportTask extends ConventionTask {
	private Boolean format = Boolean.TRUE;
	private Boolean comments = Boolean.TRUE;
	private String dialects = "org.hibernate.dialect.MySQL5Dialect";
	private String persistenceUnitName = "default";
	private String delimiter = ";";
	private String targetDirectory = "build/ddl";

Our Task extends the ConventionTask class. This will allow us to configure the task from the project build file, using the Gradle Convention mechanism.

First we define some properties to control the output of the task. The dialects property for example is a comma separated list of Hibernate dialects we want to create DDL for. All these properties will be configurable in the build file later on.

	private FileCollection classpath;

	/**
	 * Returns the classpath for the Hibernate Tools
	 */
	@InputFiles
	public FileCollection getClasspath() {
		return classpath;
	}

	/**
	 * Set the classpath for the web application
	 */
	public void setClasspath(FileCollection classpath) {
		this.classpath = classpath;
	}

The classpath property will allow us to specify the classpath that should be used by the task when trying to generate the schema. This is important because we will need the runtime classpath of the project containing the persistent entities. We’ll see how this property gets configured when we create the plugin later on. Not the @InputFiles annotation on the getter.

Next is the main method of the task.

@org.gradle.api.tasks.TaskAction
protected void start() {
	ClassLoader originalClassloader = this.getClass().getClassLoader();
	try {
		List classpath = setUpClassPath();
		URLClassLoader hibernateToolsClassloader = new URLClassLoader(
			classpath.toArray(new URL[classpath.size()]),
			originalClassloader);
		Thread.currentThread().setContextClassLoader(
			hibernateToolsClassloader);
		exportSchema();
	} catch (MalformedURLException e) {
		logger.error("Error trying to set the Hibernate Tools classpath");
	} finally {
		Thread.currentThread().setContextClassLoader(
			originalClassloader
		);
	}
}

This method is annotated with the TaskAction annotation. Note that there are 2 TaskAction classes in the Gradle API, in different packages. Only the one in the tasks package is an annotation. TaskAction indicates that the annotated method will be called when Gradle starts the task. This method creates a new classloader, containing the classpath we specified above and puts that classloader in the current thread. Then it calls the exportSchema method, which will do the actual work. Afterwards, it resets the current thread contextClassLoader to the original one. This reason for all this classloader stuff is because Hibernate uses the contextClassLoader of the current thread when instantiating a JpaConfiguration.

private void exportSchema() {
	Ejb3Configuration configuration = new Ejb3Configuration();
	Map properties = new HashMap();
	properties.put("hibernate.format_sql", format);
	properties.put("hibernate.use_sql_comments", comments);
	configuration = configuration
		.configure(persistenceUnitName, properties);

	if (configuration == null) {
		logger.error("Error: Unable to export schema");
		return;
	}

	for (final String dialect : getDialectList()) {
		try {
			export(configuration, dialect);
		} catch (final Exception e) {
			logger.error("Error exporting DDL for dialect " + dialect, e);
		}
	}
}

The exportSchema() method creates a new JPA configuration, using the persistenceUnit we configured. It looks for the configuration of this persistenceUnit in the classpath resource META-INF/persistence.xml. If the persistence.xml file can’t be found, an error is logged and the task ends. If the JPA configuration is created succesfully, an export is performed for every dialect we specified in the task properties.

That completes the hardest part. Now we’ll write a plugin so we can easily reuse this functionality in all our JPA projects. You can download the full source code of this task here.

Tasks vs. Plugins

As you have seen in the previous section, a task delivers some extra functionality to a build, in our case generating DDL. Some readily available tasks in Gradle are the Java compile and jar tasks.

A plugin is used to alter the build script, for example adding tasks, dependency configuration or conventions to the script. In other words, they are used to plug the functionality provided by the task in the build. So tasks and plugins complement each other nicely in Gradle.

The plugin

The easiest way to write a Gradle plugin seems to be in Groovy, in the build file itself. I’ll use java for this too however, for 2 reasons. First, I don’t know Groovy well enough. Second, I want to reuse my plugin in other projects, and I don’t know if that’s possible when writing it in the build file, the manual doesn’t mention this. When using good old Java, I can create a jar and put it in a repository somewhere.

What does our plugin need to do? It has to add the SchemaExport task to the project build. We would like to be able to configure the task with some properties, so the plugin will have to register a convention for it. And finally, the plugin has to pass the runtime classpath of the project to the task, so the Hibernate configuration can load our persistent classes.

public class HibernateToolsPlugin implements Plugin {

	public static final String SCHEMA_EXPORT = "schemaExport";

	@Override
	public void use(Project project, ProjectPluginsContainer container) {
		System.out.println("Using Hibernate Tools Plugin");
		container.usePlugin(JavaPlugin.class, project);

		HibernateToolsConvention hibernateToolsConvention = new HibernateToolsConvention();
		Convention convention = project.getConvention();
		convention.getPlugins().put("hibernateTools", hibernateToolsConvention);

		configureSchemaExport(project, hibernateToolsConvention);
	}

A plugin needs to implement the Plugin interface. This interface has only 1 method: use. This method is called when we add the method usePlugin() to a build file.

Our use() method does 3 things:

1. Make sure the build also uses the Java plugin. Not much use for Hibernate without Java.
2. Add a convention to the build, which will allow us to configure the schemaExport task. We will look at the HibernateToolsConvention class later.
3. Configure and register the schemaExport task.

private void configureSchemaExport(final Project project, final HibernateToolsConvention hibernateToolsConvention) {
	project.getTasks().withType(SchemaExportTask.class).whenTaskAdded(new Action() {
		public void execute(SchemaExportTask schemaExport) {
			schemaExport.getConventionMapping().map("classpath", new ConventionValue() {
				public Object getValue(Convention convention, IConventionAware conventionAwareObject) {
					return getJavaConvention(project).getSourceSets().
						getByName(SourceSet.MAIN_SOURCE_SET_NAME).
						getRuntimeClasspath();
				}
			});
			schemaExport.getConventionMapping().map("format", new ConventionValue() {
				public Object getValue(Convention convention, IConventionAware conventionAwareObject) {
					return hibernateToolsConvention.getFormat();
				}
			});
			schemaExport.getConventionMapping().map("comments", new ConventionValue() {
				public Object getValue(Convention convention, IConventionAware conventionAwareObject) {
					return hibernateToolsConvention.getComments();
				}
			});
			schemaExport.getConventionMapping().map("dialects", new ConventionValue() {
				public Object getValue(Convention convention, IConventionAware conventionAwareObject) {
					return hibernateToolsConvention.getDialects();
				}
			});
			schemaExport.getConventionMapping().map("persistenceUnitName", new ConventionValue() {
				public Object getValue(Convention convention, IConventionAware conventionAwareObject) {
					return hibernateToolsConvention.getPersistenceUnitName();
				}
			});
			schemaExport.getConventionMapping().map("delimiter", new ConventionValue() {
				public Object getValue(Convention convention, IConventionAware conventionAwareObject) {
					return hibernateToolsConvention.getDelimiter();
				}
			});
			schemaExport.getConventionMapping().map("targetDirectory", new ConventionValue() {
				public Object getValue(Convention convention, IConventionAware conventionAwareObject) {
					return hibernateToolsConvention.getTargetDirectory();
				}
			});

		}
	});

	SchemaExportTask schemaExport = project.getTasks().add(SCHEMA_EXPORT, SchemaExportTask.class);
	schemaExport.setDescription("Generates DDL scripts for your database from your JPA persistent classes.");
}

What’s going on here? The first thing we do is registering a listener that fires an action when the SchemaExport task is added to the project. This action injects the runtime classpath of the project in our SchemaExport task. Remember we need this to run the schema export. Notice how convenient Gradle makes it to retrieve that classpath from the project. The rest of this action takes the properties from the schemaExport convention and injects them in the task.

After registering this listener, the task itself is added to the project, as well as a description.

So that was the plugin. The only thing we need to take a look at now is the convention object, but there is really is nothing much to say about it. It’s just a simple bean with a number of properties.

You can download the source code of the plugin as well as the convention object here.

Using the plugin

In order to use this plugin in our domain model project, we will need to add it as a dependency to our build script. According to the manual, you do this using the buildscript() method, passing in a closure which declares the dependencies.

buildscript {
        dependencies {
                classpath fileTree(dir: "D:/meiji-framework/gradle/hibernate-tools/build/libs", includes: ['*.jar'])
        }
}

This adds the jar-file of the plugin to the build classpath. That’s not enough however. Since we are using a file dependency at the moment, there are no transitive dependencies. But we also need hibernate. The hibernate dependencies are on the Maven central repository. So we need to add these lines as well. The complete buildscript method now looks like this:

buildscript {
        repositories {
                mavenCentral()
                mavenRepo urls: "http://repository.jboss.com/maven2"
        }

        dependencies {
                classpath group: 'org.hibernate', name: 'hibernate-entitymanager', version: '3.4.0.GA'
                classpath fileTree(dir: "D:/meiji-framework/gradle/hibernate-tools/build/libs", includes: ['*.jar'])
        }
}

Now we can add the plugin itself. This is easy:

usePlugin(org.meijiframework.gradle.plugins.HibernateToolsPlugin)

Configuring the plugin is easy as well. Let’s say we want DDL files for 4 databases: Oracle, MySQL, PostgreSQL and HSQL:

schemaExport.dialects = 'org.hibernate.dialect.Oracle10gDialect, org.hibernate.dialect.MySQL5Dialect, org.hibernate.dialect.PostgreSQLDialect, org.hibernate.dialect.HSQLDialect'

That’s it! Now when we start the command ‘gradle schemaExport’, we get 4 directories in build/ddl: hsql, mysql5, oracle10g and postgresql. Each of these contains 3 files: create.sql, drop.sql and drop_create.sql.

Day 2 conclusion

This is all very nice, but it’s not perfect yet. For one, having to specify all transitive dependencies for the plugin is not acceptable. Luckily, that should be easily fixed once I deploy the plugin to a repository, along with a descriptor. That’s for the next blog post though.

What would be really great, is if you could use the dependency notation with the usePlugin() method, like this:

usePlugin('org.meijiframework:gradle-hibernate-tools:1.0')

I don’t think this would be very hard to implement, so who knows, maybe it will be added before they reach version 1.0.

A slight concern

As I’m getting more acquainted with Gradle, I do have a slight concern. One of the great things about Maven is the rather strict convention. I mean, if you download a project with a POM, you know for sure that an ‘mvn clean install’ will build, test and package the project, and all plugins the developer added to each phase will be executed.

Gradle also has conventions to a certain level, but they are not enforced and I have a feeling that the philosophy is more like Ant. You create your own tasks (or targets, in Ant terms), mark some of them as default, but there is no guarantee that ‘gradle build’ will even work or that every plugin in the buildfile is used when you run a task. In short, I’m afraid that in the end, you will have to investigate the build file of project when you download it, just like you did in the Ant days. With Maven, you don’t have to worry about it.

At the 2008 Devoxx conference, I attended a talk about Gradle, which looked promising, so I made up my mind to investigate it in the near future. Due to lots of work and tight deadlines, that near future became a year later, so here we are.

What is Gradle?

Gradle is a build system, based on Groovy. Its developers promise that it gives you the best of both worlds between Ant and Maven, and then some. You get the build-by-convention, dependency management and multi-project support from Maven, the flexibility of Ant and the power of Groovy. It is now at version 0.8 and has a very nice user guide, which is already more than 200 pages long. It took Maven years to get that kind of coverage!

The experiment

I am currently working on a completely new version of my Java development framework, so I decided the time was right to try and ditch Maven.

As I’m building the new framework, I’m testing it with an example project called BeeWorks MoneyPile, a simple accounting program I use for creating invoices, tracking expenses and handling contacts. BeeWorks MoneyPile is a multi-project erm… project, consisting of a domain model, a middle tier and a web application. Every one of those projects has specific build system requirements. These requirements are, in broad strokes:

• dependency management
• build profiles (development, production)
• custom plugins (hibernate tools, embedded Tomcat or Jetty)
• compilation
• unit tests
• keyword substitution in resource files
• release management
• javadocs and documentation
• packaging

The first part of MoneyPile I will try to switch to Gradle while writing the next 2 blog posts is the domain model, together with the MoneyPile parent build of course. This should be fairly straightforward, since all I’m doing here is compiling, running unit tests, packaging and generating DDL files using Hibernate tools. Oh, and generating Eclipse project files would be nice too. So let’s get to it.

Installing Gradle

Installing Gradle is quite simple, much like Ant or Maven. Just download the distribution from the Gradle website and unzip it. Then add an environment variable called GRADLE_HOME pointing to the Gradle installation directory (in my case c:/java/gradle-0.8), and add %GRADLE_HOME%/bin to your PATH environment variable (on Linux this would be $GRADLE_HOME/bin). Then fire up a command prompt, and run ‘gradle -v‘. If installed correctly you should get some information about Groovy, Ant and Java versions.

By the way: if you’re on Mac OS X, you can use MacPorts to install gradle. You still need to set the environment variables though:

export GRADLE_HOME=/opt/local/share/java/gradle
export PATH=$PATH:$GRADLE_HOME/bin

After installing on Mac OS X, my first build failed, because of a permissions problem on the ~/.gradle directory. The simplest solution is to just delete ~/.gradle first:

sudo rm -rf ~/.gradle

First things first

The first thing to do is to create the Gradle build file, in the project folder. The name of this file is build.gradle. The file can remain empty for now.

Dependencies

The domain model of MoneyPile consists of a number of POJOs, annotated with JPA, Bean Validation (JSR 303) and Hibernate Search annotations. In the unit tests, I use the Bean Validation framework for testing valid and invalid instances of model classes.

This means we will need to specify a number of dependencies before considering compilation. These are the compile scope dependencies:

• ejb3 persistence
• hibernate annotations
• hibernate commons annotations
• validation api
• hibernate search
• log4j
• slf4j
• slf4j log4j12
• commons logging

The test scope needs some more dependencies:

• junit 4
• hibernate validator 4

The good thing about Gradle dependency management is that you can use the familiar Maven repositories. Adding the Maven central repository to your build is as simple as this:

repositories {
  mavenCentral()
}

I’m using some dependencies that are not yet available in the central repository however, so let’s take a look how we can add the JBoss repository to our build as well. According to the manual, adding this line to the repositories section should do the trick:

mavenRepo urls: "http://repository.jboss.com/maven2"

That was simple. Now let’s add the dependencies:

dependencies {
  compile group: 'org.slf4j', name: 'slf4j-log4j12', version: '1.5.2'
  compile group: 'log4j', name: 'log4j', version: '1.2.14'
  compile group: 'commons-logging', name: 'commons-logging', version: '1.1.1'
  compile group: 'org.hibernate', name: 'ejb3-persistence', version: '1.0.2.GA'
  compile group: 'org.hibernate', name: 'hibernate-annotations', version: '3.4.0.GA'
  compile group: 'org.hibernate', name: 'hibernate-commons-annotations', version: '3.3.0.ga'
  compile group: 'javax.validation', name: 'validation-api', version: '1.0.CR5'
  compile group: 'org.hibernate', name: 'hibernate-search', version: '3.1.0.GA'
  testCompile group: 'junit', name: 'junit', version: '4.4'
  testCompile group: 'org.hibernate', name: 'hibernate-validator', version: '4.0.0.CR1'
}

Nice and concise isn’t it? Each line corresponds to a <dependency> tag in a Maven POM. ‘compile’ and ‘testCompile’ are the dependency scope, ‘group’ is the groupId, ‘name’ is the artifactId and ‘version’ is the version.

Building

We should now be able to compile the project. The project source tree follows the Maven convention, so building it takes only one line in the build file:

usePlugin 'java'

Now, when running the command ‘gradle build’, we see that Gradle does about the same as a Maven build: compile sources, process resources, process classes, compile test sources, process test resources, process test classes, run unit tests, package a jar and assemble a project archive.

Our build still needs some finetuning however. The jar file that was generated is called model-unspecified.jar because we didn’t specify a project name or version. Also, we want to be sure we’re compiling for java 1.6. Finally, we want to specify some default build tasks. To do all this, we add the following to the top of our build file, right below the usePlugin line:

defaultTasks 'clean', 'build'

sourceCompatibility = 1.6
version = '1.0.0-SNAPSHOT'
jar.baseName = 'moneypile-model'
manifest.mainAttributes(
   'Implementation-Title': 'BeeWorks MoneyPile - Domain Model',
   'Implementation-Version': version
)

Thanks to the default tasks, we can now just run the command ‘gradle’, which will perform both the clean and build tasks. The resulting jar-file will be named ‘moneypile-model-1.0.0-SNAPSHOT’.

Dependencies again

So far so good. Now let’s look in a little more detail at what gradle does with the project dependencies. Transitive dependencies are nice, but you often end up downloading jar-files you don’t really want.

The compile and testCompile classifiers you see on each line of the dependency section above are actually artifact configurations, used to group the dependencies in what Maven calls scopes. You can define scopes yourself, but the java plugin already defines some typical ones: compile, runtime, testCompile, testRuntime, archives and default. Check the Gradle manual for details on all of those. The ones we are interested in right now are compile, testCompile, runtime and testRuntime. Note that by default, the compile (and testCompile) configuration does not use transitive dependencies.

When using Maven, one of the most useful plugins is the dependency plugin, which can generate a dependency tree for your project. Luckily, Gradle has this as well:

gradle -q --dependencies

This spits out the dependency tree in the console, but on Windows that’s rather useless, so I prefer to have a report. To get this, add this line to the top of the build file:

usePlugin 'project-reports'

Then, using the command ‘gradle dependencyReport’, you get a file dependencies.txt in the folder build/reports/project, which contains the dependency tree. Looking at the runtime dependencies of the domain model project, you’ll notice that there is more than one version of hibernate-core in the tree. Gradle determines which version to use in a very simple way: it just takes the newest version. In this case, this is just fine. If you want to fine-tune your dependencies, Gradles offers a lot of options: you can work with excludes, you can turn off transitive dependencies for certain modules, or you can put your dependencies in a Subversion repository. Whichever way you choose, it’s certain to be more concise than using excludes in a Maven POM.

To really be sure which jar-files gradle will put in your runtime classpath, the Gradle Cookbook offers a nice trick: just copy all artifacts from the runtime configuration in a special build folder using this task:

task copyRuntimeDependencies(dependsOn: configurations.runtime.buildArtifacts, type: Copy) {
    into('build/output/lib')
    from configurations.runtime
    from configurations.runtime.allArtifacts*.file
}

For the MoneyPile domain model project, this results in the following files:

antlr-2.7.6.jar
asm-1.5.3.jar
asm-attrs-1.5.3.jar
cglib-2.1_3.jar
commons-collections-3.1.jar
commons-logging-1.1.1.jar
dom4j-1.6.1.jar
ehcache-1.2.3.jar
ejb3-persistence-1.0.2.GA.jar
hibernate-3.2.1.ga.jar
hibernate-annotations-3.4.0.GA.jar
hibernate-commons-annotations-3.3.0.ga.jar
hibernate-core-3.3.1.GA.jar
hibernate-search-3.1.0.GA.jar
jta-1.1.jar
log4j-1.2.14.jar
lucene-core-2.4.0.jar
persistence-api-1.0.jar
slf4j-api-1.5.2.jar
slf4j-log4j12-1.5.2.jar
validation-api-1.0.CR5.jar
xml-apis-1.0.b2.jar

That looks about right for now. I’m sure I’ll need more control over the dependencies further down the line, but for now, let’s consider the dependency management of MoneyPile as done.

OK, so what’s next? We have compiling, unit tests and packaging covered. That leaves us with generating Eclipse project files and DDL files using Hibernate Tools.

Eclipse support

Generating Eclipse project files is very easy: add the eclipse plugin to the build file:

usePlugin('eclipse')

Then run ‘gradle eclipse’, and you’re ready to import your project in Eclipse. There is no such support for NetBeans yet, but apparently IntelliJ IDEA 9.0 will have native Gradle support.

Hibernate DDL generation

I saved the hardest part for last of course. For my Maven builds, I wrote a custom plugin that uses Hibernate Tools to generate DDL files for a number of databases, configurable with a plugin property. As far as I can see, there are several options for doing this with Gradle, but I’ll explore those in the next part of this series.

You can download the build file for this post here. It’s only 37 lines. Just to give you an idea: The POM file for this project was about 350 lines of XML.

Day 1 conclusion

My first experience with Gradle was surprisingly pleasant. The manual is very good, and everything I tried worked as advertised. The biggest advantage Gradle has is obviously its use of Groovy, rather than XML. This makes build files much more concise and easier to read, while being extremely powerful. The architecture its creators built on top of that seems well thought out. I can’t wait to start with the next part of my quest!

De wereldvermaarde experts van AGE, prof. dr. ir. William F. Van Impe en dr. ir. Peter O. Van Impe, zorgen voor de theorie en de implementatie van de geotechnische berekeningen. BeeWorks bouwt daar een gebruiksvriendelijke user interface rond en zal instaan voor de verdeling van de software.

In eerste instantie wordt er gedacht aan een viertal applicaties, waarvan een eerste al wordt verwacht in december.

Voorlopig staan er nog maar 3 projecten in de portfolio. Dit wordt de komende weken uitgebreid.

Wat denk je ervan? Elke feedback is welkom!

Ik kreeg de opdracht om de overschakeling op het systeem van de vaste lesblokken te coördineren en om een nieuw softwarepakket voor auditoriumbeheer te ontwikkelen. Het doel was om alle leslokalen en alle lesroosters van de UGent weer centraal te beheren.

Field study

Ik begon het project met de overschakeling op de vaste lesblokken. Wegens de deadline was het onmogelijk om eerst de nieuwe software te ontwikkelen: ik had nog 3 maanden. Bovendien gaf deze fase mij de kans om een grondige field study te doen en een goed beeld te krijgen hoe de gebruikers de bestaande applicatie gebruikten, en wat er verwacht werd van de nieuwe toepassing.

Requirements

Behalve het systeem van de vaste lesblokken waren dit de belangrijkste requirements:

geen academische reservaties die eeuwig geldig blijven: lesroosters moesten vanaf nu elk jaar opnieuw aangemaakt worden, om te vermijden dat het systeem vol zat met ongebruikte reservaties.

gedetailleerd toegangsbeheer: Universiteit Gent bestaat uit 11 min of meer autonome faculteiten, elk met hun eigen infrastructuur. Sommige auditoria worden gedeeld, andere behoren exclusief tot een of meerdere vakgroepen, en de faculteiten willen over het algemeen de volledige controle houden over wie welk lokaal kan gebruiken. Dit was dus een belangrijke voorwaarde om alle faculteiten weer te overhalen om met het nieuwe systeem te werken.

gebruiksvriendelijkheid: Het aanmaken van reservaties moest gemakkelijk zijn, zowel voor lesroosters als voor eenmalige reservaties, met duidelijke feedback over eventuele conflicten. Voor de student was het belangrijk om een handig overzicht te hebben van haar lesroosters, bij voorkeur aangepast aan het persoonlijke curriculum.

schaalbaarheid: De universiteit heeft meer dan 30000 studenten en 6000 personeelsleden. Op piekmomenten vragen al die studenten vrijwel tegelijk hun lesrooster op. Performantie was dus heel belangrijk.

integratie: De nieuwe toepassing moest kunnen communiceren met onder andere SAP, LDAP, D-ISAM en een aantal Oracle databases.

Visie

Tijdens mijn field study ontwikkelde ik de visie dat de centrale administratie van de universiteit eigenlijk een software platform nodig had met een soort van Service Oriented Architecture aan de serverzijde (hoewel ik toen de term SOA nog niet kende), een rijke gebruikersinterface voor personeel, en een webgebaseerde, gepersonaliseerde interface voor studenten en docenten. Het auditoriumbeheer kon dienen als een perfecte proof of concept hiervoor.

De applicatie was verdeeld in modules, zowel op de server als in de gebruikersinterface. Elke module bestond uit een aantal services, waarop telkens een gedetailleerde toegangscontrole toegepast kon worden. Zo kreeg een medewerker van de centrale administratie bij het opvragen van een lijst van lokalen bijvoorbeeld de volledige lijst, terwijl een medewerker van een faculteit een veel beperktere lijst kon zien.

De web applicatie liet studenten en docenten toe om hun persoonlijke kalender te bekijken en te beheren, met een interface die veel weg had van Google Calendar (wat toen nog niet bestond).

Deze visie bleek een schot in de roos maar kwam enkele jaren te vroeg: 5 jaar later, in 2008, werd het grootste softwareontwikkelingsproject in de geschiedenis van de UGent, OASIS, er volledig op gebaseerd.

Technologie

De applicatie werd volledig gebouwd op J2EE, met EJBs. De centrale databank is PostgreSQL, maar er worden ook gegevens gelezen uit Oracle (JDBC), LDAP (JNDI) en D-ISAM (RMI-IIOP en session beans). Dit alles draait op een JBoss applicatieserver. De toegangscontrole werd gerealiseerd met JAAS en AOP.

De gebruikersinterface voor personeel werd ontwikkeld met Java Swing, met behulp van een groot aantal eigen componenten en een eigen look and feel. De communicatie tussen client en server gebeurt via RMI-IIOP over SSL. Beveiliging werd ook hier met JAAS gedaan, met een op maat gemaakt authenticatiemechanisme.

De web applicatie voor studenten en docenten werd gebouwd met Struts, JSP en XSL transformaties. Een van de JSP tags die hiervoor ontwikkeld werden vormde de basis voor de Schedule JSF component in Apache MyFaces.

Resultaat

De ontwikkeling van deze toepassing duurde ongeveer 6 maanden, net op tijd om er de lesroosters voor het academiejaar 2003-2004 mee op te stellen. Daarna introduceerde ik het nieuwe pakket in elke faculteit, leidde de gebruikers op en stond nog een klein jaar in voor bug fixes en change requests, tot ik een nieuwe uitdaging aangeboden kreeg. Intussen worden alle auditoria en de meeste leslokalen van de 11 faculteiten met deze toepassing beheerd en worden de lesroosters voor alle opleidingen van de UGent ermee aangemaakt.

Voor de look and feel werd gebruik gemaakt van een bestaande WordPress theme. Die werd aangepast en vertaald naar het Nederlands. Op die manier realiseerden we een professioneel ogende website voor een bijzonder laag budget.

bezoek de website