Last week, JavaLobby published an article about easyb called “Is easyb Easy?”.
Yes, that’s exactly what you will find out by reading this article. easyb is a BDD framework for the Java platform written by Andrew Glover. This article goes in detail about how to write a
1. Scenarios within Stories
2. Run these Stories from Ant
3. Generate a report.
Check out the article to find out what the verdict was. Also, give it a try and let us know your verdict as well.
But I don’t like to learn new things
Yes, this is exactly what I am frequently asked by my clients and many developers. It isn’t easy to answer this question. There are several projects using Ant. Should you run away from Ant just because there is a new cool tool out there called Gant? Should you switch to Gant just because you dislike XML? Not at all. Let’s take a closer look and see what might make you switch to Gant.
When to choose Gant?
1. Complicated Build Files. If your ant build files are becoming too complicated, and hard to manage, it’s time to see if using Gant can help. Let me explain what I mean by complicated build files. If you have too much of conditional logic within your build files, say something similar on the lines shown below in Listing 1:
Code Listing 1:
<if>
<isset property="sqlserver"/>
<then>
<do something here/>
</then>
</if>
<if>
<isset property="oracle"/>
<then>
<do something else here/>
</then>
</if>
<if>
<isset property="derby"/>
<then>
<do something for derby here/>
</then>
</if>
<if>
<isset property="db2"/>
<then>
<do something for db2 here/>
</then>
</if>
Or even something like this where you might be supporting deployment to different application servers based on some property in your build.properties or by the user as shown in listing 2.
Code Listing 2:
<if>
<isset property="server.jboss4"/>
<then>
<deploy to JBoss 4/>
</then>
<elseif>
<isset property="server.weblogic10"/>
<then>
<deploy to web logic/>
</then>
</elseif>
<elseif>
<isset property="server.glassfish"/>
<then>
<deploy to GlassFish/>
</then>
</elseif>
<elseif>
<isset property="server.someother version"/>
<then>
<deploy to this some other version/>
</then>
</elseif>
</if>
Things get out of hand when you have conditional logic as shown above in your build scripts. The listings I have are just the skeleton, imagine what happens when we start adding the actual deployment logic for all these application servers. It doesn’t matter how you refactor this, it is still going to be very complicated. Trust me, I have written build scripts which were several thousand lines, and refactoring them was not a trivial task.
2. Custom Ant Tasks. I myself am guilty of writing many of these. There are many situations which arise in projects where we create custom ant tasks. It is simple once you know how to write one, and than for every complicated task you need to perform, you involuntarily will start writing custom ant tasks.
Anyone writing a custom ant task will:
a. Create a new class that extends Ant’s org.apache.tools.ant.Task class.
b. For each attribute, write a setter method.
c. Write an execute()method that does what you want this task to do.
There isn’t anything wrong in doing the above, but imagine each time you want to make a small change you will have to make changes within your Java source code, compile, test, re-package.
3. Scripting. You can extend Ant further by not writing custom ant tasks, but by using small snippets of code written in an interpreted language like JRuby, BeanShell, or Groovy. These code snippets can be placed within your build files or in separate text files. If you are using Groovy’s Ant task, your build file might look something like this:
<groovy classpathref="build.classpath">
import some.package
import another.package
def fullpath = "${.basedir}/${defaulttargetdir}"
def somefile = new SomeFile(projectName:"${pname}",
buildLabel:"${label}", buildTime:"${new Date()}")
def xml = "${fullpath}/dashboard.xml"
new File(path).write(somefile.generateReport())
ant.xslt(in:path,
out:"${properties.defaulttargetdir}/some.html",
style:"${properties.defaulttargetdir}/lib/report-style.xsl")
</groovy>
Imagine having several lines of XML in your build files which have many of these small snippets of scripts. I myself don’t like mixing and matching build files with code snippets. If you have a team where everyone is in the same page, everything works fine. What if a team member has no clue about any of the Scripting languages? He/She will have no clue how to make minor changes when things go badly. If you have all the above or even one of the above three cases, you seriously need to consider using Gant. To quote Aristotle:
For the things we have to learn before we can do them, we learn by doing them.
So, lets see how easy it is to learn Gant and see how things can improve.
This part covers some very basics of Gant. The next part, will dive deeper into Gant by using it with a sample project to build our application, and we will also see how to use it with our CI Server.
What’s Gant?
Gant is a build tool that uses both Groovy and Ant. With Gant, you describe your build process using Groovy scripts. Stated simply, Gant allows you to specify the build logic using Groovy instead of XML. The next thing you may ask is ” Is Gant a competitor to Ant?”. Let me quote from the Gant web site to make things more clear here :
Whilst it might be seen as a competitor to Ant, Gant uses Ant tasks for many of the actions, so Gant is really an alternative way of doing builds using Ant, but using a programming language rather than XML to specify the build rules.
Download and Install Gant.
In order for Gant to work, you should have Groovy installed. You can download and follow the installation instructions for Groovy here.
As I said earlier also, in order to use Gant, you should have knowledge of Groovy as well. If you have never written Groovy code before, there are many interesting books on Groovy like:
You can also read the getting started guide on the Groovy web site, which should give you a good starting point.
Download the latest version of Gant from here. Gant is currently at version 1.4.0. Unzip it to a folder. If you already have your GROOVY_HOME set, that’s all you need to use Gant.
Getting Started.
Open a console, and type gant. You should see a message as shown below:
meera-subbaraos-macbook-9:~ meerasubbarao$ gant
Cannot open file build.gant
meera-subbaraos-macbook-9:~ meerasubbarao$
You are all set at this point to use Gant in your projects.
Help Information: Open a console, and type gant -h. This will provide you with all the necessary help information you need as shown below:
meera-subbaraos-macbook-9:CodeMetricsProject meerasubbarao$ gant -h
usage: gant [option]* [target]*
-c,–usecache Whether to cache the generated class andperform modified checks on the file before re-compilation.
-n,–dry-run Do not actually action any tasks.
-C,–cachedirThe directory where to cache generated
classes to.
-D= Define to have value .
Creates a variable namedfor use in the scripts and a property
namedfor the Ant tasks.
-L,–lib
Add a directory to search for jars and
classes.
-P,–classpath
Specify a path to search for jars and
classes.
-T,–targets Print out a list of the possible targets.
-V,–version Print the version number and exit.
-d,–debug Print debug levels of information.
-f,–fileUse the named build file instead of the
default, build.gant.
-h,–help Print out this message.
-l,–gantlib
A directory that contains classes to be used
as extra Gant modules,
-p,–projecthelp Print out a list of the possible targets.
-q,–quiet Do not print out much when executing.
-s,–silent Print out nothing when executing.
-v,–verbose Print lots of extra information.
Create a new file called build.gant at the root of your project. 
Did a similarity between Ant and Gant strike you here? Ant build files are usually called build.xml, and they are created as a common practice within the root of your project folder as well.
If you have written or even modified Ant build files, you will know that it contains one project element, which in turn contains a name,the default target and the base directory.
Code Listing 4:
<project name="GantSamples" basedir="." default="compile">
So for example, sayHello target in Ant would look something like this:
<target name="sayHello" description="Saying Hello"> <echo message="Hello from Stelligent"/> </target>
Lets create the sayHello target, and also see how to set it as the default target in Gant as well.
A Gant target has a name and a description:
Code Listing 5:
target ( target-name : target-description ) {
groovy code sequence
}
The above sayHello target in Gant would translate as shown below:
target(sayHello:"Saying hello"){
Ant.echo(message:"Hello from Stelligent")
}
Now, open a command window and type gant at the root of the project where the build.gant file exists. You should be able to see a output like:
meera-subbaraos-macbook-9:CodeMetricsProject meerasubbarao$ gant
Target default does not exist.
Gant is complaining that we haven’t set a Default target. Lets see how to do the same:
Default target: Within Ant, you define the default target from within the project element as seen in Listing 4. The default target is the target called if no target is specified from the command line. There however is no project tag within Gant. There are two ways of specifying the default target as shown below
1. You simply create a target whose name is default.
target ( 'default' , 'The default target.' ) { aTarget ( )
2. or even simply:
setDefaultTarget ( aTarget )
In order to get our sayHello target working, we need to add one of the above scirpts to our build.gant file.
Code Listing 6:
setDefaultTarget(sayHello)
or
target ("default": "The default target." ) {
sayHello ( )
}
Complete listing of build.gant:
target(sayHello:"Saying hello"){
Ant.echo(message:"Hello from Stelligent")
}
/*
target ("default": "The default target." ) {
sayHello ( )
}
*/
setDefaultTarget(sayHello)
And you should be able to see:
meera-subbaraos-macbook-9:CodeMetricsProject meerasubbarao$ gant
[echo] Hello from Stelligent
meera-subbaraos-macbook-9:CodeMetricsProject meerasubbarao$
That was easy! If you have build files and it is becoming unmanageable by your team, there is a tool out there which can convert your Ant scripts to Gant scripts as well. I haven’t used it, but you can try it here.
In this part of the series, we learned when to move over from Ant to Gant, downloaded and installed Gant, and finally wrote a simple gant build file. In the next part of this series, we will see Gant in Action within a simple Java project.
And as always, keep us posted here if you are encountering any problems getting started with Gant. Stay tuned.
Roy has some provocative thoughts on TDD and getting developers to write unit tests. I don’t agree with all of them, but it’s worth a read.
Some of his interesting points:
I suggest you read the whole thing.
In the last two articles, “UML Diagrams within Javadocs” and “Visual Documentation of Ant Dependencies in 3 Simple Steps” we saw how easy and valuable it was to automate technical documentation. By using open source tools, we were easily able to provide good technical documentation within a few minutes, and at no cost at all. We were also able to keep this up-to date by adding additional tasks to our Ant build files, and run them from our CI Server(Hudson in our case) on commit and nightly builds, and also publish the results.
In this article, I will be showing you how to use yet another tool called Dxoygen for generating technical documentation based on your source code. We all have used Javadoc and have been using it for a long time, right? So, you may ask what’s the need to have another tool which produces the same HTML documentation? Doxygen has a slight edge over Javadoc and here are a few reasons why you should consider using the same:
1. With Javadoc you have to remember all the HTML tags, you need to embed within your code comments. However, with Doxygen code comments are much more concise and polished, without the need for any HTML.
2. Doxygen can also generate a variety of diagrams, we will take a look at some of them later.
3. Doxygen also provides a structured view on the source code. As I mentioned in 2 above in the form of various diagrams, cross-referenced and syntax highlighted code.
4. You get all the above benefits even if the code does not have any comments at all.
5. Last but not the least, Doxygen is a documentation system not for just Java but also for various other languages like C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#.
So, without wasting further time, lets see what we need to get started with Doxygen.
Step 1. Download, Install Doxygen
Download the binary distribution for Doxygen for the operating system you are using. I downloaded the binary distribution for Mac OS X called Doxygen-1.5.6.dmg. Installation is very simple, just drag the doxygen icon from this folder to the Applications folder, or wherever you want to keep it; as shown below. I dropped it within my Applications folder. Just be sure to remember where you dragged it. To uninstall, just delete the file. It is completely self-contained.
Step 2: Configure Doxygen.
To generate documentation using Doxygen, you will need a configuration file called the Doxyfile. You can generate this file in two ways; either by using the Doxygen wizard or by using the command line option. Lets see how to use both these options to generate the configuration file:
a. Command line.
Open a command window and type the following as shown below:
You should be able to locate the configuration file created within your default user folder. The file looks like this:
# Doxyfile 1.5.6
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project
#
# All text after a hash (#) is considered a comment and will be ignored
# The format is:
# TAG = value [value, …]
# For lists items can also be appended using:
# TAG += value [value, …]
# Values that contain spaces should be placed between quotes (” “)#—————————————————————————
# Project related configuration options
#—————————————————————————# This tag specifies the encoding used for all characters in the config file
# that follow. The default is UTF-8 which is also the encoding used for all
# text before the first occurrence of this tag. Doxygen uses libiconv (or the
# iconv built into libc) for the transcoding. See
# http://www.gnu.org/software/libiconv for the list of possible encodings.DOXYFILE_ENCODING = UTF-8
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.PROJECT_NAME =
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
# if some version control system is used.PROJECT_NUMBER =
b. Wizard Option.
Launch the Doxygen application, and you should be able to create the configuration file using the wizard approach as shown below.
The user interface is quite intuitive so I am going to skip explaining this in detail.
The wizard approach was the one I used to get the initial settings for the configuration file, which you can always modify later.
A few options in my Doxygen configuration file are as follows:
# Doxyfile 1.5.6
#—————————————————————————
# Project related configuration options
#—————————————————————————
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = PetStore
PROJECT_NUMBER = 1.0
#—————————————————————————
# Build related configuration options
#—————————————————————————
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = NO
EXTRACT_LOCAL_CLASSES = YES
#—————————————————————————
# configuration options related to the HTML output
#—————————————————————————
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
GENERATE_TREEVIEW = YES
Step 3. Doxygen and Ant.
In order to use Doxygen, we need an Ant task. There is already an Ant task written for Doxygen which you can download from here.
As always, since using Mac, when I downloaded the binaries and tried to use them, I got the ever famous error message :
java.lang.UnsupportedClassVersionError: Bad version number in .class file
So, had to do download the source, compile, and jar it up. Copy this library to your projects folder. So, lets start making changes to our build file.
3.a: Lets define the Doxygen task:
<taskdef name="doxygen" classname="org.doxygen.tools.DoxygenTask" classpath="lib/ant_doxygen.jar" />
3.b: To generate HTML documentation:
<target name="generate-doxygen-docs">
<taskdef name="doxygen" classname="org.doxygen.tools.DoxygenTask"
classpath="lib/ant_doxygen.jar" />
<doxygen configFilename="reports/Doxyfile">
<property name="INPUT" value="${srcdir}" />
<property name="RECURSIVE" value="yes" />
</doxygen>
</target>
3.c: Lets combine them in a target and run the same:
[doxygen] Exec: /Applications/Doxygen.app reports/Doxyfile
BUILD FAILED
/CodeMetricsProject/build.xml:91: Doxygen not found on the PATH.Total time: 7 seconds
3.d: So, to launch Doxygen not in the path, we make changes to the doxygen task as shown below:
<doxygen doxygenPath="/Applications/Doxygen.app/Contents/Resources/doxygen" configFilename="reports/Doxyfile">
Lets run the target again and see if it fixed things. Yes indeed.
generate-doxygen-docs:
[doxygen] Exec: /Applications/Doxygen.app/Contents/Resources/doxygen reports/DoxyfileBUILD SUCCESSFUL
Total time: 8 seconds
4. Integrate with Hudson.
4.a Hudson Job and Ant Target.
Once you have an Ant target working, calling this from your CI server is trivial. Within Hudson, select your Job, click on configure and add this new target to be called when running the build.
4.b Publish the Reports.
4. c: Sample Reports.
Force a build, and take a detailed look at the reports generated by Doxygen as shown below:
I have given you a brief overview of Doxygen in this article, how to configure the same, and use it effectively to generate technical documentation on a continuous basis; either on commit builds or nightly builds. The Doxygen web site has lots of information on how to use it with other programming languages and also has tutorials in languages other than English as well.
As always, if you are having trouble getting Doxygen to work, leave a comment or check out the Doxygen web site.