Java Annotations

Java Annotations in Java

Annotation is code about the code, that is metadata about the program itself. In other words, organized data about the code, embedded within the code itself. It can be parsed by the compiler, annotation processing tools and can also be made available at run-time too.

We have basic java comments infrastructure using which we add information about the code / logic so that in future, another programmer or the same programmer can understand the code in a better way. Javadoc is an additional step over it, where we add information about the class, methods, variables in the source code. The way we need to add is organized using a syntax. Therefore, we can use a tool and parse those comments and prepare a javadoc document which can be distributed separately.

Javadoc facility gives option for understanding the code in an external way, instead of opening the code the javadoc document can be used separately. IDE benefits using this javadoc as it is able to render information about the code as we develop.

Annotation Types

Documented

When a annotation type is annotated with @Documented then wherever this annotation is used those elements should be documented using Javadoc tool.

Inherited

This meta annotation denotes that the annotation type can be inherited from super class. When a class is annotated with annotation of type that is annotated with Inherited, then its super class will be queried till a matching annotation is found.

Retention

This meta annotation denotes the level till which this annotation will be carried. When an annotation type is annotated with meta annotation Retention, RetentionPolicy has three possible values:

@Retention(RetentionPolicy.RUNTIME)
public @interface Developer {
	String value();
}

Class When the annotation value is given as ‘class’ then this annotation will be compiled and included in the class file.

Runtime The value name itself says, when the retention value is ‘Runtime’ this annotation will be available in JVM at runtime. We can write custom code using reflection package and parse the annotation. I have give an example below.

Source This annotation will be removed at compile time and will not be available at compiled class.

Target

This meta annotation says that this annotation type is applicable for only the element (ElementType) listed. Possible values for ElementType are, CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE.

@Target(ElementType.FIELD)
public @interface FieldInfo { }

Creating Your Own Annotations

It is possible to create your own (custom) Java annotations. Annotations are defined in their own file, just like a Java class or interface. Here is custom Java annotation example:

@interface MyAnnotation {
    String   value();
    String   name();
    int      age();
    String[] newNames();
}

This example defines an annotation called MyAnnotation which has four elements. Notice the @interfacekeyword. This signals to the Java compiler that this is a Java annotation definition.

Notice that each element is defined similarly to a method definition in an interface. It has a data type and a name. You can use all primitive data types as element data types. You can also use arrays as data type. You cannot use complex objects as data type. To use the above annotation, you could use code like this:

@MyAnnotation(
    value="123",
    name="Jakob",
    age=37,
    newNames={"Jenkov", "Peterson"}
)
public class MyClass {
}

As you can see, I have to specify values for all elements of the MyAnnotation annotation.

Element Default Values

You can specify default values for an element. That way the element becomes optional and can be left out. Here is an example of how the annotation definition looks with a default value for an element:

@interface MyAnnotation {
    String   value() default "";
    String   name();
    int      age();
    String[] newNames();
}

The value element can now be left out when using the annotation. If you leave it out, it will be considered as if you had used the default value for the value element. Here is an example of an annotation with an element value left out, so that element is set to the default value:

@MyAnnotation(
    name="Jakob",
    age=37,
    newNames={"Jenkov", "Peterson"}
)
public class MyClass {
}

Notice that the value element is no longer present.

@Retention

You can specify for your custom annotation if it should be available at runtime, for inspection via reflection. You do so by annotating your annotation definition with the @Retention annotation. Here is how that is done:

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String   value() default "";
}

Notice the @Retention annotation added above the MyAnnotation definition:

@Retention(RetentionPolicy.RUNTIME)

The RetentionPolicy class contains two more values you can use:

RetentionPolicy.CLASS means that the annotation is stored in the .class file, but not available at runtime. This is the default retention policy, if you do not specify any retention policy at all.

RetentionPolicy.SOURCE means that the annotation is only available in the source code, and not in the .class files and not a runtime. If you create your own annotations for use with build tools that scan the code, you can use this retention policy. That way the .class files are not polluted unnecessarily.

@Target

You can specify which Java elements your custom annotation can be used to annotate. You do so by annotating your annotation definition with the @Target annotation. Here is a @Target Java annotation example:

import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
@Target({ElementType.METHOD})
public @interface MyAnnotation {
    String   value();
}

This example shows a Java annotation that can only be used to annotate methods.

The ElementType class contains the following possible targets:

• ElementType.ANNOTATION_TYPE
• ElementType.CONSTRUCTOR
• ElementType.FIELD
• ElementType.LOCAL_VARIABLE
• ElementType.METHOD
• ElementType.PACKAGE
• ElementType.PARAMETER
• ElementType.TYPE

Most of these are self explaining, but a few are not. Therefore I will explain the targets which are not obvious.

The ANNOTATION_TYPE target means Java annotation definitions. Thus, the annotation can only be used to annotate other annotations. Like the @Target and @Retention annotations.

The TYPE target means any type. A type is either a class, interface, enum or annotation.

@Inherited

The @Inherited annotation signals that a custom Java annotation used in a class should be inherited by subclasses inheriting from that class. Here is an @Inherited Java annotation example:

java.lang.annotation.Inherited
@Inherited
public @interface MyAnnotation {
}
@MyAnnotation
public class MySuperClass { ... }
public class MySubClass extends MySuperClass { ... }

In this example the class MySubClass inherits the annotation @MyAnnotation because MySubClass inherits from MySuperClass, and MySuperClass has a @MyAnnotation annotation.

@Documented

The @Documented annotation is used to signal to the JavaDoc tool that your custom annotation should be visible in the JavaDoc for classes using your custom annotation. Here is a @Documented Java annotation example:

import java.lang.annotation.Documented;
@Documented
public @interface MyAnnotation {
}
@MyAnnotation
public class MySuperClass { ... }

When generating JavaDoc for the MySuperClass class, the @MyAnnotation is now included in the JavaDoc.

You will not use the @Documented annotation often, but now you know it exists, if you should need it.

Built-in Java Annotations

Java comes with three built-in annotations which are used to give the Java compiler instructions. These annotations are:

• @Deprecated
• @Override
• @SuppressWarnings

Each of these annotations are explained in the following sections.

@Deprecated

The @Deprecated annotation is used to mark a class, method or field as deprecated, meaning it should no longer be used. If your code uses deprecated classes, methods or fields, the compiler will give you a warning. Here is @Deprecated Java annotation example:

@Deprecated
public class MyComponent {
}

The use of the @Deprecated Java annotation above the class declaration marks the class as deprecated.

You can also use the @Deprecated annotation above method and field declarations, to mark the method or field as deprecated.

When you use the @Deprecated annotation, it is a good idea to also use the corresponding @deprecatedJavaDoc symbol, and explain why the class, method or field is deprecated, and what the programmer should use instead. For instance:

@Deprecated
/**
  @deprecated Use MyNewComponent instead.
*/
public class MyComponent {
}

@Override

The @Override Java annotation is used above methods that override methods in a superclass. If the method does not match a method in the superclass, the compiler will give you an error.

The @Override annotation is not necessary in order to override a method in a superclass. It is a good idea to use it still, though. In case someone changed the name of the overridden method in the superclass, your subclass method would no longer override it. Without the @Override annotation you would not find out. With the @Override annotation the compiler would tell you that the method in the subclass is not overriding any method in the superclass.

Here is an @Override Java annotation example:

public class MySuperClass {
    public void doTheThing() {
        System.out.println("Do the thing");
    }
}
public class MySubClass extends MySuperClass{

    @Override
    public void doTheThing() {
        System.out.println("Do it differently");
    }
}

In case the method doTheThing() in MySuperClass changes signature so that the same method in the subclass no longer overrides it, the compiler will generate an error.

@SuppressWarnings

The @SuppressWarnings annotation makes the compiler suppress warnings for a given method. For instance, if a method calls a deprecated method, or makes an insecure type cast, the compiler may generate a warning. You can suppress these warnings by annotating the method containing the code with the @SuppressWarnings annotation.

Here is a @SuppressWarnings Java annotation example:

@SuppressWarnings
public void methodWithWarning() {
}