org.springframework.web.bind.annotation

Annotation Type ControllerAdvice



  • @Target(value=TYPE)
     @Retention(value=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 with @ControllerAdvice can be declared explicitly as Spring beans or auto-detected via classpath scanning. All such beans are sorted via AnnotationAwareOrderComparator, i.e. based on @Order and Ordered, and applied in that order at runtime. For handling exceptions, an @ExceptionHandler will be picked on the first advice with a matching exception handler method. For model attributes and InitBinder initialization, @ModelAttribute and @InitBinder methods will also 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 to a 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 annotations(), basePackageClasses(), and basePackages() (or its alias value()) to define a more narrow subset of targeted Controllers. If multiple selectors are declared, OR logic is applied, meaning selected Controllers should match at least one selector. Note that selector checks are performed at runtime and 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 and Description
      java.lang.Class<? extends java.lang.annotation.Annotation>[] annotations
      Array of annotations.
      java.lang.Class<?>[] assignableTypes
      Array of classes.
      java.lang.Class<?>[] basePackageClasses
      Type-safe alternative to value() for specifying the packages to select Controllers to be assisted by the @ControllerAdvice annotated class.
      java.lang.String[] basePackages
      Array of base packages.
      java.lang.String[] value
      Alias for the basePackages() attribute.
    • Element Detail

      • value

        @AliasFor(value="basePackages")
        public abstract java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.Class<? extends java.lang.annotation.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:
        {}