org.springframework.web.bind.annotation

Annotation Type ControllerAdvice

@Target(value=TYPE)
 @Retention(value=RUNTIME)
 @Documented
 @Component
public @interface ControllerAdvice

Indicates the annotated class assists a "Controller".

Serves as a specialization of @Component, allowing for implementation classes to be autodetected through classpath scanning.

It is typically used to define @ExceptionHandler, @InitBinder, and @ModelAttribute methods that apply to all @RequestMapping methods.

One of annotations(), basePackageClasses(), basePackages() or its alias value() may be specified to define specific subsets of Controllers to assist. When multiple selectors are applied, OR logic is applied - meaning selected Controllers should match at least one selector.

The default behavior (i.e. if used without any selector), the @ControllerAdvice annotated class will assist all known Controllers.

Note that those checks are done at runtime, so adding many attributes and using multiple strategies may have negative impacts (complexity, performance).

Since:

3.2

Author:

Rossen Stoyanchev, Brian Clozel, Sam Brannen

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Class<? extends Annotation>[]	annotations Array of annotations.
Class<?>[]	assignableTypes Array of classes.
Class<?>[]	basePackageClasses Type-safe alternative to value() for specifying the packages to select Controllers to be assisted by the @ControllerAdvice annotated class.
String[]	basePackages Array of base packages.
String[]	value Alias for the basePackages() attribute.

Element Detail

value

@AliasFor(value="basePackages")
public abstract String[] value

Alias for the basePackages() attribute.

Allows for more concise annotation declarations e.g.: @ControllerAdvice("org.my.pkg") is equivalent to @ControllerAdvice(basePackages="org.my.pkg").

Since:

4.0

See Also:

basePackages()

Default:

{}

basePackages

@AliasFor(value="value")
public abstract String[] basePackages

Array of base packages.

Controllers that belong to those base packages or sub-packages thereof will be included, e.g.: @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

public abstract Class<?>[] basePackageClasses

Type-safe alternative to value() for specifying the packages to select Controllers to be assisted 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

public abstract Class<?>[] assignableTypes

Array of classes.

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

Since:

4.0

Default:

{}

annotations

public abstract Class<? extends Annotation>[] annotations

Array of annotations.

Controllers that are annotated with this/one of those annotation(s) will be assisted by the @ControllerAdvice annotated class.

Consider creating a special annotation or use a predefined one, like @RestController.

Since:

4.0

Default:

{}