Module io.inverno.mod.web.server
Package io.inverno.mod.web.server.annotation

Annotation Interface WebRoute

@Documented @Retention(SOURCE) @Target(METHOD) @Inherited public @interface WebRoute

Specifies a web route in a web controller.

A web route is an annotated method in a web controller which basically implements the exchange handler logic. The method parameters can be bound to the request parameters or the request body using annotations like @CookieParam, @FormParam, @HeaderParam, @PathParam, @QueryParam and @Body.

Some specific method parameter can also be specified when needed like the exchange being processed declared as Exchange or WebExchange and a server-sent event factory as described by SseEventFactory.

The method's return type describes the payload of the response, it can either be:

  • void to produce an empty response
  • ByteBuf, Mono<ByteBuf>, Flux<ByteBuf> or Publisher<ByteBuf> to produce raw data
  • Mono<T>, Flux<T> or Publisher<T> where type T is a super type of WebResponseBody.SseEncoder.Event<ByteBuf> to produce server-sent events with raw data
  • Mono<T>, Flux<T> or Publisher<T> where type T is a super type of WebResponseBody.SseEncoder.Event<U> and U not a ByteBuf to produce server-sent events with encoded data based on the media type specified by the @SseEventFactory annotated method parameter
  • Resource to produce a static resource
  • T, Mono<T>, Flux<T> or Publisher<T> where T is none of the above to produce encoded data based on the content type of the response

A response payload is encoded using one of the MediaTypeConverter injected in the web server module and corresponding to the content type of the response which is automatically set in case of successful content negotiation, basically when there's a match between the media type produced by the route and what the client accepts, otherwise the response content type must be set explicitly or an InternalServerErrorException stating that no media was specified will be thrown.

A simple web route can be defined as follows in a web controller bean: 


 @WebController( path = "/book" )
 @Bean
 public class BookController {

     @WebRoute( path = "{id}", method = Method.PUT, consumes = "application/json", produces = "application/json" )
     public Book update(@Body Book book) {
         ...
     }
 }
Since:
1.0
Author:
Jeremy Kuhn
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    consumes
    The list of media ranges that the content type of a request must match to be served by the route as defined by RFC 7231 Section 5.3.2.
    String[]
    language
    The list of languages that a request must match (i.e. accept at least one of them) to be served by the route.
    boolean
    matchTrailingSlash
    Indicates whether trailing slash in the request path should be matched by the route.
    Method[]
    method
    The list of HTTP methods to which the method of a request must belong to be served by the route.
    String[]
    path
    The path that the absolute path of a request must match to be served by the route.
    String[]
    produces
    The list of media types that the request must match (i.e. accept at least one of them) to be served by the route.

  • Element Details

    • method

      Method[] method

      The list of HTTP methods to which the method of a request must belong to be served by the route.

      Returns:
      an array of HTTP methods
      Default:
      {}

    • path

      String[] path

      The path that the absolute path of a request must match to be served by the route.

      A path can be a parameterized path parameters as defined by URIBuilder.

      Note that this path will be normalized in the resulting route.

      Returns:
      an array of path
      Default:
      {}

    • matchTrailingSlash

      boolean matchTrailingSlash

      Indicates whether trailing slash in the request path should be matched by the route.

      When activated, the route matches a path regardless of whether it ends with a slash as long as the path matches one of the paths specified in the route with or without trailing slash.

      Returns:
      true to match path with or without trailing slash, false otherwise
      Default:
      false

    • consumes

      String[] consumes

      The list of media ranges that the content type of a request must match to be served by the route as defined by RFC 7231 Section 5.3.2.

      Returns:
      an array of media ranges
      Default:
      {}

    • produces

      String[] produces

      The list of media types that the request must match (i.e. accept at least one of them) to be served by the route.

      Returns:
      an array of media types
      Default:
      {}

    • language

      String[] language

      The list of languages that a request must match (i.e. accept at least one of them) to be served by the route.

      Returns:
      an array of language tags
      Default:
      {}