Class Context
Object
|
+--Context
- class
Context
Bean object that contains the configuration properties
shared by the client Engine page and by each Push-page.
The class constructor, its prototype and any other properties should never
be used directly; actually, Context is not even defined as a global name.
Defined in lscommons.js
See:
Constructor Summary |
Context
()
Used by Lightstreamer to provide context properties bean objects
to the LightstreamerEngine and PushPage objects.
|
Method Summary |
void
|
setDebugAlertsOnClientError(<boolean> enable)
Setter method that enables/disables debug mode.
|
void
|
setDomain(<String> domain)
Setter method that specifies the value to be set as the
"document.domain" page property for the client Engine page and all
Push-pages.
|
void
|
setRemoteAlertsOnClientError(<boolean> enable,<int> maxMexLen,<int> maxMex)
Setter method that enables/disables remote debug mode.
|
Context
Context()
Used by Lightstreamer to provide context properties bean objects
to the LightstreamerEngine and PushPage objects.
setDebugAlertsOnClientError
void setDebugAlertsOnClientError(<boolean> enable)
Setter method that enables/disables debug mode. In debug mode, errors
caused by unexpected conditions or by an incorrect use of the APIs
are notified through an alert message. This applies to the same errors
that are notified through the onClientError event handler on the page.
The alert is issued asynchronously.
The setting is local to each page and can be different on different
pages.
Default value:
- For a Push-Context.prototype.Page = true;; hence, startup errors that occur before
this call are always notified by an alert. However, no such startup
error can occur, provided that the PushPage object is created and
setDebugAlertsOnClientError(false) is called as the first
Lightstreamer-related operations on the page.
- For an Engine Context.prototype.page = the;current setting on the Master Push-Page
when PushPage.createEngine() is called.
Lifecycle: The setting can be changed at any time.
Parameters:
enable
- true to enable debug mode, false to disable.
setDomain
void setDomain(<String> domain)
Setter method that specifies the value to be set as the
"document.domain" page property for the client Engine page and all
Push-pages.
In fact, the same domain value should be set on all pages in order
for Lightstreamer to work. This requires that both Lightstreamer Server
and the Web Server which supplies the front-end pages belong to the
domain set.
Note that other front-end pages may need to explicitly perform the same
"document.domain" setting, in order to access properties on the client
Engine page or a Push-Page.
The domain for the Engine page is automatically configured by the
library, based on the domain configured for the Master Push-Page,
hence setting the domain for the Engine page is not needed.
Setting the domain is not required only when the front-end pages are
supplied by the internal web server of Lightstreamer Server (although
this scenario is only suggested for demo purpose); more precisely,
in that case, the default domain setting is adequate.
Remarks:
As said, for the Engine page, each Push-Page and the streaming pages
supplied by Lightstreamer Server, the domain name set must be consistent
with the hostname used to request the pages.
In the typical case, in which the Web Server hostname has the form
www.mycompany.com and Lightstreamer Server hostname has the form
push.mycompany.com, the "mycompany.com" domain is always accepted.
In special cases, the consistency rules may be browser dependent.
For instance, if the Web Server hostname has the short form mycompany.com
and Lightstreamer Server hostname has the form push.mycompany.com,
the "mycompany.com" domain has been found not to be accepted by Internet
Explorer prior to version 8 (hence, no domain setting is available in
this case, as "com" is too broad to be accepted). The limitation affects
all cases in which the domain name is the same as the hostname.
A similar case is when both the Web Server and Lightstreamer Server
sit on different ports of the same host. If the hostname is
www.mycompany.com, then setting the "mycompany.com" domain will work,
whereas setting the "www.mycompany.com" domain won't work on IE7.
On the other hand, on IE7, keeping the default domain on all pages would
work.
Because of the above limitations, using Lightstreamer in a production
environment in which the hostnames don't have the typical form is not
recommended. If such limitation is faced in a test environment, the
suggested workaround is to manipulate the client "hosts" file in order
to provide suitable hostnames to access the two servers.
Default value: The host name of the server that supplies the
front-end pages.
Lifecycle:
- For a Push-Context.prototype.Page = the;domain should be set on the
PushPage.context object before calling PushPage.bind().
The declared domain is set on the page by the library when the
bind method is called. If, for any reason, the domain setting is needed
before this moment, it can be set explicitly on the page.
- For an Engine Context.prototype.page = the;method is available only for backward
compatibility; as the domain for the Engine page is automatically
configured by the library, calling setDomain on the
LightstreamerEngine.context object is never needed.
Parameters:
domain
- The value to be set as the "document.domain" property of the web site. A null value can also be specified, with no effect.
setRemoteAlertsOnClientError
void setRemoteAlertsOnClientError(<boolean> enable,<int> maxMexLen,<int> maxMex)
Setter method that enables/disables remote debug mode. In remote debug mode,
errors caused by an incorrect use of the APIs are notified by sending a message
to Lightstreamer Server and then logged under the LightstreamerLogger.webclient
category as TRACE messages. This applies to the same errors that are notified
through the onClientError event handler on the page.
The setting is local to each page and can be different on different pages.
Note that when referring to a Push-Page, remote debug mode is effective only if
the page gets binded with an Engine page. Otherwise, error messages
are accumulated until this condition is satisfied.
In a clustered server environment, debugging messages are sent to the load-balancer
until a session is established with a specific server; after that, messages are sent
to the session server.
Default value:
- For a Push-Context.prototype.Page = false;; hence, startup errors that occur before
this call will not appear in the remote log. However, no such unreported
startup error can occur, provided that the PushPage object is created
and setRemoteAlertsOnClientError(true) is called as the first
Lightstreamer-related operations on the page.
- For an Engine Context.prototype.page = the;current setting on the Master Push-Page
when PushPage.createEngine() is called.
Lifecycle: The setting can be changed at any time.
Parameters:
enable
- true to enable remote debug mode, false to disable.
maxMexLen
- [Optional] maximum length allowed for each message to be sent to Lightstreamer Server; longer messages are truncated. Note that the message may include the whole source code of an event handler.
This parameter is optional; if missing or null, then no truncation is performed.
maxMex
- [Optional] maximum number of messages sent to the server during page lifetime. Note that an error occurring upon reception of an update may be reported to the Server once for each update.
This parameter is optional; if missing or null, then all messages are sent to the Server.
Lightstreamer HTML Client API
Documentation generated by
JSDoc on Tue May 22 11:46:54 2012