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

Annotation Interface WebRoute

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

Specifies a Web route in a Web client stub.

A Web route is an annotated method in a Web client stub interface which basically defines the resource endpoints exposed on an HTTP server that needs to be consumed in an application. The method parameters can be bound to the request parameters or the request body using annotations like @CookieParam, @FormParam, @HeaderParam, @PathParam, @QueryParam, @PartParam and @Body.

Some specific method parameters can be specified when needed like a WebExchange.Configurer<? extends T> where T is the type of the exchange context to give access to the actual Web exchange.

The method's return type should eventually expose the response from the server and it must be reactive, the HTTP request being only sent when the response Mono is subscribed. A Web route method can then return any of:

  • Mono<Void>, Flux<Void> or Publisher<Void> when no response body is expected in which case the returned publisher normally fails when an error status (i.e. 4xx or 5xx) is received from the server. This behaviour can be controlled with WebExchange.failOnErrorStatus(boolean) and InterceptedWebExchange.failOnErrorStatus(java.util.function.Function).
  • Mono<WebExchange<? extends T>> where T is the type of the exchange context when there is a need to access the Web exchange before actually sending the request which is only sent when the WebExchange.response() Mono is subscribed. Note that this can also be achieved with a WebExchange.Configurer in the method parameters.
  • Mono<Response> when there is a need to access response status, headers...
  • Mono<ByteBuf>, Flux<ByteBuf> or Publisher<ByteBuf> in order to consume payload as raw data.
  • Mono<String>, Flux<String> or Publisher<String> in order to consume payload as string data.
  • Mono<T>, Flux<T> or Publisher<T> where T is none of the above in order to consume payload as encoded data.

An encoded response payload is decoded using one of the MediaTypeConverter injected in the Web client module and corresponding to the content type of the response. If no matching converter could be found a MissingConverterException stating that no media was specified will be thrown.

A simple Web route can be defined as follows in a Web client stub interface: 


 @WebClient( uri = "http://host:8080/book" )
 public interface BookClient {

     @WebRoute( path = "{id}", method = Method.PUT, produces = "application/json", consumes = "application/json" )
     Book update(@PathParam String id, @Body Book book);
 }
Since:
1.12
Author:
Jeremy Kuhn

  • Element Details

    • method

      Method method

      The HTTP method to use to consume the destination resource.

      Returns:
      an HTTP method
      Default:
      GET

    • path

      String path

      The path to the destination resource relative to the destination URI.

      A path can be a parameterized path as defined by URIBuilder. Path parameter can then be passed to the Web route method by defining path parameters.

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

      Returns:
      a path
      Default:
      ""

    • consumes

      String[] consumes

      The list of media ranges that the request accepts from the server in the response as defined by RFC 7231 Section 5.3.2.

      Returns:
      an array of media ranges
      Default:
      {}

    • produces

      String produces

      The media types of the content produced by the request as defined by RFC 7231 Section 3.1.1.5.

      The request body content type basically specifies which MediaTypeConverter is be used to encode the request payload.

      Returns:
      a media type
      Default:
      ""

    • language

      String[] language

      The list of language tags that the request accepts from the server in the response as defined by RFC 7231 Section 5.3.5.

      Returns:
      an array of language tags
      Default:
      {}