Java annotations in a Web 2.0 world

Tue, 05 Sep 2006 20:29:00 GMT

Question : What do you get if you cross Java 5 annotations with Web 2.0?

Answer : Something like this - a tag cloud based upon annotations and their use within a codebase.

I didn't talk about annotations in my previous blog entry and the reason for this is that I'm not really a heavy user of them. A few @Override annotations here and there (courtesy of Eclipse), a couple of Spring @Transactional annotations and that's pretty much it. I've often thought about using annotations more (see Requirements coverage, for example) but the spark and necessity have never been there. However, now that I'm doing more Java 5 development and starting to use annotations, I've started thinking about other ways in which they could be used.

For me, the interest comes in trying to enrich a codebase with metadata that describes something more about the code than you can get from comments or the code itself. Or failing that, metadata that provides an easier way to find what you're looking for. For example, wouldn't it be great to see which code was considered to be "framework code"? What about making it easy to find those few really good examples of Oracle BLOB handling rather than saying, "they're somewhere in the DAO layer"? What about tagging up classes and methods with a keyword summarising their functional purpose. You've probably come across the Java Almanac during your travels - it's basically a whole bunch of useful code snippets that demonstrate how to use the various Java APIs. Now, imagine something like this across your own code. You probably have countless examples of APIs, techniques for doing things, implementations of patterns, gotchas and so on. Imagine attaching metadata to your source code by tagging it up, del.icio.us style.

@Keywords({"oracleblobhandling", "frameworkcode"})
@Keywords({"interestratecalculation", "businesslogic"})
@Pattern("factory")

Now, imagine for a moment that you've tagged up your source code and put effort into enriching the metadata associated with it. Something like the tag cloud shown above gives you an immediate view on which annotations you've used, how often they're used and so on. The screenshot above is a basic tag cloud that shows the annotations used within a codebase, the size of each showing the relative frequency with which each annotation is used. Click on an annotation and you can get more information about exactly where the annotation is used.

Just out of curiosity, I built a tag cloud from the Java 5 source code. Only 440 uses of @Deprecated. ;-)

Taking this concept further, you can get access to the actual values associated with annotation attributes, so it would be easy to build a tag cloud based upon only the values associated with an @Keywords annotation, for example. Effectively, you can filter and group on whatever level of annotation information you want to because it's all available via a set of APIs.

I've only just started playing with this so it'll be interesting to see how it pans out. Having attempted to generate tag clouds from a number of projects, I'll say the following. (1) Not many projects are using annotations (hence the small tag clouds!) and (2) the annotation processing APIs are a little verbose and sometimes unstable.

I'll save the technical details for another day, but essentially I've taken the tag cloud code out of Pebble and dropped it into an Annotation Processor, which gets executed through the Annotation Processing Tool (apt), via the apt Ant task that's included with Ant 1.7 beta 1.

What do you think? Would you find this a useful addition to your development environment?

Requirements coverage

Wed, 05 Oct 2005 14:17:15 GMT

Via TheServerSide.com, I just read an article called Requirement Coverage - Another dimension to Unit Testing. Essentially, it talks about a way to map requirements onto your unit tests and then use those unit tests to help you determine that you actually have coverage of the requirements. This is done through a tool called JRequire.

Now I've not used the tool, but I have been thinking about something similar for a little while. Well, kind of. I mean, the thought of mapping my requirements to my unit tests (even if they are really acceptance tests) doesn't enthrall me. On a large project in the past, we had a fairly large spreadsheet that mapped flows from use cases onto high level operations on service interfaces. I must admit that I left the project before any real development started so I don't know if this approach was eventually taken down to the code level. If it was, I don't even want to think about how complex this would have become.

Anyway, I think that there's a simpler way to do this. If you take most [ requirements | use cases | stories ], you can typically map these back to a single entry point in the application. I'm thinking of things like an action in a web MVC architecture, a listener in a desktop application or even an operation on a service. Assuming a Java implementation, what if you were to use an annotation to highlight the fact that these points of entry represent a requirement or a particular flow through a use case? Depending on how your requirements are coded, you could also annotate methods that implement exceptional flows if desired.

How about something like...

@Requirement(id=1,name="Get account balance")
public String execute(HttpServletRequest request,
  HttpServletResponse response) {
  ...
}

I need to think about this some more but there are some obvious benefits.

Searching for the code that implements a certain requirement is easy because you can just search for the annotation.
The annotations could be used at runtime to produce stats about how frequently features implemented from requirements are actually used, perhaps by reflecting on the annotations or by code injection.
The above technique could also be used to get coverage information on requirements during acceptance test runs, ensuring that your acceptance tests do test all requirements.

I think there's something here and the lack of traceability between requirements and code is certainly a gap in most projects. Any thoughts? How do you map requirements to code?

Simon Brown - annotations tag

Java annotations in a Web 2.0 world

Requirements coverage