Class Table

Object
   |
   +--Table

Direct Known Subclasses:

NonVisualTable, VisualTable

class Table

The base class for the hierarchy of the data-table classes. It contains the subscription details and the event handlers needed to process the real-time data. A specialized (derived) object, rather than a Table object, should be created and used. After the creation, a data-table object is in the "inactive" state. When a data-table object is added to a PushPage object, through the PushPage.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 lspushpage.js

Constructor Detail

Table

Table(<GroupDescriptor> tGroup, <SchemaDescriptor> tSchema, <String> tSubscriptionMode)

Used by specialized data table objects to inherit the support for the properties and event handlers common to all data tables management.

Parameters:
tGroup - A group descriptor object, which identifies the items that provide values for the data table rows. An Array of item names or a String group identifier can also be used directly, instead of a group descriptor object.
Note that, in case a GroupListDescriptor or an array is used, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.
tSchema - A schema descriptor object, which identifies the fields that represent the data table columns. An Array of field names or a String schema identifier can also be used directly, instead of a schema descriptor object.
Note that, in case a SchemaListDescriptor or an array is used, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.
tSubscriptionMode - the subscription mode for the items, required by Lightstreamer Server. Permitted values are:
• MERGE
• DISTINCT
• RAW
• COMMAND

getClassName

String getClassName()

Inquiry method that returns the name of the class of this instance. Useful to know which class in the Table hiearchy the current object is an instance of (e.g. OverwriteTable, NonVisualTable, etc.).

Returns:
The name of the class of this instance.

getId

String getId()

Inquiry method that returns the identifier associated to the data table, provided that the data table is currently in "running" state.

Returns:
The identifier associated to the data table, if the data table is currently in "running" state; null otherwise.

See:
- PushPage.addTable()

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 involved item. If a group identifier has been used as group descriptor for the data table, then a null value is supplied.

See:
- setSnapshotRequired()
- UpdateItemInfo.isSnapshot()

onItemUpdate

void onItemUpdate(<Number> itemPos, <UpdateItemInfo> 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. By setting a custom handler, it is possible to extend each update by synthesizing and adding new fields to the fields received from the Server. These added fields are then processed by Lightstreamer in the same way as subscribed fields; in particular, they can be associated to HTML cells.
Extra fields allow the front-end to format the special fields required by Lightstreamer (e.g. the numeric fields for sorting or charting) without the involvement of the supplier Data Adapter. They also allow to display the same field on more than one HTML cell, avoiding the redundancy of requesting the field more than once in the subscription schema.

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. Values for extra fields can be added to the object before returning.
Note: the UpdateItemInfo instance supplied to the method may be reused by Lightstreamer across subsequent calls; so, it should not be stored and used after the method termination.
itemName - name of the involved item. If a group identifier has been used as group descriptor for the data table, then a null value is supplied.

onLostUpdates

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

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 involved item. 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 lost updates pertain to a second-level item (this, in turn, is only possible if setRequestedMaxFrequency() with the "unfiltered" argument was issued, as second-level items are always in "MERGE" mode). In this case, it specifies the value of the key that identifies the second-level item, while the other arguments identify the first-level item to which the key refers.

See:
- setRequestedMaxFrequency()
- MultiDynaMetapushTable
- NonVisualTable.setCommandLogic()

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 PushPage.removeTable() and PushPage.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. In case of a VisualTable, the cleaning of the visual table content has already been performed, according with the VisualTable.setClearOnAdd(), VisualTable.setClearOnRemove() and/or VisualTable.setClearOnDisconnected() settings.

Default implementation: do nothing

setDataAdapter

void setDataAdapter(<String> dataAdapter)

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 PushPage.addTable(), the Data Adapter name is specified in the subscription request.

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

See:
- Connection.setAdapterName()

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 PushPage.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.

See:
- GroupDescriptor

setRequestedBufferSize

void setRequestedBufferSize(<Number> size)

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 PushPage.addTable(), the buffer size is specified in the subscription request.

Parameters:
size - 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 (the check is case insensitive).

See:
- setRequestedMaxFrequency()

setRequestedMaxFrequency

void setRequestedMaxFrequency(<String> freq)

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 PushPage.addTable(), the maximum frequency is specified in the subscription request.

Parameters:
freq - 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. The check for the string constants is case insensitive.

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 PushPage.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 PushPage.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.

See:
- UpdateItemInfo.isSnapshot()