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

Annotation Interface WebSocketRoute

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

Specifies a WebSocket route in a Web client stub.

A WebSocket route is an annotated method in a Web client stub interface which basically defines the WebSocket endpoints exposed on an HTTP server to which an application needs to connect. As for a WebRoute, method parameters can be bound the upgrading request parameter using annotations like @CookieParam, @FormParam, @HeaderParam, @PathParam and @QueryParam.

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

WebSocket outbound data are also specified in the method parameters as:

  • Consumer<BaseWeb2SocketExchange.Outbound> in order to explicitly configure the WebSocket outbound.
  • Mono<ByteBuf>, Flux<ByteBuf> or Publisher<ByteBuf> in order to produce message payload as raw data.
  • Mono<String>, Flux<String> or Publisher<String> in order to produce message payload as string data.
  • Mono<T>, Flux<T> or Publisher<T> in order to produce message payload as encoded data in which case the negotiated subprotocol is used to determine the MediaTypeConverter to use to encode message content.

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

  • Mono<Web2SocketExchange<? extends T>> where T is the type of the exchange context when there is a need to access the WebSocket exchange before actually sending the upgrade request which is only sent when the WebExchange.webSocket() Mono is subscribed. Note that this can also be achieved with a Web2SocketExchange.Configurer in the method parameters.
  • Mono<Inbound> when there is a need to explicitly access the WebSocket inbound
  • Mono<ByteBuf>, Flux<ByteBuf> or Publisher<ByteBuf> in order to consume message payload as raw data.
  • Mono<String>, Flux<String> or Publisher<String> in order to consume message payload as string data.
  • Mono<T>, Flux<T> or Publisher<T> in order to consume message payload as encoded data in which case the negotiated subprotocol is used to determine the MediaTypeConverter to use to decode message content.

In above inbound and outbound data definition, each published element is interpreted as a single message content, in order to send or receive messages with fragmented payloads, publishers of publishers can be specified as for instance Flux<Flux<String>>.

A simple WebSocket endpoint can be defined as follows in a Web client stub: 


 @WebClient( uri = "http://host:8080/chat" )
 public interface ChatClient {
 
     @WebRoute( subprotocol = json" )
     Flux<Message> joinChat(Flux<Message> outbound);
 }
Since:
1.12
Author:
Jeremy Kuhn

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    closeOnComplete
    Specifies whether the WebSocket exchange should be closed when the outbound frames publisher completes successfully.
    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.
    WebSocketMessage.Kind
    messageType
    The type of WebSocket messages consumed and produced by the WebSocket.
    String
    path
    The path to the WebSocket endpoint relative to the destination URI.
    String
    subprotocol
    The subprotocol specifying the message format and used to resolve the MediaTypeConverter used to encode and decode inbound and outbound messages.

  • Element Details

    • path

      String path

      The path to the WebSocket endpoint relative to the destination URI.

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

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

      Returns:
      a path
      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:
      {}

    • subprotocol

      String subprotocol

      The subprotocol specifying the message format and used to resolve the MediaTypeConverter used to encode and decode inbound and outbound messages.

      Returns:
      a subprotocol
      Default:
      ""

    • messageType

      WebSocketMessage.Kind messageType

      The type of WebSocket messages consumed and produced by the WebSocket.

      Returns:
      a WebSocket message type
      Default:
      TEXT

    • closeOnComplete

      boolean closeOnComplete

      Specifies whether the WebSocket exchange should be closed when the outbound frames publisher completes successfully.

      Returns:
      true to close the WebSocket exchange when the outbound frames publisher completes, false otherwise
      See Also:
      Default:
      true