Table of Contents
Just a second...

Using the JavaScript Classic API

The JavaScript® client library is located in the clients/js directory of the Diffusion™ installation. Two versions are provided, an uncompressed file, and a minimized file with the extension min.js.

For full API documentation, see JavaScript Classic API documentation

To enable the Diffusion client for production use, host the diffusion-js-classic.js client library on a dedicated web server and load the client library into your web page:
<script type="text/javascript" src="library_location/diffusion-js-classic.js"></script> 

Dependent transport files

The JavaScript client depends on other files located in the same directory: clients/js/diffusion-flash.swf and clients/js/diffusion-silverlight.xap. These files provide Flash® and Silverlight® transport capabilities, respectively. Removing these files prevents the JavaScript client from using these transports.

You can configure the JavaScript client to point to specific versions of both the Flash and the Silverlight transports. This is available through the connection details.

var connectionDetails = new DiffusionClientConnectionDetails();

connectionDetails.libPath = "/lib/js/diffusion";
connectionDetails.libFlashPath = "diffusion-flash.swf";
connectionDetails.libSilverlightPath = "diffusion-silverlight.xap";

Connection details

The DiffusionClientConnectionDetails object has over 20 attributes that change the way that the client behaves. Any attributes that are not set are provided with default values when used.

You can provide an anonymous object instead of instantiating a new DiffusionClientConnectionDetails object.

Connecting

A Diffusion client is a singleton with global scope. It can be called from anywhere. To connect to Diffusion, call the connect method. The method takes two parameters, first is the connection details and the optional second object is the client credentials. The following example is using an anonymous connection object:

DiffusionClient.connect({
   debug : true,
   onCallbackFunction : function(isConnected) {
       console.log("Diffusion client is connected: " + isConnected);
   }
})

If the client connection fails, the JavaScript client attempts to connect through other protocols. This is called protocol cascading.

Credentials

Credentials can either be supplied on the connect method or set separately using the DiffusionClient.setCredentials(...) method. These credentials are used for all transports that are used to connect to Diffusion. The DiffusionClientCredentials object is a simple one of username and password attributes.

// Connect with supplied credentials
DiffusionClient.connect({...}, {
	username : "foo",
	password : "bar"
});
// Connect, and send credentials later
DiffusionClient.connect({
	onCallbackFunction : function() {
		DiffusionClient.sendCredentials({
			username : "foo",
			password : "bar"
		});
	}
});

If authentication of the client connection fails, the JavaScript client attempts to protocol cascade and to connect through a different protocol with the same credentials. Use the onConnectionRejectFunction to close the client connection and prevent this from happening.

Events

The connection details have attributes that are listeners for certain events. If these are set in the connection object, they are called when these events happen.

Table 1. JavaScript functions called on events
Function Description
onDataFunction This function is responsible for handling messages from Diffusion. This function is called with an argument of WebClientMessage. This function is called even if there is a topic listener in place for a topic.
onBeforeUnloadFunction This function is called when the user closes the browser or navigates away from the page.
onCallbackFunction This function is called when Diffusion has connected, or exhausted all transports and cannot connect. This function is called with a boolean argument.
onInvalidClientFunction This function is called when an invalid Diffusion operation is called, for instance if Diffusion.subscribe is called before Diffusion.connect
onCascadeFunction This function is called when the client cascades transports. The function is called with an argument of the {String} transport name or NONE if all transport are exhausted.
onPingFunction This function is called with an argument of PingMessage when the ping response has been returned from the server.
onAbortFunction This function is called when the Diffusion server terminates the client connection (or the connection has been banned).
onLostConnectionFunction This function is called when the client loses connection with the Diffusion server
onConnectionRejectFunction This function is called when the client connection is rejected by the Diffusion server because of incorrect credentials. Use this function to close the connection when the authentication fails and prevent the client attempting to connect over a different protocol with the same incorrect credentials.
onMessageNotAcknowledgedFunction This function is called when a message that is requested as Acknowledge did not respond in time.
onServerRejectedCredentialsFunction This function is called after a DiffusionClient.sendCredentials and the server rejected the credentials.
onTopicStatusFunction This function is called if the status of a subscribed topic changes.

Receiving messages

The onDataFunction with a class called WebClientMessage contains only one message even if the messages sent from the Diffusion server are batched. If this is the case, this method is repeatedly called until all of the messages are exhausted. The WebClientMessage class wraps the message sent from the Diffusion server with utility methods like isInitialTopicLoad() and getTopic. See the jsdoc for the full list of utility methods.

Sending messages

There are two ways of sending messages to the Diffusion server:
  • The DiffusionClient.send(topic, message) method
  • The sendTopicMessage method
If user headers are required, it is best to use the TopicMessage class. The following example shows how to send a message using the TopicMessage class.
var topicMessage = new TopicMessage("Echo", "This is a message");	
topicMessage.addUserHeader("Header1");
topicMessage.addUserHeader("Header2");

DiffusionClient.sendTopicMessage(topicMessage);

Subscribing and unsubscribing

To subscribe and unsubscribe use the DiffusionClient.subscribe(topic) and DiffusionClient.unsubscribe(topic) methods respectively. The parameter can be a topic, a topic selector, or a comma-delimited list of topics

Topic listeners

During the lifetime of the connection, it might be required to have modular components that are notified about topic messages. These are topic listeners. A topic listener calls a supplied function with a WebClientMessage object when the topic of the message matches the pattern supplied. It is also worth noting that the onDataMessage function is called as well as the topic listener function. You can have many topic listeners on the same topic pattern if required. For example, if you want to be notified about a particular topic, you can use the following example code:

DiffusionClient.addTopicListener("^Logs$", onDataTradeEvent);
Note:
The characters ^ $ are regular expression characters. For more information, see Regular expression. The preceding code example means that the listener is only interest in receiving the message event if the topic is Logs. If the following example code is used, any topic name that has Logs in it matches.
var listenerRef = DiffusionClient.addTopicListener("Logs", onLogEvent, this);

Retain the listener reference if you want to remove the topic listener at a later date.

Failover

The JavaScript client does not support autofailover. You can still implement this using the onLostConnectionFunction.

Special Features

Paged topic data handling

Where paged topic data is in use at the server there are features within the client API which simplify the handling of messages to and from such a topic.