ItemUpdate

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

var changedFields: [String : String?] { get }

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

var changedFieldsByPositions: [Int : String?] { get }

Values for each field in the Subscription. The related field name is used as key for the values in the map.

var fields: [String : String?] { get }

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.

var fieldsByPositions: [Int : String?] { get }

The name of the item to which this update pertains.

The name will be nil if the related Subscription was initialized using an “Item Group”.

var itemName: String? { get }

The 1-based position in the “Item List” or “Item Group” of the item to which this update pertains.

var itemPos: Int { get }

Returns the current value for the specified field.

The value of a field can be nil in the following cases:

• a nil value has been received from the Server, as nil is a possible value for a field;

• no value has been received for the field yet;

• the item is subscribed to with the COMMAND mode and a DELETE command is received (only the fields used to carry key and command information are valued).

func value(withFieldPos fieldPos: Int) -> String?

Returns the current value for the specified field.

The value of a field can be nil in the following cases:

• a nil value has been received from the Server, as nil is a possible value for a field;

• no value has been received for the field yet;

• the item is subscribed to with the COMMAND mode and a DELETE command is received (only the fields used to carry key and command information are valued).

func value(withFieldName fieldName: String) -> String?

Tells 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 information 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.

Note that, in case of two-level behavior, 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.

var isSnapshot: Bool { get }

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.

Unless the Subscription mode is COMMAND, 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.

If the Subscription mode is COMMAND, 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.

func isValueChanged(withFieldPos fieldPos: Int) -> Bool

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.

Unless the Subscription mode is COMMAND, 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.

If the Subscription mode is COMMAND, 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.

func isValueChanged(withFieldName fieldName: String) -> Bool

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);
• sending the JSON Patch difference has been evaluated by the Server as more efficient than sending the full new value.

Note that the last condition can be enforced by leveraging the Server’s <jsonpatch_min_length> configuration flag, so that the availability of the JSON Patch form would only depend on the Client and the Data Adapter.
When the above conditions are not met, the method just returns nil; in this case, the new value can only be determined through value(...). For instance, this will always be needed to get the first value received.

func valueAsJSONPatchIfAvailable(withFieldName fieldName: String) -> 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);
• sending the JSON Patch difference has been evaluated by the Server as more efficient than sending the full new value.

Note that the last condition can be enforced by leveraging the Server’s <jsonpatch_min_length> configuration flag, so that the availability of the JSON Patch form would only depend on the Client and the Data Adapter.
When the above conditions are not met, the method just returns nil; in this case, the new value can only be determined through value(...). For instance, this will always be needed to get the first value received.

func valueAsJSONPatchIfAvailable(withFieldPos fieldPos: Int) -> String?