Interface ItemUpdate
Contains all the information related to an update of the field values for an item.
It reports all the new values of the fields.
COMMAND Subscription
If the involved Subscription is a COMMAND Subscription, then the values for the current
update are meant as relative to the same key.
Moreover, if the involved Subscription has a two-level behavior enabled, 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). When the two-level behavior is enabled, in all methods where a field name 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. In case of name conflict, the first-level field is 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 field list + 1. If a field schema had been specified for either first-level or second-level Subscriptions, then client-side knowledge of the first-level schema length would be required.
Namespace: com.lightstreamer.client
Assembly: Lightstreamer.DotNetStandard.Client.Api.dll
Syntax
public interface ItemUpdate
Properties
ChangedFields
Returns an immutable Map containing the values for each field changed with the last server update. The related field name is used as key for the values in the map. Note that if the Subscription mode of the involved Subscription is COMMAND, 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 present as changed, with null value. All of this is also true on tables that have the two-level behavior enabled, but in case of DELETE commands second-level fields will not be iterated.
Declaration
IDictionary<string, string> ChangedFields { get; }
Property Value
Type | Description |
---|---|
IDictionary<string, string> | An immutable Map containing the values for each field changed with the last server update. |
ChangedFieldsByPosition
Returns an immutable Map containing the values for each field changed with the last server update. The 1-based field position within the field schema or field list is used as key for the values in the map. Note that if the Subscription mode of the involved Subscription is COMMAND, 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 present as changed, with null value. All of this is also true on tables that have the two-level behavior enabled, but in case of DELETE commands second-level fields will not be iterated.
Declaration
IDictionary<int, string> ChangedFieldsByPosition { get; }
Property Value
Type | Description |
---|---|
IDictionary<int, string> | An immutable Map containing the values for each field changed with the last server update. |
Fields
Returns an immutable Map containing the values for each field in the Subscription. The related field name is used as key for the values in the map.
Declaration
IDictionary<string, string> Fields { get; }
Property Value
Type | Description |
---|---|
IDictionary<string, string> | An immutable Map containing the values for each field in the Subscription. |
FieldsByPosition
Returns an immutable Map containing the values for each field in the Subscription. The 1-based field position within the field schema or field list is used as key for the values in the map.
Declaration
IDictionary<int, string> FieldsByPosition { get; }
Property Value
Type | Description |
---|---|
IDictionary<int, string> | An immutable Map containing the values for each field in the Subscription. |
ItemName
Declaration
string ItemName { get; }
Property Value
Type | Description |
---|---|
string | Read-only property |
ItemPos
Declaration
int ItemPos { get; }
Property Value
Type | Description |
---|---|
int | Read-only property |
Snapshot
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 Subscription.RequestedSnapshot
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 to with the RAW subscription mode, then no snapshot is sent by the Server;
- if the item is subscribed to with the MERGE subscription mode, then the snapshot consists of exactly one event, carrying the current value for all fields;
- if the item is subscribed to with the DISTINCT subscription mode, then the snapshot
consists of some of the most recent updates; these updates are as many as specified
through
Subscription.RequestedSnapshot
, unless fewer are available; - if the item is subscribed to with the COMMAND subscription mode, then the snapshot consists of an "ADD" event for each key that is currently present.
Declaration
bool Snapshot { get; }
Property Value
Type | Description |
---|---|
bool | true if the current update event belongs to the item snapshot; false otherwise. |
Methods
getValue(int)
Returns the current value for the specified field
Declaration
string getValue(int fieldPos)
Parameters
Type | Name | Description |
---|---|---|
int | fieldPos | The 1-based position of the field within the "Field List" or "Field Schema". |
Returns
Type | Description |
---|---|
string | The value of the specified field; it can be null in the following cases:
|
getValue(string)
Returns the current value for the specified field
Declaration
string getValue(string fieldName)
Parameters
Type | Name | Description |
---|---|---|
string | fieldName | The field name as specified within the "Field List". |
Returns
Type | Description |
---|---|
string | The value of the specified field; it can be null in the following cases:
|
getValueAsJSONPatchIfAvailable(int)
Inquiry method that gets the difference between the new value and the previous one as a JSON Patch structure, provided that the Server has used the JSON Patch format to send this difference, as part of the "delta delivery" mechanism. This, in turn, requires that:
- the Data Adapter has explicitly indicated JSON Patch as the privileged type of compression for this field;
- both the previous and new value are suitable for the JSON Patch computation (i.e. they are valid JSON representations);
- the item was subscribed to in MERGE or DISTINCT mode (note that, in case of two-level behavior, this holds for all fields related with second-level items, as these items are in MERGE mode);
- sending the JSON Patch difference has been evaluated by the Server as more efficient than sending the full new value.
When the above conditions are not met, the method just returns null; in this case, the new value can only be determined through
Declaration
string getValueAsJSONPatchIfAvailable(int fieldPos)
Parameters
Type | Name | Description |
---|---|---|
int | fieldPos | The 1-based position of the field within the "Field List" or "Field Schema". |
Returns
Type | Description |
---|---|
string | A JSON Patch structure representing the difference between the new value and the previous one, or null if the difference in JSON Patch format is not available for any reason. |
Exceptions
Type | Condition |
---|---|
ArgumentException | if the specified field is not part of the Subscription. |
getValueAsJSONPatchIfAvailable(string)
Inquiry method that gets the difference between the new value and the previous one as a JSON Patch structure, provided that the Server has used the JSON Patch format to send this difference, as part of the "delta delivery" mechanism. This, in turn, requires that:
- the Data Adapter has explicitly indicated JSON Patch as the privileged type of compression for this field;
- both the previous and new value are suitable for the JSON Patch computation (i.e. they are valid JSON representations);
- the item was subscribed to in MERGE or DISTINCT mode (note that, in case of two-level behavior, this holds for all fields related with second-level items, as these items are in MERGE mode);
- sending the JSON Patch difference has been evaluated by the Server as more efficient than sending the full new value.
When the above conditions are not met, the method just returns null; in this case, the new value can only be determined through
Declaration
string getValueAsJSONPatchIfAvailable(string fieldName)
Parameters
Type | Name | Description |
---|---|---|
string | fieldName | The field name as specified within the "Field List". |
Returns
Type | Description |
---|---|
string | A JSON Patch structure representing the difference between the new value and the previous one, or null if the difference in JSON Patch format is not available for any reason. |
Exceptions
Type | Condition |
---|---|
ArgumentException | if the specified field is not part of the Subscription. |
isValueChanged(int)
Inquiry method that asks whether the value for a field has changed after the reception of the last update from the Server for an item. If the Subscription mode is COMMAND then the change is meant as relative to the same key.
Declaration
bool isValueChanged(int fieldPos)
Parameters
Type | Name | Description |
---|---|---|
int | fieldPos | The 1-based position of the field within the "Field List" or "Field Schema". |
Returns
Type | Description |
---|---|
bool | Unless the Subscription mode is COMMAND, the return value is true in the following cases:
|
isValueChanged(string)
Inquiry method that asks whether the value for a field has changed after the reception of the last update from the Server for an item. If the Subscription mode is COMMAND then the change is meant as relative to the same key.
Declaration
bool isValueChanged(string fieldName)
Parameters
Type | Name | Description |
---|---|---|
string | fieldName | The field name as specified within the "Field List". |
Returns
Type | Description |
---|---|
bool | Unless the Subscription mode is COMMAND, the return value is true in the following cases:
|