Mastering Java Annotations

What are Java Annotations?

Java annotations are special tags or markers you can add to your code to provide additional information (metadata) about your classes, methods, or fields. They don't affect how the code runs but can influence how the compiler or frameworks work with the code.

Where is it used?

Annotations are used in various places:

• At compile-time: To give instructions to the compiler (e.g., @Override to check if a method overrides a parent method).
• By development tools: Tools like IDEs can use annotations to highlight issues or offer suggestions.
• At runtime: Frameworks such as Spring and Hibernate use annotations to configure how your code should behave, like managing databases, dependency injection, or handling HTTP requests.

Why do we need Java Annotations?

• Improve readability: They make code easier to understand by clearly indicating behavior or intent.
• Enable compiler checks: The compiler can check for issues like overriding methods, or deprecating features.
• Reduce boilerplate code: Annotations help remove repetitive code, especially in frameworks like Spring and Hibernate. Instead of writing lengthy configuration code, you can simply annotate parts of your code.

Types of Annotations

Java annotations can be broadly categorized into three types:

Built-in Annotations:

Java provides several built-in annotations that are frequently used:

1. @Override

The @Override annotation ensures that a method is correctly overriding a method from its superclass. If the method does not match any method in the superclass, the compiler will generate an error.

package com.codeedx;
 
public class OverrideExample {
    public static void main(String[] args) {
 
    }
}
 
class Parent {
    void display() {
        System.out.println("Parent display");
    }
}
 
class Child extends Parent {
    @Override
    void display() {
        System.out.println("Child display");
    }
 
// This would cause a compile-time error because there is no `disp` method in the Parent class.
//     @Override
//     void disp() {
//         System.out.println("Child disp");
//     }
}
 

2. @Deprecated

The @Deprecated annotation marks a method, class, or field as deprecated. Using deprecated elements generates a warning during compilation, indicating that the element should not be used and may be removed in the future.

package com.codeedx;
 
class Example {
 
    @Deprecated
    void oldMethod() {
        System.out.println("This method is deprecated");
    }
 
    void newMethod() {
        System.out.println("Use this method instead");
    }
}
 
public class DeprecatedExample {
    public static void main(String[] args) {
        Example example = new Example();
        example.oldMethod();  // Compiler warning: The method oldMethod() from the type Example is deprecated
        example.newMethod();  // No warnings, recommended method
    }
}
 

3. @SuppressWarnings

The @SuppressWarnings annotation tells the compiler to ignore specific warnings for the annotated element. This is often used to suppress warnings about unchecked operations or deprecated methods.

package com.codeedx;
 
import java.util.ArrayList;
import java.util.List;
 
public class SuppressWarningsExample {
    @SuppressWarnings("unchecked")
    void uncheckedWarning() {
        List rawList = new ArrayList();  // Warning: unchecked conversion
        rawList.add("Hello");
        List<String> stringList = rawList;  // Suppressed warning
    }
 
    @SuppressWarnings("deprecation")
    void useDeprecatedMethod() {
        oldMethod();  // Suppressed warning for using a deprecated method
    }
 
    @Deprecated
    void oldMethod() {
        System.out.println("Deprecated method");
    }
}
 

4. @FunctionalInterface

The @FunctionalInterface annotation is used to ensure that an interface has exactly one abstract method, which is required for it to be a functional interface. This allows the interface to be used with lambda expressions and method references.

package com.codeedx;
 
@FunctionalInterface
interface MyFunctionalInterface {
    void doSomething();  // The single abstract method
 
    // Uncommenting the below line will cause a compile-time error
    // because a functional interface can only have one abstract method.
    // void anotherMethod();
}
 
class FunctionalInterfaceExample {
    public static void main(String[] args) {
        MyFunctionalInterface func = () -> System.out.println("Doing something");
        func.doSomething();
    }
}
 

5. @SafeVarargs

The @SafeVarargs annotation is used to suppress warnings for potentially unsafe operations on variable-length argument lists (varargs) when dealing with generics. This annotation can only be applied to methods or constructors that are final, static, or private.

package com.codeedx;
 
import java.util.List;
 
public class SafeVarargsExample {
 
    @SafeVarargs
    private final void printList(List<String>... lists) {
        for (List<String> list : lists) {
            System.out.println(list);
        }
    }
 
    public static void main(String[] args) {
        SafeVarargsExample example = new SafeVarargsExample();
        List<String> list1 = List.of("Apple", "Banana");
        List<String> list2 = List.of("Carrot", "Date");
 
        example.printList(list1, list2);  // No warnings, even though varargs are used with generics
    }
}
 

Meta-annotations:

Meta-annotations are annotations that can be applied to other annotations. Java provides several meta-annotations, including:

• @Target: Specifies the types of elements an annotation can be applied to (e.g., method, field, class). Possible options include:
  • ElementType.ANNOTATION_TYPE: Annotation type declarations.
  • ElementType.CONSTRUCTOR: Constructor declarations.
  • ElementType.FIELD: Field declarations (includes enum constants).
  • ElementType.LOCAL_VARIABLE: Local variable declarations.
  • ElementType.METHOD: Method declarations.
  • ElementType.PACKAGE: Package declarations.
  • ElementType.PARAMETER: Parameter declarations.
  • ElementType.TYPE: Class, interface (including annotation type), or enum declarations.
  • ElementType.TYPE_PARAMETER: Type parameter declarations (since Java 8).
  • ElementType.TYPE_USE: Use of a type (since Java 8).
• @Retention: Specifies how long annotations with the annotated type are to be retained. Possible options are:
  • RetentionPolicy.SOURCE: Annotations are retained only in the source code and are discarded during compilation.
  • RetentionPolicy.CLASS: Annotations are recorded in the class file by the compiler but are not retained at runtime. (Default behavior)
  • RetentionPolicy.RUNTIME: Annotations are recorded in the class file and are retained by the JVM at runtime, so they can be read reflectively.
• @Inherited: Indicates that an annotation type is automatically inherited. When a class is annotated with an annotation that is marked with @Inherited, its subclasses will automatically inherit the annotation.
• @Documented: Indicates that the annotation should be included in the Javadoc.
• @Repeatable: Allows the same annotation to be applied multiple times to a single element. This is particularly useful when you need to specify multiple instances of an annotation on the same target.

Custom Annotations:

Custom annotations are user-defined annotations tailored to specific use cases. These annotations allow you to define and apply metadata that suits your application needs.

How to Create Custom Annotations

Creating custom annotations in Java is straightforward. A custom annotation is defined using the @interface keyword, followed by defining its elements (which look like methods).

Here’s a step-by-step guide:

1. Define the Annotation: You start by using the @interface keyword. Below is an example of a custom annotation named @MyAnnotation:

   package com.codeedx.customannotation;
    
       import java.lang.annotation.ElementType;
       import java.lang.annotation.Retention;
       import java.lang.annotation.RetentionPolicy;
       import java.lang.annotation.Target;
    
       @Target(ElementType.METHOD) // This annotation can only be applied to methods
       @Retention(RetentionPolicy.RUNTIME) // The annotation will be available at runtime
       public @interface MyAnnotation {
           String value() default "default value"; // value element with a default value
           int count() default 1; // count element with a default value
       }
    

   In this example:

   • The @Target meta-annotation restricts the use of @MyAnnotation to methods.
   • The @Retention meta-annotation specifies that @MyAnnotation should be available at runtime, which is necessary if you want to process the annotation via reflection.
   • The annotation has two elements: value and count, both with default values.

2. Apply the Custom Annotation: Once you’ve defined your custom annotation, you can apply it to the appropriate elements of your code:

   package com.codeedx.customannotation;
    
       public class AnotherClass {
    
           @MyAnnotation(value = "Custom value", count = 5)
           public void customMethod() {
               System.out.println("Method with custom value invoked");
           }
    
           @MyAnnotation  // Using default values
           public void defaultMethod() {
               System.out.println("Method with default values invoked");
           }
       }
    
       ```

3. Invoke and Process Custom Annotations:

To make custom annotations useful, you often need to process them at runtime, which typically involves using Java Reflection. Here’s how you can invoke and process a custom annotation:

You can retrieve and process annotations using reflection by accessing the annotated elements (like methods or classes):

package com.codeedx.customannotation;
 
    import java.lang.reflect.Method;
 
    public class AnnotationProcessor {
        public static void main(String[] args) {
            Class<?> clazz = AnotherClass.class;
            for(Method method: clazz.getDeclaredMethods())
            {
                if(method.isAnnotationPresent(MyAnnotation.class))
                {
                    MyAnnotation annotation = method.getAnnotation(MyAnnotation.class);
                    System.out.println("Method: " + method.getName());
                    System.out.println("Value: " + annotation.value());
                    System.out.println("Count: " + annotation.count());
                }
            }
        }
    }
 

This code does the following:

• It uses reflection to iterate over all methods in MyClass.
• For each method, it checks if @MyAnnotation is present using method.isAnnotationPresent(MyAnnotation.class).
• If the annotation is present, it retrieves the annotation and prints its elements.

Coding Exercise

Problem Statement

Write a program where certain methods need to be executed multiple times based on an annotation. Create a custom annotation that allows specifying how many times a method should be invoked, and implement logic to automatically invoke the method the specified number of times using reflection.

Coding Exercise - Solution

• All Solutions are available on github (opens in a new tab).

Step 1: Create the MethodLimiter Annotation

package com.codeedx.customannotation;
 
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
 
// Define the custom annotation MethodLimiter with a maxlimit element
@Retention(RetentionPolicy.RUNTIME)
public @interface MethodLimiter {
    int maxlimit() default 1;  // Default limit is 1 if not specified
}
 

Step 2: Apply the Annotation on the execute() Method

package com.codeedx.customannotation;
 
public class AnotherClass {
 
    @MethodLimiter(maxlimit = 3)  // This method will be invoked 3 times
    public void execute() {
        System.out.println("Method executed");
    }
}
 

Step 3: Use the Annotation with Reflection

package com.codeedx.customannotation;
 
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
 
public class AnnotationProcessor {
    public static void main(String[] args) throws InvocationTargetException, IllegalAccessException {
        // Get the class object for AnotherClass
        Class<?> clazz = AnotherClass.class;
        AnotherClass anotherClassObj = new AnotherClass();
 
        // Iterate through all methods of AnotherClass
        for (Method method : clazz.getDeclaredMethods()) {
            // Check if the method is annotated with MethodLimiter
            if (method.isAnnotationPresent(MethodLimiter.class)) {
                // Get the MethodLimiter annotation
                MethodLimiter annotation = method.getAnnotation(MethodLimiter.class);
                System.out.println("Method: " + method.getName());
                System.out.println("Max limit: " + annotation.maxlimit());
 
                // Invoke the method based on the maxlimit value
                for (int i = 0; i < annotation.maxlimit(); i++) {
                    method.invoke(anotherClassObj);  // Invoke the method
                }
            }
        }
    }
}
 

Explanation

• The execute() method now has the @MethodLimiter(maxlimit = 3) annotation, which means it should be invoked 3 times.
• The AnnotationProcessor uses reflection to check if execute() is annotated with @MethodLimiter, and then it invokes the method 3 times based on the maxlimit value.

Output

When you run the AnnotationProcessor, the output will be:

Method: execute
Max limit: 3
Method executed
Method executed
Method executed

This example demonstrates the updated method execute() being invoked multiple times as controlled by the MethodLimiter annotation.

Conclusion

As you learn more about Java annotations, they’ll become an important tool for you. By understanding how to use them, it will make your code easier to read and maintain. You’ll also be able to write flexible code that can change based on the extra information you add with annotations. Mastering annotations will help you write better, cleaner code and make your development work easier and more efficient.