Class FlashTable

Object
   |
   +--FlashTable

class FlashTable

Represents a data table that can be fed with real-time data (delivered by Lightstreamer Server). It contains the subscription details and the event handlers needed to process the real-time data. When a FlashTable object is added to a JavaScriptBridge object, through the JavaScriptBridge.addTable() method, its state becomes "running". This means that the Engine activates a subscription to the required items through Lightstreamer Server and the data-table object begins to receive real-time events.
Defined in lsjavascriptbridge.as

Constructor Detail

FlashTable

FlashTable(<String> _group,<String> _schema,<String> _mode)

Creates an object to be used to describe a data table. The object can be supplied to JavaScriptBridge.addTable() and JavaScriptBridge.removeTable(), in order to bring the data table to "running" or back to "inactive" state.

Parameters:
_group - a String group identifier, which identifies the items that provide values for the data table rows.
An Array of String with the names of the items in the group can also be used directly, instead of a group identifier; the items will be assigned position numbers accordingly; numbers should not be used as field names. However, in this case, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.
_schema - a String schema identifier, which identifies the fields that represent the data table columns.
An Array of String with the names of the fields in the schema can also be used directly, instead of a schema identifier; the fields will be assigned position numbers accordingly; numbers should not be used as field names. However, in this case, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.
_mode - the subscription mode for the items, required by Lightstreamer Server. Permitted values are:
• MERGE
• DISTINCT
• RAW
• COMMAND

onEndOfSnapshot

void onEndOfSnapshot(<Number> itemPos,<String> itemName)

Event handler that is called by Lightstreamer to notify that all snapshot events for an item in the data table 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 setting a custom handler it is possible to perform actions which require that all data table initial values have been received.

Default implementation: do nothing

Parameters:
itemPos - 1-based index of the item within the group.
itemName - name of the item or null, depending on the way the group was identified in the FlashTable constructor. In case an Array of item names was supplied, the name is available; otherwise null is passed.

See:
- setSnapshotRequired()

onItemUpdate

void onItemUpdate(<Number> itemPos,<FlashUpdateItemInfo> updateInfo,<String> itemName)

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

Default implementation: do nothing

Parameters:
itemPos - 1-based index of the item within the group.
updateInfo - a value object containinig the updated values for all the fields, together with the old values for the fields.
itemName - name of the item or null, depending on the way the group was identified in the FlashTable constructor. In case an Array of item names was supplied, the name is available; otherwise null is passed.

onLostUpdates

void onLostUpdates(<Number> itemPos,<Number> lostUpdates,<String> itemName)

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 data table. 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 setting a custom handler it is possible to perform recovery actions.

Default implementation: do nothing

Parameters:
itemPos - 1-based index of the item within the group.
lostUpdates - The number of consecutive updates dropped for the item.
itemName - name of the item or null, depending on the way the group was identified in the FlashTable constructor. In case an Array of item names was supplied, the name is available; otherwise null is passed.

See:
- setRequestedMaxFrequency()

onStart

void onStart()

Event handler that is called by Lightstreamer to notify that a data table has been successfully subscribed to through the Server. This can happen multiple times in the life of a data table, in case the data table subscription is performed multiple times through JavaScriptBridge.removeTable() and JavaScriptBridge.addTable(). 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.

Default implementation: do nothing

setDataAdapter

void setDataAdapter(<String> adapter)

Setter method that sets the name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items in the Group.
The Data Adapter name is configured on the server side through the "name" attribute of the "data_provider" element, in the "adapters.xml" file that defines the Adapter Set (a missing attribute configures the "DEFAULT" name).
Note: If more than one Data Adapter is needed to supply all the items in a set of items, then it is not possible to group all the items of the set in a single logical table. Multiple logical tables have to be defined.

Invocation: optional.

Default value: "DEFAULT".

Lifecycle: The Data Adapter name can be set and changed while the data table is in "inactive" state. Each time the data table is brought to "running" state through JavaScriptBridge.addTable(), the Data Adapter name is specified in the subscription request.

Parameters:
adapter - the name of the Data Adapter. A null value is equivalent to the "DEFAULT" name.

setItemsRange

void setItemsRange(<Number> _start,<Number> _end)

Setter method that sets a range of items within the specified group. Items outside of this range are not subscribed. The support for ranges allows the front-end to use generic group identifiers as group descriptors, yet being able to subscribe to subsets of such groups or even to single items from such groups, without the need to introduce more specific group identifiers.
Moreover, this method allows for continually resubscribing different item subsets without the need for creating different data table objects.

Invocation: optional.

Default value: all the items in the specified group.

Lifecycle: The items range can be set and changed while the data table is in "inactive" state. Each time the data table is brought to "running" state through JavaScriptBridge.addTable(), the items range is specified in the subscription request.

Parameters:
_start - 1-based index of the first item in the group that has to be subscribed.
_end - 1-based index of the last item in the group that has to be subscribed.

setRequestedBufferSize

void setRequestedBufferSize(<Number> buffSize)

Setter method that sets the length to be requested to Lightstreamer Server for the internal queueing buffers for the items in the data table. A Queueing buffer is used by the Server to accumulate a burst of updates for an item, so that they can all be sent to the client, despite of bandwidth or frequency limits. It can be used only when the subscription mode is MERGE or DISTINCT and unfiltered dispatching has not been requested. Note that the Server may pose an upper limit on the size of its internal buffers.

Invocation: optional.

Default value: 1 if the subscription mode is MERGE; "unlimited" otherwise

Lifecycle: The buffer size can be set and changed while the data table is in "inactive" state. Each time the data table is brought to "running" state through JavaScriptBridge.addTable(), the buffer size is specified in the subscription request.

Parameters:
buffSize - The length of the internal queueing buffers to be used in the Server. If a 0 value or the string "unlimited" is supplied, then the buffer length is decided by the Server.

See:
- setRequestedMaxFrequency()

setRequestedMaxFrequency

void setRequestedMaxFrequency(<String> maxFreq)

Setter method that sets the maximum update frequency to be requested to Lightstreamer Server for all the items in the data table. It can be used only if the subscription mode is MERGE, DISTINCT or COMMAND (in the latter case, the frequency limitation applies to the UPDATE events for each single key). Note that frequency limits on the items can also be set on the server side and this request can only be issued in order to furtherly reduce the frequency, not to rise it beyond these limits.
This method can also be used to request unfiltered dispatching for the items in the data table. However, unfiltered dispatching requests may be refused if any frequency limit is posed on the server side for some item.
Edition Note: A further global frequency limit is also imposed by the Server, if it is running in Presto edition; this specific limit also applies to RAW mode and to unfiltered dispatching.
Edition Note: A further global frequency limit is also imposed by the Server, if it is running in Allegro edition; this specific limit also applies to RAW mode and to unfiltered dispatching.
Edition Note: A further global frequency limit is also imposed by the Server, if it is running in Moderato edition; this specific limit also applies to RAW mode and to unfiltered dispatching.

Invocation: optional.

Default value: "unlimited"

Lifecycle: The maximum frequency can be set and changed as long as the data table is in "inactive" state. Each time the data table is brought to "running" state through JavaScriptBridge.addTable(), the maximum frequency is specified in the subscription request.

Parameters:
maxFreq - The maximum update frequency (expressed in updates per second) for each item in the data table. If a 0 value or the string "unlimited" is supplied, then the maximum frequency is decided by the Server. It is also possible to supply the string "unfiltered", to ask for unfiltered dispatching, if it is allowed for the items.

setSelector

void setSelector(<String> selector)

Setter method that sets the selector name for all the items in the data table. The selector is a filter on the updates received. It is executed on the Server and implemented by the Metadata Adapter.

Invocation: optional.

Default value: null (no selector).

Lifecycle: The selector can be set and changed while the data table is in "inactive" state. Each time the data table is brought to "running" state through JavaScriptBridge.addTable(), the selector is specified in the subscription request.

Parameters:
selector - name of a selector, to be recognized by the Metadata Adapter, or null to unset the selector.

setSnapshotRequired

void setSnapshotRequired(<boolean> required)

Setter method that enables/disables snapshot delivery request for the items in the data table. The snapshot can be requested only if the subscription mode is MERGE, DISTINCT or COMMAND.

Invocation: optional.

Default value: false

Lifecycle: The snapshot request can be set and changed as long as the data table is in "inactive" state. Each time the data table is brought to "running" state through JavaScriptBridge.addTable(), the snapshot request is specified in the subscription request.

Parameters:
required - true/false to request/not request snapshot delivery. If the subscription mode is DISTINCT, instead of true, it is also possible to supply a number, to specify the requested length of the snapshot (though the length of the received snapshot may be less than requested, because of insufficient data or server side limits); passing true means that the snapshot length should be determined only by the Server.