Frequently Asked Questions

This document is designed to answer the most common questions users of SL4B have.

Contents

• Common Problems and Answers
• How do I specify which Liberator I want the client to connect to?
• What is the JavaScript RTTP provider?
• How do I use the JavaScript RTTP provider?
• How do I use the applet RTTP provider?
• Why do I get an error message saying that the web page and liberator do not share the same domain?
• Why do I get permission denied errors?
• How should the SL4B library be deployed?
• Why might I want to use multiple subscribers?
• How should I assign my onload/onbeforeunload window event handlers?
• Why does the client connect successfully, then reconnect immediately afterwards?
• How do I troubleshoot any problems?

Common Problems and Answers

Symptom/Question	Probable Cause	Solution
I get a permission denied error when I load the SL4B enabled web page	document.domain issue	See the Why do I get permission denied errors section.
When I load the examples, they do not work	Liberator location unknown	The examples are designed to work, unmodified, when they are hosted on a Liberator. The DataSource "demosrc" that is provided with all Liberator installations must be configured to connect to the Liberator to supply the data for the examples. If the examples are hosted from a web server you will need to modify the .../configuration/common-attributes.js file to specify the serverurl attribute and probably jscontainerpath too. Please see the How do I specify which Liberator I want the client to connect to, How do I use the JavaScript RTTP provider and How should the SL4B library be deployed sections of this FAQ for further information.
When I load the examples, the status bar contains a message saying that the login failed	Liberator auth module does not accept the user "demouser"	The example pages are configured to use the username "demouser" and the password "demopass" to login to the Liberator. This user is valid with the default Liberator auth module (xmlauth), however if demouser has been modified or removed from users.xml, or if a different auth module has been configured, then a login failure response will be received by the example pages.
When I load the examples, the status bar contains a message saying that it has connected to Liberator, but no data appears	demosrc is not running or is not configured	The data displayed within the examples is supplied by the example DataSource, "demosrc", that is provided with all Liberator installations. The demosrc must be configured to connect to the Liberator and it must be running for the examples to work.
How do I enable JavaScript/AJAX streaming?	-	The SL4B_JavaScriptRttpProvider is used to provide the JavaScript/AJAX streaming functionality. This is configured by setting the rttpprovider attribute to javascript.
The examples work but my test page doesn't display anything	Client code issue	Has the this.initialise(); method call been added to constructor of the SL4B_AbstractSubscriber subclass? This method must be called (see the examples). Is the ready method being called? The easiest way to do this is to add a temporary alert in the ready callback method to ensure it is being called. Are the relevant callback methods being called (e.g. recordUpdated)? Add an alert into the relevant callback method to ensure it is being called. Are the updates to be displayed using the RTSL_DisplayUpdate method call? This will cause HTML to flash when updated. Ensure that the unary enableFlash attribute has been set and that the rtsl directory is available on the Liberator/web server. Does the HTML element that is to be updated exist? The element needs to be available from the DOM in order to be updated. Enable debuging (setting the level to debug) and look for any errors.

Back to contents

How do I specify which Liberator I want the client to connect to?

The SL4B library assumes that the base URL for the Liberator is the base URL for the SL4B script itself (e.g. if SL4B is loaded from ../../sl4b, then the root Liberator URL is /, whilst if SL4B is loaded from http://liberator.example.com/sl4b-test/sl4b then the Liberator URL is http://liberator.example.com). If this is not the case (as is recommended in the How should the SL4B library be deployed section), then the serverurl configuration attribute must be used.

Back to contents

What is the JavaScript RTTP provider?

The JavaScript RTTP provider is an subclass of the SL4B_AbstractRttpProvider that uses pure JavaScript/AJAX techniques to communicate with the Liberator. It does not use a Java applet, and is therefore does not require the user to have a Java Virtual Machine (JVM) installed on their machine, nor is it effected by any JVM version compatiblity issues.

Back to contents

How do I use the JavaScript RTTP provider?

To configure SL4B to use the JavaScript RTTP provider, the rttpprovider attribute must be set to the value javascript.

In order for the JavaScript RTTP provider to connect to a Liberator, SL4B must be deployed on the Liberator. The SL4B-enabled page assumes that SL4B has been deployed under the root htdocs folder as /sl4b, and therefore the container HTML files required by the JavaScript RTTP provider are available from /sl4b/javascript-rttp-provider. If this is not the case (e.g. SL4B was deployed to the /sl4b-test/sl4b folder) the jscontainerpath attribute must be defined. It will also be necessary to set the serverurl attribute (please see the How do I specify which Liberator I want the client to connect to section for more details).

Please see the Web Server And Liberator Host Name Issue section for more information on issues that might be encountered when using the JavaScript RTTP provider.

Example:

<script type="text/javascript" src="http://devweb.example.com/sl4b"
        serverurl="http://liberator.example.com"
        rttpprovider="javascript"
        jscontainerpath="sl4b-test/sl4b/javascript-rttp-provider" ></script>

Back to contents

How do I use the applet RTTP provider?

To configure SL4B to use the applet RTTP provider, the rttpprovider attribute can either be omitted, or it can be set to the value applet.

In order for the applet RTTP provider to connect to a Liberator, the RTTP applet must be deployed on the Liberator. The SL4B-enabled page assumes that RTTP applet has been deployed under the /applet within the root htdocs folder (this is part of the standard Liberator installation). If this is not the case (e.g. the applet was deployed to the /applet-test folder) the appletpath attribute must be defined. It will also be necessary to set the serverurl attribute (please see the How do I specify which Liberator I want the client to connect to section for more details).

<script type="text/javascript" src="http://devweb.example.com/sl4b"
        serverurl="http://liberator.example.com"
        appletpath="applet-test" ></script>

Back to contents

Why do I get an error message saying that the web page and liberator do not share the same domain?

If a JavaScript RTTP provider is used, and the SL4B-enabled page is not hosted by the Liberator, the web server that hosts it must share a common domain with the Liberator. This means that all host names must be fully qualified (i.e. devweb.example.com rather than devweb) and that IP addresses are not used (even though these might resolve to valid host names, the JavaScript security model does not recognise this). This applies to both the src and serverurl attributes.

The table below shows what will happen with various host name combinations. Although it shows different web server host names being applied, the same issue will occur if the Liberator host name was not fully qualified.

Back to contents

Why do I get permission denied errors?

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 are considered to have the same origin when:

• They have the same host name
• They have the same port
• They use the same protocol

Web pages that fail either of the first 2 restrictions (they have different host names or different port numbers), but that reside within a common domain can overcome this limitation provided they both mutually choose to do so. Each web page has a document.domain property, which specifies where the page has come from (e.g. a page downloaded from www.example.com will have a document.domain value of "www.example.com"). To allow pages hosted from different servers to communicate with each other, both pages need to set their document.domain property to the same value, however the security model restricts what values each page can set its document.domain property to. The main restrictions are that it can only be widened, not narrowed (i.e. a page from "www.example.com" can be set to "example.com", but not the other way around), and that it must be at least two levels deep (e.g. "example.com" is valid but "com" is not).

If the JavaScript RTTP provider is used, and the SL4B-enabled web page is loaded from a web server other than the Liberator, the SL4B library automatically determines what the common domain is and sets the document.domain property accordingly. This allows the page to connect to the Liberator and receive data. However, the impact of this is that the SL4B-enabled web page will no longer be able to communicate with other web pages that have been loaded from the web server, including ones that are launched from the page, unless they have also had their document.domain property set to the correct value. If the page attempts to call another page that does not have the same domain setting, a JavaScript "permission denied" error will occur.

There are three ways of getting around this:

1. Set the commondomain configuration attribute. The SL4B library will use this attribute to set the document.domain property whilst it is loading.
2. Hard code the document.domain property to the relevant value within the pages that the SL4B-enabled page needs to communicate with.
3. Add code to the pages that the SL4B-enabled page needs to communicate with that takes the value of the document.domain property from the page's query string, then sets it. The following code snippet demonstrates how this might be implemented:

   <script type="text/javascript">
   // function to get the parameter with the specified name from the query string
   function getParameter(sName)
   {
      var oMatch = window.location.search.match(new RegExp("[?&]" + sName + "=([^&]*)"));
      return ((oMatch == null)?null:oMatch[1]);
   }
   
   // get the value of the "domain" parameter from the query string
   var sDomain = getParameter("domain");
   if (sDomain != null)
   {
      // if the "domain" parameter was specified in the query string, set the
   	// document.domain property accordingly
      document.domain = sDomain;
   }
   </script>
   

Note: As of SL4B version 4.3, KeyMaster now also depends on inter-frame communication with the main SL4B frame, and so relies on the document.domain being common for the SL4B-enabled page, the Liberator and the KeyMaster. Since KeyMaster now uses frames, you can no longer have the KeyMaster URL use a different protocol to the to the SL4B-enabled page or Liberator. If this is not the case, a permission denied error will be generated for this reason too.

How should the SL4B library be deployed?

It is recommended that the SL4B library is hosted from the same web server as the page that includes it. This virtually guarantees that if the web page can be loaded, SL4B can too. This ensures that only a single set of error handling code needs to be implemented within the page to handle the situation when the Liberator is down, using a SL4B_ConnectionListener. If SL4B were loaded from the Liberator, and the Liberator is down when the page is loaded, extra error handling code would need to be implemented to detect that the SL4B script itself had not loaded.

If the JavaScript RTTP provider is used the same version of the SL4B library must be deployed on both the web server and the Liberator. When upgrading to a new version of the SL4B library, it must be deployed to both the web server and the Liberator, otherwise there may be incompatibilities between the old and new versions of SL4B that prevent the JavaScript RTTP provider from working reliably.

Back to contents

Why might I want to use multiple subscribers?

SL4B allows multiple subclasses of SL4B_AbstractSubscriber to be created. There are two main advantages gained by this:

1. The multiple subscriber model fits well with web pages that contains several different real time components (e.g. three separate tables of data). Each real time component can have its own subscriber, allowing the components to be added or removed from the page without impacting the other components in the page. This is especially useful for pages that are constructed by a portlet engine, which takes different snippets of HTML code and merges them into a single page.
2. If a web page is displaying two (or more) different types of data, each of which needs its own distinct manipulation before being displayed, the logic for this can be moved into two separate subscriber classes. An example of this is a web page that displays both equity and foreign exchange market data, where the equity data is displayed to 2 decimal places, whilst the foreign exchange data is displayed to 4 decimal places.

Back to contents

How should I assign my onload/onbeforeunload window event handlers?

The SL4B library hooks into the window onload and onbeforeunload event handlers in order to function correctly (please note that the window.onload and the body.onload event handlers are synonymous). It attaches the event handlers using either the addEventListener method in fully W3C compliant browsers or the attachEvent method in Internet Explorer. This means that the SL4B event handlers for the page onload and onbeforeunload events sit in parallel with any custom ones defined within the page, however it is possible in some browsers that the custom event handlers may override SL4B's ones. This issue can be detected by setting the SL4B debug level to info and looking for messages of the format "WindowEventHandler.onLoad: method invoked" within the log. If it appears that the SL4B event handler is not being invoked, there are two approaches that can be taken:

1. The page's custom event handlers are registered using the SL4B_WindowEventHandler.addListener() method, instead of directly on the window.
2. The event handler is registered on the window, and when it is called, it proxies event onto the SL4B library by invoking the SL4B_WindowEventHandler.onLoad() and SL4B_WindowEventHandler.onBeforeUnload() methods as appropriate.

Warning: It is important that only one of the following techniques is used. If both are applied a "circular reference" may occur, with the web page event handler and the SL4B event handler recursively calling each other until the JavaScript callstack limit is reached.

Back to contents

Why does the client connect successfully, then reconnect immediately afterwards?

This problem can occur if content is added to the page using a body.innerHTML += "new content..." statement. When the content of page is extended in this manner, the page's HTML is reparsed, which triggers the SL4B library to attempt to reconnect. The following code snippet demonstrates an alternative technique that can be used to add the content to the page without effecting the SL4B connection:

var oContainerElement = document.createElement("div");
oContainerElement.innerHTML = "<b>my</b> html fragment";
document.getElementsByTagName("body").item(0).appendChild(oContainerElement);

Back to contents

How do I troubleshoot any problems?

If an SL4B-enabled page is not behaving as expected (e.g. it cannot to connect to a Liberator, or is not receiving updates for objects that have been subscribed to) the SL4B client log should be enabled. This is achieved by setting the debug configuration attribute in one of the following ways.

1. Setting it programmatically (within the attribute configuration file):

   SL4B_Accessor.getConfiguration().setAttribute("debug", SL4B_DebugLevel.DEBUG);

2. Setting it within the SL4B script tag:

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

3. Specifying it via the web page URL:

   http://liberator.example.com/demo/mysl4bpage.html?debug=warn

The most important debug levels when trouble shooting are warn, debug, rttp-finer and rttp-finest.

Debug Level	Description
warn	This is the level at which any exceptions thrown by the client callback methods are logged. The SL4B library automatically catches any exceptions that are thrown by a client callback method (e.g. attempting to update a DOM element that does not exist) to prevent the exception from terminating the RTTP message processing thread, which may result in the client missing some updates.
debug	This is the most relevant level for investigating connection issues. It should provide enough information to determine why the client cannot connect, or reconnect, to a Liberator. The most important log message to loog for is LiberatorUrlCheck.onError[frmRequest]: Liberator unavailable. This indicates that either: The serverurl attribute is misconfigured. Check that the server URL (including the protocol and port number) appears to be correct (e.g. http://liberator.example.com). The Liberator is genuinely down. Request the Liberator URL with a web browser - if a "server cannot be found" message is received, the Liberator is either down or is not accessible from the client. The jscontainerpath attribute is misconfigured. Request the url-check.gif file from the location specified within the log (e.g. http://liberator.example.com/sl4b/javascript-rttp-provider/url-check.gif?1146572641830) - if a "404 file not found" error is received, the attribute has been been misconfigured or SL4B has not been copied to the correct location on the Liberator.
rttp-finer	This level is primarily used to log the RTTP messages that are sent to, and received from, the Liberator. Typically this level should only be used to provide a client log for Caplin support to analyse if the client is requesting data but is not receiving any updates for it.
rttp-finest	This level is used to log the inner workings of the SL4B library. This is for use solely by Caplin support so that they can track down where within the library the problem has occurred.

See the SL4B_Logger and SL4B_DebugLevel documentation for more information.

Back to contents