Tuesday, October 23, 2012

Introducing : Active Annotations

In this article I'd like to introduce you to a new important language feature for Xtend. Xtend is a statically-typed language which compiles down to readable Java source code.

Active Annotations in a Nutshell

Active Annotations allow for participating during the translation of Xtend code to Java source code. You basically declare an annotation and with it provide the processing instructions where you can
  • issue errors and warnings,
  • provide corresponding quickfixes,
  • apply all kind of changes and enhancements to the target Java classes,
  • introduce new Java types or
  • even update or create ordinary text files (e.g. web.xml).

To use such an annotation you just have to have it on your class path like any ordinary Java annotation.
You could for instance want to have an annotation called @Entity, which turns simple classes with fields into data classes tailored for your project-specific context. You'd define and maintain the definition of what an entity is right in your project and would version and distribute it just like any other API. The IDE will be fully aware of the processing changes. Not only will errors, warnings and quickfixes be available in the IDE but also the scopes, type computation and content assistance will behave according to your processing instructions.

General Use Cases

Let's have a look at some use cases. Xtend already comes with two annotations, whose processing for now is hard coded into the compiler. We did so, to gain some experience with the general idea and will of course replace the hard coded version with 100% library-based annotations in a future release.
One of these annotations is the @Property annotation, which translates a simple field into a Java-Bean property. That is given the following Xtend code
   // Xtend
   @Property String name
you'll get this Java code :
   // Java
   private String name;
   public String getName() {
      return this.name;
   public void setName(String name) {
      this.name = name;
The other annotation Xtend already has is @Data which translates a class with fields into a value object รก la domain-driven design, i.e. it creates an immutable class with a value-based equals and hashcode implementation and a nice toString implementation. We will likely support other generic use cases such as @Delegate, which generated delegate methods for an annotated field and @Builder which will automatically derive a builder API for a set of classes.

Framework-specific Use Cases

You might have seen pre-built annotations which do participate in the compilation project with other technologies. The real coolness about active annotations in Xtend is that everybody can develop their own project specific ones easily. If you want to change the behavior, just navigate to the annotation and do your changes. You will instantly see the result, since every referencing Xtend file will be re compiled on change. And it is fully transparent since everything is translated to readable Java source code!
With this simplicity to develop and deploy them people will be able to use them to remove tedious structural boilerplate in many Java APIs. We for instance built two active annotations for GWT. One for remote services, which automatically derives the required interfaces and adds the required super class. Another which automatically adds fields declared in a UI-Binder XML file. You can find some slides here and the source code is on github.


Today we have a working prototype, which you can play around with if you are brave enough. But there's no documentation and the API changes on a daily bases, so better wait a bit. We will release a beta version of this new feature with the next release (planned for December/January), but this will still lack some important features and the API will be subject to change.

I am very excited and think active annotations really solve a huge class of problems in a very nice way and am really curious with what kind of annotations people will come up in the future.

Alan Kay once said about Lisp that it is not a language but a building material. Active annotations bring the power of Lisp Macros to the statically typed Java world.