Kaazing WebSocket Gateway
Orange guy with box of questions

How to Use the JavaScript DarkstarClient Client Library

Technologies used: Project Darkstar and JavaScript

This document contains the following sections:

Overview of Project Darkstar

Project Darkstar is an open-source gaming software infrastructure project. Originally created by Sun Microsystems it is now maintained by the Project Darkstar Community. Project Darkstar makes it easier to develop and run highly-scalable online games, virtual worlds, and social networking applications. Project Darkstar was built to address a slew of common gaming scalability problems such as zone overloading, data corruption, and server under-utilization.

For more information about Project Darkstar, visit http://www.projectdarkstar.com.

WebSocket and Project Darkstar

WebSocket enables direct communication from the browser to a Project Darkstar Server (PDS). Kaazing Gateway provides the DarkstarClient client library, which radically simplifies Web application design. Web developers can use the browser’s native JavaScript support and code directly against the back-end PDS without the need for custom Servlets or server-side programming.

Using the DarkstarClient JavaScript client library, you can take advantage of the Project Darkstar features, making JavaScript a first-class citizen in Project Darkstar systems (similar to C and Java clients). This means that you can not only run Project Darkstar games directly in a browser, but you can also expose parts of an existing game in a browser. For example, you can expose a game's chat interface in the browser so that users can stay connected to their gaming friends when they are "working."

The DarkstarClient JavaScript library uses Kaazing's ByteSocket client library, because Project Darkstar protocol sends only binary data. Since the implementation is layered on top of ByteSocket, which uses WebSocket--and thus the entire stack of Kaazing HTML 5 Communications client libraries--applications developed using the DarkstarClient JavaScript library are provided with guaranteed persistence, reliability, and message-receipt acknowledgment all the way to the browser.

Note: You should be familiar with Project Darkstar before you start creating a Web application using the DarkstarClient JavaScript client library.

Taking a Look at the Project Darkstar Demo

Before you start, take a look at a demonstration that was built with the DarkstarClient JavaScript library: the Project Darkstar Web client demo that is part of the Kaazing Gateway demo bundle. To see this demo in action, perform the following steps:

  1. Start the Kaazing WebSocket Gateway demo bundle as described in Getting Started.
  2. In a browser, navigate to http://localhost:8000/demo/demo.html#darkstar.

The PDS's HelloChannels tutorial demonstrates how a PDS manages data channels. When you log in to the PDS, it creates a client/server connection for you so you can communicate privately with the PDS. The server also joins you to publish/subscribe channels that you have to be a part of to participate in a game (for example, a poker table publish/subscribe channel that broadcasts table actions). The demo requires a connection to a PDS. The next section describes how to set up a local PDS and run the HelloChannels demo.

In the HelloChannels demo you are automatically joined to the Foo and Bar channels and you can send messages to those channels. You can also send private messages to the PDS using the client/server connection. In games, you send private data (for example, information about poker cards that are only dealt to you) to the session and you send shared data (for example, poker cards that are dealt to an entire table) to a publish/subscribe channel.

Note: This demo makes it look like information is sent to the different channels in text format. However, the Project Darkstar protocol always sends only binary data, so behind the scenes the client encodes the text and adds it to a ByteBuffer object before sending it to the PDS. In a real game, the information exchange would likely use a binary format directly.

Setting Up a Project Darkstar Server

To set up a PDS on your local system, perform the following steps:

  1. Download the Project Darkstar Server (source and binary) from http://www.projectdarkstar.com/current-distribution.html.
  2. Unpack the distribution into a directory of your choice (for example, C:\darkstar\sgs-server-dist-0.9.8). This directory contains the PDS and its components and is referred to as DARKSTAR_HOME in the Kaazing documentation.
  3. Open a command prompt and navigate to DARKSTAR_HOME.
  4. Run  java -jar bin/sgs-boot.jar tutorial/conf/HelloChannels.boot
    This runs the bootable PDS jar file and starts the HelloChannels tutorial demo.
  5. Start Kaazing Gateway as described in Getting Started.
  6. Open a browser and navigate to http://localhost:8000/demo/demo.html#darkstar and log in to the demo to verify that it is working.

Configuring Kaazing Gateway to Connect to a Project Darkstar Server

The following is an example of the default configuration element for the Darkstar service, as specified in the configuration file KAAZING_HOME/conf/gateway-config.xml:

<!-- Proxy to local Darkstar server -->
<service>
  <!-- ws:// scheme refers to WebSocket -->
  <!-- wss:// scheme refers to WebSocket (secure) -->
  <accept>ws://localhost:8000/darkstar</accept>
  <accept>wss://localhost:9000/darkstar</accept>

  <type>proxy</type>
  <properties>
    <connect>tcp://localhost:1139</connect>
  </properties>

  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
  <cross-site-constraint>
    <allow-origin>https://localhost:9000</allow-origin>
  </cross-site-constraint>
</service>

As you can see, this service is configured to accept WebSocket Project Darkstar requests from the browser at ws://localhost:8000/darkstar and securely at wss://localhost:9000/darkstar and proxy those requests to the locally installed PDS (localhost) at port 1139 (PDS servers typically use port 1139).

To configure Kaazing Gateway to accept WebSocket requests at another URL or to connect to a different PDS, you can edit KAAZING_HOME/conf/gateway-config.xml, update the values for the accept elements or change the connect property, save the file, and restart Kaazing Gateway. For example, the following configuration configures Kaazing Gateway to accept WebSocket Project Darkstar requests at ws://localhost:8011/darkstar and proxy those requests to a remote PDS (darkstar.example.com) on port 1139.

<!-- Proxy to Darkstar server -->
<service>
  <accept>ws://localhost:8011/darkstar</accept>

  <type>proxy</type>
  <properties>
    <connect>tcp://darkstar.example.com:1139</connect>
  </properties>

  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
</service>

Using the DarkstarClient JavaScript Library in a Web Application

This section contains the following subsections:

Note: The DarkstarClient API is not finalized and is provided for evaluation purposes. Users of this protocol may have to change their code in future releases until the APIs are finalized. Your feedback is appreciated and can be provided at www.kaazing.org.

Creating the DarkstarClient Object

In this section you'll see how you create the DarkstarClient Object. Before you create the client object, open your Web application in your favorite editor and import the appropriate client libraries. In the <HEAD> section of your HTML Web application file, add the following script includes:

<script src="/html5/ByteSocket.js"></script>
<script src="/protocol/DarkstarClient.js"></script>

Since the Project Darkstar protocol sends only binary data, you must include a reference to the ByteSocket client library.

Next, create an instance of the DarkstarClient object as shown in the following example.

var client = new DarkstarClient();

Now that you have created an instance of the DarkstarClient object, you can use commands and attach callback functions to handle the interactions between the client and the PDS. As with all the Kaazing protocols, there are two types of functions--command functions and asynchronous callback functions.

  • Command Functions--Client-initiated operations that are sent from the client to the PDS. For example, to log in to the PDS, you use the login function. The following are the Project Darkstar command functions:
    • connect
    • disconnect
    • login
    • send
    • sendchannel
  • Asynchronous Callback Functions--Server messages that are sent from the PDS to the client at any time (asynchronously). For example, after a user has successfully logged in, the onloginsuccess callback function is called on the client. Some examples of Project Darkstar callback functions are:
    • onchanneljoin
    • onchannelleave
    • onchannelmessage
    • onclose
    • onopen

Refer to the DarkstarClient JavaScript API documentation for the complete list of all the Project Darkstar command and callback functions.

Connecting and Logging In to a Project Darkstar Server

In this section, you'll see how you can connect and log in to a PDS. This is a two-step process:

  1. First, you make a connection with Kaazing Gateway, which is configured to proxy requests to the PDS. To do this, you use the connect function and pass in the URL of the Darkstar service. This URL is the one specified in the accept element in the Kaazing Gateway configuration file KAAZING_HOME/conf/gateway-config.xml. By default it is ws://localhost:8000/darkstar). When you successfully connect, you receive the onopen callback.

client.connect(url);

  1. Next, you log in to the PDS by passing in the user name and password values.

client.login({username:"<user_name>", password:"<password>"});

Note: To simplify the caching of user credentials, Kaazing Open Gateway provides the plaintext keyring and Kaazing WebSocket Gateway provides the encrypted keyring. Refer to Kaazing Security Overview for more information about using the keyring.

The following example shows how you can use the onopen callback function, which is received after a connection to the PDS is established, to start the login process.

client.connect(url);
client.onopen = function() {
  // call the authorization callback passed in
  client.login(darkstarKey);
}

Once you have successfully logged in, a connection for client/server communication is created on the PDS and the onloginsuccess callback function is called on the client.

Note: A given user name can only be used in one connection at a time. Make sure you use different user names if your server does not require authentication.

Using Channels and Sending Messages

In this section you will see how you can use channels and send and receive Project Darkstar messages.

Using Channels

The PDS decides which channels a client is joined to. After the PDS joins you to a channel, the onchanneljoin callback function is called on the client. This notifies the client that the PDS has joined you to a specific channel. When you are removed from a channel, the onchannelleave callback function is called on the client. The following example shows how you can use the data that is returned in the onchanneljoin callback function.

client.onchanneljoin = function(id, name) {
  alert('You have joined channel ' + name + ' with the id ' + id);
}

Sending and Receiving Messages

Once you are joined to a channel, you can send a message using the sendchannel command (for shared messages to the publish/subscribe channel) or the send command (for private client/server communication messages) as shown in the following example. Since the Project Darkstar protocol sends only binary data, you use a ByteBuffer to hold the data. Refer to the ByteBuffer JavaScript API documentation for more information about ByteBuffer.

var buffer = new ByteBuffer();

// ...
// Fill buffer with data
// ...

buffer.flip();

client.send(buffer);

The onchannelmessage and onmessage callback functions must be implemented to handle incoming messages (from a channel or private client/server communication connection, respectively). These callback functions can be used to display the messages in the UI as shown in the following example.

client.onmessage = function(msg) {
  alert('Private message from server : ' + Charset.UTF8.decode(msg));
}

Note: The Project Darkstar protocol requires the callback functions onloginredirect, onreconnectfailure, and onreconnectsuccess. However, the current implementation of Kaazing Gateway does not deliver these to the client.

Summary

As you have seen in this how-to, you can build Web applications that can communicate directly from the browser with a Project Darkstar Server using the DarkstarClient JavaScript client library. Thus, with the help of WebSocket the browser now enjoys the first-class citizenry of Project Darkstar communications that has, until recently, been enjoyed only by desktop applications and browser plugins.

Refer to the DarkstarClient JavaScript API documentation for the complete list of all the Project Darkstar command and callback functions.