Java Magazine, March/April 2016

ORACLE COM JAVAMAGAZINE MARCH APRIL 2016 35 inside java Annotations appeared on the Java platform for Java 5 more than ten years ago and they have become an integral part of the ecosystem In this article I go over a brief history of how and why annotations came about and then dive into technical details explaining how they operate how they are best used and how to write your own Origins The idea of adding metadata to source code is quite old and comes from the simple realization that very often the code you write doesnt contain all the information a tool needs to do its job On the Java platform an early form of annotations began to appear before Java 5 but because the language did not officially support them developers resorted to the unlikely Javadoc tool to add annotations to their code Specifically two tools brought annotations into the spotlight in the early 2000s EJBGen which enabled developers to add Javadoc annotations to their source code and which then generated the complicated EJB XML descriptors XDoclet which took EJBGens idea to the next level by providing a general framework for using Javadoc tags as annotations for any domain not just for EJBs These two tools became popular very quickly and opened the door for annotations to become officially supported by the JVM JSR 250 Common Annotations for the Java Platform was created specifically for this purpose and was scheduled to ship with Java 5 The idea was to make annotations type safe and extensible so that developers could easily write their own Its interesting to note that since 2004 there has been only one major update to annotations in the JDK JSR 308 which added more locations where annotations could be placed But thats pretty much it Today you are still using the same annotations as specified in 2005 with hardly any modifications JSR 308 added some minor utility that was discussed in the March April 2014 issue Its hard to deny that JSR 250 has been a stable success that enabled many innovations which Ill discuss shortly When to Use Annotations Like all tools annotations should be used judiciously They are a great match for a certain category of problems but a poor choice when key conditions are not met The main alternative to annotations is configuration files Such files can hold the metadata that your code cant contain just like annotations so how do you decide whether specific metadata should be stored in annotations or in an external file The general rule of thumb is If the metadata is tied to a Java element method field variable class package and so on then it should be placed in an annotation Otherwise it should be stored in a configuration file As I mentioned EJBs were the first target for annotations because their deployment descriptors were complicated XML files that referenced methods in the code and added extra information to them This approach was error prone because refactoring code such as renaming a method might not be reflected in the deployment descriptor and the application now fails to work Instead annotating the method that CÉDRIC BEUST Annotations An Inside Look How annotations work how best to use them and how to write your own