Create replacement API for handling merged annotations [SPR-17161]

[spring-projects-issues]

Phil Webb opened SPR-17161 and commented

The existing AnnotationUtils and AnnotatedElementUtils have grown quite a bit over the years and could do with being revisited now that we have pretty comprehensive support for merged annotations throughout the framework.

Some common issues with the current utils classes include:

• Quite a broad API (~58 public methods between them) that can make it hard for users to find the right method.
• Some performance concerns. The classes often appear near the top when profiling applications and a typical application will synthesize quite a few annotations.
• Difficult to evolve. We have some ideas around using annotation processing at compile time to pre-compute some information. It's quite hard to currently plug this in to the existing code.
• Complicated meta-data relationships. There's quite a complicated relationship between AnnotatedTypeMetadata and the utils and the meta-data API is different.

A new API could help us to determine which methods are really needed and provide the potential for more intelligent caching or pre-computed data.

---

Affects: 5.1 RC1

[spring-projects-issues]

Phil Webb commented

Some initial prototype work for this is here: https://github.com/philwebb/spring-framework/tree/annotations

The new API tries to separate the representation of merged annotations from the way that they're discovered. This helps to reduce the surface area of the API since find... vs get... semantic methods are no longer needed. For example, to get only the direct annotations and related meta-annotations you would call MergedAnnotations.from(element, SearchStrategy.DIRECT). For a complete search of all superclasses and interface you would do MergedAnnotations.from(element, SearchStrategy.EXHAUSTIVE). Regardless of the method used to find the MergedAnnotations, the API is identical and contains contains methods to:

• Determine if an annotation is present
• Get a single merged annotation
• Get a stream of a specific annotation type
• Get a stream of all annotations

The MergedAnnotation interface allows you to inspect information about the annotation and synthesize it if required. The method on the interface are also designed to be used when working with streams. Some typical examples:

// is an annotation present or meta-present
mergedAnnotations.isPresent(ExampleAnnotation.class);

// get the merged "value" attribute of ExampleAnnotation (either direct or meta-present)
mergedAnnotations.get(ExampleAnnotation.class).getString("value");

// get all meta-annotations but no direct annotations
mergedAnnotations.stream().anyMatch(MergedAnnotation::isMetaPresent);

// get all ExampleAnnotation declarations (include any meta-annotations) and print the merged "value" attributes
mergedAnnotations.stream(ExampleAnnotation.class).map(a -> a.getString("value")).forEach(System.out::println);