Finding All Beans with a Custom Annotation

1. Overview

In this tutorial, we’ll explain how to find all beans annotated with a custom annotation in Spring. We’ll show different methods depending on the Spring version we use.

2. With Spring Boot 2.2 or Later

Since Spring Boot 2.2, we can use the getBeansWithAnnotation method.

Let’s build an example. First, we’ll define our custom annotation. Let’s annotate it with @Retention(RetentionPolicy.RUNTIME) to make sure the annotation can be accessed by the program during runtime:

@Retention( RetentionPolicy.RUNTIME )
public @interface MyCustomAnnotation {

}

Now, let’s define a first bean annotated with our annotation. We’ll also annotate it with @Component:

@Component
@MyCustomAnnotation
public class MyComponent {

}

Then, let’s define another bean annotated with our annotation. However, this time we’ll create it thanks to a @Bean annotated method in a @Configuration file:

public class MyService {

}

@Configuration
public class MyConfigurationBean {

    @Bean
    @MyCustomAnnotation
    MyService myService() {
        return new MyService();
    }
}

Now, let’s write a test to check that the getBeansWithAnnotation method can detect both of our beans:

@Test
void whenApplicationContextStarted_ThenShouldDetectAllAnnotatedBeans() {
    try (AnnotationConfigApplicationContext applicationContext = new AnnotationConfigApplicationContext( MyComponent.class, MyConfigurationBean.class )) {
        Map<String,Object> beans = applicationContext.getBeansWithAnnotation(MyCustomAnnotation.class);
        assertEquals(2, beans.size());
        assertTrue(beans.keySet().containsAll(List.of("myComponent", "myService")));
    }
}

3. With an Older Spring Version

3.1. Historical Context

In Spring Framework versions prior to 5.2, the getBeansWithAnnotation method would only detect beans annotated at the class or interface level but was not able to detect the beans annotated at the factory method level.

Spring Framework dependency has been upgraded to 5.2 in Spring Boot 2.2, so that’s why with older versions of Spring, the test we have just written would fail:

• the MyComponent bean is correctly detected because the annotation is at the class level
• the MyService bean is not detected because it’s created through a factory method

Let’s see how we can get around this behavior.

3.2. Decorate Our Custom Annotation with @Qualifier

There’s a rather straightforward workaround: We can simply decorate our annotation with @Qualifier.

Our annotation will then look like:

@Retention( RetentionPolicy.RUNTIME )
@Qualifier
public @interface MyCustomAnnotation {

}

Now, we’re able to auto-wire both annotated beans. Let’s check that out with a test:

@Autowired
@MyCustomAnnotation
private List<Object> annotatedBeans;

@Test
void whenAutowiring_ThenShouldDetectAllAnnotatedBeans() {
    assertEquals(2, annotatedBeans.size());
    List<String> classNames = annotatedBeans.stream()
        .map(Object::getClass)
        .map(Class::getName)
        .map(s -> s.substring(s.lastIndexOf(".") + 1))
        .collect(Collectors.toList());
    assertTrue(classNames.containsAll(List.of("MyComponent", "MyService")));
}

This workaround is the simplest, however, it might not fit our needs, for instance, if we don’t own the annotation.

Let’s also note that decorating our custom annotation with @Qualifier will turn it into a Spring qualifier.

3.3. Listing the Beans Created via a Factory Method

Now that we’ve understood that the problem mainly arises with beans created via factory methods, let’s focus on how to list only those. We’ll present a solution that functions in all cases without implying any change to our custom annotation. We’ll use reflection to access the beans’ annotations.

Given that we have access to the Spring ApplicationContext, we’ll follow a series of steps:

• Access the BeanFactory
• Look up the BeanDefinition associated with each bean
• Check if the source of the BeanDefinition is an AnnotatedTypeMetadata, which means we’ll be able to access the annotations of the bean
• If the bean has annotations, check if the desired annotation is among them

Let’s create our own BeanUtils utility class and implement this logic inside a method:

public class BeanUtils {

    public static List<String> getBeansWithAnnotation(GenericApplicationContext applicationContext, Class<?> annotationClass) {
        List<String> result = new ArrayList<String>();
        ConfigurableListableBeanFactory factory = applicationContext.getBeanFactory();
        for(String name : factory.getBeanDefinitionNames()) {
            BeanDefinition bd = factory.getBeanDefinition(name);
            if(bd.getSource() instanceof AnnotatedTypeMetadata) {
                AnnotatedTypeMetadata metadata = (AnnotatedTypeMetadata) bd.getSource();
                if (metadata.getAnnotationAttributes(annotationClass.getName()) != null) {
                    result.add(name);
                }
            }
        }
        return result;
    }
}

Alternatively, we could also write the same function using Streams:

public static List<String> getBeansWithAnnotation(GenericApplicationContext applicationContext, Class<?> annotationClass) {
    ConfigurableListableBeanFactory factory = applicationContext.getBeanFactory();
    return Arrays.stream(factory.getBeanDefinitionNames())
        .filter(name -> isAnnotated(factory, name, annotationClass))
        .collect(Collectors.toList());
}

private static boolean isAnnotated(ConfigurableListableBeanFactory factory, String beanName, Class<?> annotationClass) {
    BeanDefinition beanDefinition = factory.getBeanDefinition(beanName);
    if(beanDefinition.getSource() instanceof AnnotatedTypeMetadata) {
        AnnotatedTypeMetadata metadata = (AnnotatedTypeMetadata) beanDefinition.getSource();
        return metadata.getAnnotationAttributes(annotationClass.getName()) != null;
    }
    return false;
}

In these methods, we’ve used a GenericApplicationContext, which is an implementation of Spring ApplicationContext that doesn’t assume a specific bean definition format.

To have access to the GenericApplicationContext, we can, for instance, inject it into a Spring component:

@Component
public class AnnotatedBeansComponent {

    @Autowired
    GenericApplicationContext applicationContext;
    
    public List<String> getBeansWithAnnotation(Class<?> annotationClass) {
        return BeanUtils.getBeansWithAnnotation(applicationContext, annotationClass);
    }
}

4. Conclusion

In this article, we’ve discussed how to list the beans annotated with a given annotation. We’ve seen that since Spring Boot 2.2, this is done naturally by the getBeansWithAnnotation method.

On the other hand, we’ve shown some alternative methods to overcome the limits of the previous behavior of this method: either by only adding @Qualifier on top of our annotation or by looking up the beans, using reflection to check whether they have the annotation or not.