Spring Boot logo

As I wrote some weeks earlier, I’m trying to implement features of the Spring Boot actuator in a non-Boot Spring MVC applications. Developing the endpoints themselves is quite straightforward. Much more challenging, however, is to be able to configure the mapping in a properties file, like in the actuator. This got me to check more closely at how it was done in the current code. This post sums up my “reverse-engineering” attempt around the subject.

Standard MVC

Usage

In Spring MVC, in a class annotated with the @Controller annotation, methods can be in turn annotated with @RequestMapping. This annotation accepts a value attribute (or alternatively a path one) to define from which path it can be called.

The path can be fixed e.g. /user but can also accepts variables e.g. /user/{id} filled at runtime. In that case, parameters should can be mapped to method parameters via @PathVariable:

@RequestMapping(path = "/user/{id}", method = arrayOf(RequestMethod.GET))
fun getUser(@PathVariable("id") id:String) = repository.findUserById(id)

While adapted to REST API, this has to important limitations regarding configuration:

  • The pattern is set during development time and does not change afterwards
  • The filling of parameters occurs at runtime

Implementation

With the above, mappings in @Controller-annotated classes will get registered during context startup through the DefaultAnnotationHandlerMapping class. Note there’s a default bean of this type registered in the context. This is summed up in the following diagram:

DefaultAnnotationHandlerMapping sequence diagram

In essence, the magic applies only to @Controller-annotated classes. Or, to be more strict, quoting the DefaultAnnotationHandlerMapping’s Javadoc:

Annotated controllers are usually marked with the Controller stereotype at the type level. This is not strictly necessary when RequestMapping is applied at the type level (since such a handler usually implements the org.springframework.web.servlet.mvc.Controller interface). However, Controller is required for detecting RequestMapping annotations at the method level if RequestMapping is not present at the type level.

Actuator

Usage

Spring Boot actuator allows for configuring the path associated with each endpoint in the application.properties file (or using alternative methods for Boot configuration).

For example, the metrics endpoint is available by default via the metrics path. But’s it possible to configure a completely different path:

endpoints.metrics.id=mymetrics

Also, actuator endpoints are by default accessible directly under the root, but it’s possible to group them under a dedicated sub-context:

management.context-path=/manage

With the above configuration, the metrics endpoint is now available under the /manage/mymetrics.

Implementation

Additional actuator endpoints should implements the MvcEndpoint interface. Methods annotated with @RequestMapping will work in the exact same way as for standard controllers above. This is achieved via a dedicated handler mapping, EndpointHandlerMapping in the Spring context.

HandlerMapping to map Endpoints to URLs via Endpoint.getId(). The semantics of @RequestMapping should be identical to a normal @Controller, but the endpoints should not be annotated as @Controller (otherwise they will be mapped by the normal MVC mechanisms).

The class hierarchy is the following:

MvcEndpoint class diagram

This diagram shows what’s part of Spring Boot and what’s not.

Conclusion

Actuator endpoints reuse some from the existing Spring MVC code to handle @RequestMapping. It’s done in a dedicated mapping class so as to separate standard MVC controllers and Spring Boot’s actuator endpoint class hierarchy. In order to achieve fully configurable mappings in Spring MVC, this is the part of the code study, to duplicate and to adapt should one wants fully configurable mappings.