Top Description Inners Methods
org.glassfish.tyrus.core.extension

public Interface ExtendedExtension

extends Extension
Imports
java.util.List, .Map, jakarta.websocket.Extension, org.glassfish.tyrus.core.frame.Frame

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. jakarta.websocket.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 and Inner Type Summary

Modifier and TypeClass and Description
public static interface
ExtendedExtension.ExtensionContext

Context present as a parameter in all ExtendedExtension methods.

Method Summary

Modifier and TypeMethod and Description
public void
destroy(ExtendedExtension.ExtensionContext
extension context to be destroyed.
context
)

Context lifecycle method.

public List<Extension.Parameter>

Returns:

parameters to be present in handshake response.
onExtensionNegotiation
(ExtendedExtension.ExtensionContext
extension context.
context
,
List<Extension.Parameter>
requested parameters (from handshake request).
requestedParameters
)

Parameter negotiation.

public void
onHandshakeResponse(ExtendedExtension.ExtensionContext
extension context.
context
,
List<Extension.Parameter>
extension parameters returned from the server.
responseParameters
)

Called only on the client side when handshake response arrives.

public Frame

Returns:

processed frame. Can be new instance.
processIncoming
(ExtendedExtension.ExtensionContext
per-connection/session context.
context
,
Frame
websocket frame representation.
frame
)

Process incoming frame.

public Frame

Returns:

processed frame. Can be new instance.
processOutgoing
(ExtendedExtension.ExtensionContext
per-connection/session context.
context
,
Frame
websocket frame representation.
frame
)

Process outgoing frame.

Inherited from jakarta.websocket.Extension:
getNamegetParameters

Method Detail

destroyback to summary
public void destroy(ExtendedExtension.ExtensionContext context)

Context lifecycle method. ExtendedExtension.ExtensionContext won't be used after this method is called.

Parameters
context:ExtendedExtension.ExtensionContext

extension context to be destroyed.

onExtensionNegotiationback to summary
public 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:ExtendedExtension.ExtensionContext

extension context.

requestedParameters:List<Extension.Parameter>

requested parameters (from handshake request).

Returns:List<Extension.Parameter>

parameters to be present in handshake response.

onHandshakeResponseback to summary
public 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:ExtendedExtension.ExtensionContext

extension context.

responseParameters:List<Extension.Parameter>

extension parameters returned from the server.

processIncomingback to summary
public 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:ExtendedExtension.ExtensionContext

per-connection/session context.

frame:Frame

websocket frame representation.

Returns:Frame

processed frame. Can be new instance.

processOutgoingback to summary
public 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:ExtendedExtension.ExtensionContext

per-connection/session context.

frame:Frame

websocket frame representation.

Returns:Frame

processed frame. Can be new instance.

org.glassfish.tyrus.core.extension back to summary

public Interface ExtendedExtension.ExtensionContext


Context present as a parameter in all ExtendedExtension methods. Maintains per connection state of current extension.

Context is created right before onExtensionNegotiation(ExtendedExtension.ExtensionContext, java.util.List) method call (server-side) or onHandshakeResponse(ExtendedExtension.ExtensionContext, java.util.List) method call (client-side). Last chance to access it is within destroy(ExtendedExtension.ExtensionContext) method invocation.

Method Summary

Modifier and TypeMethod and Description
public Map<String, Object>

Returns:

property map.
getProperties
()

Mutable, not synchronised property map.

Method Detail

getPropertiesback to summary
public Map<String, Object> getProperties()

Mutable, not synchronised property map.

Synchronisation is not necessary if you are accessing this map only during ExtendedExtension methods invocation.

Returns:Map<String, Object>

property map.