Class UpdateItemInfo
Object
|
+--UpdateItemInfo
- class
UpdateItemInfo
Contains all the information related to an update of the field
values for an item. It reports all the new and old values of the fields
and allows you to add extra fields to the update, though it does not allow
you to alter the values received from the Server.
If the involved table behaves with a "COMMAND logic", then the old
values for the current update are meant as relative to the same key.
Moreover, if the involved table behaves in "MultiMetapush logic",
then each update may be associated with either a first-level or
a second-level item. In this case, the reported fields are always the union
of the first-level and second-level fields and each single update can
only change either the first-level or the second-level fields
(but for the "command" field, which is first-level and is always set to
"UPDATE" upon a second-level update); note that the second-level field
values are always null until the first second-level update occurs).
With "MultiMetapush logic" behaviour, in all methods where a field
descriptor has to be supplied, the following convention should be followed:
- The field name can always be used, both for the first-level and the
second-level fields (of course, unless schema identifiers were used as
schema descriptors for the related table). In case of name conflict,
the first-level field is meant. If, however, the name is preceded by
the "$" character, then a second-level field is always meant.
- The field position can always be used; however, the field positions
for the second-level fields start at the highest position of the
first-level schema + 1. If schema identifiers were used as schema
descriptors for the related table, client-side knowledge of the
first-level schema lenght would be required.
The class constructor, its prototype and any other properties should never
be used directly; actually, UpdateItemInfo is not even defined as a global name.
Defined in lspushpage.js
See:
Method Summary |
void
|
addField(<FieldDescriptor> field, <String> value, <boolean> remember)
Operation method that adds an internally computed extra field to the
fields received from the Server for an item.
|
void
|
forEachChangedField(<Function> iterator)
Registers an iterator function that will be called once per each field changed with the last server update.
|
String
|
getNewValue(<FieldDescriptor> field)
Inquiry method that gets the new value for a specified field, as
received from the Server with the current update or as previously
set, in case an extra field is specified.
|
Number
|
getNumFields()
Inquiry method that gets the number of fields received from the Server
with the current update.
|
String
|
getOldValue(<FieldDescriptor> field)
Inquiry method that gets the previous value for a specified field,
after the reception of an update from the Server for an item.
|
boolean
|
isSnapshot()
Inquiry method that asks whether the current update belongs to the item
snapshot (which carries the current item state at the time of subscription).
|
boolean
|
isValueChanged(<FieldDescriptor> field)
Inquiry method that asks whether the value for a field has changed
after the reception of an update from the Server for an item.
|
UpdateItemInfo
UpdateItemInfo()
Used by Lightstreamer to provide a value object to each call of the
Table.onItemUpdate() event handler.
addField
void addField(<FieldDescriptor> field, <String> value, <boolean> remember)
Operation method that adds an internally computed extra field to the
fields received from the Server for an item. With "extra field" we mean
a field that is not recognized as a subscribed field. Such a field can
be represented by a position number greater than the number of
subscribed fields (returned by getNumFields()) or by a field
name different than the name of any subscribed field. In particular,
if a group identifier has been used as group descriptor for the data
table, then the field names are not known, therefore any field name can
be used to define an extra field.
Only alphanumeric strings should be used for extra field names
(underscore and dot characters and an initial "#" are also allowed);
moreover, using numbers as field names is not supported.
Note that because of the limitations of getNumFields() when the
related data table behaves in "MultiMetapush logic", only in that case
the method may return null, hence it may not be useful in order to
determine valid extra field position indexes.
Extra fields are treated in the same way as subscribed fields; in
particular, they can be associated to HTML cells.
Parameters:
field
- a field descriptor object suitable for representing an extra field. A proper String field name or a Number representing a proper field position can also be used directly, instead of a field descriptor object.
Note that no name/position association is defined for extra fields. This means that each extra field can only be accessed in one way (by name or by position).
value
- value to be assigned to the field for the current update. Null is a legal value, though it cannot be distinguished from an unassigned value. A value of type Number is also allowed; this makes possible for the result of a numeric expression to be directly supplied to addField; "commaAsDecimalSeparator" settings, where required, are ignored for such values.
remember
- [Optional] if true, then the value will be automatically assigned at each further update for the item (until a new call to addField for the field). If the object behaves in "COMMAND logic", then this applies to the updates related to the current key. If false, then, at the next update, the field will be left NULL.
The parameter is optional, with true as its default value.
forEachChangedField
void forEachChangedField(<Function> iterator)
Registers an iterator function that will be called once per each field changed with the last server update. As not part of the server update, extra
fields are excluded from the iteration.
Note that if the involved table behaves with a "COMMAND logic", then changed fields are meant as relative to the previous update for the same key.
On such tables if a DELETE command is received, all the fields, excluding the key field, will be iterate as changed. All of this is also true on
tables that behave in "MultiMetapush logic", but in case of DELETE commands second-level fields will not be iterated.
Note that the iterator is executed before this method returns.
Parameters:
iterator
- Function instance that will be called once per each field changed on the last update received from the server.
Each iterator call will receive the following parameters: -
<Number> fieldPos
1-based index of the field within the schema. -
<String> fieldName
name of the involved changed field. If a schema identifier has been used as schema descriptor for the data table, then a null value is supplied. -
<String> oldValue
previous value for the field. See getOldValue() for details. -
<String> newValue
new value for the field. See getNewValue() for details. -
<UpdateItemInfo> updateInfo
original UpdateItemInfo instance upon the forEachChangedField method has been called.
getNewValue
String getNewValue(<FieldDescriptor> field)
Inquiry method that gets the new value for a specified field, as
received from the Server with the current update or as previously
set, in case an extra field is specified.
Parameters:
field
- a field descriptor object for the requested field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
Returns:
The field value; it can be null in the following cases: - a null value has been received from the Server, as null is a possible value for a field
- the item is subscribed with the COMMAND mode and a DELETE command is received (only the fields used to carry key and command informations are valued)
- the specified field is an extra field that has not been set
getNumFields
Number getNumFields()
Inquiry method that gets the number of fields received from the Server
with the current update. The value, however, is the same across all
updates pertaining to the same item, because it is determined by the
schema associated to the item at subscription.
The fields received from the Server are always associated to consecutive
field numbers starting from 1.
Only in case the related data table behaves in "MultiMetapush logic",
it may not be possible to determine the correct number of fields of the
data table. This only happens when a schema identifier is used as the
schema descriptor for the second-level schema and no update for any
second-level item has been received yet.
Note that the value returned does not include the extra fields.
Returns:
The number of fields received from the Server, or null if the total number of fields cannot be determined (see above).
getOldValue
String getOldValue(<FieldDescriptor> field)
Inquiry method that gets the previous value for a specified field,
after the reception of an update from the Server for an item.
This also applies to extra fields.
If the object behaves in "COMMAND logic", then the previous
values refer to the last update with the same key value.
Parameters:
field
- a field descriptor object for the requested field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
Returns:
The field previous value; it can be null in the following cases: - a null value had been received from the Server, as null is a possible value for a field
- the object doesn't behave in "COMMAND logic" and it is the first update ever received for the item (it may be a snapshot-related update)
- the object behaves in "COMMAND logic" and it is the first update ever received for the item with the involved key field value (i.e. the event carries an "ADD" command; it may be a snapshot-related update)
- the specified field is an extra field that had not been set
isSnapshot
boolean isSnapshot()
Inquiry method that asks whether the current update belongs to the item
snapshot (which carries the current item state at the time of subscription).
Snapshot events are sent only if snapshot information was requested
for the items through Table.setSnapshotRequired() and precede
the real time events.
Snapshot informations take different forms in different subscription
modes and can be spanned across zero, one or several update events.
In particular:
- if the item is subscribed with the RAW subscription mode, then no
snapshot is sent by the Server
- if the item is subscribed with the MERGE subscription mode, then
the snapshot consists of exactly one event, carrying the current value
for each field
- if the item is subscribed with the DISTINCT subscription mode, then
the snapshot consists of some of the most recent updates; these updates
are as many as specified through Table.setSnapshotRequired(), if
available
- if the item is subscribed with the COMMAND subscription mode, then
the snapshot consists of an "ADD" event for each key that is currently
present
Note that, in case of "MultiMetapush logic", snapshot-related updates
for both the first-level item (which is in COMMAND mode) and any
second-level items (which are in MERGE mode) are qualified with this
flag.
Returns:
true if the current update event belongs to the item snapshot; false otherwise.
isValueChanged
boolean isValueChanged(<FieldDescriptor> field)
Inquiry method that asks whether the value for a field has changed
after the reception of an update from the Server for an item.
This also applies to extra fields; in this case, if a value has not
been set for a field, then it is treated as a null value.
If the object behaves in "COMMAND logic", then the change is
meant as relative to the same key.
Parameters:
field
- a field descriptor object for the requested field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
Returns:
Unless the object behaves in "COMMAND logic", the return value is true in the following cases: - it is the first update for the item
- the new field value is different than the previous field value received for the item
In "COMMAND logic", the return value is true in the following cases: - it is the first update for the involved key value (i.e. the event carries an "ADD" command)
- the new field value is different than the previous field value received for the item, relative to the same key value (the event must carry an "UPDATE" command)
- the event carries a "DELETE" command (this applies to all fields other than the field used to carry key information)
In all other cases, the return value is false.
Lightstreamer HTML Client API
Documentation generated by
JSDoc on Tue May 22 11:46:54 2012