Package org.springframework.web.bind.annotation

# Annotation Interface ControllerAdvice

@Target(TYPE) @Retention(RUNTIME) @Documented @Component public @interface ControllerAdvice
Specialization of `@Component` for classes that declare `@ExceptionHandler`, `@InitBinder`, or `@ModelAttribute` methods to be shared across multiple `@Controller` classes.

Classes annotated with `@ControllerAdvice` can be declared explicitly as Spring beans or auto-detected via classpath scanning. All such beans are sorted based on `Ordered` semantics or `@Order` / `@Priority` declarations, with `Ordered` semantics taking precedence over `@Order` / `@Priority` declarations. `@ControllerAdvice` beans are then applied in that order at runtime. Note, however, that `@ControllerAdvice` beans that implement `PriorityOrdered` are not given priority over `@ControllerAdvice` beans that implement `Ordered`. In addition, `Ordered` is not honored for scoped `@ControllerAdvice` beans — for example if such a bean has been configured as a request-scoped or session-scoped bean. For handling exceptions, an `@ExceptionHandler` will be picked on the first advice with a matching exception handler method. For model attributes and data binding initialization, `@ModelAttribute` and `@InitBinder` methods will follow `@ControllerAdvice` order.

Note: For `@ExceptionHandler` methods, a root exception match will be preferred to just matching a cause of the current exception, among the handler methods of a particular advice bean. However, a cause match on a higher-priority advice will still be preferred over any match (whether root or cause level) on a lower-priority advice bean. As a consequence, please declare your primary root exception mappings on a prioritized advice bean with a corresponding order.

By default, the methods in an `@ControllerAdvice` apply globally to all controllers. Use selectors such as `annotations()`, `basePackageClasses()`, and `basePackages()` (or its alias `value()`) to define a more narrow subset of targeted controllers. If multiple selectors are declared, boolean `OR` logic is applied, meaning selected controllers should match at least one selector. Note that selector checks are performed at runtime, so adding many selectors may negatively impact performance and add complexity.

Since:
  3.2
Author:
  Rossen Stoyanchev, Brian Clozel, Sam Brannen
See Also:
  - `Controller`
  - `RestControllerAdvice`

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
Description
`Class<? extends Annotation>[]`
`annotations`
Array of annotation types.
`Class<?>[]`
`assignableTypes`
Array of classes.
`Class<?>[]`
`basePackageClasses`
Type-safe alternative to `basePackages()` for specifying the packages in which to select controllers to be advised by the `@ControllerAdvice` annotated class.
`String[]`
`basePackages`
Array of base packages.
`String`
`name`
Alias for `Component.value()`.
`String[]`
`value`
Alias for the `basePackages()` attribute.

## Element Details

### name

@AliasFor(annotation=org.springframework.stereotype.Component.class, attribute="value") String name
Alias for `Component.value()`.

Since:
  6.1

Default:
  ""

### value

@AliasFor("basePackages") String[] value
Alias for the `basePackages()` attribute.

Allows for more concise annotation declarations — for example, `@ControllerAdvice("org.my.pkg")` is equivalent to `@ControllerAdvice(basePackages = "org.my.pkg")`.

Since:
  4.0
See Also:
  - `basePackages()`

Default:
  {}

### basePackages

@AliasFor("value") String[] basePackages
Array of base packages.

Controllers that belong to those base packages or sub-packages thereof will be included — for example, `@ControllerAdvice(basePackages = "org.my.pkg")` or `@ControllerAdvice(basePackages = {"org.my.pkg", "org.my.other.pkg"})`.

`value()` is an alias for this attribute, simply allowing for more concise use of the annotation.

Also consider using `basePackageClasses()` as a type-safe alternative to String-based package names.

Since:
  4.0

Default:
  {}

### basePackageClasses

Class<?>[] basePackageClasses
Type-safe alternative to `basePackages()` for specifying the packages in which to select controllers to be advised by the `@ControllerAdvice` annotated class.

Consider creating a special no-op marker class or interface in each package that serves no purpose other than being referenced by this attribute.

Since:
  4.0

Default:
  {}

### assignableTypes

Class<?>[] assignableTypes
Array of classes.

Controllers that are assignable to at least one of the given types will be advised by the `@ControllerAdvice` annotated class.

Since:
  4.0

Default:
  {}

### annotations

Class<? extends Annotation>[] annotations
Array of annotation types.

Controllers that are annotated with at least one of the supplied annotation types will be advised by the `@ControllerAdvice` annotated class.

Consider creating a custom composed annotation or use a predefined one, like `@RestController`.

Since:
  4.0

Default:
  {}