Class representing a Subscription to be submitted to a Lightstreamer Server.
It contains subscription details and the delegates needed to process the real-time data.
After the creation, an LSSubscription object is in the "inactive" state. When a Subscription object is subscribed to on a LSLightstreamerClient object, through the subscribe: (LSLightstreamerClient) method, its state becomes "active". This means that the client activates a subscription to the required items through Lightstreamer Server and the LSSubscription object begins to receive real-time events.
A Subscription can be configured to use either an Item Group or an Item List to specify the items to be subscribed to and using either a Field Schema or Field List to specify the fields.
"Item Group" and "Item List" are defined as follows:
-
"Item Group": an Item Group is a String identifier representing a list of items. Such Item Group has to be expanded into a list of items by the getItems method of the MetadataProvider of the associated Adapter Set. When using an Item Group, items in the subscription are identified by their 1-based index within the group.
It is possible to configure the LSSubscription to use an "Item Group" using the itemGroup property.
-
"Item List": an Item List is an array of Strings each one representing an item. For the Item List to be correctly interpreted a LiteralBasedProvider or a MetadataProvider with a compatible implementation of getItems has to be configured in the associated Adapter Set.
Note that no item in the list can be empty, can contain spaces or can be a number.
When using an Item List, items in the subscription are identified by their name or by their 1-based index within the list.
It is possible to configure the Subscription to use an "Item List" using the items property or by specifying it in the constructor.
"Field Schema" and "Field List" are defined as follows:
-
"Field Schema": a Field Schema is a String identifier representing a list of fields. Such Field Schema has to be expanded into a list of fields by the getFields method of the MetadataProvider of the associated Adapter Set. When using a Field Schema, fields in the subscription are identified by their 1-based index within the schema.
It is possible to configure the LSSubscription to use a "Field Schema" using the fieldSchema property.
-
"Field List": a Field List is an array of Strings each one representing a field. For the Field List to be correctly interpreted a LiteralBasedProvider or a MetadataProvider with a compatible implementation of getFields has to be configured in the associated Adapter Set.
Note that no field in the list can be empty, can contain spaces or can be a number.
When using a Field List, fields in the subscription are identified by their name or by their 1-based index within the list.
It is possible to configure the LSSubscription to use a "Field List" using the fields property or by specifying it in the constructor.
| - (nullable NSString *) valueWithItemName: |
|
(nonnull NSString *) |
itemName |
| fieldName: |
|
(nonnull NSString *) |
fieldName |
|
|
| |
Returns the latest value received for the specified item/field pair.
It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND LSSubscriptions, use commandValueWithItemName:key:fieldName: instead.
Note that internal data is cleared when the LSSubscription is unsubscribed from.
This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return nil.
- Exceptions
-
| NSException | if an invalid item name or field name is specified. |
- Parameters
-
| itemName | an item in the configured "Item List" |
| fieldName | a item in the configured "Field List" |
- Returns
- the current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet.
| - (nullable NSString *) valueWithItemName: |
|
(nonnull NSString *) |
itemName |
| fieldPos: |
|
(NSUInteger) |
fieldPos |
|
|
| |
Returns the latest value received for the specified item/field pair.
It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
In case of COMMAND LSSubscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use commandValueWithItemName:key:fieldPos: instead.
Note that internal data is cleared when the LSSubscription is unsubscribed from.
This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return nil.
- Exceptions
-
| NSException | if an invalid item name is specified. |
| NSException | if the specified field position is out of bounds. |
- Parameters
-
| itemName | an item in the configured "Item List" |
| fieldPos | the 1-based position of a field within the configured "Field Schema" or "Field List" |
- Returns
- the current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet.
| - (nullable NSString *) valueWithItemPos: |
|
(NSUInteger) |
itemPos |
| fieldName: |
|
(nonnull NSString *) |
fieldName |
|
|
| |
Returns the latest value received for the specified item/field pair.
It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
In case of COMMAND LSSubscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use commandValueWithItemPos:key:fieldName: instead.
Note that internal data is cleared when the Subscription is unsubscribed from.
This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return nil.
- Exceptions
-
| NSException | if an invalid field name is specified. |
| NSException | if the specified item position is out of bounds. |
- Parameters
-
| itemPos | the 1-based position of an item within the configured "Item Group" or "Item List" |
| fieldName | a item in the configured "Field List" |
- Returns
- the current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet.
| - (nullable NSString *) valueWithItemPos: |
|
(NSUInteger) |
itemPos |
| fieldPos: |
|
(NSUInteger) |
fieldPos |
|
|
| |
Returns the latest value received for the specified item/field pair.
It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
In case of COMMAND LSSubscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND LSSubscriptions, use commandValueWithItemPos:key:fieldPos: instead.
Note that internal data is cleared when the LSSubscription is unsubscribed from.
This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return nil.
- Exceptions
-
| NSException | if the specified item position or field position is out of bounds. |
- Parameters
-
| itemPos | the 1-based position of an item within the configured "Item Group" or "Item List" |
| fieldPos | the 1-based position of a field within the configured "Field Schema" or "Field List" |
- Returns
- the current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet.
| - (NSArray*) commandSecondLevelFields |
|
readwritenonatomiccopy |
The "Field List" to be subscribed to through Lightstreamer Server for the second-level items.
It can only be used on COMMAND Subscriptions.
Any change to this property will override any "Field List" or "Field Schema" previously specified for the second-level.
Setting this property enables the two-level behavior: in synthesis, each time a new key is received on the COMMAND Subscription, the key value is treated as an Item name and an underlying LSSubscription for this Item is created and subscribed to automatically, to feed fields specified by this method. This mono-item LSSubscription is specified through an "Item List" containing only the Item name received. As a consequence, all the conditions provided for subscriptions through Item Lists have to be satisfied. The item is subscribed to in "MERGE" mode, with snapshot request and with the same maximum frequency setting as for the first-level items (including the "unfiltered" case). All other LSSubscription properties are left as the default. When the key is deleted by a DELETE command on the first-level LSSubscription, the associated second-level LSSubscription is also unsubscribed from.
Specifying nil as parameter will disable the two-level behavior.
This property can only be set while the LSSubscription instance is in its "inactive" state.
- Exceptions
-
| NSException | if any of the field names in the "Field List" contains a space or is a number or is empty/nil. |
| NSException | if the LSSubscription is currently "active". |
| NSException | if the LSSubscription mode is not "COMMAND". |
| - (NSString*) commandSecondLevelFieldSchema |
|
readwritenonatomiccopy |
The "Field Schema" to be subscribed to through Lightstreamer Server for the second-level items.
It can only be used on COMMAND Subscriptions.
Any change to this property will override any "Field List" or "Field Schema" previously specified for the second-level.
Setting this property enables the two-level behavior: in synthesis, each time a new key is received on the COMMAND Subscription, the key value is treated as an Item name and an underlying Subscription for this Item is created and subscribed to automatically, to feed fields specified by this method. This mono-item LSSubscription is specified through an "Item List" containing only the Item name received. As a consequence, all the conditions provided for subscriptions through Item Lists have to be satisfied. The item is subscribed to in "MERGE" mode, with snapshot request and with the same maximum frequency setting as for the first-level items (including the "unfiltered" case). All other LSSubscription properties are left as the default. When the key is deleted by a DELETE command on the first-level LSSubscription, the associated second-level LSSubscription is also unsubscribed from.
Specifying nil as parameter will disable the two-level behavior.
This property can only be set while the LSSubscription instance is in its "inactive" state.
- Exceptions
-
| - (NSString*) dataAdapter |
|
readwritenonatomiccopy |
Name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items for this Subscription.
The Data Adapter name is configured on the server side through the "name" attribute of the "data_provider" element, in the "adapters.xml" file that defines the Adapter Set (a missing attribute configures the "DEFAULT" name).
Note that if more than one Data Adapter is needed to supply all the items in a set of items, then it is not possible to group all the items of the set in a single Subscription. Multiple LSSubscriptions have to be defined.
Default: the default Data Adapter for the Adapter Set, configured as "DEFAULT" on the Server.
This property can only be set while the LSSubscription instance is in its "inactive" state.
- Exceptions
-
| - (NSString*) requestedBufferSize |
|
readwritenonatomiccopy |
Length to be requested to Lightstreamer Server for the internal queuing buffers for the items in the Subscription.
A Queuing buffer is used by the Server to accumulate a burst of updates for an item, so that they can all be sent to the client, despite of bandwidth or frequency limits. It can be used only when the subscription mode is MERGE or DISTINCT and unfiltered dispatching has not been requested. If the string "unlimited" is supplied, then the buffer length is decided by the Server (the check is case insensitive). Note that the Server may pose an upper limit on the size of its internal buffers.
Default: nil, meaning to not request a buffer size to the server; this means that the buffer size will be 1 for MERGE subscriptions and "unlimited" for DISTINCT subscriptions. See the "General Concepts" document for further details.
This property can only be changed while the LSSubscription instance is in its "inactive" state.
- Exceptions
-
| NSException | if the LSSubscription is currently "active". |
| NSException | if the specified value is not nil nor "unlimited" nor a valid positive integer number. |
| - (NSString*) requestedMaxFrequency |
|
readwritenonatomiccopy |
Maximum update frequency to be requested to Lightstreamer Server for all the items in the LSSubscription.
The maximum update frequency is expressed in updates per second and applies for each item in the LSSubscription; for instance, with a setting of 0.5, for each single item, no more than one update every 2 seconds will be received. If the string "unlimited" is supplied, then the maximum frequency is decided by the Server. It is also possible to supply the string "unfiltered", to ask for unfiltered dispatching, if it is allowed for the items, or a nil value to avoid sending any frequency request to the server. The check for the string constants is case insensitive.
It can be used only if the Subscription mode is MERGE, DISTINCT or COMMAND (in the latter case, the frequency limitation applies to the UPDATE events for each single key).
Note that frequency limits on the items can also be set on the server side and this request can only be issued in order to furtherly reduce the frequency, not to rise it beyond these limits.
This property can also be set to request unfiltered dispatching for the items in the Subscription. However, unfiltered dispatching requests may be refused if any frequency limit is posed on the server side for some item.
A further global frequency limit is also imposed by the Server, if it is running in Presto edition; this specific limit also applies to RAW mode and to unfiltered dispatching.
A further global frequency limit is also imposed by the Server, if it is running in Allegro edition; this specific limit also applies to RAW mode and to unfiltered dispatching.
A further global frequency limit is also imposed by the Server, if it is running in Moderato edition; this specific limit also applies to RAW mode and to unfiltered dispatching.
Default: nil, meaning to not request any frequency limit to the server. As a consequence the server will try to not apply any frequency limit to the subscription (i.e.: "unlimited", see the "General Concepts" document for further details)
This method can can be called at any time with some differences based on the LSSubscription status:
-
If the LSSubscription instance is in its "inactive" state then this property can be changed at will.
-
If the LSSubscription instance is in its "active" state then this property can still be changed unless its current or target value is "unfiltered" or nil. Also if the Subscription instance is in its "active" state and the connection to the server is currently open, then a request to change the frequency of the LSSubscription on the fly is sent to the server.
- Exceptions
-
| NSException | if the LSSubscription is currently "active" and the current value of this property is nil or "unfiltered". |
| NSException | if the LSSubscription is currently "active" and the given parameter is nil or "unfiltered". |
| NSException | if the specified value is not nil nor one of the special "unlimited" and "unfiltered" values nor a valid positive number. |
| - (NSString*) requestedSnapshot |
|
readwritenonatomiccopy |
Enables/disables snapshot delivery request for the items in the LSSubscription.
The snapshot delivery is expressed as "yes"/"no" to request/not request snapshot delivery (the check is case insensitive). If the LSSubscription mode is DISTINCT, instead of "yes", it is also possible to supply a number, to specify the requested length of the snapshot (though the length of the received snapshot may be less than requested, because of insufficient data or server side limits); passing "yes" means that the snapshot length should be determined only by the Server. Nil is also a valid value; if specified no snapshot preference will be sent to the server that will decide itself whether or not to send any snapshot.
The snapshot can be requested only if the LSSubscription mode is MERGE, DISTINCT or COMMAND.
Default: "yes" if the LSSubscription mode is not "RAW", nil otherwise.
This property can only be changed while the LSSubscription instance is in its "inactive" state.
- Exceptions
-
| NSException | if the LSSubscription is currently "active". |
| NSException | if the specified value is not "yes" nor "no" nor nil nor a valid integer positive number. |
| NSException | if the specified value is not compatible with the mode of the Subscription:
-
In case of a RAW LSSubscription only nil is a valid value;
-
In case of a non-DISTINCT LSSubscription only nil, "yes" and "no" are valid values.
|
1.8.11