Lightstreamer macOS Client  2.1.2
Native macOS Client library for Lightstreamer
Instance Methods | Properties | List of all members
LSItemUpdate Class Reference

Contains all the information related to an update of the field values for an item. More...

#import <LSItemUpdate.h>

Inheritance diagram for LSItemUpdate:

Instance Methods

(nullable NSString *) - valueWithFieldPos:
 Returns the current value for the specified field. More...
 
(nullable NSString *) - valueWithFieldName:
 Returns the current value for the specified field. More...
 
(BOOL) - isValueChangedWithFieldPos:
 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. More...
 
(BOOL) - isValueChangedWithFieldName:
 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. More...
 

Properties

NSDictionary * changedFields
 Values for each field changed with the last server update. More...
 
NSDictionary * changedFieldsByPositions
 Values for each field changed with the last server update. More...
 
NSDictionary * fields
 Values for each field in the LSSubscription. More...
 
NSDictionary * fieldsByPositions
 Values for each field in the LSSubscription. More...
 
NSString * itemName
 The name of the item to which this update pertains. More...
 
NSUInteger itemPos
 The 1-based position in the "Item List" or "Item Group" of the item to which this update pertains. More...
 
BOOL snapshot
 Tells whether the current update belongs to the item snapshot (which carries the current item state at the time of Subscription). More...
 

Detailed Description

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 LSSubscription
If the involved LSSubscription is a COMMAND LSSubscription, then the values for the current update are meant as relative to the same key.
Moreover, if the involved LSSubscription 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 nil 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:

Method Documentation

◆ isValueChangedWithFieldName:()

- (BOOL) isValueChangedWithFieldName: (nonnull NSString *)  fieldName

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.

Parameters
fieldNameThe field name as specified within the "Field List".
Exceptions
NSExceptionif LSLightstreamerClient::limitExceptionsUse is NO and the specified field is not part of the LSSubscription.
Returns
Unless the Subscription mode is COMMAND, the return value is YES 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 YES 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 NO, including if LSLightstreamerClient::limitExceptionsUse is YES and the specified field is not part of the LSSubscription.

◆ isValueChangedWithFieldPos:()

- (BOOL) isValueChangedWithFieldPos: (NSUInteger)  fieldPos

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.

Parameters
fieldPosThe 1-based position of the field within the "Field List" or "Field Schema".
Exceptions
NSExceptionif LSLightstreamerClient::limitExceptionsUse is NO and the specified field is not part of the LSSubscription.
Returns
Unless the Subscription mode is COMMAND, the return value is YES 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 YES 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 NO, including if LSLightstreamerClient::limitExceptionsUse is YES and the specified field is not part of the LSSubscription.

◆ valueWithFieldName:()

- (nullable NSString *) valueWithFieldName: (nonnull NSString *)  fieldName

Returns the current value for the specified field.

Parameters
fieldNameThe field name as specified within the "Field List".
Exceptions
NSExceptionif LSLightstreamerClient::limitExceptionsUse is NO and the specified field is not part of the LSSubscription.
Returns
The value of the specified field; it 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 informations are valued).
  • LSLightstreamerClient::limitExceptionsUse is YES and the specified field is not part of the LSSubscription.

◆ valueWithFieldPos:()

- (nullable NSString *) valueWithFieldPos: (NSUInteger)  fieldPos

Returns the current value for the specified field.

Parameters
fieldPosThe 1-based position of the field within the "Field List" or "Field Schema".
Exceptions
NSExceptionif LSLightstreamerClient::limitExceptionsUse is NO and the specified field is not part of the LSSubscription.
Returns
The value of the specified field; it 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 informations are valued).
  • LSLightstreamerClient::limitExceptionsUse is YES and the specified field is not part of the LSSubscription.

Property Documentation

◆ changedFields

- (NSDictionary*) changedFields
readnonatomicassign

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

Exceptions
NSExceptionif the LSSubscription was initialized using a field schema.

◆ changedFieldsByPositions

- (NSDictionary*) changedFieldsByPositions
readnonatomicassign

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

◆ fields

- (NSDictionary*) fields
readnonatomicassign

Values for each field in the LSSubscription.

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

Exceptions
NSExceptionif the LSSubscription was initialized using a field schema.

◆ fieldsByPositions

- (NSDictionary*) fieldsByPositions
readnonatomicassign

Values for each field in the LSSubscription.

The 1-based field position within the field schema or field list is used as key for the values in the map.

◆ itemName

- (NSString*) itemName
readnonatomicassign

The name of the item to which this update pertains.


The name will be nil if the related LSSubscription was initialized using an "Item Group".

◆ itemPos

- (NSUInteger) itemPos
readnonatomicassign

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

◆ snapshot

- (BOOL) snapshot
readnonatomicassign

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 LSSubscription::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 LSSubscription::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.

Returns
YES if the current update event belongs to the item snapshot; NO otherwise.

The documentation for this class was generated from the following file: