Listener Component API

The Listener Component is a simple CFC that you write in order to handle WebSocket events. It may implement any of the methods below, which will be called by the WebSocket extension when certain events are triggered.

All of the methods are optional, meaning that you don't need to implement any method that handles an event which you prefer to ignore.

All of the methods are called with named arguments, meaning that using different names or order in the method signature will have no affect on the arguments.

onHandshake:

This method is called when a client websocket initiates a connection and performs a "handshake". It allows you to inspect the values and reject the connection by returning false or throwing an exception.

onHandshake(endpointConfig, request, response, sessionScope, applicationScope)[:boolean]

@param endpointConfig - javax.websocket.server.ServerEndpointConfig - see https://docs.oracle.com/javaee/7/api/javax/websocket/server/ServerEndpointConfig.html

@param request - javax.websocket.server.HandshakeRequest - see https://docs.oracle.com/javaee/7/api/javax/websocket/server/HandshakeRequest.html

@param response - javax.websocket.HandshakeResponse - see https://docs.oracle.com/javaee/7/api/javax/websocket/HandshakeResponse.html

@param sessionScope - the Session Scope associated with the incoming connection

@param applicationScope - the Application Scope associated with the incoming connection

returning (optional) a falsey value, or throwing an exception will terminate the incoming connection

onOpen:

This method is called when a connection from a client websocket is being opened. It allows you to inspect the values and reject the connection by returning false or throwing an exception.

onOpen(websocket, endpointConfig, sessionScope, applicationScope)[:boolean]

@param websocket - see WebSocket API

@param endpointConfig - javax.websocket.EndpointConfig - see https://docs.oracle.com/javaee/7/api/javax/websocket/EndpointConfig.html

@param sessionScope - the Session Scope associated with the incoming connection

@param applicationScope - the Application Scope associated with the incoming connection

returning (optional) a falsey value, or throwing an exception will terminate the incoming connection

onMessage:

This method is called when the client websocket sends a message. Currently only text messages are implemented.

onMessage(websocket, message, sessionScope, applicationScope)[:string]

@param websocket - see WebSocket API

@param message - String

@param sessionScope - the Session Scope associated with the incoming connection

@param applicationScope - the Application Scope associated with the incoming connection

returning (optional) a String object will send it back to the websocket client as a reply.

onError:

This method is called when an error occurs, usually terminating the connection.

onError(websocket, throwable, sessionSCope, applicationScope)

@param websocket - see WebSocket API

@param throwable - see https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html

@param sessionScope - the Session Scope associated with the incoming connection

@param applicationScope - the Application Scope associated with the incoming connection

onClose:

This method is called when the connection is closed.

onClose(websocket, closeReason, sessionSCope, applicationScope)

@param websocket - see WebSocket API

@param closeReason - javax.websocket.CloseReason - see https://docs.oracle.com/javaee/7/api/javax/websocket/CloseReason.html

@param sessionScope - the Session Scope associated with the incoming connection

@param applicationScope - the Application Scope associated with the incoming connection

onChannelOpen:

This method is called when a new channel is opened

onChannelOpen(channel, connectionManager)

@param channel - String - the channel name

@param connectionManager - see ConnectionManager API

onChannelClose:

This method is called when a channel is closed

onChannelClose(channel, connectionManager)

@param channel - String - the channel name

@param connectionManager - see ConnectionManager API

onSubscribe:

This method is called when a websocket connection subscribes to a channel

onSubscribe(channel, subscribers, websocket, connectionManager)

@param channel - String - the channel name

@param subscribers - int - the number of subscribers for that channel

@param websocket - see WebSocket API - the websocket connection that has subscribed to the channel

@param connectionManager - see ConnectionManager API

onUnsubscribe:

This method is called when a websocket connection unsubscribes from a channel. If all of the users have unsubscribed then the channel is closed, and the onChannelClose event will fire.

onUnsubscribe(channel, subscribers, websocket, connectionManager)

@param channel - String - the channel name

@param subscribers - int - the number of subscribers for that channel

@param websocket - see WebSocket API - the websocket connection that has unsubscribed from the channel

@param connectionManager - see ConnectionManager API