Creating and Using Annotations in Simple Java Projects with Examples

One common mistake beginners make is treating annotations as mere comments in code. They often forget that annotations are powerful metadata instructions that influence compilation, runtime behavior, and framework logic. Misunderstanding this leads to missed opportunities for cleaner, declarative programming.

In real-world projects, annotations are everywhere:

Spring uses @Autowired for dependency injection.
Hibernate maps entities with @Entity.
JUnit marks tests with @Test.

But before mastering frameworks, it’s crucial to understand how to create and use annotations in simple projects. Think of annotations as sticky notes for your code—instead of writing extra logic everywhere, you can mark your classes, methods, or fields with reusable metadata and let processors or reflection do the heavy lifting.

Defining a Simple Annotation

Annotations in Java are defined with the @interface keyword.

public @interface Todo {
    String value();
}

This defines a simple annotation @Todo with one element value.

Adding Meta-Annotations

To make annotations practical, you usually add meta-annotations like @Retention and @Target.

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface LogExecution {
    String message() default "Executing method";
}

@Retention(RUNTIME) makes the annotation available at runtime for reflection.
@Target(METHOD) restricts usage to methods only.

Using the Custom Annotation

public class Calculator {

    @LogExecution(message = "Running addition")
    public int add(int a, int b) {
        return a + b;
    }

    @LogExecution
    public int multiply(int a, int b) {
        return a * b;
    }
}

Here, methods are annotated with @LogExecution.

Processing the Annotation with Reflection

To make annotations functional, you use reflection to inspect and act upon them.

import java.lang.reflect.Method;

public class AnnotationProcessor {
    public static void main(String[] args) throws Exception {
        Calculator calculator = new Calculator();

        for (Method method : Calculator.class.getDeclaredMethods()) {
            if (method.isAnnotationPresent(LogExecution.class)) {
                LogExecution log = method.getAnnotation(LogExecution.class);
                System.out.println(log.message());
                Object result = method.invoke(calculator, 3, 2);
                System.out.println("Result: " + result);
            }
        }
    }
}

Output:

Running addition
Result: 5
Executing method
Result: 6

Real-World Applications in Simple Projects

Logging – Mark methods with @LogExecution to add logs automatically.
Validation – Use annotations like @NotEmpty to validate fields.
Configuration – Annotate classes with @Config to load settings.
Testing – Build a lightweight test runner that executes methods marked with @TestCase.

📌 What's New in Java Versions?

Java 5 – Introduced custom annotations and meta-annotations (@Retention, @Target).
Java 8 – Added repeatable and type annotations.
Java 9 – Allowed annotations in module descriptors.
Java 11 – No major changes to custom annotations.
Java 17 – No major changes.
Java 21 – No significant updates.

Pitfalls and Best Practices

Pitfalls

Forgetting @Retention(RUNTIME) when reflection is required.
Overusing annotations—leading to “annotation hell.”
Creating custom annotations without clear use cases.

Best Practices

Always define retention and target for clarity.
Keep annotations small and meaningful.
Combine with reflection or annotation processing to make them useful.
Document usage with Javadoc for team clarity.

Summary + Key Takeaways

Annotations provide declarative metadata that simplifies development.
Custom annotations are defined with @interface and enhanced by meta-annotations.
Reflection allows you to process and act upon annotations dynamically.
Start small (logging, validation, configs) before applying advanced frameworks like Spring or Hibernate.

FAQ

What’s the difference between built-in and custom annotations?
Built-in ones (@Override, @Deprecated) are part of Java, while custom ones are developer-defined.
Do annotations execute code directly?
No, they’re metadata. Code is executed only when frameworks or reflection process them.
When should I use RetentionPolicy.RUNTIME?
Use it when your annotations must be processed at runtime.
Can annotations have multiple elements?
Yes, you can define multiple elements like fields in an interface.
Can annotations have default values?
Yes, define defaults like String role() default "USER";.
Can I apply multiple annotations on the same method?
Yes, and Java 8 introduced repeatable annotations for the same type.
How are annotations processed in large frameworks?
Frameworks like Spring and Hibernate scan classes and use reflection to apply logic.
Can I use annotations to replace configuration files?
Yes, many modern frameworks prefer annotation-based configuration.
Are annotations part of the compiled bytecode?
Yes, depending on the retention policy.
What’s the risk of overusing annotations?
Code can become cluttered and harder to maintain—always prioritize simplicity.