This document is the API Specification for Caplin SL4B SDK 4.4.11.

Summary

StreamLink for Browsers (SL4B) provides an object oriented JavaScript API that enables the creation of dynamic web applications within a browser. It allows a web developer to create a web page that has bi-directional communication with a server, without the need to reload the page or write their own streaming or polling mechanism to get required data from the server.

SL4B provides a subscription based API that can communicate with a Caplin Liberator, using the Real Time Text Protocol (RTTP). It allows the web page to subscribe and unsubscribe to the objects available from the Liberator, to receive notifications of updates to these objects, to create and delete objects, and to contribute data to existing objects.

Note: The SL4B library requires developers to write object oriented Javascript code. Although this is straight forward and simple to achieve, those who would like more information may find Douglas Crockford's Site to be a useful resource.

Contents

• What's New in Version 4.4
• Introduction
  • Subscriber
  • RTTP Provider
• Containers
• Configuring SL4B
  • Script Tag
  • Configuration File
  • Attribute List
  • Connection Failover
  • Latency
• JavaScript Security (document.domain Issues)
• Monitoring The Connection
• Using Multiple Frames
  • Master Frame
  • Slave Frames
  • JavaScript Security and Multiple Frames
• Using The Flash Library
  • Flash Library Functions
• Enabling Debugging
  • Logging Your Own Debug Messages
• Backwards Compatibility
  • RTML
  • RTSL
    • Overview
    • Functions
    • Callback Functions
  • Known Issues
• File Summary

What is new in version 4.4

The new functionality in version 4.4 of StreamLink for Browsers consists of:

• Container Paging: 
  • This is the ability to request a subset of the items within a container, for example just those that are to be drawn on screen. See the Container Object section for details.

Back to contents

Introduction

Updating a web page to use the SL4B library requires the following steps:

1. Adding a script tag to load SL4B within the page(s) where it will be used (see Script Tag for more information)
2. Writing one or more subscriber classes
3. The instantiation of one, or more, of the subscriber classes

The subscriber classes (subclasses of SL4B_AbstractSubscriber) are key to all SL4B implementations. Subscriber classes have a particular form, and may implement a number of pre-defined methods. Most of this will happen automatically because subscriber classes inherit from the abstract subscriber base class. The methods the subscriber class implements are callback methods, that will be invoked as object update events are received.

To subscribe to receive notifications of object updates a subscriber must be registered, with the appropriate parameters, with a singleton object: the RTTP provider. The subscriber will continue to receive object update callbacks until the subscriber is unsubscribed, again using the RTTP provider.

The subscriber classes may continue to add or remove object subscriptions during their lifetime, but subscription is not possible immediately after the construction of the subscriber object because the SL4B library needs to be fully initialised beforehand. The subscriber's ready() method will be invoked as soon as it is OK for the subscriber to make subscriptions. Apart from the constructor, the ready() method is the one method that all subcriber classes must implement.

The following code demonstrates what a subscriber class might actually look like:

<script type="text/javascript" id="sl4b" src="/sl4b" rttpprovider="javascript"></script>
<script type="text/javascript">
// class definition for SimpleSubscriber
function SimpleSubscriber(sObjectName)
{
   // Store the object name as a member variable so it can be used later on; no subscription can
   // take place until this object's ready() method has been called.
   this.m_sObjectName = sObjectName;

   // Invokes the initialise method on the base class (i.e. SL4B_AbstractSubscriber), this
   // must be called within the constructor of all SL4B_AbstractSubscriber subclasses.
   this.initialise();
}

// Defines SimpleSubscriber as a subclass of SL4B_AbstractSubscriber.
SimpleSubscriber.prototype = new SL4B_AbstractSubscriber;

// Overrides the ready() method from SL4B_AbstractSubscriber; once this method has been invoked
// it becomes safe to make object subscriptions.
SimpleSubscriber.prototype.ready = function() {
   // Use the RTTP provider to setup the subscription; a reference to this object is passed in
   // since it will be acting as the subscriber, and will receive the notification updates.
   SL4B_Accessor.getRttpProvider().getObject(this, this.m_sObjectName);
};

// Overrides the recordUpdated() callback method from SL4B_AbstractSubscriber; this method will
// be invoked whenever new object data becomes available.
SimpleSubscriber.prototype.recordUpdated = function (sObjectName, sFieldName, sValue) {
   // add code to process the record update here
}

// Creates a new SimpleSubscriber to receive streaming updates for /DEMO/MSFT.
new SimpleSubscriber("/DEMO/MSFT");
</script>

Note: This web page will use a JavaScript RTTP provider to communicate with the Liberator since that is what is specified via the rttpprovider configuration attribute within the script tag. Many other configuration attributes can be specified within the SL4B script tag, or within an external file (the location of which is defined using the configurationfile attribute. More information about the configuration of SL4B can be found within the Configuring SL4B section.

Note: The ability to have multiple subscribers within the same page allows RTML, RTSL and SL4B to all be used within the same frame. Both the RTML and RTSL library extensions are built on top of SL4B and use their own subclasses of SL4B_AbstractSubscriber to interact with the Liberator behind the scenes.

Subscriber

SL4B_AbstractSubscriber is the base class for any classes that want to be notified when particular events occur, such as record updates. Subscriber classes are implemented by developers to subscribe to one or more objects on a Liberator, and then process the updates that are received for those objects. All of the base classes callback methods, except for ready (which must be implemented by the subclass), have empty implementations, preventing developers from having to implement lots of empty method implementations for callback methods they are not interested in.

A web page subscribes to some particular events from the Liberator using the SL4B_AbstractRttpProvider.getObject() method. Two parameters must be provided: a reference to the SL4B_AbstractSubscriber object that will receive the updates and the name of the object to subscribe to. Since different RTTP provider implementations are available, and the specific provider that is used is defined using the rttpprovider configuration attribute, a reference to the RTTP provider can only be obtained via the SL4B_Accessor.getRttpProvider() method.

RTTP Provider

SL4B_AbstractRttpProvider is a standard interface that decouples objects that want to interact with a Liberator from the implementation of how the client actually interacts with the Liberator. This allows a web page to change how it communicates to a Liberator (e.g. Java applet vs direct AJAX communication) by making a configuration change, rather than having to make code changes within the page. The rttpprovider attribute, defines which RTTP Provider will actually be used, and can be set to one of the following values:

Back to contents

Configuring SL4B

The SL4B library is included into a page using a script tag that will look something like this:

<script type="text/javascript" id="sl4b" src="/sl4b" user="demouser" includertsl></script>

The library can be configured either by defining attributes within the script tag, or by referencing an external configuration file. There are two types of attributes: standard or unary. The standard type has a value associated with the attribute, such as the attribute user having the value 'demouser'. The unary type has no associated value (e.g. the includertsl).

Script Tag

SL4B attributes are specified within the SL4B script tag in the same way as standard HTML attributes. The example below shows how the user and enableflash attributes can be set within the script tag.

<script type="text/javascript" id="sl4b" src="/sl4b" user="demouser" enableflash></script>

Note: Any attributes defined within the script tag will override the values defined within a configuration file (if used). This allows many pages to share the same configuration file, with individual pages overriding particular attributes where necessary.

Configuration File

A configuration file will only be used if the configurationfile attribute is defined within the SL4B script tag. This attribute should be the path to the configuration file (the configuration file is loaded via a script tag and must be valid JavaScript). Within the JavaScript configuration file, a reference to the configuration object can be obtained by invoking the SL4B_Accessor.getConfiguration() method. The setAttribute() method can then be used to set the value of a particular attribute.

The following code snippet is taken from a JavaScript configuration file, which sets the user attribute to "demouser":

var oConfiguration = SL4B_Accessor.getConfiguration();
oConfiguration.setAttribute("user", "demouser");

Attribute List

The Configuration Attributes page lists all of the available attributes that can be used to modify the behaviour of the SL4B library.

Connection Failover

SL4B can be configured to failover from one Liberator to another if it loses its connection. The library will automatically re-subscribe to all the objects the client was watching, and will generate suitable SL4B_ConnectionListener events to allow a page to know what the current connection state is. Please see Connection Failover for more information.

Latency

Latency measurement can be enabled using the enablelatency configuration attribute.

For latency to be measured the Liberator server must return a timestamp field with every record, this is configured in the liberator configuration file (rttpd.conf) using the following code:

	latency-chain-enable
	timestamp-field INITIAL_TIMESTAMP

The timestamp field must also exist in the Liberator field definition file (fields.conf).

All SL4B subscriptions for which latency should be measured must request either all fields or include the timestamp field in their field list.

If the timestamp field name chosen is not the default (INITIAL_TIMESTAMP) then the SL4B configuration attribute timestampfield must also be defined.

The latency value for the current update can be retrieved from the the SL4B_Statistics object (which can be obtained from the SL4B_Accessor).

Example code for accessing the latency of the current update:

	var latency = SL4B_Accessor.getStatistics().getLatency();

The SL4B_Statistics object also contains methods for retrieving the average latency and clock offset.

Back to contents

JavaScript Security (document.domain Issues)

JavaScript's security model restricts the browser functionality to prevent malicious scripts from running within a browser session, and performing cross-site interaction. One of the restrictions applied by the security model (The Same Origin Policy) is that a web page downloaded from one web server cannot perform inter-frame communication with a web page from another web server of a different origin. Two web pages fail the 'Same Origin Policy' if any of the following URL attributes are different:

• Host name
• Port number
• Access protocol (e.g. http or https)

If two pages have different hostnames or port numbers, compliance with the 'Same Origin Policy' is possible if the document.domain property is set to a common sub-domain of the two pages. Compliance is never possible if the access protocols differ.

For example, if pages A and B are hosted at 'www.subA.common-domain.com' and 'www.subB.common-domain.com', then the document.domain should be set to 'common-domain.com'. The common domain must be at least 2 levels deep ('common-domain.com' is valid, but 'com' is not) and the common domain must be a subset of the full domain.

If SL4B enabling a website results in 'permission denied' errors, these may be circumvented by setting the document.domain property on all non-SL4B frames to be the same value SL4B will use. The document.domain value an SL4B page uses is set by the SL4B configuration attribute commondomain. If the attribute is not explicitly set, a common domain is chosen automatically.

It is strongly recommended that the commondomain configuration attribute is explicitly set, since the automatic determination of this value by SL4B is not always appropriate.

Back to contents

Monitoring The Connection

In addition to receiving data updates for any objects that have been subscribed to, it is also possible to receive notifications of the state of the connection of the Liberator. This allows the web page to find out:

• The current connection status
• User authentication status
• Service health
• Statistics regarding the performance of the clients connection

The following example shows how one could use the connection status information to change the behaviour of a web application:

<script type="text/javascript" id="sl4b" src="/sl4b" rttpprovider="javascript"></script>
<script type="text/javascript">
// the ExampleConnectionListener class implements some of the methods that will be called as the
// state of the connection changes
function ExampleConnectionListener()
{
}

// the ExampleConnectionListener inherits from SL4B_ConnectionListener
ExampleConnectionListener.prototype = new SL4B_ConnectionListener;

ExampleConnectionListener.prototype.connectionWarning = function(sMessage) {
   // there is currently a problem with the connection which SL4B is trying to overcome
}

ExampleConnectionListener.prototype.connectionError = function() {
   // SL4B has failed to reconnect
}

ExampleConnectionListener.prototype.connectionOk = function(sHostName, nConnectionType, nTime) {
   // the connection is now ok again.
}

// create an instance of ExampleConnectionListener and register it with the RTTP provider
SL4B_Accessor.getRttpProvider().addConnectionListener(new ExampleConnectionListener());
</script>

The SL4B_ConnectionListener class documentation explains all of the callback methods that can be implemented by a connection listener.

By default, the SL4B registers its own connection listener to receive notifications of connection level events and output them to the browser's status bar. This behaviour can be disabled by using the nobrowserstatus configuration attribute.

When SL4B reconnects to a Liberator that has recently restarted a problem can occur. By default, clients will be allowed to connect even if they wish to subscribe to a data service that is not yet connected. This results in the clients receiving "Not Available" messages and not being subscribed. This can be avoided by setting the "required-state" attribute in the Liberator configuration for the data service to "ok". See the Liberator Admin guide for more information.

Back to contents

Using Multiple Frames

The default installations of IE and Firefox restrict a client to only being able to make two connections to any particular server at any one time. Since SL4B connects to a Liberator using a a persistent streaming connection, one of the connections is always in use. The other connection is used to make new subscriptions and so forth. Unfortunately this restriction applies to the browser as a whole, which means that if a browser contains two or more frames that are SL4B-enabled, the number of connections allowed to the Liberator will be used by the persistent streaming connections. This means that only two frames will ever be able to receive data, and that whilst they are connected, no subscriptions can be made.

The master and slave frame functionality gets around this by allowing a single frame, designated as the master, to be responsible for establishing and maintaining the connection with the Liberator. The other frames, the slaves, delegate all of their requests to the master frame.

This functionality also improves the performance and responsiveness of any web site that contains multiple SL4B-enabled page, since a Liberator connection only needs to be established once, a single user license is required (rather than one per page), and there is no bandwidth wastage with duplicate updates being sent to the same client but down different connections.

For optimal performance of a multiple framed web site, the master frame should be one that does not change (such as a navigation bar). If a web site does not use frames, but is likely to have many pages that will be SL4B-enabled, it is recommended that an "invisible" master frame with 0 height is created, with a second frame that fills the whole browser window containing the actual web site content pages. In this case each content page uses an established connection to obtain data from the Liberator which will improve its speed.

The example HTML below shows how a simple master/slave frameset can be created. In this case, the master frame is the navigation bar at the top of the web site, whilst the content pane below it will contain the slave frame.

<html>
<head>
   <title>Equity Pages</title>
</head>
<frameset rows="200,*">
   <frame src="navigation-bar.html">   <!-- master frame -->
   <frame src="us-equities.html">      <!-- slave frame -->
</frameset>
</html>

Warning: The master/slave frame functionality in SL4B is not fully compatible with the original versions of RTML and RTSL. This was necessary to provide support for Mozilla Firefox and other non-Internet Explorer browsers. If the master and slave frames do not access each other via the top frame (i.e. the SL4B-enabled pages are contained within a sub-frameset of the main frameset), the slave frames will not work. Setting the containerframelocation attribute on the master frame solves this problem. Please see master frame location known issue for more information.

Master Frame

The master frame loads the RTTP provider specified by the rttpprovider configuration attribute. It is responsible for connecting and logging into the Liberator using the specified RTTP provider. It uses the relevant configuration parameters that have been specified for the page, such as appletpath and gcfreq.

For most web sites, the master frame does not need any special configuration attributes. However, if the master/slave frameset is contained within another frameset, one must specify the common root frame of the master and slave frames must be specified via the containerframelocation configuration attribute. For example:

<script type="text/javascript" id="sl4b" src="/sl4b" user="demouser" password="demopass"
        multiupdates containerframelocation="parent.parent" commondomain="example.com"></script>
<script type="text/javaScript">
	// MasterFrameSubscriber class would be defined here...
	new MasterFrameSubscriber();
</script>

Slave Frames

A slave frame uses a special RTTP provider called SL4B_SlaveFrameRttpProvider. This provider does not connect to a Liberator directly, but instead acts as a proxy to the RTTP provider within the master frame. As a result, any of the attributes regarding the configuration of the RTTP provider are ignored within a slave frame. The slave frame must, however, define the usemasterframe and the frameid configuration attributes, and may need to define the containerframelocation attribute (it defaults to top).

The example below shows how a typical slave frame might be configured.

<script type="text/javascript" id="sl4b" src="/sl4b" usemasterframe frameid="us-equities"
        containerframelocation="parent.parent" commondomain="example.com"></script>
<script type="text/javaScript">
	// SlaveFrameSubscriber class would be defined here...
	new SlaveFrameSubscriber();
</script>

JavaScript Security and Multiple Frames

One common problem with using the master/slave frame functionality, particularly if the JavaScript RTTP provider is used, is that the master frame, all of the slaves and the container frame must all share exactly the same document.domain property value. In order to use the JavaScript RTTP provider this value must have been to a widened scope (e.g. example.com rather than appserver.example.com) within the master frame. In this case all the slave frames and the container frame must have their document.domain values set to the same as the master frame (i.e. example.com for the above example).

The SL4B library includes a configuration attribute, commondomain, that is used by the library to automatically set the document.domain property within any SL4B-enabled page. To minimise the potential impact of the JavaScript security model, it is recommended that this attribute is used in all SL4B pages, perfereably being defined within a configuration file shared by all the pages.

Back to contents

Using The Flash Library

The flash library provides a convenient and efficient way to display flashing updates within a web page without having to code timeouts to remove that flashes after a certain amount of time. This optional library is only available if the unary enableflash configuration attribute is defined.

The RTSL_CreateUpdate() function creates an update object which defines the value that will be displayed, the colour it will flash, and how long the flash will last for. The RTSL_DisplayUpdate() function is used to display an update generated by RTSL_CreateUpdate.

The Object Oriented Example demonstrates the library being used.

The following code snippet how an update can be created and displayed:

<script type="text/javascript" id="sl4b" src="/sl4b" enableflash></script>
<script type="text/javaScript">
function Subscriber() {
   this.initialise();
}
Subscriber.prototype = new SL4B_AbstractSubscriber;

Subscriber.prototype.ready = function () {
   SL4B_Accessor.getRttpProvider().getObjects(this, "/DEMO/MSFT", "dLast");
}

Subscriber.prototype.recordUpdated = function(sObjectName, sFieldName, sValue) {
   // create an update
   var oUpdate = RTSL_CreateUpdate("divMSFT_dLast", "Relative", sValue, false, true, null, 1000);

   // now display the update
   RTSL_DisplayUpdate(oUpdate);
}

new Subscriber();
</script>

<!-- element to be updated -->
<div id="divMSFT_dLast">-</div>

Flash Library Functions

The following functions are provided flash library:

Back to contents

Enabling Debugging

The SL4B client log is an invaluable troubleshooting tool when you are having problems. It can be enabled by setting the value of the debug configuration attribute to the warn level or greater. For example:

<script type="text/javascript" id="sl4b" src="/sl4b" debug="warn"></script>

Alternatively, the client log can be enabled in a production site withour changing the code or affecting other users. This is achieved by setting the debug level within the URL query string. If the site was hosted at 'example.com', then the following URL would have the same effect as the script above:

http://example.com?debug=warn

The debug level of logging (e.g. ?debug=debug) is generally the most appropriate for troubleshooting general connection problems. For more subtle problems, rttp-finer and even rttp-finest can be more useful, although they will also include a quantity of low-level information (including all of the RTTP messages sent and received by the client). Depending on the volume of data being sent, enabling low-level logging may severely impact the performance of the client.

Logging Your Own Debug Messages

The logging facility used within SL4B is also available for use by end users. The logger object (see SL4B_Logger) can be accessed with SL4B_Accessor.getLogger(), and logged to at the various logging levels. Messages can be output to the log using the log() or printMessage() methods.

Back to contents

Backwards Compatibility

SL4B includes two extensions libraries that can optionally be included within a web page. These provide the RTML and RTSL compatibility layers, which allow existing or new pages to continue to use the RTML/RTSL interfaces.

RTML

The RTML compatibility layer allows new pages to be created using the simple RTML markup, which makes it possible to display real time updaing data within a web page without having to write any JavaScript. It also allows most existing web pages that make use of RTML to continue to function without any need for them to be changed.

RTSL

The RTSL compatibility layer allows the majority of web pages that have been written using RTSL to continue to function without any need for their source code to be changed. Please consult the Backwards Compatibility - Known Issues section for information on which areas might be problematic. New web pages can continue to be developed using RTSL, possibly combining RTSL, RTML and SL4B objects within the same page where appropriate.

Overview

The simplest RTSL enabled web page will subscribe to a record object on a Liberator and display the updates to the record's fields within the page. To do this, a web page must include a script tag that loads the RTSL library, implements one or more RTSL callback functions and subscribes to data using an RTSL function.

Script Tag

The RTSL script tag can be written in two ways. The first example below shows the script tag that should be used with this new SL4B library. The includertsl unary attribute tells SL4B that the RTSL extension library must be loaded within this page.

<script type="text/javascript" id="sl4b" src="/sl4b" includertsl user="demouser" password="demopass"></script>

The second example demonstrates that the old style RTSL script tag can still be used. In this case the includertsl attribute is unnecessary.

<script type="text/javascript" id="rtsl" src="/rtsl" user="demouser" password="demopass"></script>

Requesting Data

The web page must wait until the RTSL_Ready callback function is called before it can interact with the Liberator. Once this callback has been received the web page can call any of the SL4B functions (e.g. RTSL_GetObject to subscribe to an object on the Liberator).

The following example shows how a client can subscribe to the RTTP object called /DEMO/MSFT using RTSL.

function RTSL_Ready()
{
   RTSL_GetObject("/DEMO/MSFT");
}

Processing Events

Events are passed to the web page by various RTSL callback functions. When a record update is received, the RTSL_RecordUpdated function will be called. The web page is able to process the update as required. A library of optional helper functions can be loaded into the page by specifing the enableflash configuration attribute. The RTSL_CreateUpdate and RTSL_DisplayUpdate helper methods can be used to display an update within the page, including a temporary background flash to give a visual indication that a value has updated.

function RTSL_RecordUpdated(sObjectName, sFieldName, sValue)
{
   // assume id of the dom element to be updated is the combination of the object and field names
   var sElementId = sObjectName + sFieldName;

   // create the update object
   var oUpdate = RTSL_CreateUpdate(sElementId, "Relative", sValue, false, false, null, 1000);

   // ask for the update to be displayed
   RTSL_DisplayUpdate(oUpdate);
}

Functions

The following list of functions can be called within an RTSL-enabled page.

RTSL also provides the following helper functions for formatting data.

Furthermore, RTSL provides an optional library of helper functions that can be used to update elements within the web page when an update is received. This library will only be available if the enableflash configuration attribute is specified within the page. These functions are defined within the flash library functions.

Callback Functions

The following callback functions can be implemented within an RTSL page. The appropriate function will be called by the library when a specific event occurs (e.g. when a record update is received, RTSL_RecordUpdated will be called).

Back to contents

Known Issues

Every attempt has been made to make the RTML and RTSL compatibility layers as backwardly compatible as possible, however there are some areas where there may be problems. The following list documents all of the known issues that might be encountered when upgrading an RTML/RTSL page to use the SL4B library.

Back to contents