Scanning Java Annotations at Runtime

1. Introduction

As we know, in the Java world, annotation is a very useful way of obtaining meta information about classes and methods.

In this tutorial, we’re going to discuss scanning Java annotations at runtime.

2. Defining Custom Annotation

Let’s start by defining a sample annotation and a sample class that uses our custom annotation:

@Target({ METHOD, TYPE })
@Retention(RUNTIME)
public @interface SampleAnnotation {
    String name();
}

@SampleAnnotation(name = "annotatedClass")
public class SampleAnnotatedClass {

    @SampleAnnotation(name = "annotatedMethod")
    public void annotatedMethod() {
        //Do something
    }

    public void notAnnotatedMethod() {
        //Do something
    }
}

Now, we are ready to resolve the “name” attribute of this custom annotation on both class-based and method-based usages.

3. Scanning Annotations with Java Reflection

With the help of Java Reflection, we can scan a specific annotated class or annotated method(s) of a specific class.

In order to achieve this goal, we need to load the class by using ClassLoader. So this method is useful when we know in which class(es) to scan annotation:

Class<?> clazz = ClassLoader.getSystemClassLoader()
  .loadClass("com.baeldung.annotation.scanner.SampleAnnotatedClass");
SampleAnnotation classAnnotation = clazz.getAnnotation(SampleAnnotation.class);
Assert.assertEquals("SampleAnnotatedClass", classAnnotation.name());
Method[] methods = clazz.getMethods();
List<String> annotatedMethods = new ArrayList<>();
for (Method method : methods) {
    SampleAnnotation annotation = method.getAnnotation(SampleAnnotation.class);
    if (annotation != null) {
        annotatedMethods.add(annotation.name());
    }
}
Assert.assertEquals(1, annotatedMethods.size());
Assert.assertEquals("annotatedMethod", annotatedMethods.get(0));

4. Scanning Annotations with Spring Context Library

Another way of scanning the annotations is using ClassPathScanningCandidateComponentProvider class which is included in the Spring Context library.

Let’s start by adding spring-context dependency:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>5.3.22</version>
</dependency>

And let’s continue with a simple example:

ClassPathScanningCandidateComponentProvider provider =
  new ClassPathScanningCandidateComponentProvider(false);
provider.addIncludeFilter(new AnnotationTypeFilter(SampleAnnotation.class));

Set<BeanDefinition> beanDefs = provider
  .findCandidateComponents("com.baeldung.annotation.scanner");
List<String> annotatedBeans = new ArrayList<>();
for (BeanDefinition bd : beanDefs) {
    if (bd instanceof AnnotatedBeanDefinition) {
        Map<String, Object> annotAttributeMap = ((AnnotatedBeanDefinition) bd)
          .getMetadata()
          .getAnnotationAttributes(SampleAnnotation.class.getCanonicalName());
        annotatedBeans.add(annotAttributeMap.get("name").toString());
    }
}

Assert.assertEquals(1, annotatedBeans.size());
Assert.assertEquals("SampleAnnotatedClass", annotatedBeans.get(0));

Completely different from Java Reflections, we can scan all classes without the need to know the specific class names.

5. Scanning Annotations with Spring Core Library

Although Spring Core doesn’t directly provide full scanning of all annotations in our code, we can still develop our own full annotation scanner by using some utility classes of this library.

First, we need to add spring-core dependency:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>5.3.22</version>
</dependency>

Here comes a simple example:

Class<?> userClass = ClassUtils.getUserClass(SampleAnnotatedClass.class);

List<String> annotatedMethods = Arrays.stream(userClass.getMethods())
  .filter(method -> AnnotationUtils
  .getAnnotation(method, SampleAnnotation.class) != null)
  .map(method -> method.getAnnotation(SampleAnnotation.class)
  .name())
  .collect(Collectors.toList());

Assert.assertEquals(1, annotatedMethods.size());
Assert.assertEquals("annotatedMethod", annotatedMethods.get(0));

With the help of AnnotationUtils and ClassUtils, it’s possible to find the methods and classes annotated with a specific annotation.

6. Scanning Annotations with Reflections Library

Reflections is a library that is said to be written in the spirit of Scannotations library. It scans and indexes the project’s classpath metadata.

Let’s add reflections dependency:

<dependency>
    <groupId>org.reflections</groupId>
    <artifactId>reflections</artifactId>
    <version>0.10.2</version>
</dependency>

Now we are ready to use the library for searching the annotated classes, methods, fields and types:

Reflections reflections = new Reflections("com.baeldung.annotation.scanner");

Set<Method> methods = reflections
  .getMethodsAnnotatedWith(SampleAnnotation.class);
List<String> annotatedMethods = methods.stream()
  .map(method -> method.getAnnotation(SampleAnnotation.class)
  .name())
  .collect(Collectors.toList());

Assert.assertEquals(1, annotatedMethods.size());
Assert.assertEquals("annotatedMethod", annotatedMethods.get(0));

Set<Class<?>> types = reflections
  .getTypesAnnotatedWith(SampleAnnotation.class);
List<String> annotatedClasses = types.stream()
  .map(clazz -> clazz.getAnnotation(SampleAnnotation.class)
  .name())
  .collect(Collectors.toList());

Assert.assertEquals(1, annotatedClasses.size());
Assert.assertEquals("SampleAnnotatedClass", annotatedClasses.get(0));

As we can see, the Reflections library provides a flexible way of scanning all annotated classes and methods. So we don’t need to start with SampleAnnotatedClass.

7. Scanning Annotations with Jandex Library

Now let’s take a look at a different library named Jandex which we can use to scan the annotations at runtime by reading the generated Jandex files of our code.

This library introduces a Maven plugin to generate a Jandex file that contains meta information related to our project:

<plugin>
    <groupId>org.jboss.jandex</groupId>
    <artifactId>jandex-maven-plugin</artifactId>
    <version>1.2.3</version>
    <executions>
        <execution>
            <phase>compile</phase>
            <id>make-index</id>
            <goals>
                <goal>jandex</goal>
            </goals>
            <configuration>
                <fileSets>
                    <fileSet>
                        <directory>${project.build.outputDirectory}</directory>
                    </fileSet>
                </fileSets>
            </configuration>
        </execution>
    </executions>
</plugin>

As we can see, after running the maven-install command, the file is generated in the classpath under the META-INF directory with the name jandex.idx. We can also modify the name of the file with rename plugin of Maven if it’s needed.

Now we are ready to scan any kind of annotation. First, we need to add the jandex dependency:

<dependency>
    <groupId>org.jboss</groupId>
    <artifactId>jandex</artifactId>
    <version>2.4.3.Final</version>
</dependency>

Now it’s time to scan the annotations:

IndexReader reader = new IndexReader(appFile.getInputStream());
Index jandexFile = reader.read();
List<AnnotationInstance> appAnnotationList = jandexFile
  .getAnnotations(DotName
  .createSimple("com.baeldung.annotation.scanner.SampleAnnotation"));

List<String> annotatedMethods = new ArrayList<>();
List<String> annotatedClasses = new ArrayList<>();
for (AnnotationInstance annotationInstance : appAnnotationList) {
    if (annotationInstance.target().kind() == AnnotationTarget.Kind.METHOD) {
        annotatedMethods.add(annotationInstance.value("name")
          .value()
          .toString());
    }
    if (annotationInstance.target().kind() == AnnotationTarget.Kind.CLASS) {
        annotatedClasses.add(annotationInstance.value("name")
          .value()
          .toString());
    }
}

Assert.assertEquals(1, annotatedMethods.size()); 
Assert.assertEquals("annotatedMethod", annotatedMethods.get(0));
Assert.assertEquals(1, annotatedClasses.size());
Assert.assertEquals("SampleAnnotatedClass", annotatedClasses.get(0));

8. Conclusion

Depending on our requirement; there are various ways of scanning annotations at runtime. Each of these ways has its own pros and cons. We can decide considering what we need.