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.
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.
The client has been tested and proved to work at the following browsers:
Desktop:
Mobile:
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 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....
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.
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>
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.
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:
It's possible to disconnect from the server by executing the disconnect method:
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 |
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:
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.
Example:
Each JSON object received from the space must be parsed before it can be dealt with by JavaScript.
Example:
