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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ExtendedExtension.ExtensionContext Context present as a parameter in all ExtendedExtension methods.

Nested classes/interfaces inherited from interface jakarta.websocket.Extension

Extension.Parameter

Method Summary

Modifier and Type	Method and Description
void	destroy(ExtendedExtension.ExtensionContext context) Context lifecycle method.
java.util.List<Extension.Parameter>	onExtensionNegotiation(ExtendedExtension.ExtensionContext context, java.util.List<Extension.Parameter> requestedParameters) Parameter negotiation.
void	onHandshakeResponse(ExtendedExtension.ExtensionContext context, java.util.List<Extension.Parameter> responseParameters) Called only on the client side when handshake response arrives.
Frame	processIncoming(ExtendedExtension.ExtensionContext context, Frame frame) Process incoming frame.
Frame	processOutgoing(ExtendedExtension.ExtensionContext context, Frame frame) Process outgoing frame.

Methods inherited from interface jakarta.websocket.Extension

getName, getParameters

Method Detail

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

java.util.List<Extension.Parameter> onExtensionNegotiation(ExtendedExtension.ExtensionContext context,
                                                           java.util.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,
                         java.util.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.