LSMPNSubscription Class Reference

Inherits from NSObject
Declared in LSMPNSubscription.h

Overview

Class representing a Mobile Push Notifications (MPN) subscription to be submitted to the MPN Module of a Lightstreamer Server.

It contains subscription details and the delegate needed to monitor its status. Real-time data is routed via native push notifications.

In order to successfully subscribe an MPN subscription, first an LSMPNDevice must be created and registered on the with [LSLightstreamerClient registerForMPN:].

After creation, an LSMPNSubscription object is in the “inactive” state. When an LSMPNSubscription object is subscribed to on an LSLightstreamerClient object, through the [LSLightstreamerClient subscribeMPN:coalescing:] method, its state switches to “active”. This means that the subscription request is being sent to the Lightstreamer Server. Once the server accepted the request, it begins to send real-time events via native push notifications and the LSMPNSubscription object switches to the “subscribed” state.

If a triggerExpression is set, the MPN subscription does not send any push notifications until the expression evaluates to true. When this happens, the MPN subscription switches to “triggered” state and a single push notification is sent. Once triggered, no other push notifications are sent.

When an LSMPNSubscription is subscribed on the server, it acquires a permanent that the server later uses to identify the same MPN subscription on subsequent sessions.

An LSMPNSubscription 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. The same rules that apply to apply to LSMPNSubscription.

An LSMPNSubscription object can also be provided by the client to represent a pre-existing MPN subscription on the server. In fact, differently than real-time subscriptions, MPN subscriptions are persisted on the server’s MPN Module database and survive the session they were created on.

MPN subscriptions are associated with the MPN device, and after the device has been registered the client retrieves pre-existing MPN subscriptions from the server’s database and exposes them in the [LSLightstreamerClient MPNSubscriptions] collection.

– initWithSubscriptionMode:

Creates an object to be used to describe an MPN subscription that is going to be subscribed to through the MPN Module of Lightstreamer Server.

The object can be supplied to [LSLightstreamerClient subscribeMPN:coalescing:] in order to bring the MPN subscription to “active” state.

Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the “inactive” state.

Permitted values for subscription mode are:

  • MERGE

  • DISTINCT

- (nonnull instancetype)initWithSubscriptionMode:(nonnull NSString *)subscriptionMode

Parameters

subscriptionMode

The subscription mode for the items, required by Lightstreamer Server.

Exceptions

NSException

If no or invalid subscription mode is passed.

Declared In

LSMPNSubscription.h

– initWithSubscriptionMode:item:fields:

Creates an object to be used to describe an MPN subscription that is going to be subscribed to through the MPN Module of Lightstreamer Server.

The object can be supplied to [LSLightstreamerClient subscribeMPN:coalescing:] in order to bring the MPN subscription to “active” state.

Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the “inactive” state.

Permitted values for subscription mode are:

  • MERGE

  • DISTINCT

- (nonnull instancetype)initWithSubscriptionMode:(nonnull NSString *)subscriptionMode item:(nonnull NSString *)item fields:(nonnull NSArray<NSString*> *)fields

Parameters

subscriptionMode

The subscription mode for the items, required by Lightstreamer Server.

item

The item name to be subscribed to through Lightstreamer Server.

fields

An array of fields for the items to be subscribed to through Lightstreamer Server. It is also possible to specify the “Field List” or “Field Schema” later through fields and fieldSchema.

Exceptions

NSException

If no or invalid subscription mode is passed.

NSException

If either the item or the fields array is left nil.

NSException

If the specified “Item List” or “Field List” is not valid; see items and fields for details.

Declared In

LSMPNSubscription.h

– initWithSubscriptionMode:items:fields:

Creates an object to be used to describe an MPN subscription that is going to be subscribed to through the MPN Module of Lightstreamer Server.

The object can be supplied to [LSLightstreamerClient subscribeMPN:coalescing:] in order to bring the MPN subscription to “active” state.

Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the “inactive” state.

Permitted values for subscription mode are:

  • MERGE

  • DISTINCT

- (nonnull instancetype)initWithSubscriptionMode:(nonnull NSString *)subscriptionMode items:(nonnull NSArray<NSString*> *)items fields:(nonnull NSArray<NSString*> *)fields

Parameters

subscriptionMode

The subscription mode for the items, required by Lightstreamer Server.

items

An array of items to be subscribed to through Lightstreamer Server. It is also possible specify the “Item List” or “Item Group” later through items and itemGroup.

fields

An array of fields for the items to be subscribed to through Lightstreamer Server. It is also possible to specify the “Field List” or “Field Schema” later through fields and fieldSchema.

Exceptions

NSException

If no or invalid subscription mode is passed.

NSException

If either the items or the fields array is left nil.

NSException

If the specified “Item List” or “Field List” is not valid; see items and fields for details.

Declared In

LSMPNSubscription.h

– initWithSubscription:

Creates an LSMPNSubscription object copying subscription mode, items, fields and data adapter from the specified real-time subscription.

The object can be supplied to [LSLightstreamerClient subscribeMPN:coalescing:] in order to bring the MPN subscription to “active” state.

Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the “inactive” state.

- (nonnull instancetype)initWithSubscription:(nonnull LSSubscription *)subscription

Parameters

subscription

The LSSubscription object to copy properties from.

Declared In

LSMPNSubscription.h

– initWithMPNSubscription:

Creates an LSMPNSubscription object copying all properties (including the subscription ID) from the specified MPN subscription.

The created LSMPNSubscription is a copy of the original LSMPNSubscription object and represents the same MPN subscription, since their subscription ID is the same. When the object is supplied to [LSLightstreamerClient subscribeMPN:coalescing:] in order to bring it to “active” state, the MPN subscription is modified: any property changed in this LSMPNSubscription replaces the corresponding value of the MPN subscription on the server.

Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the “inactive” state.

- (nonnull instancetype)initWithMPNSubscription:(nonnull LSMPNSubscription *)mpnSubscription

Parameters

mpnSubscription

The LSMPNSubscription object to copy properties from.

Declared In

LSMPNSubscription.h

– addDelegate:

Adds a delegate that will receive events from the LSMPNSubscription instance.

The same delegate can be added to several different LSMPNSubscription instances.

Lifecycle: a delegate can be added at any time. A call to add a delegate already present will be ignored.

- (void)addDelegate:(nonnull id<LSMPNSubscriptionDelegate>)delegate

Parameters

delegate

An object that will receive the events as documented in the LSMPNSubscriptionDelegate interface. Note: delegates are stored with weak references: make sure you keep a strong reference to your delegates or they may be released prematurely.

Declared In

LSMPNSubscription.h

– removeDelegate:

Removes a delegate from the LSMPNSubscription instance so that it will not receive events anymore.

Lifecycle: a delegate can be removed at any time.

- (void)removeDelegate:(nonnull id<LSMPNSubscriptionDelegate>)delegate

Parameters

delegate

The delegate to be removed.

See Also

Declared In

LSMPNSubscription.h

  delegates

List containing the LSMPNSubscriptionDelegate instances that were added to this LSMPNSubscription.

@property (nonatomic, readonly, nonnull) NSArray<id<LSMPNSubscriptionDelegate> > *delegates

See Also

Declared In

LSMPNSubscription.h

  mode

The mode specified for this LSMPNSubscription.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly, nonnull) NSString *mode

Declared In

LSMPNSubscription.h

  dataAdapter

Name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items for this LSMPNSubscription.

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 LSMPNSubscription. Multiple LSMPNSubscriptions have to be defined.

Default: the default Data Adapter for the Adapter Set, configured as DEFAULT on the Server.

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument adapter on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nullable) NSString *dataAdapter

Exceptions

NSException

if the LSMPNSubscription is currently “active”.

Declared In

LSMPNSubscription.h

  fields

The “Field List” to be subscribed to through Lightstreamer Server.

Any change to this property will override any “Field List” or “Field Schema” previously specified.

Note: if the LSMPNSubscription has been created by the client, such as when obtained through [LSLightstreamerClient MPNSubscriptions], fields are always expressed with a “Field Schema”“, even if originally the MPN subscription used a "Field List”.

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument schema on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nonnull) NSArray<NSString*> *fields

Exceptions

NSException

if any of the field names in the list contains a space or is empty/nil.

NSException

if the LSMPNSubscription is currently “active”.

NSException

when reading, if the LSMPNSubscription was initialized with a “Field Schema” or was not initialized at all.

Declared In

LSMPNSubscription.h

  fieldSchema

The “Field Schema” to be subscribed to through Lightstreamer Server.

Any change to this property will override any “Field List” or “Field Schema” previously specified.

Note: if the LSMPNSubscription has been created by the client, such as when obtained through [LSLightstreamerClient MPNSubscriptions], fields are always expressed with a “Field Schema”“, even if originally the MPN subscription used a "Field List”.

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument schema on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nonnull) NSString *fieldSchema

Exceptions

NSException

if the LSMPNSubscription is currently “active”.

NSException

when reading, if the LSMPNSubscription was initialized with a “Field List” or was not initialized at all.

Declared In

LSMPNSubscription.h

  itemGroup

The “Item Group” to be subscribed to through Lightstreamer Server.

Any change to this property will override any “Item List” or “Item Group” previously specified.

Note: if the LSMPNSubscription has been created by the client, such as when obtained through [LSLightstreamerClient MPNSubscriptions], items are always expressed with an “Item Group”“, even if originally the MPN subscription used an "Item List”.

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument group on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nonnull) NSString *itemGroup

Exceptions

NSException

if the LSMPNSubscription is currently “active”.

NSException

when reading, if the LSMPNSubscription was initialized with an “Item List” or was not initialized at all.

Declared In

LSMPNSubscription.h

  items

The “Item List” to be subscribed to through Lightstreamer Server.

Any change to this property will override any “Item List” or “Item Group” previously specified.

Note: if the LSMPNSubscription has been created by the client, such as when obtained through [LSLightstreamerClient MPNSubscriptions], items are always expressed with an “Item Group”“, even if originally the MPN subscription used an "Item List”.

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument group on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nonnull) NSArray<NSString*> *items

Exceptions

NSException

if any of the item names in the “Item List” contains a space or is a number or is empty/nil.

NSException

if the LSMPNSubscription is currently “active”.

NSException

when reading, if the LSMPNSubscription was initialized with an “Item Group” or was not initialized at all.

Declared In

LSMPNSubscription.h

  notificationFormat

JSON structure to be used as the format of push notifications.

This JSON structure is sent by the server to the push notification service provider (i.e. Apple’s APNs), hence it must follow its specifications.

The JSON structure may contain named arguments with the format ${field}, or indexed arguments with the format $[1]. These arguments are replaced by the server with the value of corresponding subscription fields before the push notification is sent.

For instance, if the subscription contains fields “stock_name” and “last_price”, the notification format could be something like this:

  • { "aps" : { "alert" : "Stock ${stock_name} is now valued ${last_price}" } }

Named arguments are available if the Metadata Adapter is a subclass of LiteralBasedProvider or provides equivalent functionality, otherwise only indexed arguments may be used. In both cases common metadata rules apply: field names and indexes are checked against the Metadata Adapter, hence they must be consistent with the schema and group specified.

Some special server-managed arguments may also be used:

  • AUTO: when specified for the badge value of the push notification, the badge will be assigned automatically as a progressive counter of all push notifications originated by MPN subscriptions with the “AUTO” value, on a per-device and per-application basis. The counter can also be reset at any time by calling [LSLightstreamerClient resetMPNBadge].

  • ${LS_MPN_subscription_ID}: the ID of the MPN subscription generating the push notification.

The LSMPNBuilder object provides methods to build an appropriate JSON structure from its defining fields.

Note: if the LSMPNSubscription has been created by the client, such as when obtained through [LSLightstreamerClient MPNSubscriptions], named arguments are always mapped to its corresponding indexed argument, even if originally the notification format used a named argument.

Note: the content of this property may be subject to length restrictions (See the “General Concepts” document for more information).

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument notification_format on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nullable) NSString *notificationFormat

Exceptions

NSException

if the LSMPNSubscription is currently “active”.

See Also

Declared In

LSMPNSubscription.h

  triggerExpression

A boolean expression that, when set, is evaluated against each update and will act as a trigger to deliver the push notification.

If a trigger expression is set, the MPN subscription does not send any push notifications until the expression evaluates to true. When this happens, the MPN subscription “triggers” and a single push notification is sent. Once triggered, no other push notifications are sent. In other words, with a trigger expression set, the MPN subscription sends at most one push notification.

The expression must be strictly in Java syntax and can contain named arguments with the format ${field}, or indexed arguments with the format $[1]. The same rules that apply to notificationFormat apply also to the trigger expression. The expression is verified and evaluated on the server.

Named and indexed arguments are replaced by the server with the value of corresponding subscription fields before the expression is evaluated. They are represented as String variables, and as such appropriate type conversion must be considered. E.g.

  • Double.parseDouble(${last_price}) > 500.0

Argument variables are named with the prefix LS_MPN_field followed by an index. Thus, variable names like LS_MPN_field1 should be considered reserved and their use avoided in the expression.

Consider potential impact on server performance when writing trigger expressions. Since Java code may use classes and methods of the JDK, a badly written trigger may cause CPU hogging or memory exhaustion. For this reason, a server-side filter may be applied to refuse poorly written (or even maliciously crafted) trigger expressions. See the “General Concepts” document for more information.

Note: if the LSMPNSubscription has been created by the client, such as when obtained through [LSLightstreamerClient MPNSubscriptions], named arguments are always mapped to its corresponding indexed argument, even if originally the trigger expression used a named argument.

Note: the content of this property may be subject to length restrictions (See the “General Concepts” document for more information).

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument trigger on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nullable) NSString *triggerExpression

Exceptions

NSException

if the LSMPNSubscription is currently “active”.

Declared In

LSMPNSubscription.h

  requestedBufferSize

Length to be requested to Lightstreamer Server for the internal queuing buffers for the items in the LSMPNSubscription.

A Queuing buffer is used by the Server to accumulate a burst of updates for an item, so that they can all sent as push notifications, despite of frequency limits. 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.

Format: an integer number (e.g. 10), or unlimited, or nil.

Default: nil, meaning to lean on the Server default based on the LSMPNSubscription mode. 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.

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument requested_buffer_size on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nullable) NSString *requestedBufferSize

Exceptions

NSException

if the LSMPNSubscription is currently “active”.

NSException

if the specified value is not nil nor unlimited nor a valid positive integer number.

Declared In

LSMPNSubscription.h

  requestedMaxFrequency

Maximum update frequency to be requested to Lightstreamer Server for all the items in the LSMPNSubscription.

The maximum update frequency is expressed in updates per second and applies for each item in the LSMPNSubscription; 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 no frequency limit is requested. It is also possible to supply the nil value stick to the Server default (which currently corresponds to unlimited). The check for the string constants is case insensitive.

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.

Edition note: a further global frequency limit could also be imposed by the Server, depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Format: a decimal number (e.g. 2.0), or unlimited, or nil.

Default: nil, meaning to lean on the Server default based on the LSMPNSubscription mode. This consists, for all modes, in not applying any frequency limit to the subscription (the same as unlimited); see the “General Concepts” document for further details.

Lifecycle: this property can only be set while the LSMPNSubscription instance is in its “inactive” state.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument requested_max_frequency on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, copy, nullable) NSString *requestedMaxFrequency

Exceptions

NSException

if the LSMPNSubscription is currently “active”.

NSException

if the specified value is not nil nor one of the special unlimited values nor a valid positive number.

Declared In

LSMPNSubscription.h

  active

Checks if the LSMPNSubscription is currently “active” or not.

Most of the LSMPNSubscription properties cannot be modified if an LSMPNSubscription is “active”.

The status of an LSMPNSubscription is changed to “active” through the [LSLightstreamerClient subscribeMPN:coalescing:] method and back to “inactive” through the [LSLightstreamerClient unsubscribeMPN:] and [LSLightstreamerClient unsubscribeMultipleMPN:] ones.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly, getter=isActive) BOOL active

Declared In

LSMPNSubscription.h

  subscribed

Checks if the LSMPNSubscription is currently subscribed to through the server or not.

This flag is switched to YES by server sent subscription events, and back to NO in case of client disconnection, [LSLightstreamerClient unsubscribeMPN:] or [LSLightstreamerClient unsubscribeMultipleMPN:] calls, and server sent unsubscription events.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly, getter=isSubscribed) BOOL subscribed

Declared In

LSMPNSubscription.h

  triggered

Checks if the LSMPNSubscription is currently triggered or not.

This flag is switched to YES when a trigger expression has been set and it evaluated to true at least once. For this to happen, the subscription must already be in active and states. It is switched back to NO if the subscription is modified with a [LSLightstreamerClient subscribeMPN:coalescing:] call on a copy of it, deleted with [LSLightstreamerClient unsubscribeMPN:] or [LSLightstreamerClient unsubscribeMultipleMPN:] calls, and server sent subscription events.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly, getter=isTriggered) BOOL triggered

See Also

Declared In

LSMPNSubscription.h

  status

The status of the subscription.

The status can be:

  • UNKNOWN: when the MPN subscription has just been created or deleted (i.e. unsubscribed). In this status active, subscribed and triggered are all NO.

  • ACTIVE: when the MPN susbcription has been submitted to the server, but no confirm has been received yet. In this status active is YES, subscribed and triggered are NO.

  • SUBSCRIBED: when the MPN subscription has been successfully subscribed on the server. If a trigger expression is set, it has not been evaluated to true yet. In this status active and subscribed are YES, triggered is NO.

  • TRIGGERED: when the MPN subscription has a trigger expression set, has been successfully on the server and the trigger expression evaluated to true at least once. In this status active, subscribed and triggered are all YES.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly, nonnull) NSString *status

Declared In

LSMPNSubscription.h

  statusTimestamp

The server-side timestamp of the subscription status.

Lifecycle: this property can be read at any time.

Related notifications: a change to this setting will be notified through a call to [LSMPNSubscriptionDelegate mpnSubscription:didChangeProperty:] with argument status_timestamp on any LSMPNSubscriptionDelegate listening to the related LSMPNSubscription.

@property (nonatomic, readonly, nullable) NSDate *statusTimestamp

See Also

Declared In

LSMPNSubscription.h

  subscriptionId

The server-side unique persistent ID of the MPN subscription.

The ID is available only after the MPN subscription has been successfully subscribed on the server. I.e. when its status is SUBSCRIBED or TRIGGERED.

Note: more than one LSMPNSubscription may exists at any given time referring to the same MPN subscription, and thus with the same subscription ID. For instace, copying an LSMPNSubscription with the copy initializer creates a second LSMPNSubscription instance with the same subscription ID. Also, the coalescing flag of [LSLightstreamerClient subscribeMPN:coalescing:] may cause the assignment of a pre-existing MPN subscription ID to the new subscription.

Two LSMPNSubscription objects with the same subscription ID always represent the same server-side MPN subscription. It is the client’s duty to keep the status and properties of these objects up to date and aligned.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly, nullable) NSString *subscriptionId

Declared In

LSMPNSubscription.h