Package org.xwiki.websocket

Interface WebSocketContext

@Role
public interface WebSocketContext

Component used to initialize and bind a WebSocket execution context to a WebSocket session, and to run code within that context when a WebSocket session is opened or when receiving messages.

Since:

13.7RC1

Version:

$Id: 1dbca681657ae04b24fca4a5ae688db6bd65769d $

Method Summary

Modifier and Type	Method	Description
<T> T	call(javax.websocket.Session session, Callable<T> callable)	Call some code within the WebSocket context bound to the given WebSocket session.
void	initialize(javax.websocket.server.ServerEndpointConfig config, javax.websocket.server.HandshakeRequest request, javax.websocket.HandshakeResponse response)	Initializes a new WebSocket context for the specified WebSocket end-point and binds it to the WebSocket connection (session).
void	run(javax.websocket.Session session, Runnable runnable)	Runs some code within the WebSocket context bound to the given WebSocket session.

Method Detail

initialize

void initialize(javax.websocket.server.ServerEndpointConfig config,
                javax.websocket.server.HandshakeRequest request,
                javax.websocket.HandshakeResponse response)

Initializes a new WebSocket context for the specified WebSocket end-point and binds it to the WebSocket connection (session). The context must be created and initialized when the WebSocket handshake is performed because later (during session opening and message handling) we don't have access to the HTTP request (headers, cookies) and response. This method is normally called by ServerEndpointConfig.Configurator.modifyHandshake(ServerEndpointConfig, HandshakeRequest, HandshakeResponse).

Note that we cannot create the execution context inside a servlet filter because servlet filters are not necessarily applied to WebSocket (upgrade) requests (it's not specified in the WebSocket JSR).

Parameters:

config - the WebSocket end-point configuration, used to bind the initialized context to the WebSocket session

request - the handshake request used to initialize the WebSocket context (e.g. authenticate the user)

response - the handshake response used to initialize the WebSocket context

run

void run(javax.websocket.Session session,
         Runnable runnable)

Runs some code within the WebSocket context bound to the given WebSocket session. This method is usually called when the WebSocket session is opened and when receiving messages because they happen in different threads and so we cannot rely on thread-local variables. Instead, we rely on the WebSocket session to pass and share the WebSocket context.

Parameters:

session - the WebSocket session used to retrieve the WebSocket context

runnable - the code to run

call

<T> T call(javax.websocket.Session session,
           Callable<T> callable)
    throws Exception

Call some code within the WebSocket context bound to the given WebSocket session. This method is usually called when receiving messages because they happen in different threads and so we cannot rely on thread-local variables. Instead, we rely on the WebSocket session to pass and share the WebSocket context.

Type Parameters:

T - the type of value returned by the code to execute

Parameters:

session - the WebSocket session used to retrieve the WebSocket context

callable - the code to call

Returns:

the value returned by the executed code

Throws:

Exception - if the code to execute throws an exception (it simply lets the exception propagate)