Creating Custom Annotations - Spring Boot

[akash-coded]

Creating a custom annotation in Spring is a powerful feature that can encapsulate logic and behavior in an easily reusable and readable way. Let's dive into creating a custom annotation from scratch and integrate it with Spring's runtime environment.

Let's assume you want to create a custom @TCSRestTemplate annotation that configures a RestTemplate bean with specific headers or timeouts.

Step 1: Define the Annotation

First, define the @TCSRestTemplate annotation in Java:

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

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface TCSRestTemplate {
    String headerName() default "";
    String headerValue() default "";
    int timeout() default 3000;
}

Step 2: Create a Configuration Class to Process the Annotation

Here, we define a configuration class that will create and configure the RestTemplate bean.

import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class TCSRestTemplateConfiguration {
  
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }

    @Bean
    public BeanPostProcessor tcsRestTemplateBeanPostProcessor() {
        return new TCSRestTemplateBeanPostProcessor();
    }
}

Step 3: Implement Bean Post-Processor for Annotation Logic

We need a BeanPostProcessor to check if our custom annotation is present and then take the necessary action.

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanPostProcessor;

public class TCSRestTemplateBeanPostProcessor implements BeanPostProcessor {

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
        if (bean instanceof RestTemplate) {
            RestTemplate restTemplate = (RestTemplate) bean;
            // read @TCSRestTemplate annotations on this bean (if any)
            // and configure it accordingly
        }
        return bean;
    }

    @Override
    public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
        return bean;
    }
}

Step 4: Use the Annotation

You can use this annotation on any Spring @Configuration class or even a @Bean method:

@Configuration
public class AppConfig {

    @TCSRestTemplate(headerName="Authorization", headerValue="Bearer xyz", timeout=5000)
    @Bean
    public RestTemplate customRestTemplate() {
        return new RestTemplate();
    }
}

Deep Dive Explanation

1. Annotation Lifecycle: Annotations in Java are meta-annotations. They are part of the source code and, based on their retention policy, can be made available during the runtime.

2. BeanPostProcessor: It provides callback methods that you can implement to provide your own (or override the container's default) instantiation logic, dependency-resolution logic, and more.

3. Spring's Environment: The Spring framework is initialized, and the beans are instantiated. At this point, our BeanPostProcessor comes into play. It checks whether the annotation is present and configures the RestTemplate bean accordingly.

4. Reflection: Spring internally uses Java Reflection to analyze your classes, interfaces, enums to understand the presence of annotations and then decides what logic to trigger based on those annotations.

Think of this process as embedding your own business rules and behavior into the Spring context lifecycle, just like how Spring Security embeds authentication and authorization rules. This way, you can leverage Spring's robustness while making it do exactly what you want.

Now, using the @TCSRestTemplate, you can define custom behavior that is readable, reusable, and nicely integrated into Spring's lifecycle.

---

Absolutely, let's dig deeper into the underlying concepts.

Concepts Involved

1. Java Annotations: These are metadata tags you attach to your source code, and depending on their retention policy, they're available at runtime. Spring uses these to determine what sort of behavior an associated component should have.

2. Reflection: Java Reflection API allows programmatic access to class attributes, methods, annotations, etc. Spring heavily leverages this to read your custom annotations and apply logic based on them.

3. Bean Lifecycle: Spring manages the lifecycle of beans. This includes instantiation, property setting, @Autowired property handling, and much more. It's in this lifecycle that your custom annotations come into play.

4. BeanPostProcessor: This is a Spring-specific interface that allows you to tap into the lifecycle of Bean Initialization. It's like a hook where you can add your custom logic.

Deep Dive into Custom Logic with @TCSRestTemplate

When the Spring application context is initialized, it scans all the bean definitions and creates bean instances. As each bean is initialized, Spring runs any BeanPostProcessor classes that have been defined. This is where your custom annotation logic will execute.

Your custom TCSRestTemplateBeanPostProcessor class scans each bean before it's initialized (postProcessBeforeInitialization method). If it sees a bean of type RestTemplate, it inspects if your custom annotation (@TCSRestTemplate) is present. If so, it reads the attributes of the annotation and modifies the bean accordingly.

Here's how you could read annotation attributes and set custom logic:

public class TCSRestTemplateBeanPostProcessor implements BeanPostProcessor {

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
        if (bean instanceof RestTemplate) {
            RestTemplate restTemplate = (RestTemplate) bean;

            // Use reflection to check if our custom annotation is present
            Class<?> objClz = bean.getClass();
            if (objClz.isAnnotationPresent(TCSRestTemplate.class)) {
                TCSRestTemplate annotation = objClz.getAnnotation(TCSRestTemplate.class);

                // Now apply our custom logic
                String headerName = annotation.headerName();
                String headerValue = annotation.headerValue();
                int timeout = annotation.timeout();

                // For example, setting a custom header and timeout
                restTemplate.getInterceptors().add(
                    (request, body, execution) -> {
                        request.getHeaders().set(headerName, headerValue);
                        return execution.execute(request, body);
                    }
                );
                
                // Here we can set the timeout or any other custom logic
                restTemplate.setRequestFactory(clientHttpRequestFactory(timeout));
            }
        }
        return bean;
    }
  
    private ClientHttpRequestFactory clientHttpRequestFactory(int timeout) {
        // set the timeout
        return new SimpleClientHttpRequestFactory();
    }
}

How to Use

Whenever you annotate a bean with @TCSRestTemplate, this logic will kick in. For instance:

@Configuration
public class AppConfig {

    @TCSRestTemplate(headerName = "Authorization", headerValue = "Bearer xyz", timeout = 5000)
    @Bean
    public RestTemplate customRestTemplate() {
        return new RestTemplate();
    }
}

In this example, as Spring initializes the customRestTemplate bean, your TCSRestTemplateBeanPostProcessor checks for the annotation, reads its attributes, and sets the header and timeout accordingly.

Summary

1. Annotations provide a way to add metadata to code.
2. Spring uses Java Reflection to read these annotations.
3. By tapping into the Bean Lifecycle using a BeanPostProcessor, we can apply custom behavior based on our annotations.

For an advanced Spring developer, understanding these hooks in Spring's lifecycle allows you to tailor the framework to your specific needs, extending its default capabilities.Absolutely, let's dig deeper into the underlying concepts.

Concepts Involved

1. Java Annotations: These are metadata tags you attach to your source code, and depending on their retention policy, they're available at runtime. Spring uses these to determine what sort of behavior an associated component should have.

2. Reflection: Java Reflection API allows programmatic access to class attributes, methods, annotations, etc. Spring heavily leverages this to read your custom annotations and apply logic based on them.

3. Bean Lifecycle: Spring manages the lifecycle of beans. This includes instantiation, property setting, @Autowired property handling, and much more. It's in this lifecycle that your custom annotations come into play.

4. BeanPostProcessor: This is a Spring-specific interface that allows you to tap into the lifecycle of Bean Initialization. It's like a hook where you can add your custom logic.

Deep Dive into Custom Logic with @TCSRestTemplate

When the Spring application context is initialized, it scans all the bean definitions and creates bean instances. As each bean is initialized, Spring runs any BeanPostProcessor classes that have been defined. This is where your custom annotation logic will execute.

Your custom TCSRestTemplateBeanPostProcessor class scans each bean before it's initialized (postProcessBeforeInitialization method). If it sees a bean of type RestTemplate, it inspects if your custom annotation (@TCSRestTemplate) is present. If so, it reads the attributes of the annotation and modifies the bean accordingly.

Here's how you could read annotation attributes and set custom logic:

public class TCSRestTemplateBeanPostProcessor implements BeanPostProcessor {

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
        if (bean instanceof RestTemplate) {
            RestTemplate restTemplate = (RestTemplate) bean;

            // Use reflection to check if our custom annotation is present
            Class<?> objClz = bean.getClass();
            if (objClz.isAnnotationPresent(TCSRestTemplate.class)) {
                TCSRestTemplate annotation = objClz.getAnnotation(TCSRestTemplate.class);

                // Now apply our custom logic
                String headerName = annotation.headerName();
                String headerValue = annotation.headerValue();
                int timeout = annotation.timeout();

                // For example, setting a custom header and timeout
                restTemplate.getInterceptors().add(
                    (request, body, execution) -> {
                        request.getHeaders().set(headerName, headerValue);
                        return execution.execute(request, body);
                    }
                );
                
                // Here we can set the timeout or any other custom logic
                restTemplate.setRequestFactory(clientHttpRequestFactory(timeout));
            }
        }
        return bean;
    }
  
    private ClientHttpRequestFactory clientHttpRequestFactory(int timeout) {
        // set the timeout
        return new SimpleClientHttpRequestFactory();
    }
}

How to Use

Whenever you annotate a bean with @TCSRestTemplate, this logic will kick in. For instance:

@Configuration
public class AppConfig {

    @TCSRestTemplate(headerName = "Authorization", headerValue = "Bearer xyz", timeout = 5000)
    @Bean
    public RestTemplate customRestTemplate() {
        return new RestTemplate();
    }
}

In this example, as Spring initializes the customRestTemplate bean, your TCSRestTemplateBeanPostProcessor checks for the annotation, reads its attributes, and sets the header and timeout accordingly.

Summary

1. Annotations provide a way to add metadata to code.
2. Spring uses Java Reflection to read these annotations.
3. By tapping into the Bean Lifecycle using a BeanPostProcessor, we can apply custom behavior based on our annotations.

For an advanced Spring developer, understanding these hooks in Spring's lifecycle allows you to tailor the framework to your specific needs, extending its default capabilities.