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 to add extra fields to the update, though it does not allow to alter the values received from the Server.
If the involved table is a MetapushTable or a DynaMetapushTable, then the object behaves with a "COMMAND logic" and the old values for the current update are meant as relative to the same key. The above also holds for a NonVisualTable, if NonVisualTable.setCommandLogic() with a "true" argument has been called at initialization time.
Note: "COMMAND logic" behaviour usually comes with COMMAND mode subscription, but there is no strict constraint over this.
Defined in lspushpage.js

Constructor Detail

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 are supported for field names; moreover, using numbers as field names is not supported.
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.

See:
- MetapushTable.setMetapushSort()
- DynaMetapushTable.setMetapushSort()
- ChartTable.setXAxis()
- ChartLine.setYAxis()
- GroupDescriptor

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

See:
- getNumFields()
- addField()

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.
Note: the value returned does not include the extra fields.

Returns:
The number of fields received from the Server.

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

See:
- getNumFields()
- addField()

isSnapshot

boolean isSnapshot()

Inquiry method that asks whether the current update belongs to the item snapshot, i.e. 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

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.

See:
- getNumFields()
- addField()