Friday, August 30, 2013

ZKGrails for Grails 2.3

I am working with a pre-release of Grails 2.3, based on ZkGrails plugin; so far we managed to make version 2.1.0 work with a few tricks.

Today could have been a great day

Since more than a month we have been waiting for the release of a Grails 2.3 version and we believed that the author was gonna release a version which at least could work with Grails 2.3, so that we could get rid of the tricks we were using to make it work.
That simply didn't happen, so I took the decision to fork it, to allow running it on newer Grails versions.

We can't guarantee that everything will work, but we have been using that version for weeks and found no critical issue; I hope this could be useful to someone else too.

The fork is distributed with LGPL3 license and you can find it at my github repository.

Wednesday, August 28, 2013

New version for Autodoc - big news!

I recently released Autodoc, an open source tool to generate documentation using annotations in java classes.

The first version was somewhat basic, a little more than a proof of concept; while fixing a few nasty bugs which came out testing the tools on more projects than I did at first, I also worked on producing a better output, having a simpler and more powerful configuration and reducing external dependencies.
The result is version 0.3.0.

A better output

I added a new index page which puts the various packages together:
The package page is now ordered in the same way as the left column and it displays field types and methods return types:

A simpler configuration

Plugins may now be identified by a short name, resulting in simpler and more readable configuration; output plugins now support configuration through a properties file:
<!-- short name of needed plugin; JPA plugin is for JPA2 annotations -->
<!-- output plugin are supposed to write to files; for example, this is the html output plugin -->

Reduced external dependencies

Since I moved to Guava, I had the chance to remove dependency on commons-io (and Reflections of course); I also configured freemarker to use slf4j logging, removing the need of log4j at runtime and moved commons-beanutils to test dependencies since it was needed only there.
This results in a smaller footprint; in the future the plugins may be moved to external projects, to further reduce the need of external dependencies (the core ones are just guava, commons-configuaration and slf4j).

Time to try it!

Just follow the instructions on Autodoc wiki and see for yourself if you find it useful; it will probably take no more than 10 minutes to add it to your exsisting maven build.
Don't be afraid to ask for assistance, I will do my best!

Friday, August 23, 2013

Java reflection libraries: Reflections vs Guava-reflection

Recently I have been working on my new open source tool: Autodoc .
A feature I needed for it to work was to get all classes in a given package, to analyze them one by one.
Searching for a solution I found out it's not a trivial task in Java, so I looked for a library to get the list I needed.

First try: Reflections

My first try was of course the very well known Reflections library; it's quite easy to use and well documented.
It worked like a charme for my test classes, but it failed miserably in the tests I did on some live projects...
The point is that Reflections will filter only classes with a specific annotation or direct subclasses of a given class! In my tool I couldn't put any constraint about common superclass or use of a specific annotation, so I had to find another library.

Saved by Guava-reflection

I looked further and found a library which seems perfect for my uses: Guava-reflection.
Guava is an impressive collection of useful utility methods and classes, and in particular the Classpath class seemed able to do the trick.
It seems simpler and less powerful than Reflections but it just lists all classes in a package and can do it recursively if needed; the code is very simple:
ClassPath classpath = ClassPath.from(Thread.currentThread()
for (ClassPath.ClassInfo classInfo : classpath
.getTopLevelClassesRecursive(packagetoParse)) {
// do whatever I need with class info

Final words

I think both libraries are very good, so I won't throw Reflections away, it could always come in handy later or on different projects. I think it's always better to have a look at both libraries before giving up and rolling out a new implementation (which will take much time and most probably won't be any better!)

Monday, August 19, 2013

Documenting annotated Java classes

I am a big fan of documentation, in particular if it can be produced automatically as a byproduct of metadata.

Introducing Autodoc

For this reason I created a small simple tool which takes JPA2 annotations and turns them into a synthetic HTML report:

I have just released a preview release, all details on how to use it are (or will soon be) on Autodoc Github page .
Currently the simplest way to use it is through its maven plugin and it only parses JPA2 annotation producing a HTML output.

Please let me know if you find it useful; I will add features based on users feedback.
Further planned improvements could be: more input plugins (javax.validation and JAX-RS seem very good candidates), support for source level annotations, more configuration options, more build tools integrations (I love ant and gradle!) and of course I hope to fix bugs as soon as possible!

And don't forget: Autodoc is free software distributed under the Apache License 2.0!

Wednesday, August 7, 2013

Build Java 5 project with Maven 3 on Ubuntu 13.04

Don't get me wrong, I love Ubuntu and I find it very good for development; almost everything I need is an "apt-get install" away.

Building legacy java 5 project with maven 3

First steps are easy, you install maven through apt-get, download java 5 from Oracle site and install it manually (there seem to be openjdk and cgj only packages).
Then you set your JAVA_HOME to point to your new installation and launch maven as usual
mvn clean install
 And that's what you get:
Exception in thread "main" java.lang.UnsupportedClassVersionError: Bad version number in .class file
All maven libs in the Ubuntu package are compiled for java 6...

Do it on your own

At this point you have to get apache's distribution ; say the file you downloaded is apache-maven-3.1.0-bin.tar.gz, the following command are supposed to be executed as root:
mkdir /usr/local/share/maven
cd /usr/local/share/maven
tar -xvzf <path_to>/apache-maven-3.1.0-bin.tar.gz
Then you have to point maven to work with the new installation (in a regular, non root, shell)
export M2_HOME=/usr/local/share/maven/apache-maven-3.1.0
And you're done!