Monday, April 14, 2014

Autodoc reaches 1.0.0 !

I recently dedicated some work in polishing Autodoc for a shiny 1.0.0 release!
It now has everything I wanted and some bonus features I found useful while using the tool on my projects.

Report is easier to read

In case you use more than one input plugin at a time (for example both JPA and VALIDATION), the screen could get a bit crowded and maybe you just want to check one of the two sets, not both.
A simple selector comes in handy, which dinamically hides unneded output:

No more obscure errors from Maven for Eclipse

I love Eclipse and Maven and I appreciated the fact that Maven for Eclipse has had so much improvement in the latest years, but there is something about it that I simply hate:

Maven Project Build Lifecycle Mapping Problem

I understand that m2e can't possibly manage all existing maven plugins out there and mine is no exception, but why the defaul beahviour is to give an error? When a colleague adds Autodoc plugin to his/her build, he/she promptly complains about the error, wrongfully thinking it's my plugin's fault... Autodoc may have its faults, but definitely this one is not on it!
Starting from version 1.0.0 I fixed this on autodoc's side, waiting for m2e to fix this.

A guide on how to write custom plugins

Finally! This was in the works since forever but it's there at last!
It's very easy to create a custom plugin for Autodoc, the validation plugin is an example created in a very little time; please let me know if you create one you think it's worth sharing, I will be glad to hear!

Autodoc 1.0.0 is on Maven Central as usual, enjoy!

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:
<inputPlugins>
<!-- short name of needed plugin; JPA plugin is for JPA2 annotations -->
<param>JPA2</param>
</inputPlugins>
<outputPlugins>
<!-- output plugin are supposed to write to files; for example, this is the html output plugin -->
<param>HTML,customConfig.properties</param>
</outputPlugins>

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()
.getContextClassLoader());
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.
Almost...

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 http://maven.apache.org/download.cgi ; 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!

Monday, July 1, 2013

ZK: How to close Bandbox using MVVM pattern

Zk is a great framework, but its documentation doesn't always provide good examples when it comes to MVVM; Bandbox examples in particular only refer to MVC.
Since I am using MVVM I had to find my own solution.

Binder to the rescue

The idea is to have the bandbox open state in the VM and to provide command handlers to change the property. Here's a groovy example:

class MyViewModel {
...
boolean bandBoxOpen = false
....
@NotifyChange('bandBoxOpen')
@Command
def onOpenBandBox() {
bandBoxOpen = true
}
@NotifyChange('bandBoxOpen')
@Command
def onCloseBandBox() {
bandBoxOpen = false
}
}

Then it's just a matter of wiring up the right event and value (in the .zul file):

<bandbox onOpen="@command('onOpenBandBox')"  open="@bind(vm.bandBoxOpen)">
...
</bandbox>

The onClose command could be fired, for example, on the double click of a list item:

<listitem onDoubleClick="@command('onCloseBandBox')">... 

P.S.: I would be more than happy to donate this solution to improve ZK documentation