Web Client 8.1.0-beta5

AbstractWidget

AbstractWidget

The base class for the hierarchy of the provided widgets. It is an abstract class representing a view on a set of tabular data, which is supposed to be some sort of HTML visualization widget. Each row in the tabular model is associated with a key.
The class offers some management methods to modify/poll the model behind the view but also implements the SubscriptionListener interface to be automatically fed by listening on a Subscription.
When listening for Subscription events the widget will choose what to use as key for its model based on the Subscription mode of the first Subscription it was added to as a listener:

  • If the Subscription mode is MERGE or RAW, the widget will use the item as key: each subscribed item will generate a row in the model. The key name will be the item name when available, otherwise the 1-based item position within the Subscription.
  • If the Subscription mode is COMMAND, the widget will use the value of the "key" field as key: each row in the COMMAND subscription will generate a row in the model. More precisely, the key value will be expressed as "<item> <key>" where <item> is the item name when available, otherwise the 1-based item position within the Subscription.
    Note that this behavior is naturally extended to two-level subscriptions.
  • If the Subscription mode is DISTINCT, the widget will use a progressive number as key: each update will generate a row in the model.
For each update received, all the included fields will be integrated into the row related to the update key. The field name will be the one specified on the related Subscription, when available; otherwise, it will be the 1-based field position within the related Subscription.
Note that if the Subscription contains the same item name or field name multiple times, their updates will not be distinguished in the model and the last value processed by the library for that name will be assigned to the model. You should ensure that item name or field name collisions cannot occur if the colliding names are used to represent different entities; for instance, this holds for collisions between first-level and second-level fields in a two-level Subscription. Collisions are also possible if the widget is added as a listener to other Subscription instances. In this case, also note that the new updates will be processed and integrated in the model in the way already determined for the first Subscription associated; so, you should ensure that the various Subscriptions yield compatible updates.
For each SubscriptionListener#onClearSnapshot event received from any of the Subscription the widget is listening to, all the rows internally associated to the cleared item are removed. In case of collisions between different items feeding the same row the row will be considered pertaining to the first item that fed it.

Note that methods from the SubscriptionListener should not be called by custom code.
Note that before any change to the internal model can be made, and thus before an instance of this class can be used as listener for a Subscription, the AbstractWidget#parseHtml method has to be called to prepare the view.
The class is not meant as a base class for the creation of custom widgets. The class constructor and its prototype should never be used directly.

Constructor

new AbstractWidget()

This is an abstract class; no instances of this class should be created.

See:

Extends

Methods

clean()

Removes all the rows from the model and reflects the change on the view.

Lifecycle: once the AbstractWidget#parseHtml method has been called, this method can be used at any time.

Throws:

if parseHtml has not been executed yet.

Type
IllegalStateException

getValue(key, field) → {String}

Returns the value from the model for the specified key/field pair. If the row for the specified key does not exist or if the specified field is not available in the row then null is returned.

Lifecycle: This method can be called at any time.

Parameters:
Name Type Description
key String

The key associated with the row to be read.
field String

The field to be read from the row.
Returns:

The current value for the specified field of the specified row, possibly null. If the value for the specified field has never been assigned in the model, the method also returns null.

Type
String

onClearSnapshot(itemName, itemPos)

Event handler that is called by Lightstreamer each time a request to clear the snapshot pertaining to an item in the Subscription has been received from the Server. More precisely, this kind of request can occur in two cases:

  • For an item delivered in COMMAND mode, to notify that the state of the item becomes empty; this is equivalent to receiving an update carrying a DELETE command once for each key that is currently active.
  • For an item delivered in DISTINCT mode, to notify that all the previous updates received for the item should be considered as obsolete; hence, if the listener were showing a list of recent updates for the item, it should clear the list in order to keep a coherent view.

Note that, if the involved Subscription has a two-level behavior enabled, the notification refers to the first-level item (which is in COMMAND mode). This kind of notification is not possible for second-level items (which are in MERGE mode).
This event can be sent by the Lightstreamer Server since version 6.0
Parameters:
Name Type Description
itemName String

name of the involved item. If the Subscription was initialized using an "Item Group" then a null value is supplied.
itemPos Number

1-based position of the item within the "Item List" or "Item Group".
Overrides:

onCommandSecondLevelItemLostUpdates(lostUpdates, key)

Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item that was subscribed to as a second-level subscription. Such notifications are sent only if the Subscription was configured in unfiltered mode (second-level items are always in "MERGE" mode and inherit the frequency configuration from the first-level Subscription).
By implementing this method it is possible to perform recovery actions.

Parameters:
Name Type Description
lostUpdates Number

The number of consecutive updates dropped for the item.
key String

The value of the key that identifies the second-level item.
Inherited From:
See:

onCommandSecondLevelSubscriptionError(code, message, key)

Event handler that is called when the Server notifies an error on a second-level subscription.
By implementing this method it is possible to perform recovery actions.

Parameters:
Name Type Description
code Number

The error code sent by the Server. It can be one of the following:

  • 14 - the key value is not a valid name for the Item to be subscribed; only in this case, the error is detected directly by the library before issuing the actual request to the Server
  • 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set
  • 21 - bad Group name
  • 22 - bad Group name for this Schema
  • 23 - bad Schema name
  • 24 - mode not allowed for an Item
  • 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)
  • 66 - an unexpected exception was thrown by the Metadata Adapter while authorizing the connection
  • 68 - the Server could not fulfill the request because of an internal error.
  • <= 0 - the Metadata Adapter has refused the subscription or unsubscription request; the code value is dependent on the specific Metadata Adapter implementation
message String

The description of the error sent by the Server; it can be null.
key String

The value of the key that identifies the second-level item.
Inherited From:
See:

onEndOfSnapshot(itemName, itemPos)

Event handler that is called by Lightstreamer to notify that all snapshot events for an item in the Subscription have been received, so that real time events are now going to be received. The received snapshot could be empty. Such notifications are sent only if the items are delivered in DISTINCT or COMMAND subscription mode and snapshot information was indeed requested for the items. By implementing this method it is possible to perform actions which require that all the initial values have been received.
Note that, if the involved Subscription has a two-level behavior enabled, the notification refers to the first-level item (which is in COMMAND mode). Snapshot-related updates for the second-level items (which are in MERGE mode) can be received both before and after this notification.

Parameters:
Name Type Description
itemName String

name of the involved item. If the Subscription was initialized using an "Item Group" then a null value is supplied.
itemPos Number

1-based position of the item within the "Item List" or "Item Group".
Inherited From:
See:

onItemLostUpdates(itemName, itemPos, lostUpdates)

Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item in the Subscription. Such notifications are sent only if the items are delivered in an unfiltered mode; this occurs if the subscription mode is:

  • RAW
  • MERGE or DISTINCT, with unfiltered dispatching specified
  • COMMAND, with unfiltered dispatching specified
  • COMMAND, without unfiltered dispatching specified (in this case, notifications apply to ADD and DELETE events only)
By implementing this method it is possible to perform recovery actions.
Parameters:
Name Type Description
itemName String

name of the involved item. If the Subscription was initialized using an "Item Group" then a null value is supplied.
itemPos Number

1-based position of the item within the "Item List" or "Item Group".
lostUpdates Number

The number of consecutive updates dropped for the item.
Inherited From:
See:

onItemUpdate(updateInfo)

Event handler that is called by Lightstreamer each time an update pertaining to an item in the Subscription has been received from the Server.

Parameters:
Name Type Description
updateInfo ItemUpdate

a value object containing the updated values for all the fields, together with meta-information about the update itself and some helper methods that can be used to iterate through all or new values.
Overrides:

onListenEnd(subscription)

Event handler that receives a notification when the SubscriptionListener instance is removed from a Subscription through Subscription#removeListener. This is the last event to be fired on the listener.

Parameters:
Name Type Description
subscription Subscription

the Subscription this instance was removed from.
Overrides:

onListenStart(subscription)

Event handler that receives a notification when the SubscriptionListener instance is added to a Subscription through Subscription#addListener. This is the first event to be fired on the listener.

Parameters:
Name Type Description
subscription Subscription

the Subscription this instance was added to.
Overrides:

onRealMaxFrequency(frequency)

Event handler that is called by Lightstreamer to notify the client with the real maximum update frequency of the Subscription. It is called immediately after the Subscription is established and in response to a requested change (see Subscription#setRequestedMaxFrequency). Since the frequency limit is applied on an item basis and a Subscription can involve multiple items, this is actually the maximum frequency among all items. For Subscriptions with two-level behavior (see Subscription#setCommandSecondLevelFields and Subscription#setCommandSecondLevelFieldSchema) , the reported frequency limit applies to both first-level and second-level items.
The value may differ from the requested one because of restrictions operated on the server side, but also because of number rounding.
Note that a maximum update frequency (that is, a non-unlimited one) may be applied by the Server even when the subscription mode is RAW or the Subscription was done with unfiltered dispatching.

Parameters:
Name Type Description
frequency String

A decimal number, representing the maximum frequency applied by the Server (expressed in updates per second), or the string "unlimited". A null value is possible in rare cases, when the frequency can no longer be determined.
Inherited From:

onSubscription()

Event handler that is called by Lightstreamer to notify that a Subscription has been successfully subscribed to through the Server. This can happen multiple times in the life of a Subscription instance, in case the Subscription is performed multiple times through LightstreamerClient#unsubscribe and LightstreamerClient#subscribe. This can also happen multiple times in case of automatic recovery after a connection restart.
This notification is always issued before the other ones related to the same subscription. It invalidates all data that has been received previously.
Note that two consecutive calls to this method are not possible, as before a second onSubscription event is fired an onUnsubscription event is eventually fired.
If the involved Subscription has a two-level behavior enabled, second-level subscriptions are not notified.

Overrides:

onSubscriptionError(code, message)

Event handler that is called when the Server notifies an error on a Subscription. By implementing this method it is possible to perform recovery actions.
Note that, in order to perform a new subscription attempt, LightstreamerClient#unsubscribe and LightstreamerClient#subscribe should be issued again, even if no change to the Subscription attributes has been applied.

Parameters:
Name Type Description
code Number

The error code sent by the Server. It can be one of the following:

  • 15 - "key" field not specified in the schema for a COMMAND mode subscription
  • 16 - "command" field not specified in the schema for a COMMAND mode subscription
  • 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set
  • 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)
  • 30 - subscriptions are not allowed by the current license terms (for special licenses only)
  • 66 - an unexpected exception was thrown by the Metadata Adapter while authorizing the connection
  • 68 - the Server could not fulfill the request because of an internal error.
  • <= 0 - the Metadata Adapter has refused the subscription or unsubscription request; the code value is dependent on the specific Metadata Adapter implementation
message String

The description of the error sent by the Server; it can be null.
Inherited From:
See:

onUnsubscription()

Event handler that is called by Lightstreamer to notify that a Subscription has been successfully unsubscribed from. This can happen multiple times in the life of a Subscription instance, in case the Subscription is performed multiple times through LightstreamerClient#unsubscribe and LightstreamerClient#subscribe. This can also happen multiple times in case of automatic recovery after a connection restart.


After this notification no more events can be recieved until a new SubscriptionListener#onSubscription event.
Note that two consecutive calls to this method are not possible, as before a second onUnsubscription event is fired an onSubscription event is eventually fired.
If the involved Subscription has a two-level behavior enabled, second-level unsubscriptions are not notified.

Overrides:

parseHtml()

Abstract method. See subclasses descriptions for details.

removeRow(key)

Removes a row from the internal model and reflects the change on the view. If no row associated with the given key is found nothing is done.

Lifecycle: once the AbstractWidget#parseHtml method has been called, this method can be used at any time.

Parameters:
Name Type Description
key String

The key associated with the row to be removed.
Throws:

if parseHtml has not been executed yet.

Type
IllegalStateException

setAutoCleanBehavior(onFirstSubscribe, onLastUnsubscribe)

Utility method that can be used to control part of the behavior of the widget in case it is used as a listener for one or more Subscription instances.
Specifying the two flags it is possible to decide to clean the model and view based on the status (subscribed or not) of the Subscriptions this instance is listening to.

Lifecycle: This method can be called at any time.

Parameters:
Name Type Description
onFirstSubscribe boolean

If true a AbstractWidget#clean call will be automatically performed if in the list of Subscriptions this instance is listening to there is no Subscription in the subscribed status and an onSubscription is fired by one of such Subscriptions.
As a special case, if in the list of Subscriptions this instance is listening to there is no Subscription in the subscribed status and this instance starts listening to a new Subscription that is already in the subscribed status, then it will be considered as if an onSubscription event was fired and thus a clean() call will be performed.
onLastUnsubscribe boolean

If true a AbstractWidget#clean call will be automatically performed if in the list of Subscriptions this instance is listening to there is only one Subscription in the subscribed status and the onUnsubscription for such Subscription is fired.
As a special case, if in the list of Subscriptions this instance is listening to there is only one Subscription in the subscribed status and this instance stops listening to such Subscription then it will be considered as if the onUnsubscription event for that Subscription was fired and thus a clean() call will be performed.
See:

updateRow(key, newValues)

Updates a row in the internal model and reflects the change on the view. If no row associated with the given key is found then a new row is created.
Example usage:
myWidget.updateRow("key1", {field1:"val1",field2:"val2"});

Lifecycle: once the AbstractWidget#parseHtml method has been called, this method can be used at any time. If called while an updateRow on the same internal model is still executing (e.g. if called while handling an onVisualUpdate callback), then the new update:

  • if pertaining to a different key and/or if called on a Chart instance, will be postponed until the first updateRow execution terminates;
  • if pertaining to the same key and if called on a StaticGrid / DynaGrid instance, will be merged with the current one.

Parameters:
Name Type Description
key String

The key associated with the row to be updated/added.
newValues Object

A JavaScript object containing name/value pairs to fill the row in the mode.
Note that the internal model does not have a fixed number of fields; each update can add new fields to the model by simply specifying them. Also, an update having fewer fields than the current model will have its missing fields considered as unchanged.
Throws:

if parseHtml has not been executed yet.

Type
IllegalStateException