Packagecom.lightstreamer.as_client
Classpublic class VisualTable
InheritanceVisualTable Inheritance mx.collections.ArrayCollection
Implements Table

A data table that will be fed with real-time data delivered by Lightstreamer Server and that can be set as the "dataProvider" property to any instance of mx.controls.listClasses.ListBase (or subclasses). The class contains the subscription details and event handlers that can be used to furtherly process the real-time data.

This data table can also be used as a non-visual object, (that is, with no association with a mx.controls.listClasses.ListBase instance), as an alternative to NonVisualTable, in order to take advantage of the features of the underlying mx.collections.ArrayCollection, such as caching of the current values.

Default MXML Propertysource

See also

mx.collections.ArrayCollection
http://livedocs.adobe.com/flex/3/langref/mx/collections/ArrayCollection.html
mx.controls.listClasses.ListBase
http://livedocs.adobe.com/flex/3/langref/mx/controls/listClasses/ListBase.html
com.lightstreamer.as_client.NonVisualTable

Public Properties
 PropertyDefined By
  binary : Boolean
[read-only] The requested encoding for the field values.
VisualTable
  dataAdapter : String
The name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items in the Group.
VisualTable
  groupString : String
[read-only] The subscribed group of items, as requested to the Server.
VisualTable
  mode : String
[read-only] The subscription mode for the items.
VisualTable
  requestedBufferSize : *
The length of Lightstreamer Server's buffer for the internal queueing of updates for each item 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 bandwidth or frequency limits.
VisualTable
  requestedMaxFrequency : *
The maximum update frequency to be requested to Lightstreamer Server for all the items in the data table.
VisualTable
  schemaString : String
[read-only] The subscription schema for the items, as requested to the Server.
VisualTable
  selector : String
The selector name for all the items in the data table, or null if no selector is needed. The selector is a filter on the updates received.
VisualTable
  snapshotRequired : *
Setter method that enables/disables snapshot delivery request Indicates whether or not to request snapshot delivery for the items in the data table.
VisualTable
Public Methods
 MethodDefined By
  
VisualTable(group:*, schema:*, mode:String, binary:Boolean = false)
Creates an object to be used to describe a data table whose values should be displayed into ListBase controls throug a dataProvider assignment.
VisualTable
  
getRangeEnd():uint
Recalls the final index, if a range of items has been set.
VisualTable
  
getRangeStart():uint
Recalls the starting index, if a range of items has been set.
VisualTable
  
setItemRange(start:uint, end:uint):void
Setter method that sets a range of items within the specified group.
VisualTable
  
setKeyPolicy(type:*, commandFieldOrLimit:* = null):void
Setter method that sets the policy in use on the model during update receipt.
VisualTable
  
setMultiMetapush(underlyingSchema:*, underlyingDataAdapter:String, underlyingBinary:Boolean = false):void
Only effective if "COMMAND logic" behaviour has been configured in setKeyPolicy().
VisualTable
Events
 Event Summary Defined By
  
CollectionEvent
Notification of an update of the values for an item in the table.VisualTable
  
EndOfSnapshotEvent
Notification that no more snapshot events are coming for an item.VisualTable
  
LostUpdatesEvent
Notification of one or more updates that were suppressed in the Server because of internal memory limitations.VisualTable
  
SubscriptionErrorEvent
Notification of a Server error in response to a subscription request.VisualTable
  
SubscriptionEvent
Notification of the accomplished subscription of all the items in the table.VisualTable
  
UnsubscriptionEvent
Notification of the unsubscription of all the items in the table.VisualTable
Public Constants
 ConstantDefined By
  ITEM_IS_KEY : int = -1
[static] Constant that can be used with the setKeyPolicy method
VisualTable
  UPDATE_IS_KEY : int = -2
[static] Constant that can be used with the setKeyPolicy method
VisualTable
Property Detail
binaryproperty
binary:Boolean  [read-only]

The requested encoding for the field values. It can be defined only at object creation.


Implementation
    public function get binary():Boolean
dataAdapterproperty 
dataAdapter:String

The name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items in the Group. If not set, the "DEFAULT" name is used.

The Data Adapter name is configured on the server side through the "name" attribute of the "data_provider" element, in the "adapters.xml" file which defines the Adapter Set. Omitting the 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 Table. Multiple tables have to be defined.


Implementation
    public function get dataAdapter():String
    public function set dataAdapter(value:String):void
groupStringproperty 
groupString:String  [read-only]

The subscribed group of items, as requested to the Server. The group can be defined only at object creation, as either an Array of item names or a String group identifier.


Implementation
    public function get groupString():String
modeproperty 
mode:String  [read-only]

The subscription mode for the items. It can be defined only at object creation.


Implementation
    public function get mode():String
requestedBufferSizeproperty 
requestedBufferSize:*

The length of Lightstreamer Server's buffer for the internal queueing of updates for each item 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 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. If a 0 value or the string "unlimited" is set, then the buffer length is decided by the Server.


Implementation
    public function get requestedBufferSize():*
    public function set requestedBufferSize(value:any):void

Throws
ConfigurationError — An invalid parameter is being set.
requestedMaxFrequencyproperty 
requestedMaxFrequency:*

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 further reduce the frequency, not to rise it beyond these limits.

This property can also be used to request unfiltered dispatching for the items in the data table, if the string "unfiltered" is set. However, unfiltered dispatching requests may be refused if any frequency limit is posed on the server side for some item. If a 0 value or the string "unlimited" is set, then the update frequency is decided by the Server.

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.


Implementation
    public function get requestedMaxFrequency():*
    public function set requestedMaxFrequency(value:any):void

Throws
ConfigurationError — An invalid parameter is being set.
schemaStringproperty 
schemaString:String  [read-only]

The subscription schema for the items, as requested to the Server. The schema can be defined only at object creation, as either an Array of field names or a String schema identifier.


Implementation
    public function get schemaString():String
selectorproperty 
selector:String

The selector name for all the items in the data table, or null if no selector is needed.

The selector is a filter on the updates received. It is executed on the Server and implemented by the Metadata Adapter.


Implementation
    public function get selector():String
    public function set selector(value:String):void
snapshotRequiredproperty 
snapshotRequired:*

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

If the subscription mode is DISTINCT, instead of true, it is also possible to supply a number, to specify the requested length (depth) of the snapshot (though the length of the received snapshot may be less than requested, because of insufficient data or server side limits); specifying true means that the snapshot length should be determined only by the Server.


Implementation
    public function get snapshotRequired():*
    public function set snapshotRequired(value:any):void

Throws
ConfigurationError — An invalid parameter is being set.
Constructor Detail
VisualTable()Constructor
public function VisualTable(group:*, schema:*, mode:String, binary:Boolean = false)

Creates an object to be used to describe a data table whose values should be displayed into ListBase controls throug a dataProvider assignment. The object can be supplied to LSClient.subscribeTable() and LSClient.unsubscribeTable(), in order to subscribe/unsubscribe it to the server.

Parameters
group:* — An Array of item names or a String group identifier. In the first case items can be accessed by name during event dispatching; however, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request. Note that item names can't be empty or null and can't contain spaces.
 
schema:* — An Array of field names or a String schema identifier. In the first case fields can be accessed by name during event dispatching and, if associated with a control field, names should be used to pair field and "column". On the contrary, if group name is specified, the pairing should be done with field indexes. However, in the first case, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request. Note that field names can't be empty or null and can't contain spaces.
 
mode:String — the subscription mode for the items, required by Lightstreamer Server. It could be one of the following: "MERGE", "DISTINCT", "COMMAND", "RAW".
 
binary:Boolean (default = false) — If true, the values received for all the subscribed fields are interpreted as binary AMF representations of objects; they have to be supplied in that form by the Data Adapter, for all the subscribed items. The objects obtained through the deserialization of the received AMF representations are inserted in the underlying ArrayCollection. Only in case mode is "COMMAND", the special "key" and "command" fields (which can only be supplied as strings by the Data Adapter) are managed as text values.

Note that items suitable for subscription in binary form are not suitable for subscription in non-binary (i.e. text) form and vice-versa.

The parameter is optional and the default value is false, which means that all fields are managed as text values.


Throws
ConfigurationError — An invalid parameter was given

See also

com.lightstreamer.as_client.LSClient.subscribeTable()
com.lightstreamer.as_client.LSClient.unsubscribeTable()
Method Detail
getRangeEnd()method
public function getRangeEnd():uint

Recalls the final index, if a range of items has been set.

Returns
uint — a 1-based index or 0 if no range has been set.
getRangeStart()method 
public function getRangeStart():uint

Recalls the starting index, if a range of items has been set.

Returns
uint — a 1-based index or 0 if no range has been set.
setItemRange()method 
public function setItemRange(start:uint, end:uint):void

Setter method that sets a range of items within the specified group. Items outside of this range are not subscribed to. 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.

Parameters

start:uint — 1-based index of the first item in the group that has to be subscribed to.
 
end:uint — 1-based index of the last item in the group that has to be subscribed to.


Throws
ConfigurationError — An invalid parameter was specified.
setKeyPolicy()method 
public function setKeyPolicy(type:*, commandFieldOrLimit:* = null):void

Setter method that sets the policy in use on the model during update receipt.

Parameters

type:* — The policy type:

If ITEM_IS_KEY is specified, then each update pertaining to an item will override the update previously received for the same item (if any) except for unchanged fields. The first update per each item will add a new row to the model. This is the default policy if MERGE or RAW was specified on the constructor.

If UPDATE_IS_KEY is specified, then each new update, regardless the pertaining item, will occupy a new row on the model. This is the default policy if DISTINCT was specified on the constructor.

If none of the previous was specified this parameter should represent the field name or index for the key field on the table. In this case, the rows are managed according to ADD, UPDATE and DELETE commands received as pushed values, which instruct the table to add a row, just modify values on a row or delete a row, where each row is identified by the value of the key field. We call this a "COMMAND logic" behaviour. This is the default policy if COMMAND was specified on the constructor (in such case the used value is "key" if an array of items was given in the constructor, 1 otherwise).

 
commandFieldOrLimit:* (default = null) — Help param for some policy types.

If UPDATE_IS_KEY was used as policy type, then this parameter represent the max number of rows the model can contain. When the limit is reached oldest values are discarded. Use null or a 0 value to set no limits. Default is 0.

If none of ITEM_IS_KEY and UPDATE_IS_KEY was used as policy type, then this field represent the command field for this table. The default value is "command" if an array of items was given in the constructor, 2 otherwise.


Throws
ConfigurationError — An invalid parameter was given

See also

ITEM_IS_KEY
UPDATE_IS_KEY
setMultiMetapush()method 
public function setMultiMetapush(underlyingSchema:*, underlyingDataAdapter:String, underlyingBinary:Boolean = false):void

Only effective if "COMMAND logic" behaviour has been configured in setKeyPolicy(). It enables a two-level extension of this behaviour, in which the values for each row are provided:

In synthesis, each time a new row is created, an underlying data table is also created and subscribed automatically to feed fields not handled by the first-level updates. This table is a mono-item table, where the item name that is used is the key value associated to the row. The item is subscribed to in "MERGE" mode, with snapshot request and with the same maximum frequency setting as for the first-level items (including the "unfiltered" case). All other subscription properties are left as the default. When the row is deleted, the underlying data table is also removed.

We call this a "MultiMetapush logic" behaviour.

Parameters

underlyingSchema:* — An Array of field names or a String schema identifier, which identifies the fields provided by the second-level items. In the first case, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.

If field names are specified, fields can be accessed by name during event dispatching and, if associated with a control field, names should be used to pair field and "column". The second-level field names should better be different from the first-level field names, so that no name conflict can arise. In case of name conflicts, a "$" character must be preponed to the second-level field name.

On the contrary, if group name is specified, the pairing should be done with field indexes. In this case, the field position indexes to be used should start from the highest position of the first-level schema + 1.

Note that the first-level and second-level schemas must be declared in the same way, i.e. both through an Array of field names of both through a schema identifier.

 
underlyingDataAdapter:String — the name of a Data Adapter (within the Adapter Set used by the current session), which identifies the underlying Data Adapter, which supplies all the second-level items; the parameter is optional and the default is the "DEFAULT" name. All the possible second-level items should be supplied in "MERGE" mode with snapshot available.

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

 
underlyingBinary:Boolean (default = false) — If true, the values received for all the second-level subscribed fields are interpreted as binary AMF representations of objects; they have to be supplied in that form by the Data Adapter, for all the possible second-level items. The objects obtained through the deserialization of the received AMF representations are inserted in the underlying ArrayCollection.

Note that items suitable for subscription in binary form are not suitable for subscription in non-binary (i.e. text) form and vice-versa.

The parameter is optional and the default value is false, which means that all fields are managed as text values.

See also

setKeyPolicy()
Event Detail
CollectionEvent Event
Event Object Type: mx.events.CollectionEvent
CollectionEvent.type property = mx.events.CollectionEvent.COLLECTION_CHANGE

Notification of an update of the values for an item in the table.

See also

mx.events.CollectionEvent
http://livedocs.adobe.com/flex/3/langref/mx/events/CollectionEvent.html
EndOfSnapshotEvent Event  
Event Object Type: com.lightstreamer.as_client.events.EndOfSnapshotEvent
EndOfSnapshotEvent.type property = com.lightstreamer.as_client.events.EndOfSnapshotEvent.END_OF_SNAPSHOT

Notification that no more snapshot events are coming for an item. This notification is always received once, when the item is subscribed in DISTINCT or COMMAND mode and the snapshot is requested.

Define the value of the type property of a EndOfSnapshot event object.
LostUpdatesEvent Event  
Event Object Type: com.lightstreamer.as_client.events.LostUpdatesEvent
LostUpdatesEvent.type property = com.lightstreamer.as_client.events.LostUpdatesEvent.LOST_UPDATES

Notification of one or more updates that were suppressed in the Server because of internal memory limitations. The notification can be sent if the subscription mode is RAW or COMMAND. It can also be sent if the subscription mode is MERGE or DISTINCT and unfiltered dispatching has been requested. In all these cases, an update loss may be unacceptable for the client (in filtered COMMAND mode, this applies to "add" and "delete" events only).

Define the value of the type property of a LostUpdates event object.
SubscriptionErrorEvent Event  
Event Object Type: com.lightstreamer.as_client.events.SubscriptionErrorEvent
SubscriptionErrorEvent.type property = com.lightstreamer.as_client.events.SubscriptionErrorEvent.SUBSCRIPTION_ERROR

Notification of a Server error in response to a subscription request.

Define the value of the type property of a SubscriptionError event object.
SubscriptionEvent Event  
Event Object Type: com.lightstreamer.as_client.events.SubscriptionEvent
SubscriptionEvent.type property = com.lightstreamer.as_client.events.SubscriptionEvent.SUBSCRIPTION

Notification of the accomplished subscription of all the items in the table. The notification is sent before any notification related with the updates.

Define the value of the type property of a Subscription event object.
UnsubscriptionEvent Event  
Event Object Type: com.lightstreamer.as_client.events.UnsubscriptionEvent
UnsubscriptionEvent.type property = com.lightstreamer.as_client.events.UnsubscriptionEvent.UNSUBSCRIPTION

Notification of the unsubscription of all the items in the table. The unsubscription may be subsequent to an unsubscribeTable call or to the closure of the connection.

Define the value of the type property of a Unsubscription event object.
Constant Detail
ITEM_IS_KEYConstant
public static const ITEM_IS_KEY:int = -1

Constant that can be used with the setKeyPolicy method

See also

setKeyPolicy()
UPDATE_IS_KEYConstant 
public static const UPDATE_IS_KEY:int = -2

Constant that can be used with the setKeyPolicy method

See also

setKeyPolicy()



Lightstreamer Flex client 2.2.1 API