Annotation is a new Java language feature introduced in JDK 5.0. It has quickly become one of the most popular, and yet most controversial, language feature in core Java. New Java frameworks, such as EJB 3.0 and Hibernate 3.0, make extensive use of annotations to eliminate the excessive XML configuration files (a.k.a. the "XML hell" in Java EE). Those annotations significantly reduce the amount of code and configuration data, and simplify the overall architecture, making application development easier. At the same time, enterprise architecture purists are complaining that annotations corrupt the separation between code and configuration, reduce the overall level of abstraction, and create more coupling between code and external frameworks. They argue that annotations should not be used to specify relationships between application components. Who is right? My view is that both arguments have merits. But as a developer, you really should make decisions based on the project at hand.

To understand which projects would benefit from annotation frameworks, we have to know a little bit of history on how annotations were introduced and evolved in the Java language. From the beginning, Java was a pure pro-gramming language to specify the behavior of the system. However, the whole idea of Java EE is to use "containers" to deliver reusable services (e.g., transaction, persistence, security, network connection, etc.) to Java objects. You have to somehow specify the relationships and dependencies between Java objects and container services. One approach is to use API calls directly in your Java components to consume container services. Java servlets and JNDI clients are such examples. However, too many framework APIs inside a Java class make the code very difficult to read and maintain (i.e., lots of boilerplate code). So, XML configuration files are widely used to specify the relationship between objects and services. This declarative approach allows you to configure the objects from the outside instead of cluttering up the business logic code with framework API calls. In fact, a large part of the Java EE specification is to standardize those XML files. Newer frameworks such as Spring even adopt an approach to put all configuration information in XML files, so that the Java business objects have zero dependency on the external frameworks (Dependency Injection via XML files). That is, you can apply services from any container to the same Java objects by just changing the XML files. This level of abstraction is great from an architecture point of view. However, it also creates huge complexity for developers and results in something known as the "XML hell."

Using XML to configure Java code has several distinct disadvantages: since XML files are processed separately from the code, they have to duplicate information already contained in the code (e.g., class names and method names, the inheritance structure, etc.) in order to configure the code. The duplication makes XML verbose even for the simplest configuration. Such XML files are also error-prone since spelling errors are not checked by the compiler or even the deployer. At the end of the day, XML configuration files simply shift the maintenance complexity and boilerplate code from Java classes to XML files. Developers are searching for better solutions.

A popular solution that emerged from the open source community is XDoclet. It uses embedded tags in Javadoc comments to specify which container services should be applied to this class or method. Then, a Javadoc-like preprocessor takes in the source code and generates all the necessary XML files based on the relationship. Since the XML configuration files are automatically generated, it's guaranteed to be correct and consistent. The developer only needs to maintain the XDoclet tags that are inside the source code file but don't clutter up the code like boilerplate code used to. The popularity of XDoclet is telling. It indicates that a large number of developers would prefer ease-of-development over added abstraction.

To capitalize on the success of XDoclet, Sun decided to introduce annotations as a formal language feature in Java. Instead of being a second class citizen embedded in code comments, annotations are now fully supported by the compiler, IDE tools, and are standardized into APIs. Using annotations, you can specify how container services are delivered to Java objects. For instance, the following example is an EJB 3.0 entity bean. The @Entity annotation tells the container that this class should be mapped to a database table. The @Id(generate=AUTO) annotation tells the container to automatically generate the primary ID value when the object is saved into the database.

@Entity
public class Reply implements Serializable {

private long id;
private String name;

@Id(generate=AUTO)
public long getId() {
   return id;
}

public String getName() {
   return name;
}
public void setName(String name) {
   this.name = name;
}
}

To use the entity bean, the @PersistenceContext annotation tells the container to inject a valid EntityManager object to the Manager-Action object. The @Transaction-Attribute annotation declares that the reserve() method is managed by the container's transaction manager, which commits changes to the database at the end of the current thread.

@Stateless
public class ManagerAction implements Manager {
private Reply reply;

@PersistenceContext
private EntityManager em;

@TransactionAttribute(TransactionAttributeType.REQUIRED)
public void reserve () {
em.persist (reply);
}
}

In addition, you can also use annotations to manage relationships between your own objects. The following example uses annotations in the JBoss SEAM Web framework. The @In annotation below injects the reply object from the Web context, which is probably mapped to fields in a JSF form requesting a user reply. This way, when the user changes the reply object from a JSF form, it is automatically validated and propagated to the ManagerAction object. Likewise, the @Out annotation outjects the allReplies variable updated in the reserve() method to the context so that all the replies can be displayed in a table on a JSF Web page.

public class ManagerAction implements Manager {

@In
private Reply reply;

@PersistenceContext
private EntityManager em;

@Out
private List <Reply> allReplies;

public String reserve () {
em.persist (reply);
allReplies = em.createQuery("from Reply r").getResultList();
return null;
}
}

Those annotations eliminate boilerplate code in both Java and XML code. The annotated code is very easy to understand. However, annotations also have a few downsides. Annotation is not as expressive as XML and it's only weakly validated at compile time. For instance, you could mistakenly place the @PersistenceContext annotation on the reply variable and the compiler would not complain. The application only fails when it deploys. In addition, perhaps the biggest argument against annotations is that they mix configuration with the Java code, and hence tie your Java objects to the particular service framework that defines the annotations (EJB 3.0 or JBoss SEAM in our examples). If you want to switch to another framework later, you'd have to go into the Java class code and change the annotations. In contrast, XML-configured Java objects (e.g., Spring POJOs) can work with any service framework without changes to the Java class - you only need to change the XML files - due to the clean separation between code and configuration. Of course, the XML approach only has an advantage when you have far more Java code than XML code, which is not the case for most business applications today.

What is the verdict? If your objects have very complex relationships or if "framework independent" business logic is essential to you, you could be better off choosing an XML-based configuration framework such as Spring or JBoss Micro-container. However, if you deal with medium-complex systems and are concerned about productivity over abstraction, annotations are perfect. The standardization of annotations in specifications like EJB 3.0 will eventually make many annotations part of the Java core API. Framework independence is less of an issue in a world with standardized frameworks. We will use annotations just as we make API calls to JDK libraries today. That is, of course, the intention Sun had when it introduced annotations into the Java language.