WebsocketRegister Function

The WebsocketRegister function is used to configure the server to accept WebSocket connections at the specified endpoint, and registers a listener component to handle events of WebSocket connections made to that endpoint.

WebsocketRegister(String endpoint, Component listener):ConnectionManager

It takes two arguments:

@param endpoint - a String that specifies the URI for incoming connections

@param listener - a Component that utilizes the Listener Component API

And returns:

@returns - a ConnectionManager object that is specific to that endpoint

Usage

You only need to call WebsocketRegister() once, so one good place to put it is in Application.cfc's onApplicationStart() method. If your listener component changes for whatever reason, though, you will have to register the new one with the endpoint by calling that function again.

/** Application.cfc */
function onApplicationStart(){

    var endpoint = "/ws/echo";
    var listener = new EchoListener();

    WebSocketRegister(endpoint, listener);
}

At this point your listener object will receive events to the methods that it implements as per the Listener Component API.

Endpoint Path Parameteres

Endpoints can specify path parameters, or placeholder templates, which will be resolved at runtime according to the URI that the client used. The placeholder is specified using the brace symbols, { and }.

For example, you can specify the endpoint to be /ws/user/{userid}, and then a connection to /ws/user/isapir will be accepted and the path param userid will be resolved to isapir, while a connection to /ws/user/micstriit will be accepted and the path param userid will be resolved to micstriit.

One of the interesting things you can do is to subscribe the incoming websocket connection to a channel with that name, which will allow you to easily send messages to that user via the ConnectionManager's broadcast() method.

You can retrieve the Path Parameters in your code via WebSocket's getPathParameters() method.

Keep in mind that even though this is one user, she might have several WebSocket connections opened, if for example she has multiple browser tabs opened to the site and each tab has opened a WebSocket connection.

Endpoint Path Parameters channel

There is a special endpoint placeholder named channel. What's special about it, is that when you use it, every connection that is opened is automatically subscribed to the channel specified in the path.

So given the endpoint /ws/chat/{channel}, for example, any user that connects to the endpoint /ws/chat/developers will be automatically subscribed to the channel developers, while any user that connects to the endpoint /ws/chat/singles will be automatically subscribed to the channel singles.

Then using the ConnectionManager's broadcast() method, you can send a message to everyone in the singles channel:

// assuming that Application.connManagerChat is the ConnectionManager 
// for endpoint `/ws/chat/{channel}`
Application.connManagerChat.broadcast("singles", "Com'on people, mingle!");

See Also

• Example: Echo