The JavaScript client makes it possible to communicate with the SemiSpace from JavaScript. This JavaScript client mimics the Java interface as closely as possible and makes it possible to distribute JSON objects between the JavaScript client and the space.

Objects in the space are available as JSON objects for the JavaScript client and JSON objects pushed to the space by the JavaScript client are available for other clients. JSON objects can also be mapped directly to any known JAVA object and vise versa.

If you are not familiar with how to work against a space we recommend you read a simple introduction before you proceed.

Communication introduction

The JavaScript client rely on communicating with the space trough a CometD implementation. SemiSpace use the latest version of CometD which use a WebSocket implementation for browsers with native WebSocket support and a the long polling Bayeux protocol for browsers not supporting WebSockets.

Browser support

The client has been tested and proved to work at the following browsers:


  • IE6 and newer
  • Opera 10.x and newer
  • FireFox 3.x and newer
  • Chrome 5.x and newer
  • Safari 3.x and newer


  • Opera Mobile 10.x and newer
  • Android 2.2 and newer
  • Fennec 2.x beta and newer


Since the JavaScript client rely on communicating with the space trough a CometD implementation the JavaScript client need one of the JavaScript libraries CometD have bindings too. These libraries are Dojo Kit and jQuery.

The SemiSpace JavaScript client does only use the CometD connection module in these libraries and does not depend on any other functions in these libraries.

There are two ways to get up and running; The "custom way" and the "easy way". If your project already are depending on one of the libraries CometD have bindings to (Dojo Kit or jQuery), the "custom way" are the part you want to dive into. If you have no existing library and just want to get up and running, the "easy way" are the part you should read.

The custom way

The CometD module are not part of the core functionality in these libraries and must therfore be installed in the library of choice.

TODO: complete description....

The easy way

For your convenience the SemiSpace Comet package come with prepared builds of DojoKit and jQuery where the CometD module have been applied. To get started, select one of the provided prebuilt libraries for your project.

Dojo Kit

To use Dojo Kit for communication with the SemiSpace server, include Dojo Kit:

<script type="text/javascript" src="/semispace-comet-server/js/lib/dojo-release-1.4.3/dojo/dojo.js"> </script>

Then include the SemiSpace JavaScript client:

<script type="text/javascript" src="/semispace-comet-server/js/core/semispace.js"> </script>


To use jQuery for communication with the SemiSpace server, include jQuery:

<script type="text/javascript" src="/semispace-comet-server/js/lib/jquery/jquery-1.4.2.js"> </script>

Then include the SemiSpace JavaScript client:

<script type="text/javascript" src="/semispace-comet-server/js/core/semispace.js"> </script>

Communicating with the space

The SemiSpace JavaScript client provides a common interface against the space so whatever JavaScript library used the methods are the same among them. The SemiSpace JavaScript client will automatically detect which JavaScript library in use so no configuration against the library are needed to get the SemiSpace JavaScript client up running.

  • Connecting to the space

To make the SemiSpace JavaScript client talk to the SemiSpace server a connection need to be stabilised. This is done by initializing the connection module.

The init method can take a connection configuration object. This object are similar to the CometD configuration.

If you run on a default setup there should be no need to provide a connection configuration to the init method. The most needed parameter in the configuration to override will probably be URL the server. To override the server URL you provide a config object to the init method as follow:

When a initialization are done you can connect by executing the connection method:

  • Disconnecting from the space

It's possible to disconnect from the server by executing the disconnect method:

  • Listening in on the communication

It is also possible to listen in on the communication between the client (browser) and the server. This can be used to get valuable information on what is going on in the browser when communicating with the server. It can also be used to provide status messages to the user on what is going on.

You listen in on the communication by providing a callback function to the meta listener method:

The provided callback function must take two metod variables as input. The first variable will get a status code, ranging from 1 to 9, from the SemiSpace JavaScript library. The second variable will get the raw communication message provided by CometD.

A popular pattern is to listen in on the status codes and provide the user with information on the connection to the server.

The status codes are as follow

value Description
1 Handshake is done. The client has contacted the server but no connection are set up yet
2 The client are now connected to the server. Data can now be excanged with the server
3 The client was connected to the server but has lost connection to the server
4 The client communicates with the server. This will occur pretty frequently since the client pings the server from time to time
5 The client was disconnected from the server by the disconnect method
6 The client has subscribed to a CometD metachannel
7 The client has unsubscribed from a CometD metachannel
8 The client has published a message to the server
9 The client tried to publish a message to the server but failed

Working against the space

When a connection is set up, its possible to send and recieve JSON objects to and from the space. This JavaScript client mimics the Java interface as closely as possible and are as follow:

  • write
  • read
  • readIfExist
  • take
  • takeIfExist
  • notify

TODO: remember release function on notify

A note on handling JSON

The JavaScript client does not stringify or parse the JSON object communicated with the space. This is left to the implementation and must be dealt with on each communication.

Each JSON object transmitted to the space must be stringified before sent.


Each JSON object received from the space must be parsed before it can be dealt with by JavaScript.