Skip to Content

Annotations: First Approach


In his former weblog Reflections on Java One, Marc Andrue Goodner also had the idea of writing about Annotations. When writing down some thoughts on this subject, I noticed that one COULD publish a book about the concern. So, I decided to cut it short at first and offer you some of my suggestions how an article or weblog (I still cannot distinguish clearly, also because I don’t know how to dedicately search for or post an article) about annotations could be structured resp. which content could be interesting.

The Big Picture

The term “Annotation” appears in several contexts. Proofreaders annotate drafts, teachers annotate work of any kind including pictures and people coping with software annotate source code or other technical “objects”. The latter activity obviously seems interesting for software development. There are several disjunctive definitions available on the web. In the next weblog I will absorb them. Here we want to concentrate on the conceptual design of the final weblog. What needs to be said is, that – from my point of view – an annotation adds semantic information to a piece of data being in the scope of the annotation. By adding semantics to data you hopefully are able to transform the annotated data into more meaningful information.

There is probably some confusion in the community what is mainly meant when speaking about annotations. Reason for this is that before introduction of JSR 175 there was no common sense about it. Since then, chances are better. The JSR 175 from Sun introduces a new concept for the Java programming language. Its title is Metadata Facility for the JavaTM Programming Language. Annotations as metadata must be interpreted – regarding JSR 175 – as well formed entities, this especially is important for refactoring source code. This is in contrast to probably most other conceptions, where an annotation could be virtually any informal text entered by a user.

Usage of Annotations

When searching at SDN, several SAP documents indicate which components support annotations. Besindes that annotations are integral part of other dedicated projects, like the Semantic Web with its Resource Description Framework (RDF).
SAP components being relevant with annotations include:

  • Enterprise Portal: Knowledge Managent & Collaboration (formal annotations)
  • Java Dictionary (informal)
  • SAP Document Management (informal)

In this context minor products like Adobe PDF offer the annotation feature as well, albeit in a different way than technically interesting.

Main focus of further considerations should be the JSR 175 introducing formal annotations for Java. The JSR suggests a tiny hierarchy consisting of annotation types and annotations depending on these annotation types.

Advantages and Disadvantages of Annotations

As pointed out, annotations allow to extract information from data. As they can be behaviour-conserving, they let you add metadata (resp. information) without modifying the original entity. So there will be no side-effects, except – of course – from interpreters executing the idea behind scanned in annotations. The benefits of annotations are used with the well-known mechanism XDoclet as well as with EJB3 to make life of the J2EE-developer more easy.

But: Annotations add a layer of indirection to a concept. Indirection itself is discussed controversely in the community, as its obvious benefits are complemented by the additional complexity they introduce. For instance, there is a weblog labelled The Annotation hell syndrom covering the topic.


These are my first thoughts on the case of annotations. I have some more information in backhand, but would like to have some comments on how to proceed best with this matter. One reason is that a weblog coping with all relevant information about annotations would be too lengthy. Therefor we could create a series, starting with basic information on annotations, going further with annotations in Java and then leading to the final part coping with common products and components using annotations. Again, it should be emphasized then what an annotation in the context of software development exactly is and what other types of annotations exist.

Be the first to leave a comment
You must be Logged on to comment or reply to a post.