This document is designed to answer the most common questions users of SL4B have.
| 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 |
|
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.
When the service configuration
attribute is used, the commondomain
attribute must also be explicitly set. The library will warn of a fatal error if the
commondomain has not been specified in this instance.
If the SL4B-enabled page fails to connect to a server when configured for connection failover
within Internet Explorer, but works in Firefox, check the ContentType response
header. This must be text/xml in order for IE to parse the XML.
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.
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>
This specifies that the Liberator is located at "http://liberator.example.com" and the HTML
container required by the JavaScript RTTP provider are available from
"http://liberator.example.com/sl4b-test/sl4b/javascript-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>
This specifies that the Liberator is located at "http://liberator.example.com" and the RTTP applet
is available from "http://liberator.example.com/applet-test".
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.
| Web Server Host Name | Liberator Host Name | Result |
|---|---|---|
localhost |
liberator.example.com |
Failure - localhost will not be resolved to the fully qualified host name of
the web server (e.g. server.example.com). |
devweb |
liberator.example.com |
Failure - the web server host name will not be resolved to its fully qualified name (e.g. devweb.example.com). |
192.0.34.166 |
liberator.example.com |
Failure - the web server IP address will not be resolved to the corresponding fully qualified host name (e.g. devweb.example.com). |
devweb.demo.com |
liberator.example.com |
Failure - although both the web server and Liberator host names have been fully qualified, they do not share a common domain. |
devweb.example.com |
liberator.example.com |
Success - both the web server and Liberator host names have been fully qualified and they
share a common domain (example.com). |
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:
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:
commondomain
configuration attribute. The SL4B library will use this attribute to set the
document.domain property whilst it is loading.document.domain property to the relevant value within the pages
that the SL4B-enabled page needs to communicate with.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.
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.
SL4B allows multiple subclasses of
SL4B_AbstractSubscriber to be created.
There are two main advantages gained by this:
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:
SL4B_WindowEventHandler.addListener()
method, instead of directly on the window.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.
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);
There are two general approaches to troubleshooting problems within the page. The first, the SL4B client log, deals with issues around connectivity to the Liberator and receiving streaming data, whilst the second, exceptions, deals with how to catch and debug exceptions that are thrown by user code during callbacks - by default SL4B suppresses these exceptions.
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.
SL4B_Accessor.getConfiguration().setAttribute("debug", SL4B_DebugLevel.DEBUG);
<script type="text/javascript" id="sl4b" src="./sl4b/" debug="info"></script>
http://liberator.example.com/demo/mysl4bpage.html?debug=warn
SL4B_DebugLevel.WARN or
greater, the SL4B client log window, displaying the logged messages, will automatically open.
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:
|
| 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.
By default, SL4B catches any exceptions thrown whilst it is executing a callback method. This
prevents other updates that are part of a batch from being lost, and it stops production users from
seeing any script errors within the page. However, this can make it quite difficult and time
consuming to track down simple script errors within a development environment. This behaviour can
be modified by setting the suppressexceptions
configuration attribute to false.
As with the suppressexceptions attribute this can be set in one of three ways:
SL4B_Accessor.getConfiguration().setAttribute("suppressexceptions", "false");
<script type="text/javascript" id="sl4b" src="./sl4b/" suppressexceptions="false"></script>
http://liberator.example.com/demo/mysl4bpage.html?suppressexceptions=false