Class PushPage

Object
   |
   +--PushPage

class PushPage

Facade class for the management of a front-end page enabled to request push data to Lightstreamer Server (we call such a page a push-enabled page, or a Push-page). Used to provide configuration settings, event handlers and operations for adding and removing data tables to the "running" tables set and managing data values received.
Exactly one PushPage instance should be bound to each Push-page instance at page loading. This should be accomplished, on each page, by creating and configuring a PushPage instance and then calling bind() on it in a static script. Each instance can then be accessed after page loading, to use operations and change settings.
Defined in lspushpage.js

Field Detail

context

Context context

Bean object that contains context properties for the page. It can be accessed in order to provide context properties. Set up by the PushPage object at its own creation.

PushPage

PushPage()

Creates an object to be bound to the page, to provide configuration settings, operations and event handlers for the management of the data tables defined in the page.

addScreenTableHelper

void addScreenTableHelper(<ScreenTableHelper> screenTable)

Operation method that provides a helper object that can be used by the framework in order to access all the HTML cells that belong to a screen table.

Lifecycle: If a helper object is used for a screen table, it should be provided before the first association of the screen table with a data table through addTable().
Only one helper object can be used for each screen table. Changes in the screen table composition should be reflected on the helper object through ScreenTableHelper.addCell().

Parameters:
screenTable - A helper object that contains the pointers for the HTML cells that make up a screen table.

addTable

Table addTable(<Table> tableSpec, <String> id)

Operation method that adds a data table to the "running" tables set, by bringing it to the "running" state and associating it to a unique identifier. The data table cannot already be in the "running" state. If a different data table is currently in the "running" set with the same identifier, it is removed first; so, the method can also be used to substitute a "running" data table with a new one.
By bringing a table to the "running" state, the subscription to all its items is requested to Lightstreamer Server. The supplied identifier allows the data table to be associated to a screen table (i.e. a set of HTML cells defined in the page).
Note that once e screen table has been associated with a data table, from then on it can only be associated with data tables of the same type.

Lifecycle: Data tables can be added to the page manager at any time after the bind() method has been called. However, if a screen table is to be associated to a data table, then the data table can be added only after all the involved HTML cells have been attached to the page DOM. With statically defined HTML cells, this usually means calling addTable() in a static script at the end of the page or in the page "onload" event handler.
If the page is a Master Push-Page (i.e. createEngine() is called), consider that the creation of the Engine page will not be performed until the Push-Page document's "onload" event. Hence, if addTable is invoked before the Push-Page loading has finished, the subscription requests will not be forwarded to Lightstreamer Server until then.
Once added, a Table instance cannot be added again to the page manager. However, after being removed through removeTable(), the instance can be added again.

Parameters:
tableSpec - A Table object, carrying the data table description and all the information needed to process its pushed values.
id - An identifier to associate to the "running" table. For a VisualTable instance, the identifier is also used to find the screen table to be used for data table values display.

Returns:
The Table instance previously contained in the "running" tables set and associated with the specified identifier (and removed, in order to be substituted with the new instance), or null if no such data table was contained.

See:
- ScreenTableHelper

bind

boolean bind()

Initialization method that binds a PushPage instance with the page object. It should be called after all initialization settings on the PushPage object have been performed, in order to enable the page as a Lightstreamer Push-page. In order to subscribe data tables through addTable(), the PushPage object must be bound, so, the binding operation should be performed as soon as possible, in a static script block evaluated at page loading.
Note that the "document.domain" property specified through Context.setDomain() is set on the page by the bind() call. If any custom operation on the page requires that the default page domain is still set, then the binding operation can be postponed, provided that subscription operations are postponed too. Conversely, if very early operations on the page already require that the domain is set, the "document.domain" setting can be performed manually before the bind call.

Returns:
true if the binding operation was successful; false otherwise.

cellMetapush

void cellMetapush(<String> tableId, <Number> row, <FieldDescriptor> field, <String> initValue, <String> initStylesheet, <String> pushedHtmlEnabled, <String> tagType, <String> updateProperty)

Helper method that creates an HTML cell in the page. The created cell is ready to be part of a screen table that can be used to display values from a data table of the type MetapushTable. By default, the cell is created by Lightstreamer as a DIV element; any another element type can be specified. By default the content of the cell will be changed upon each server update but for INPUT and TEXTAREA cells (in that case the value property will be changed); any other property can be specified. The method can be used as an alternative way of defining such cells in the page, rather than explicitly declaring (or dynamically attaching) elements owning the "source='Lightstreamer'" special attribute. The association of the screen table with a MetapushTable object will be made through addTable().
For this function, it is also available the shorter alias name "LS_cM", defined on the page Window object.

Lifecycle: The function synthesizes the cell HTML code and appends it to the page through a "document.write" call. Then, it can be used only in a static script to be evaluated at page loading.
Note that if "cellMetapush" is used to create a cell for a screen table at page loading, then all the cells of such a screen table must be created in this way: explicitly declared cells are ignored for this screen table.

Parameters:
tableId - The identifier of the screen table to which the cell belongs. The screen table will be associated to a MetapushTable object as soon as this object is brought to "running" state through addTable() and this identifier is specified.
row - A 1-based row index. After the association with a MetapushTable object, the cell will be used as part of this data row.
field - a field descriptor object, to be used for the cell/field association. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
initValue - [Optional] the content to be written as the initial value of the cell element. This parameter is optional; if missing or null, then the cell is left empty. The supplied value will also be put in the cell in case of cell clearing.
initStylesheet - [Optional] the name of an existing stylesheet to be associated with the cell element. This parameter is optional; if missing or null, then no stylesheet is applied to the cell. The supplied stylesheet will also be applied in case of cell clearing.
pushedHtmlEnabled - [Deprecated] this setting is now ignored and is only kept for compatibility with previously developed code. A cell created with this method can now be used with both simple and HTML values. See {VisualTable#setPushedHtmlEnabled}.
tagType - [Optional] an element type name, like "DIV" or "SPAN", to specify the element type to be used for the created cell. Though DIV or SPAN are the suggested ones, any element type is allowed. This parameter is optional; if missing or null, then a DIV element is created.
updateProperty - [Optional] the property of the cell to be updated in response to a new value received from the server. Any string can be specified; moreover a value of a stylesheet can be specified using the "style.attribute" form (note that the DOM attribute name should be used, not the CSS name; e.g. "style.backgroundColor" is accepted, while "style.background-color" is not). WARNING: also events like "onclick" can be assigned; in such cases make sure that no malicious code will be pushed by the Data Adapter (for example through the injection of undesired JavaScript code). This parameter is optional; if missing or null the content of the cell will be updated (but for INPUT and TEXTAREA element types where the value property willbe updated).

cellOverwrite

void cellOverwrite(<String> tableId, <ItemDescriptor> item, <FieldDescriptor> field, <String> initValue, <String> initStylesheet, <String> pushedHtmlEnabled, <String> tagType, <String> updateProperty)

Helper method that creates an HTML cell in the page. The created cell is ready to be part of a screen table that can be used to display values from a data table of the type OverwriteTable. By default, the cell is created by Lightstreamer as a DIV element; any another element type can be specified. By default the content of the cell will be changed upon each server update but for INPUT and TEXTAREA cells (in that case the value property will be changed); any other property can be specified. The method can be used as an alternative way of defining such cells in the page, rather than explicitly declaring (or dynamically attaching) elements owning the "source='Lightstreamer'" special attribute. The association of the screen table with an OverwriteTable object will be made through addTable().
For this function, it is also available the shorter alias name "LS_cell", defined on the page Window object.

Lifecycle: The function synthesizes the cell HTML code and appends it to the page through a "document.write" call. Then, it can be used only in a static script to be evaluated at page loading.
Note that if "cellOverwrite" is used to create a cell for a screen table at page loading, then all the cells of such a screen table must be created in this way: explicitly declared cells are ignored for this screen table.

Parameters:
tableId - The identifier of the screen table to which the cell belongs. The screen table will be associated to an OverwriteTable object as soon as this object is brought to "running" state through addTable() and this identifier is specified.
item - an item descriptor object, to be used for the cell/item association. A String item name or a Number representing an item position can also be used directly, instead of an item descriptor object.
field - a field descriptor object, to be used for the cell/field association. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
initValue - [Optional] the content to be written as the initial value of the cell element. This parameter is optional; if missing or null, then the cell is left empty. The supplied value will also be put in the cell in case of cell clearing.
initStylesheet - [Optional] the name of an existing stylesheet to be associated with the cell element. This parameter is optional; if missing or null, then no stylesheet is applied to the cell. The supplied stylesheet will also be applied in case of cell clearing.
pushedHtmlEnabled - [Deprecated] this setting is now ignored and is only kept for compatibility with previously developed code. A cell created with this method can now be used with both simple and HTML values. See {VisualTable#setPushedHtmlEnabled}.
tagType - [Optional] an element type name, like "DIV" or "SPAN", to specify the element type to be used for the created cell. Though DIV or SPAN are the suggested ones, any element type is allowed. This parameter is optional; if missing or null, then a DIV element is created.
updateProperty - [Optional] the property of the cell to be updated in response to a new value received from the server. Any string can be specified; moreover a value of a stylesheet can be specified using the "style.attribute" form (note that the DOM attribute name should be used, not the CSS name; e.g. "style.backgroundColor" is accepted, while "style.background-color" is not). WARNING: also events like "onclick" can be assigned; in such cases make sure that no malicious code will be pushed by the Data Adapter (for example through the injection of undesired JavaScript code). This parameter is optional; if missing or null the content of the cell will be updated (but for INPUT and TEXTAREA element types where the value property willbe updated).

cellScroll

void cellScroll(<String> tableId, <Number> row, <FieldDescriptor> field, <String> initValue, <String> initStylesheet, <String> pushedHtmlEnabled, <String> tagType, <String> updateProperty)

Helper method that creates an HTML cell in the page. The created cell is ready to be part of a screen table that can be used to display values from a data table of the type ScrollTable. By default, the cell is created by Lightstreamer as a DIV element; any another element type can be specified. By default the content of the cell will be changed upon each server update but for INPUT and TEXTAREA cells (in that case the value property will be changed); any other property can be specified. The method can be used as an alternative way of defining such cells in the page, rather than explicitly declaring (or dynamically attaching) elements owning the "source='Lightstreamer'" special attribute. The association of the screen table with a ScrollTable object will be made through addTable().
For this function, it is also available the shorter alias name "LS_cs", defined on the page Window object.

Lifecycle: The function synthesizes the cell HTML code and appends it to the page through a "document.write" call. Then, it can be used only in a static script to be evaluated at page loading.
Note that if "cellScroll" is used to create a cell for a screen table at page loading, then all the cells of such a screen table must be created in this way: explicitly declared cells are ignored for this screen table.

Parameters:
tableId - The identifier of the screen table to which the cell belongs. The screen table will be associated to a ScrollTable object as soon as this object is brought to "running" state through addTable() and this identifier is specified.
row - A 1-based row index. After the association with a ScrollTable object, the cell will be used as part of this data row.
field - a field descriptor object, to be used for the cell/field association. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
initValue - [Optional] the content to be written as the initial value of the cell element. This parameter is optional; if missing or null, then the cell is left empty. The supplied value will also be put in the cell in case of cell clearing.
initStylesheet - [Optional] the name of an existing stylesheet to be associated with the cell element. This parameter is optional; if missing or null, then no stylesheet is applied to the cell. The supplied stylesheet will also be applied in case of cell clearing.
pushedHtmlEnabled - [Deprecated] this setting is now ignored and is only kept for compatibility with previously developed code. A cell created with this method can now be used with both simple and HTML values. See {VisualTable#setPushedHtmlEnabled}.
tagType - [Optional] an element type name, like "DIV" or "SPAN", to specify the element type to be used for the created cell. Though DIV or SPAN are the suggested ones, any element type is allowed. This parameter is optional; if missing or null, then a DIV element is created.
updateProperty - [Optional] the property of the cell to be updated in response to a new value received from the server. Any string can be specified; moreover a value of a stylesheet can be specified using the "style.attribute" form (note that the DOM attribute name should be used, not the CSS name; e.g. "style.backgroundColor" is accepted, while "style.background-color" is not). WARNING: also events like "onclick" can be assigned; in such cases make sure that no malicious code will be pushed by the Data Adapter (for example through the injection of undesired JavaScript code). This parameter is optional; if missing or null the content of the cell will be updated (but for INPUT and TEXTAREA element types where the value property willbe updated).

createEngine

String createEngine(<String> applicationName, <String> path, <String> onSimilarEngineFound, <boolean> suppressDefaultStatusChangeHandler)

Operation method that creates a hidden IFRAME hosted by this Push-Page and loads the client Engine page into it. If the front-end includes more than one Push-Page, then only one of them should be elected for the creation of the Engine page; all other Push-Pages should share the Engine page through the seekEngine() method (but see "SHARE_SESSION" below for special cases). A Push-Page that is currently hosting the Engine page is referred to as the current "Master Push-Page".
As a consequence of the createEngine call, after Engine page creation, the Master Push-Page onEngineCreation() event handler will be called, allowing the Master Push-Page to complete the Engine configuration; this usually includes setting connection properties and changing the status to "STREAMING".
Whenever possible, the Master Push-Page should be a permanent page. If a reload of a Master Push-Page were requested, then the connection to Lightstreamer Server would be reestablished too. If no Push-Page is a permanent page, but some other permanent page is available, then it may be preferable to transform one such page into a fake Push-Page that does not define any data table, so as to elect it as the Master Push-Page.

Lifecycle: The Master Push-Page should call createEngine as soon as possible, possibly by a script that is evaluated during page loading, just after the bind() call (which ensures that the domain configuration is completed). However, the creation of the Engine page will be deferred and performed upon the Push-Page document's "onload" event.
If any conflicts with page loading operations arise, then the createEngine method can also be called after the page loading has terminated (in the document "onload" event handler, for instance).
Note that creating the Engine page does not cause a connection to Lightstreamer Server to be immediately performed, as the Engine initially starts in "DISCONNECTED" status.
Note that a warning alert, just for debugging purpose, is issued if neither seekEngine() nor createEngine() has been called some seconds after bind() has been called. Remind that warning alerts can be suppressed through Context.setDebugAlertsOnClientError().

Parameters:
applicationName - A unique alphanumeric name for the front-end application. The name can be used by other Push-Pages in order to locate the Engine page, through the seekEngine() method.
path - The base URL of Lightstreamer Web Client Library resources (i.e. the URL of the directory containing the Library resources), in absolute or relative form.
Note that a path in a relative form will be appended to the directory part of the Push-Page url, as usual; for instance, if the page is accessed through "http://www.mysite.com/myApp/index.html", then "http://www.mysite.com/myApp/" will be used. Hence, you should consider all the possible paths through which the page can be accessed; for instance "www.mysite.com/myApp/" would be ok, while "www.mysite.com/myApp" might not work and should not be allowed.
onSimilarEngineFound - [Optional] The action to be taken in case an Engine page with the same application name and coming from the same host is found in the browser. This is the signal that another instance of the same application is already running in the browser.
Can be one of the following:
• "FAIL" The Engine creation fails and push data will not be available for this Push-Page; seekEngine() calls performed by other Push-Pages belonging to the same application instance will also fail in finding the Engine.
  This policy may be useful in order to avoid that multiple streaming connections are open (note that the browser may have a limited pool of connections) or that multiple sessions for the same user are open, for applications in which the "SHARE_SESSION" option is not feasible.
  In case of Engine creation failure, the onEngineCreation() event handler will still be called, with a null LightstreamerEngine pointer.
• "SHARE_SESSION" The current Engine instance is used instead of creating a new one.
  Note that it is an application responsibility to ensure that the configuration of the existing instance of the Engine (the user credentials, for instance) is consistent with the configuration required by the new instance of the application front-end. In particular, note that the allocated bandwidth would be shared among the two (or more) application instances as well.
  When this policy is applied, it is possible for other Push-Pages to call seekEngine() without providing a "Reference Push-Page pointer".
  Sharing the Engine page also enables the so called "engine migration" feature. If the Master Push-Page is closed and other Push-Pages share the Engine with it and a new Master Push-Page is not immediately provided by the application, then one of the existing Push-Pages will be automatically chosen as the new Master Push-Page; this page will load a new Engine page and will make it available for the other pages for sharing.
  The new Engine will be automatically configured by library code, by replicating the configuration of the previous one, but for the event handlers. As a consequence, no call to onEngineCreation() will be performed. This allows the library to elect any page as the new Master, regardless that the page started as a potential Master (i.e. it called "createEngine" and did not create the Engine because it could share it) or not (i.e. it called seekEngine()).
  Note that, in the latter case, the library url path, which is not supplied by seekEngine(), will also be inherited from the previous Engine, so it might not be related with the url of the new Master page.
• "NEW_SESSION". The Engine is going to be created in any case; other Push-Pages belonging to the same application instance will be allowed to link to this Engine instance only.
This parameter is optional; if null or missing, then "NEW_SESSION" is assumed.
Note that this parameter should always be set as the same value for all runs of the front-end application and for any different front-end application that shares the same application name and can be supplied by the same host.
Also note that there may be cases in which the library is not able to determine whether a similar Engine page is currently active. In any of those cases, the library would behave as though "NEW_SESSION" were specified. One such case is when client-side cookies are not enabled.
Moreover, there may be cases in which "SHARE_SESSION" is specified and the library is not able to obtain a reference to a currently active Engine page. In any of those cases, the library would also behave as though "NEW_SESSION" were specified. One such case is when the existing Engine page is in a different window in Opera browser. Another case is when the existing engine page comes from a different host than the current page (though still under the same domain) on Firefox 2.x browser. In the above cases, a temporary popup window might also show-up during the failed attempt to acquire the Engine page pointer.
suppressDefaultStatusChangeHandler - [Optional] if true, the default handling provided by the Engine for the LightstreamerEngine.onStatusChange() event is disabled. This parameter is optional; if missing or null, then the default handling is enabled.

See:
- LightstreamerEngine
- LightstreamerEngine.changeStatus()

getTable

Table getTable(<String> id)

Inquiry method that returns a Table instance that is currently in the "running" tables set and is associated to a supplied identifier, if any.

Parameters:
id - The identifier previously associated through addTable() to the requested Table instance.

Returns:
A Table object, representing a data table currently in "running" state, or null.

getTables

Map getTables()

Inquiry method that returns a map containing all the Table instances for this PushPage that are currently in "running" state. This map could be iterated to get all the contained instances.
Internal second-level tables related with any MultiDynaMetapushTable are not included.

Returns:
A map object, containing all the data Tables currently in "running" state. Each Table object is indexed by the identifier previously associated through addTable(), so that getTables()["myId"] yields the table associated to "myId". The map object can be empty.

getWindowReference

Window getWindowReference()

Inquiry method that returns the reference to the Window object relative to the HTML page where this instance of PushPage was created.

Returns:
A pointer to the Window object relative to the HTML page where this instance of PushPage was created.

isMasterPushPage

boolean isMasterPushPage()

Inquiry method that allows a page to know whether it is currently hosting the Engine page. The inquiry can only be made inside the onEngineReady() event handler or after it, until the next call to onEngineLost().
The inquiry only makes sense for applications in which the Engine is created by specifying "SHARE_SESSION" as onSimilarEngineFound in the createEngine() call. In this case, a page may call createEngine() and not become the Master Push-Page. Conversely, a page may call seekEngine() and, by virtue of the "engine migration" feature, it may later become the Master Push-Page.

Returns:
true if the Push-Page is currently hosting the Engine page.

onClientAlert

void onClientAlert(<Number> code,<String> errorMex)

Event handler that is called whenever a browser related problem arises.
By default an alert is prompted to inform the final user. If the default implementation is overridden, the default alert will not be shown and some custom recovery should be taken.
Note that it is not advisable to stop the alerts, because they notify the final user on any critical conditions that prevent the application from working.

Default implementation: Shows an alert with the error code and information message.

Parameters:
code - The error code related to the error. It can be one of the following:
• 100 - A specific antivirus software installed on the client machine could prevent the framework from working properly.
• 110 - The JavaScript engine of the browser is not respecting the timeouts in setTimeout method calls.
• 120 - There are probably other web applications connected to the same Lightstreamer Server within the same browser instance. That could prevent the current application from connecting to the Server.
• 130 - Firebug is known to cause memory issues with
errorMex - The text of the alert that will be displayed to the user.

onClientError

void onClientError(<String> errorMex)

Event handler that is called whenever an unexpected condition prevents some library operation on this PushPage from working correctly. Possible cases usually fall into one of the following categories:
• A library operation method or property setter has been invoked with an incorrect argument; in this case, an exception will eventually be thrown by the invoked method. This also includes setters of Engine properties.
• An unexpected condition prevents an operation method from working correctly.
• A custom event handler defined in this page (other than onClientError) raises an exception.
• An unexpected condition occurs during an internal library task.
By setting a custom handler it is possible to log the problem or perform recovery actions, such as refreshing the page. When the error occurs during an API method invocation (i.e. the first two cases above), the handler is invoked in a blocking way before the method returns; however, any recovery action won't be able to restore the normal behavior of the affected method. Otherwise, the handler is invoked asynchronously with respect to application code.
In a normal operation scenario, such notification should never occur.
Note that all errors occurring before the Push-Page initialization is complete (i.e. the bind() method has been called) are buffered and sent on bind() return, to the listener currently set.

Default implementation: do nothing

Parameters:
errorMex - The description of the error generated on the page.

onEngineCreation

void onEngineCreation(<LightstreamerEngine> engine)

Event handler that is called on a Master Push-Page, as a consequence of the createEngine() call, as soon as the Engine page has been created. This allows the Master Push-Page to complete the Engine configuration; this usually includes setting connection properties and changing the status to "STREAMING".
If "SHARE_SESSION" is specified as onSimilarEngineFound in the createEngine() call and an Engine page with the same application name is found in the browser (so that sharing occurs), then the handler is not called.
If "SHARE_SESSION" is specified as onSimilarEngineFound in the createEngine() call, then the handler should not be used in order to perform unique operations on the Engine (i.e. operations to be performed by only one Push-Page, like setting an application-level event handler on the Engine). This is because, each time an "engine migration" occurs, a new Engine is created but no call to "onEngineCreation" is performed. For that task, use onEngineReady() and distinguish the Master Push-Page through isMasterPushPage() instead.
The handler should be set before the createEngine() call.

Default implementation: do nothing

Parameters:
engine - The LightstreamerEngine instance bound to the Engine page. A null value can also be supplied if "FAIL" was specified as onSimilarEngineFound in the createEngine() call and an Engine page with the same application name has been found in the browser. When this happens, the new Engine page has not been created and no Engine page is available for the Push-Page.
The object received is a local proxy for the object residing on the Engine page; all configuration settings and inquiries are forwarded to the Engine page; however, the event handlers specified on the proxy object are specific for the Push-Page and are executed locally on the page.

See:
- LightstreamerEngine.changeStatus()

onEngineLost

void onEngineLost()

Event handler that is called as soon as the Push-Page notices that the previously used reference to the LightstreamerEngine object bound to the Engine page can no longer be used. This may happen, for instance, if the Push-page is on a popup and the Master Push-Page is closed or refreshed. This helps preventing error conditions if the page needs to call methods on this object (in order to manage the Engine state, for instance).
After losing the LightstreamerEngine reference, the Push-Page will try to recover the problem and access a (possibly different) Engine page, in order to perform the required subscriptions again (but see the "SHARE_SESSION" case on createEngine() for a more complex case of recovery).

Default implementation: do nothing

onEngineReady

void onEngineReady(<LightstreamerEngine> engine)

Event handler that is called as soon as the Push-page has created the Engine page (in case of a Master Push-Page) or has linked to the Engine page (in case of a non-Master Push-Page) AND the LightstreamerEngine object on the Engine page is ready to be used (that is, the onEngineCreation() event handler call on the Master Push-Page has returned).
The handler should be set before the PushPage object bind() call is performed, in order to ensure that the Engine page link is not available yet, hence the "engine ready" event is still to happen.
Implementing this event handler allows the Push-Page to get a reference to the LightstreamerEngine object (in order to manage the Engine state, for instance). It also allows the Push-page to set its own event handlers for the LightstreamerEngine object. The LightstreamerEngine pointer received is valid until the onEngineLost() event handler is called.
The handler is also called after a call to onEngineLost(), as soon as a (possibly different) LightstreamerEngine object becomes available again.

Default implementation: do nothing

Parameters:
engine - The LightstreamerEngine instance bound to the Engine page.
The object received is a local proxy for the object residing on the Engine page; all configuration settings and inquiries are forwarded to the Engine page; however, the event handlers specified on the proxy object are specific for the Push-Page and are executed locally on the page.

See:
- onEngineCreation()

onServerDeny

void onServerDeny(<Number> code, <String> message, <Table> affectedTable, <Number> refItemPos, <String> refItemName, <String> refKey)

Event handler that is called when the Server notifies an error on a subscription/unsubscription request issued by this page on behalf of a table. By setting a custom handler it is possible to perform recovery actions.
Note that, in order to perform a new subscription attempt, removeTable() and addTable() should be issued again, even if no change to the table attributes has been applied.

Default implementation: Shows an alert with the error code and information message.

Parameters:
code - The error code sent by the Server. It can be one of the following:
• 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set
• 20 - session interrupted
• 21 - bad Group name
• 22 - bad Group name for this Schema
• 23 - bad Schema name
• 24 - mode not allowed for an Item
• 25 - bad Selector name
• 26 - unfiltered dispatching not allowed for an Item, because a frequency limit is associated to the item
• 27 - unfiltered dispatching not supported for an Item, because a frequency prefiltering is applied for the item
• 28 - unfiltered dispatching is not allowed by the current license terms (for special licenses only)
• 29 - RAW mode is not allowed by the current license terms (for special licenses only)
• <= 0 - the Metadata Adapter has refused the subscription or unsubscription request; the code value is dependent on the specific Metadata Adapter implementation
message - The description of the error sent by the Server; it can be null.
affectedTable - The pointer to the involved table object.
refItemPos - only supplied when the data table behaves in "MultiMetapush logic" and the subscription error pertains to an underlying data table. In this case, it specifies the 1-based index of the related first-level item within the group.
refItemName - only supplied when the data table behaves in "MultiMetapush logic" and the subscription error pertains to an underlying data table. In this case, it specifies the name of the related first-level item. However, if a group identifier has been used as group descriptor for the data table, then a null value is supplied.
refKey - only supplied when the data table behaves in "MultiMetapush logic" and the subscription error pertains to an underlying data table. In this case, it specifies the value of the key on the first-level item to which the second-level item is related.

See:
- Connection.setAdapterName()
- MultiDynaMetapushTable
- NonVisualTable.setCommandLogic()

removeTable

Table removeTable(<String> id)

Operation method that removes a data table that is currently in the "running" tables set and is associated with a supplied identifier, if any, by bringing it back to the "inactive" state.
By bringing back a table to the "inactive" state, the unsubscription to all its items is requested to Lightstreamer Server. Moreover, all the received contents of the data table are discarded. However, the values displayed in an associated screen table can be left on the page, by setting false to VisualTable.setClearOnRemove() before calling removeTable.

Lifecycle: Data tables, once added, can be removed from the page manager at any time.

Parameters:
id - The identifier previously associated through addTable() to the Table instance to be removed.

Returns:
The Table instance removed, or null if no data table in the "running" tables set was associated with the specified identifier.

seekEngine

void seekEngine(<String> applicationName, <Window> ref)

Operation method that allows any Push-Page that has not been elected as the Master Push-Page to link with an existing Engine page instance.
The Engine page should have been supplied to the front-end by calling createEngine() in the Master Push-Page and should be always accessible during the Push-Page lifetime, though it may be temporarily uninitialized at startup or refresh time (see the "SHARE_SESSION" case in createEngine() for special cases of Engine page creation; they can all naturally be brought back into this schema).
In order to make it possible to find the current Engine page, the unique application name supplied to the createEngine() call on the Master Push-Page should be specified. Optionally, a pointer to the Master Push-Page window object can also be supplied; alternatively, a pointer to the window object of another Push-Page which has already performed seekEngine can be supplied. Let's call it "Reference Push-Page pointer".
Under normal conditions, the search for the Engine page based on the application name succeeds. However, sometimes it may fail to find the Engine page or to access it (for instance, from Push-Pages hosted by popup windows in Opera browser). So, it is always recommended that a valid pointer to a Reference Push-Page page is provided.
Moreover, if the "onSimilarEngineFound" argument supplied to the createEngine() call on the Master Push-Page was "FAIL" or "NEW_SESSION" (or if it was left as the default value, which is "NEW_SESSION"), then providing a Reference Push-Page pointer is mandatory, as it ensures that the Engine page found belongs to the same instance of the application front-end. In particular, in case "FAIL" was supplied and the Engine page creation failed because a different application instance was already running, seekEngine will also fail to link with an Engine page and push data will not be available for this Push-Page.
Note that if a "document.domain" has been declared for the various Push-pages through the Context.setDomain() setting (the usual case), then other front-end pages may need to explicitly perform the same "document.domain" setting in order for each Push-page to be able to reach the Master Push-Page pointer.

Lifecycle: A non-Master Push-Page should link to the Engine page as soon as possible. Ideally, seekEngine should be invoked in a script that is evaluated during page loading, just after the bind() call (which ensures that the domain configuration is completed).
Note that a warning alert, just for debugging purpose, is issued if neither seekEngine() nor createEngine() has been called some seconds after bind() has been called. Remind that warning alerts can be suppressed through Context.setDebugAlertsOnClientError().

Parameters:
applicationName - A unique alphanumeric name for the front-end application, as supplied to the Engine page through createEngine().
ref - The pointer to the Master Push-Page or to another Push-Page which has already performed seekEngine.
In case the "onSimilarEngineFound" argument supplied to createEngine() was "SHARE", this parameter can be omitted; if not supplied, Lightstreamer will try to find the Engine page based on the application name only.

See:
- LightstreamerEngine

setCheckEngineTimeout

void setCheckEngineTimeout(<Number> checkEngineTimeout)

Setter method that sets the interval of the periodic check of the accessibility of the client Engine page.

Invocation: optional.

Default value: 5000 (5 seconds).

Lifecycle: This value can be set and changed at any time.

Parameters:
checkEngineTimeout - The time (in milliseconds) between two checks of the accessibility of the Engine page.

See:
- LightstreamerEngine