jWebSocket "Hello World"

This section shows you how you can easily create your first jWebSocket "Hello World" client from scratch. "Hello World" requires an already running jWebSocket Server. For your first tests you can use ours at ws://jWebSocket.org:8787, you can test it here. In the Installation-Guide you will find how to setup your own jWebSocket Server in less than 5 minutes.

Basically a WebSocket communication between client and server needs to be initiated by the client. Once the connection is established the client sends messages either to the server or to other clients via the server. In the opposite direction the server sends messages to the client by using the same connection. Unless the connection is terminated either by the server or the client both partners can bi-directionally exchange arbitrary messages. That's almost everything you need to start your first jWebSocket project.

Embedding the jWebSocket Script

The only thing you need to do, to use jWebSocket in your web pages is to put a single script tag into the head section of your HTML code.

Embedding jWebsocket.js into your HTML page

This makes jWebSocket available to your page. You can either use the full inline documented source code in jWebSocket.js, which is the best choice to learn jWebSocket or the minified version in jWebSocket_min.js which is recommended for your production system.

Creating the jWebSocketClient instance

jWebSocket provides the jWebSocketJSONClient class within the jWebSocket specific namespace jws. This class provides the methods to connect and disconnect as well as to exchange messages with the server by using the JSON protocol. The namespace avoids naming conflicts with other frameworks.

// jws.browserSupportsWebSockets checks if web sockets are available
// either natively, by the FlashBridge or by the ChromeFrame.
if( jws.browserSupportsWebSockets() ) {
  jWebSocketClient = new jws.jWebSocketJSONClient();
  // Optionally enable GUI controls here
} else {
  // Optionally disable GUI controls here
  var lMsg = jws.MSG_WS_NOT_SUPPORTED;
  alert( lMsg );
}

Instantiating the jWebSocket Client

Connect and Logon

In order to initiate the connection from the client to the server the logon method of the jWebSocketClient can be used. This method connects to the server and passes username and password for the authentication.

log( "Connecting to " + lURL + " and logging in as '" + gUsername + "'..." );
var lRes = jWebSocketClient.logon( lURL, gUsername, lPassword, {
  // OnOpen callback
  OnOpen: function( aEvent ) {
    log( "jWebSocket connection established." );
  },
  // OnMessage callback
  OnMessage: function( aEvent, aToken ) {
    log( "jWebSocket '" + aToken.type + "' token received, full message: '" + aEvent.data + "'" );
  },
  // OnClose callback
  OnClose: function( aEvent ) {
    log( "jWebSocket connection closed." );
  }
});

Authenticating a gainst then jWebSocket Server

The server assigns a unique Id to the client, so that a certain client can always be uniquely addressed even if the same user logs in at multiple browser instances.

Sending and Broadcasting Tokens

If the connection was successfully established the client sends its messages via the send method to another client or broadcasts it to all connected clients by using the broadcast method of the jWebSocketClient.

// lMsg is a string
if( lMsg.length > 0 ) {
  var lRes = jWebSocketClient.broadcastText(
    "",   // broadcast to all clients (not limited to a certain pool)
    lMsg  // broadcast this message
  );
  if( lRes.code != 0 ) {
    // display error
  }
}

Broadcasting a message with jWebSocket

Sending messages is always non-blocking, i.e. the both send and broadcast do not wait until a potential result is returned. An optional result is returned asynchronously as described in the next section.

Processing Incoming Messages

Messages from the server to the client are pushed asynchronously. Therefore the jWebSocketClient class provides the OnMessage event. As already shown above in the logon method your application simply adds a listener to this event and processes the message as desired.

  :
  // OnMessage callback
  OnMessage: function( aEvent, aToken ) {
    log( "jWebSocket '" + 
      aToken.type + "' token received, full message: '" + 
      aEvent.data + "'"
    );
  },
  :

Processing incoming messages

You will find a reference to the jWebSocket Token set here.

Logoff and Disconnect

On demand both server and client can terminate an existing connection. On the client side this is done by the close method of the jWebSocketClient.

if( jWebSocketClient ) {
  jWebSocketClient.close();
}

Closing the connection on the client

The server automatically terminates the connection after a certain time of inactivity on the line. In this case the OnClose event is fired which can be handled by the corresponding callback as shown in logon method above. The timeout can be configured and you can optionally run a keep-alive or a re-connect watchdog.