January 23, 2021
Hot Topics:

An Introduction to Java Annotations

  • By M. M. Islam Chisty
  • Send Email »
  • More Articles »

The Retention Annotation

The retention annotation indicates where and how long annotations with this type are to be retained. There are three values:

  • RetentionPolicy.SOURCE—Annotations with this type will be by retained only at the source level and will be ignored by the compiler
  • RetentionPolicy.CLASS—Annotations with this type will be by retained by the compiler at compile time, but will be ignored by the VM
  • RetentionPolicy.RUNTIME—Annotations with this type will be retained by the VM so they can be read only at run-time

Example 5 shows you the RetentionPolicy.RUNTIME value in action:

Java Annotation Example 5

public @interface Test_Retention {
String doTestRetention();

In this example, the @Retention(RetentionPolicy.RUNTIME) annotation indicates that your Test_Retention annotation is to be retained by the VM so that it can be read reflectively at run-time.

The Documented Annotation

The documented annotation indicates that an annotation with this type should be documented by the javadoc tool. By default, annotations are not included in javadoc. But if @Documented is used, it then will be processed by javadoc-like tools and the annotation type information will also be included in the generated document. Example 6 demonstrates using @Documented further:

Java Annotation Example 6

public @interface Test_Documented {
String doTestDocument();

Next, update your TestAnnotations class as follows:

public class TestAnnotations {
public static void main(String arg[]) {
new TestAnnotations().doSomeTestRetention();
new TestAnnotations().doSomeTestDocumented();
@Test_Retention (doTestRetention="Hello retention test")
public void doSomeTestRetention() {
System.out.printf("Testing annotation 'Retention'");
@Test_Documented(doTestDocument="Hello document")
public void doSomeTestDocumented() {
System.out.printf("Testing annotation 'Documented'");

Now, if you run the javadoc command and view the generated TestAnnotations.html file, you will see something like Figure 1.

Figure 1

As you can see from the screenshot, there is no annotation-type information for the doSomeTestRetention() method. But, this description is provided for the doSomeTestDocumented() method. This is because of the @Documented tag attached with your Test_Documented annotation. Your earlier annotation Test_Retention did not include this tag.

The Inherited Annotation

This is a bit of a complex annotation type. It indicates that the annotated class with this type is automatically inherited. More specifically, if you define an annotation with the @Inherited tag, then annotate a class with your annotation, and finally extend the class in a subclass, all properties of the parent class will be inherited into its subclass. With Example 7, you will get an idea about the benefits of using the @Inherited tag.

Java Annotation Example 7

First, define your annotation:

public @interface myParentObject {
boolean isInherited() default true;
String doSomething() default "Do what?";

Next, annotate a class with your annotation:

public Class myChildObject {

As you can see, you do not have to define the interface methods inside the implementing class. These are automatically inherited because of using the @Inherited tag. What would happen if you define the implementing class in old-fashioned Java-style? Take a look at this—defining the implementation class in an old-style-java way:

public class myChildObject implements myParentObject {
public boolean isInherited() {
return false;
public String doSomething() {
return "";
public boolean equals(Object obj) {
return false;
public int hashCode() {
return 0;
public String toString() {
return "";
public Class annotationType() {
return null;

Do you see the difference? You can see that you will have to implement all the methods that the parent interface owns. Besides the isInherited() and doSomething() methods from myParentObject, you will have to implement the equals(), toString(), and hasCode() methods of java.lang.Object and also the annotationType() method of java.lang.annotation.Annotation class. It does not matter whether you want to implement these methods or not; you will have to include these in your inherited object.


This article has shown you how you can make your development easier through the use of JDK5's annotation feature. Annotations do not directly affect the semantics of a program. Development and deployment tools can read these annotations and process them in some fashion, perhaps producing additional Java programming language source files, XML documents, or other artifacts to be used in conjunction with the program containing the annotations. You now can do the same things as you would do before, but with less code and better compile-time error detection. The objective is to spend less time on unhandy code-writing and focus more on business logic rules. This article is Part I of a series on Java Annotations. In Part II, you will learn about how to use annotations to develop a simple Web application with a flat table. Lastly, in Part III you will see a complex example that includes multiple database tables relationships.

Java Annotation Resources

  1. New Features and Enhancements J2SE 5.0 at http://www.mathcs.carleton.edu/courses/course_resources/j2se-1.5.0-docs/relnotes/features.html
  2. J2SE 5.0 in a Nutshell at http://java.sun.com/developer/technicalArticles/releases/j2se15/
  3. Annotations in Tiger, Part 1: Add metadata to Java code at http://www-128.ibm.com/developerworks/java/library/j-annotate1/
  4. What's New in Java 1.5? at http://www.cs.indiana.edu/classes/jett/sstamm/
  5. Tiger in NetBeans4 at http://cropcrusher.web.infoseek.co.jp/shufujava/sunone/nb/nb4tiger_en.html
  6. Taming the tiger at http://www.denverjug.org/meetings/files/200408_Tiger.pdf

About the Author

M. M. Islam Chisty currently works as a Software Engineer for M&H Informatics. His responsibilities include development and re-engineering of Web-based applications using J2EE technologies. M. Chisty has a B.S. degree in computer science from North South University. He loves spending his free time doing R&D on latest Java based technologies, watching TV, and listening to music. And, he's a great WWE fan, too. You can contact M.Chisty at mchisty@gmail.com.

Page 3 of 3

This article was originally published on October 14, 2005

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