Migrate JavaScript Applications to Kaazing Gateway 4.x

This topic explains how to migrate Kaazing Gateway 3.3-3.5 JavaScript clients built using the ByteSocket API to the WebSocket API in Kaazing Gateway 4.x. Kaazing Gateway 4.x no longer includes the ByteSocket API because the WebSocket API in the Kaazing Gateway 4.x JavaScript library supports binary messaging.

After the simple code changes described in this topic, updated ByteSocket implementations can continue to deliver binary messages using a ByteBuffer object in which you store the bytes that you want to send. The ByteBuffer interface is now included in the WebSocket library to support existing ByteBuffer implementations. To continue to use ByteBuffer, you must replace references to ByteSocket.js with WebSocket.js.

Notes:

Before You Begin

This procedure is part of Checklist: Build JavaScript WebSocket Clients.

Note: Learn about supported browsers, operating systems, and platform versions in the Release Notes.

To Migrate ByteSocket Applications to Kaazing Gateway 4.x

  1. In your JavaScript client, replace the following script tag: 
    <script src="/javascript/ByteSocket.js"></script>

    with script tags for the WebSocket library (that also contains the ByteBuffer code):

    <script src="/javascript/WebSocket.js"></script>
  2. Replace ByteSocket objects with WebSocket objects. For example, replace: 
    byteSocket = new ByteSocket("ws://example.com:8000/path");

    with:

    var factory = new WebSocketFactory();
websocket = factory.createWebSocket("ws://example.com:8000/path");
websocket.binaryType = "bytebuffer";

    The websocket.binaryType = "bytebuffer" statement creates a ByteBuffer object with the data received from the WebSocket message event. This is similar to how ByteSocket data objects were managed in Kaazing Gateway 3.x.

  3. The remaining code from a ByteSocket object needs only a minor change (highlighted below). When you send messages, you send binary data using a ByteBuffer object as shown in the following example. Since you are sending binary data, you first have to create a ByteBuffer object in which you store the bytes that you want to send.

    Here is an example of ByteSocket code from earlier versions of Kaazing Gateway. The function takes a text string entered by a user (message.value), puts the string into a buffer using the UTF-8 character set to encode the string as bytes (putString()), flips the buffer to put in read mode (flip()), and sends the buffer to the Gateway (byteSocket.send(buf)):

    send.onclick = function() {
    var buf = new ByteBuffer();
    buf.putString(message.value, Charset.UTF8);
    buf.flip();
    log("SENT: " + buf);
    byteSocket.send(buf);
}

    Here is the equivalent function in WebSocket code from Kaazing Gateway 4.x:

    send.onclick = function() {
    var buf = new ByteBuffer();
    buf.putString(message.value, Charset.UTF8);
    buf.flip();
    log("SENT: " + buf);
    websocket.send(buf);
}

    Note that the only different in these functions is that the ByteSocket object (byteSocket) is changed to a WebSocket object (websocket).

For more information, see the ByteBuffer in the JavaScript API.

Binary Support with Blob and Array Buffer

In addition to including binary support with ByteBuffer, Kaazing Gateway 4.x includes support for blob and array buffer.

Here is an example of a function using blob:

//  Run this function when the Send Blob button is clicked
sendBlob.onclick = function() {
    try {
        /* Use BlobUtils to create a Blob from a string via UTF-8 encoding. 
        Returns a blob instance*/
        var blob = BlobUtils.fromString(message.value, "transparent");
        // Log the blob
        log("SEND BLOB: " + blob);
        // Identify the data type of the WebSocket connection as blob
        websocket.binaryType = "blob";
        // Send the blob over WebSocket
        websocket.send(blob);
    } catch (e) {
        log("EXCEPTION: "+e);
    }
}

Note the binaryType specified for the WebSocket message is websocket.binaryType = "blob". Blob is the default binary type for a binary message, but you must specify a value for binaryType.

Here is an example of a function using ByteBuffer and the browser’s support for ArrayBuffer to convert a string into binary and then send that binary as an array buffer:

// Takes a string and returns an array of bytes decoded as UTF8
var getBytes = function(str) {
    // Create a new ByteBuffer container for the binary data
    var buf = new ByteBuffer();
    // Encode a string into a ByteBuffer
    Charset.UTF8.encode(str, buf);
    /* Flip the buffer so that it can be read starting at 0,
    switching the buffer from writing mode to reading mode.
    */
    buf.flip();
    // Return the byte array to the sendArrayBuffer function
    return buf.array;
}

// Run this function when the Send Array Buffer button is clicked
sendArrayBuffer.onclick = function() {
    try {
        /* Send the text message to the getBytes function,
        and get a byte buffer array back
        */
        var bytes = getBytes(message.value);
        // View the byte buffer as an array of 8-bit unsigned integers
        var array = new Uint8Array(bytes);
        // Identify the data type of the WebSocket connection as arraybuffer
        websocket.binaryType = "arraybuffer";
        // Send the array buffer over WebSocket
        websocket.send(array.buffer);
    } catch (e) {
        // Log exceptions
        log("EXCEPTION: "+e);
    }
}

Note the binaryType specified for the WebSocket message is websocket.binaryType = "arraybuffer". Always specify the binaryType when sending a message as an Array Buffer.

Next Step

Secure Your JavaScript Client

See Also

JavaScript API documentation