@annotation, @within, @target, @args

## What it is Spring AOP pointcut expressions use AspectJ's pointcut language. Besides the common `execution(...)`, `within(...)`, `args(...)` designators, AspectJ provides four **annotation-presence** designators: `@annotation`, `@within`, `@target`, and `@args`. They select join points based on where an annotation is present rather than on class/method names. `@annotation(SomeAnnotation)` matches a **method-execution join point when the method being executed is directly annotated** with `SomeAnnotation`. (In Spring AOP the only join point kind is method execution — there is no field or constructor weaving.) ```java @Retention(RetentionPolicy.RUNTIME) // MANDATORY — Spring reads annotations reflectively at runtime @Target(ElementType.METHOD) public @interface Audited {} @Aspect @Component public class AuditAspect { @Before("@annotation(com.example.Audited)") public void audit(JoinPoint jp) { /* runs before any @Audited method */ } } ``` ## How it differs from execution()/within() - `execution(* com.example.service.*.*(..))` selects by **method signature pattern** (return type, package, class, name, args). - `within(com.example.service..*)` selects by the **type** in which the join point occurs (name pattern). - `@annotation(X)` selects by the **annotation present on the method** — no name or package coupling. Developers opt in per method by adding `@X`. This inversion of control is why annotation designators scale so well: the aspect declares *what capability* to apply, and any method across the codebase can request it by adding the annotation. ## Key requirements and mechanics - **Retention must be `RUNTIME`.** With `SOURCE` or `CLASS` retention the annotation is invisible at runtime and never matches. - `@annotation` is a **static** matcher: whether a method carries the annotation is known when Spring builds the proxy, so there is no per-invocation runtime residue check (unlike `@target`/`@args`). - **Java method annotations are NOT inherited.** If a subclass overrides an annotated method without re-declaring the annotation, `@annotation` no longer matches that overriding method. (Spring's own `@Transactional`/`@Cacheable` support works around this with `AnnotatedElementUtils`/merged-annotation lookup, but a raw `@annotation` pointcut does not.) ## Reading annotation attributes You can **bind** the annotation instance to an advice parameter whose name matches the designator reference, then read its attributes: ```java @Around("@annotation(audited)") public Object around(ProceedingJoinPoint pjp, Audited audited) throws Throwable { String level = audited.level(); // read attribute return pjp.proceed(); } ``` ## When to use Use `@annotation` for **cross-cutting behavior that individual methods opt into**: auditing, custom caching, retry, rate-limiting, metrics timing. It is the cleanest, most explicit of the annotation designators and the safest performance-wise.