Quick Start Guide

So you heard that Kaazing has made Gateway open source, and have decided that it is time to take the real-time plunge? Brilliant! If you have been doing request/response for a while, the change to event-driven can be intimidating, but we have your back. Lean in, follow along, and take your first steps into the world of real-time.


Jump to the Live Demo


First, a quick splash of background. Gateway differs from other real-time solutions you may have encountered based on WebSocket or HTTP Keep-Alive (long polling). Gateway integrates with enterprise standard message brokers, and passes all the benefit over to your application. Some of these benefits include …

If that seems like a decent number of benefits to consider, we agree! To help you get your head around all of it, the following tutorial in easy to digest steps.

New Tricks

The first step in getting all these feature benefits is to teach the browser a new trick - how to speak to a message broker.

Client libraries (JavaScript, Java, iOS, and more) to make this happen are part of Gateway. For this example, we are going to use the messaging standard, AMQP, with JavaScript. You can download the AMQP libraries from the Kaazing GitHub repository.

In the “javascript” directory, you can find “Amqp-0-9-1.js” library. You can drop this into your web page to teach your browser these new tricks. For this example, we will be using a helper library which loads this script for you.

Connecting

Communication to a message broker works on a pattern called “publish/subscribe”. Sending messages is called “publish” and happens to a named exchange on the message broker. “Subscribe” allows your application to listen for messages from any number of queues. In the case of AMQP, queues are bound to exchanges via a route. If you are familiar with other publish/subscribe systems, you might think of this as a “topic.”

Using publish/subscribe, you can have numerous systems sending and receiving messages without knowing anything about one another. The systems do not even have to be the same technology stack - and Internet of Things devices can participate in the conversation, too.

As you might imagine, taking advantage of the aforementioned features can introduce quite the API. For this example, using basic publish/subscribe, we have wrapped all the defaults into a separate JavaScript file called “gateway.js”. Drop this file into your page, and all you have to think about is the actual act of publishing and subscribing.

1
2
3
// Configure real-time communication	
kaazing = Gateway.connect( KAAZING_ID );
kaazing.on( Gateway.EVENT_MESSAGE, doConsumeMessage );

Publish

In this example we will send the mouse movements from one screen, to any other screens connected to the broker.

When the mouse (or touch point) is down, the application will send the position of the mouse position. So long as the pointer is down, the coordinates will continue to be sent. When the mouse is released, a message to that effect will be sent, and the event listeners removed.

1
2
3
4
5
6
7
8
9
// Broadcast event and coordinates
// Data is sent to a specific topic
// Map touch or mouse to similar structure
kaazing.publish( QUICK_START, JSON.stringify( {
    action: DOCUMENT_DOWN,
    changes: mapPoints( event ),
    color: color,
    touch: touch
} ) );

Subscribe

Regardless of the client issuing the pointer event messages, nothing will be rendered (in this configuration) until the messages arrive to the clients that are subscribed to that data. When the data arrives, a graphic indicator is placed on the screen at the corresponding position.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Called when a message arrives
// Decodes message to data structure
// Decision tree based on content
function doConsumeMessage( message )
{
    var config = null;
    var data = null;

    // Turn String message into JSON data
    data = JSON.parse( message );

    // Decision tree
    // Based on custom message content
    if( data.action == DOCUMENT_DOWN )
    {
        // Interaction is down
        // Build and place visual indicators
    } else if( data.action == DOCUMENT_MOVE ) {
        // Moving interactions
        // Reposition visual indicators
    } else if( data.action == DOCUMENT_UP ) {
        // Interaction is up
        // Remove visual indicator for specific change
    }
}

Upon connecting, we register an event listener for messages called “doConsumeMessage.” That function is called when a message arrives, and includes the String content of the message. There are various other properties on the message event that can be accessed by using the Gateway AMQP library directly. In this case, the content received in doConsumeMessage is the “body” property of the event.

The message body is sent and received in a binary format. Convenience methods are invoked to convert the binary content to String content for this example. At that point we have JSON data ready to be parsed into a JavaScript object. Also note that since this example supports touch events, and there can be more than one touch at a time, the pointer data is presented as an Array.

Conclusion

Presenting a remote mouse is really just scratching the surface of the possibilities of Kaazing Gateway. Once you have the ability to push data to clients in real-time, a whole new world starts to emerge. Kaazing has customers in finance, logistics and more. Let us help you deliver real-time features in your next project!


Jump to the Live Demo