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
<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.
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
- The DiffusionClient.send(topic, message) method
- The sendTopicMessage method
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);
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 handlingWhere 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.