January 27, 2021
Hot Topics:

Make Your Code Work for You with Java Annotations

  • By David Thurmond
  • Send Email »
  • More Articles »

Annotations are a familiar sight to any Java developer who has ever read the Java API docs. They are the text snippets preceded by an @ sign that have been appearing in JavaDoc comments since Java was introduced. They may seem like simple snippets of extra information, but there is much more to annotations than meets the eye. Here, you will learn how to use annotations at coding time, compile time, and run time to make the most of your development efforts.

What Are Annotations?

An annotation is a snippet of text in a JavaDoc comment that provides a little extra information. For example, listing 1 shows a method that is discouraged from continued use as indicated by the @Deprecated annotation.

Listing 1: A sample annotation in code

 * @Deprecated
 * This method does something that was super duper ten years ago.
public void doSomething() {
}    // doSomething()

When Javadocs are generated for this method, it is flagged as deprecated, and will appear in the Deprecated section of your generated API docs. Also, at compile time, you will receive a warning that you are using a method that is no longer recommended for use.

Although this useful functionality has been around for many years, the real power of annotations was unleashed in JDK 1.5 when the annotations API was made available to developers. For the first time, developers could write their own annotations. This made it possible for developers to create their own home-grown annotations, opening the way for the creation of powerful development tools.

One such tool is the ubiquitous JUnit testing framework. JUnit version 4.5 takes advantage of its own set of annotations to allow developers to set up, execute, and tear down test cases simply by placing annotations within their code. For details on JUnit 4.5 and how annotations are used to perform automated unit testing, see my article, "Test Cases Made Easy with JUnit 4.5."

Next, I will discuss how to create your own annotations, and how to use them at coding time, compile time, and run time to create your own development tools.

Creating an Annotation

First things first; before you can create any powerful new development tools, you will need to create annotations to use in your code. Listing 2 shows the simplest annotation you can create. This annotation, @ExecTime, is referred to as a tagging annotation, because it does not allow any parameters to be specified as part of the annotation.

Listing 2: ExecTime.java

package com.dlt.developer.annotation;

import java.lang.annotation.*;

public @interface ExecTime {
}    // interface ExecTime

This code is just an interface with no business logic built into it. The interface has no methods; this indicates that the annotation will not accept any parameters, similar to the @Deprecated annotation shown earlier.

The @interface annotation in this code indicates that the interface is itself to be an annotation. It is necessary for the java.lang.annotation package to be imported before the @interface annotation and the other annotations shown here can be used without generating compile-time errors.

The next interesting thing to note about the ExecTime annotation in Listing 2 is this line:


This line indicates that the @ExecTime annotation is to be compiled into the class files and should be made available to the Java VM at run time. This makes it possible for development tools to look for the @ExecTime annotation through reflection at run time and to perform a specific task because the annotation was present in the code.

The other possible values for the @Retention annotation are RetentionPolicy.SOURCE and RetentionPolicy.CLASS.

  • The RetentionPolicy.SOURCE constant indicates that the annotation should be discarded by the compiler, and is usable by any development tools at coding time only.
  • The RetentionPolicy.CLASS constant indicates that the annotation is useful to the compiler, and should be retained in the .class file for use by the compiler at compile time. The@SuppressWarnings and @Overrides annotations are examples of compile-time annotations. These annotations tell the compiler to behave differently based on the presence of these annotations within the source code. For example, if a method is tagged with the @Overrides annotation, the compiler will generate an error if the method signature doesn't match the overridden method's signature.

Unless you are writing your own Java compiler, it is not possible to create your own useful compile-time annotations. New compile-time annotations would instead be introduced to support new language features or enhancements to the Java compiler.

The other noteworthy part of ExecTime.java is the line:


This line indicates that the annotation should appear only on a method declaration. Placing the @ExecTime annotation on a class declaration or constructor, for example, would generate a compiler error. It is possible to specify that an annotation may appear on one or more elements within a Java program, including on constructors, fields, local variables, method declarations, package declarations, parameter declarations; and class, interface, or enumeration declarations.

The ExecTime.java program demonstrates the basics of creating an annotation. Listing 3 shows the code for a more complex annotation, @Help, which accepts parameters.

Listing 3: Help.java

package com.dlt.developer.annotation;

import java.lang.annotation.*;

public @interface Help {
   int contextID();
   String topic();
   String text();
}    // interface Help

Page 1 of 4

This article was originally published on December 15, 2008

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date