Archive for the ‘Java’ Category @ Devoxx09: Dojo Crud Components

January 12th, 2010 Tom Comments off

I had the privilege to host a mini workshop at Devoxx09 as BOF session. The session was pretty late (9pm) and not during the university track, which probably explains why not too many people showed up. Nonetheless, I talked about our experiences with dojo there and got some positive feedback about our architectural approach. In the talk, I mainly discussed why we chose dojo as RIA technology, elaborated on the custom dojo components we developed and explained how we integrated DWR and our custom dojo components with an enterprise computing software architecture.

These are the slides:

Creating custom dojo builds in maven

June 25th, 2009 Tom 8 comments

We make extensive use of the dojo toolkit in our Java web applications. An important step in the development process of a dojo web application is creating a custom dojo build.  This post describes how we create custom dojo builds as part of our maven build process.

Why custom dojo builds

We use a lot of dijits and custom built dojo components in our web applications.  By consequence, you can easily end up with a web application that uses dozens of components. In a non-cross domain dojo setup, each component is downloaded synchronously in order not to break the component dependency graph. No need to explain that your application will load slowly if you don’t take extra precautions (slow script error, anyone?).  A custom dojo build optimizes the load and execution time of a dojo application (more details can be found in the dojo documentation).

We build, test, package and deploy our Java (web) applications with maven, and creating a custom dojo build is part of that build process.

Our maven approach

Preparing your maven project for a custom dojo builds consists of three steps:

  1. Obtaining a dojo source distribution
  2. Unpacking the source distribution
  3. Running the build script in the obtained dojo source distribution

Step 2 and 3 require configuring a plugin in the project’s POM file. We only use standard maven plugins, i.e. plugins that exist in the maven repository.  We did not write custom plugins.

After executing these steps, you can do two things:

  1. Build a war file that contains a web application with a dojo production build
  2. Prepare Eclipse configuration files to run the application on a WTP enabled Eclipse IDE

The rest of this post describes the 5 points outlined above in greater detail. The build process is parametrized using parameters in the maven POM file. Each parameter is explained at the end of the post.

1. Obtaining a dojo source distribution

To be able to make a custom dojo build, you need a source distribution of dojo. Unfortunately, dojo source distributions are not released to the main maven repository. There are two options:

  1. Download the source distribution from the dojo download page using the wagon-maven-plugin. However, this plugin downloads the dojo source distribution each time you preform a maven build. Not very efficient.
  2. Download the dojo source build and install it manually in your local repository, or a maven repository server hosted by your own organization. Obtaining the source distribution of dojo then boils down to adding a maven dependency for the source distribution (explained in Step 2).

We only describe the second option. As soon as dojo source releases are also deployed to the main maven repository, your maven build process will download the source release automatically, provided the group and artifact ID are the same as the ones used in this post.

The command we use to install a dojo source distribution in our local maven repository is (for version 1.3.1):

mvn install:install-file \
  -DgroupId=org.dojotoolkit \
  -DartifactId=dojo \
  -Dversion=1.3.1 \
  -Dpackaging=zip \
  -Dclassifier=sources \
  -Dfile=./ \
  -DgeneratePom \

To install the source distribution to a remote maven repository server, you must use the deploy plugin instead (mvn deploy:deploy-file).

2. Unpacking the source distribution

Before we can make a custom build, we must first unpack the dojo source distribution. Now that we have the source distribution in our maven repository server/local maven repository, this can be done easily with the maven-dependency-plugin. Adding the following piece of XML to the <build> section of your POM file unpacks the source distribution during the generate-sources phase of the maven build lifecycle. The dojo version you want to use and the location to which the sources are extracted are configurable with the dojo.version and the webresources.javascript.location parameter respectively.


We also rename the directory name of the unpacked directory from the verbose “dojo-release-<version>-src” to the more convenient “dojo-<version>” (the name you want to give is configurable through the dojo.source.local.unpacked.location parameter):

            tofile="${dojo.source.local.unpacked.location}" />

3. Running the dojo custom build script

Once the sources are unpacked, we run the custom build script by means of the exec-maven-plugin. The plugin runs the build script in the Rhino JavaScript interpreter, which is included in the dojo source distribution. Again, some POM parameters can be configured to guide the build process. The POM parameters can be mapped directly to the parameters that can be passed to the dojo custom build script.

      <!-- releaseDir: don't forget the slash at the end! -->

4. Building the WAR

After creating the custom dojo build, it must now be added to you web application’s WAR. This must be done by configuring the maven-war-plugin. The files created by the custom build must be added as additional web resources. The following POM excerpt adds additional web resources that are located in a directory defined by the webresources.location parameter. We put all generated web resources in that directory, which includes the files that are generated by the custom build process. Note that the unpacked dojo source distribution, which is in fact also a generated resource, is excluded from the war.

            <!-- this is relative to the pom.xml directory -->

5. Generating eclipse project files

If you configure your POM file as described above, you can generate WTP compliant eclipse project files with the maven-eclipse-plugin.

mvn -Dwtpversion=2.0 -DdownloadSources=true -DdownloadJavadocs=true \
    eclipse:clean eclipse:eclipse

The maven-eclipse-plugin runs in the generate-resources phase of the maven lifecycle. The unpacking of the dojo source distribution is done in the generate-sources and process-sources phases of the maven build lifecycle, which both occur before the generate-resources phase (for more information, see the maven documentation on the build lifecycle.

Also, since version 2.6 of the maven-eclipse-plugin, all web resources that are defined in the maven-war-plugin section of your POM file are also added to the eclipse project. By consequence, the dojo source distribution you are using in your project is automatically deployed to the server that you’re using in your eclipse IDE for testing and debugging purposes.

Note that creating the custom build is done in the compile phase of the maven lifecycle, which occurs after the generate-resources phase. This means that the custom build won’t be available in your eclipse IDE unless you first compile the project using maven and refresh your project. The prerequisite for this to work is that the custom build must be placed somewhere inside the web resources directory that you have defined in the maven-war-plugin section.

POM Parameters

In this post we have made extensive use of POM parameters. This section enumerates and explains all the parameters we’ve mentioned in earlier sections

  <!-- files and directory locations -->
  <!-- dojo custom build parameters -->
  • webresources.location: the location where all generated webresources will be located. Since these resources are generated, they will end up in the target directory of your maven project
  • webresources.javascript.location: the location where all generated javascript resources can be found. This location is relative to the webresources.location; in this example in the js subdirectory.
  • dojo.version: the version of dojo you’re using in this maven project
  • dojo.source.basename: the name of the directory that is created when you unpack the dojo source distribution. This is typically “dojo-release-<dojo.version>-src”.
  • dojo.source.friendlyname: a less verbose name for the directory that holds the dojo source distribution. Here it is “dojo-<dojo.version>”
  • dojo.source.local.unpacked.location: this is the fully qualified location of the dojo source distribution in the maven project. This defines a directory with the name configure in dojo.source.friendlyname in the javascript webresources directory

The remainder of the parameters is used to parametrize the dojo build script. For more information on custom builds, please see the dojo documentation on custom builds.

  • the location of the javascript file that contains the build profile
  • what actions must be performed in the dojo build process. This is typically “clean, release”
  • the version this dojo custom build will carry. We use a combination of the project’s artifact ID and version
  • How will the release be named. This corresponds with the name of the directory in which the custom build will be placed
  • the location where the custom build will be created. In this location a directory will be created with the name that you’ve configured in the parameter.

There are obviously more parameters that you can pass to the build script, feel free to add your own.

Concluding remarks

It may require some tinkering before you get things working, or before things work the way you want. In the end, it’s a bit of juggling with files to get them all in the correct location. But once you’re there, you get dojo custom builds for free each time you do a maven build… provided you create a correct dojo build profile of course.