Document ControllerAdviceBean as internal usage

[sinanoezdemir]

Enhancement/ Misleading description in javadoc.

In the Javadoc of ControllerAdviceBean you can read

Encapsulates information about an @ControllerAdvice Spring-managed bean without necessarily requiring it to be instantiated.
The findAnnotatedBeans(ApplicationContext) method can be used to discover such beans. However, a ControllerAdviceBean may be created from any object, including ones without an @ControllerAdvice annotation.

ControllerAdviceBean

Reading this I assume, that it should be possible to create ControllerAdviceBeans and register them programmatically (without using the @ControllerAdvice annotation).

As far as I understood the ExceptionHandlerExceptionResolver is the class keeping the ControllerAdviceBeans to apply matching ExceptionHandlers when an exception occurs.

However, when initialising the exceptionHandlerAdviceCache it uses ControllerAdviceBean.findAnnotatedBeans which scans the application context for beans annotated with @ControllerAdvice.

The exceptionHandlerAdviceCache is otherwise not modifiable. So there is actually no other way to add ControllerAdviseBeans besides using the annotation.

I think that's why the Javadoc is misleading.

However, it would be great to have the ability to define ControllerAdviseBeans without using the @ControllerAdvice annotation.

• Context: I am developing in a micro service environment and we have multiple micro services using the same ControllerAdvise which we extracted into a Library. I do not want libraries to contain spring component annotations. I rather would like to instantiate a bean in the configurations of each micro service. With the current implementation it's not possible to "just" remove the annotation and instantiate that bean in a configuration.

I assumed something similar to this should work.

@Configuration
public class SomeConfiguration {

  @Bean
  public ControllerAdviceBean myControllerAdvice() {
    return new ControllerAdviceBean(new MyControllerAdvice());
  }

}

//Example
public  class MyControllerAdvise {

    @ExceptionHandler({Exception.class})
    public ResponseEntity<Object> handleRemainingExceptions(Exception exception, WebRequest request) {
      // does something
      return ResponseEntity.internalServerError().body("Something went wrong");
    }
    
 }

Please excuse me if I misunderstood a concept here. Just trying to suggest an improvement.

[rishiraj88]

I agree with you, @sinanoezdemir , about your note on the Javadoc of ControllerAdviceBean (in the beginning of your comment). I, too, find the exact match between your statements and the Javadoc statements. That should be altered.

However, pardon me for not diving deep into your usecase and context of micro services.

[sbrannen]

Related Issues

• ControllerAdviceBean javadoc is inconsistent with its implementation [SPR-13759] #18332
• Support @ControllerAdvice on @Bean factory method #25346

[bclozel]

Hello @sinanoezdemir , thanks for bringing this up. We have discussed this today as a team and I'll summarize here.

We're not sure if you don't want your shared library to be scanned for components, or if it's scanned by micro-services but you would like to make this bit optional.

1. If you don't want your library to be scanned by mistake, this is a quite common concer. Spring Boot is contributed numerous configuration classes that should never be scanned. If an application scans the org.springframework.boot namespace, this is considered as an invalid setup. There might be ways to explicitly reject such situations and tell the user.
2. If your library is scanned but you would like to optionally contribute this component, there are many ways to express that with Spring: profiles, conditions, functional registration of beans...

Are your applications using Spring Boot? If so, you could contribute your own auto-configurations and never rely on scanning for your library components. Your classes would still be annotated with @ControllerAdvice but could be conditionally contributed to the application context.

Now depending on the outcome of this discussion, we might revisit the ControllerAdviceBean javadoc and part of its implementation: this is a public type that needs to be shared for Spring MVC and WebFlux, but it's not meant for public use. As you've found out, non-annotated @ControllerAdvice instances are not supported at the moment and we could streamline the current implementation to reflect that as it's only partially there.

[sinanoezdemir]

@bclozel thanks for your response.

I just mentioned this issue because of what you sad in your last sentence

As you've found out, non-annotated @ControllerAdvice instances are not supported at the moment

In our team we try to avoid relying on component scanning for libraries. Instead we want to manually configure the beans within the services and use the libraries like a blue print for these kind of things. In this case exception handling.

I have a working workaround but I think it would be great if it would be possible to register ControllerAdvices by annotation and programmatically. Off course I understand that this is probably easier sad then done.

[bclozel]

In our team we try to avoid relying on component scanning for libraries. Instead we want to manually configure the beans within the services and use the libraries like a blue print for these kind of things. In this case exception handling.

Thanks for your response.

I have a working workaround but I think it would be great if it would be possible to register ControllerAdvices by annotation and programmatically. Off course I understand that this is probably easier sad then done.

I don't think that pointing to a class would really qualify as programmatic registration. This class would still contain @ExceptionHandler method and would still be annotated-driven. You could look at how we handle programmatic registration of mappings for controllers in Spring MVC. As you can see, there is no annotation involved here anymore.

Are your applications using Spring Boot? If so, you could contribute your own auto-configurations and never rely on scanning for your library components. Your classes would still be annotated with @ControllerAdvice but could be conditionally contributed to the application context.

The auto-configuration approach would be more aligned with your vision of programmatic registration in this case. Have you considered this?

[qzmer1104]

I have the same concerns。

1、common-spring.jar
@RestControllerAdvice(basePackages="com.a") class GlobalExceptionHandler {}
org.springframework.boot.autoconfigure.AutoConfiguration.imports
xxx.xxx.GlobalExceptionHandler

2、app-1
app package
com.a.xxxxConotroller
pom.xml
maven import common-spring.jar

GlobalExceptionHandler is useful

2、app-2
app package
com.c.controller
pom.xml
maven import common-spring.jar
GlobalExceptionHandler is useless

We may no need to package a new common-spring.jar just only modify the basePackages

[bclozel]

@qzmer1104 so you are looking for something like this, but for exception handling?

Have you considered custom auto-configurations?

[sinanoezdemir]

Thank you, @bclozel, for your responses.

I agree that @ExceptionHandler and @configuration would still be necessary, but that is acceptable. My main goal was to avoid relying on component scanning. With the configuration class, you have to register the bean manually, and the library containing the exception handlers does not create beans by itself. We try to avoid the creation of beans within libraries whenever possible.

We also considered auto-configuration, and that approach would work. There are ways to implement a workaround, so that is not the issue. I just thought it would be beneficial if the framework supported this method of declaring controller advices.

[bclozel]

We have discussed this as a team and think that conditional configurations or Spring Boot auto-configurations are the preferred way of handling this use case.

We'll repurpose this issue to update the ControllerAdviceBean Javadoc to make it obvious that this is for internal use (it's really public because it must be used from different packages). In the process, we should review its constructors and code paths to check whether some of those partially implement this "programmatic registration" feature that we don't intend to support. If we find any, we should deprecate/remove those code paths.