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.
The class constructor, its prototype and any other properties should never
be used directly; actually, Table is not even defined as a global name.
Defined in lspushpage.js
Constructor Summary |
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.
|
Method Summary |
String
|
getClassName()
Inquiry method that returns the name of the class of this instance.
|
GroupDescriptor
|
getGroup()
Inquiry method that returns the GroupDescriptor associated to the data table.
|
String
|
getId()
Inquiry method that returns the identifier associated to the data table,
provided that the data table is currently in "running" state.
|
SchemaDescriptor
|
getSchema()
Inquiry method that returns the SchemaDescriptor associated to the data table.
|
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.
|
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.
|
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.
|
void
|
onStart()
Event handler that is called by Lightstreamer to notify that a data
table has been successfully subscribed to through the Server.
|
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.
|
void
|
setItemsRange(<Number> start, <Number> end)
Setter method that sets a range of items within the specified group.
|
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.
|
void
|
setRequestedMaxFrequency(<Number> freq)
Setter method that sets the maximum update frequency to be requested to
Lightstreamer Server for all the items in the data table.
|
void
|
setSelector(<String> selector)
Setter method that sets the selector name for all the items in the
data table.
|
void
|
setSnapshotRequired(<boolean> required)
Setter method that enables/disables snapshot delivery request for the
items in the data table.
|
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.
getGroup
GroupDescriptor getGroup()
Inquiry method that returns the GroupDescriptor associated to the data table.
If the table was created with a GroupListDescriptor or an array of strings then a GroupListDescriptor is returned.
If the table was created with a GroupIdDescriptor or a string then a GroupIdDescriptor is returned.
If the table was created with a null as GroupDescriptor, the table is an instance of a subclass of VisualTable and is
in "running" state, then a GroupListDescriptor is returned, otherwise null is returned.
Returns:
The GroupDescriptor associated to the data table.
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.
getSchema
SchemaDescriptor getSchema()
Inquiry method that returns the SchemaDescriptor associated to the data table.
If the table was created with a SchemaListDescriptor or an array of strings then a SchemaListDescriptor is returned.
If the table was created with a SchemaIdDescriptor or a string then a SchemaIdDescriptor is returned.
If the table was created with a null as SchemaDescriptor, the table is an instance of a subclass of VisualTable and is
in "running" state, then a SchemaListDescriptor is returned, otherwise null is returned.
Returns:
The SchemaDescriptor associated to the data table.
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.
Note that, in case of "MultiMetapush logic", 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.
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.
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 that 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.
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 that 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.
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.
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.
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.
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.
Default value: 1 if the subscription mode is MERGE;
the special value "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).
setRequestedMaxFrequency
void setRequestedMaxFrequency(<Number> 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.
Default value: the special value "unlimited"
Lifecycle: The maximum frequency can be set and changed as
long as the data table is in "inactive" state.
Once the Table is in the "active" state this setting can still be changed
and a request to change the table frequency limit will be sent to the server,
but if the current or target value is "unfiltered" then an error will be
generated.
Parameters:
freq
- The maximum update frequency (expressed in updates per second) for each item in the data table; for instance, with a setting of 0.5, for each single item, no more than one update every 2 seconds will be received. 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.
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.
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.
Lightstreamer HTML Client API
Documentation generated by
JSDoc on Tue May 22 11:46:54 2012