Package org.glassfish.tyrus.core.extension

Interface ExtendedExtension

All Superinterfaces:
Extension
public interface ExtendedExtension extends Extension
WebSocket Extension.

Capable of parameters negotiation, incoming and outgoing frames processing.

Extensions are ordered as they appear in handshake response headers, as per RFC 6455, chapter 9.1. It does not state any ordering in regards of sender/receiver side and current implementation reflects that. See TODO below for possible issue related to ordering.

Let's say we have negotiated two extensions, ext1 and ext2 in this order without parameters, so handshake response headers will be: "sec-websocket-extensions: ext1, ext2". Prefix "c_" means client side, prefix "s_" server side. 

   client -> server

                +--------+   +--------+                  +--------+   +--------+
   client  >----| c_ext1 |-->| c_ext2 |--> [network] --> | s_ext1 |-->| s_ext2 |--> server
                +--------+   +--------+                  +--------+   +--------+

   client <- server

                +--------+   +--------+                  +--------+   +--------+
   client  <----| c_ext2 |<--| c_ext1 |<-- [network] <-- | s_ext2 |<--| s_ext1 |<-- server
                +--------+   +--------+                  +--------+   +--------+

Any exception thrown from processIncoming or processOutgoing will be logged. Rest of extension chain will be invoked without any modifications done in "faulty" extension. OnError won't be triggered. (this might change). 

TODO:\
 - naming.
 - ordering - we might need to ensure that compression/decompression is invoked first when receiving and last when
 sending message (to enable access to uncompressed data for other extensions).
 - param negotiation.
 - param validation.
 - general validation - two extensions using same rsv bit cannot be "negotiated" for same session/connection.
 - negotiation exception handling (onExtensionNegotiation)
Author:
Pavel Bucek

  • Method Details

    • processIncoming

      Frame processIncoming(ExtendedExtension.ExtensionContext context, Frame frame)
      Process incoming frame.

      Passed frame is unmasked in case it was masked when received (server to client communication).

      Parameters:
      context - per-connection/session context.
      frame - websocket frame representation.
      Returns:
      processed frame. Can be new instance.

    • processOutgoing

      Frame processOutgoing(ExtendedExtension.ExtensionContext context, Frame frame)
      Process outgoing frame.

      Passed frame is unmasked. Frame payload will be masked when required (server to client communication).

      Parameters:
      context - per-connection/session context.
      frame - websocket frame representation.
      Returns:
      processed frame. Can be new instance.

    • onExtensionNegotiation

      List<Extension.Parameter> onExtensionNegotiation(ExtendedExtension.ExtensionContext context, List<Extension.Parameter> requestedParameters)
      Parameter negotiation. Executed before handshake response is sent to the client (server only). Returned list of parameters will be present in handshake response headers.

      TODO: Seems like list of all "requested" extensions should be passed (at least all with the same name) - the TODO: extension implementation should be able to choose which version (parameter set) will be used for the TODO: established WebSocket session. (We should also properly describe that this method will be called only once TODO: per extension per websocket session and have the possibility to NOT add this extension to negotiated TODO: extensions).

      Parameters:
      context - extension context.
      requestedParameters - requested parameters (from handshake request).
      Returns:
      parameters to be present in handshake response.

    • onHandshakeResponse

      void onHandshakeResponse(ExtendedExtension.ExtensionContext context, List<Extension.Parameter> responseParameters)
      Called only on the client side when handshake response arrives.

      Can be used to process extension parameters returned from server side.

      Parameters:
      context - extension context.
      responseParameters - extension parameters returned from the server.

    • destroy

      void destroy(ExtendedExtension.ExtensionContext context)
      Context lifecycle method. ExtendedExtension.ExtensionContext won't be used after this method is called.
      Parameters:
      context - extension context to be destroyed.