MpnSubscription

Adds a listener that will receive events from the MpnSubscription instance.
The same listener can be added to several different MpnSubscription instances.

Lifecycle: a listener can be added at any time.

Inquiry method that gets the JSON structure used by the Sever to send notifications.

Inquiry method that gets the trigger expression evaluated by the Sever.

Inquiry method that can be used to read the name of the Data Adapter specified for this MpnSubscription through MpnSubscription#setDataAdapter.

Lifecycle: This method can be called at any time.

Inquiry method that can be used to read the "Field List" specified for this MpnSubscription.
Note: if the MpnSubscription has been created by the client, such as when obtained through LightstreamerClient#getMpnSubscriptions, fields are always expressed with a "Field Schema"", even if originally the MPN subscription used a "Field List".

Lifecycle: This method can only be called if the MpnSubscription has been initialized using a "Field List".

Inquiry method that can be used to read the field schema specified for this MpnSubscription.
Note: if the MpnSubscription has been created by the client, such as when obtained through LightstreamerClient#getMpnSubscriptions, fields are always expressed with a "Field Schema"", even if originally the MPN subscription used a "Field List".

Lifecycle: This method can only be called if the MpnSubscription has been initialized using a "Field Schema"

Inquiry method that can be used to read the item group specified for this MpnSubscription.
Note: if the MpnSubscription has been created by the client, such as when obtained through LightstreamerClient#getMpnSubscriptions, items are always expressed with an "Item Group"", even if originally the MPN subscription used an "Item List".

Lifecycle: This method can only be called if the MpnSubscription has been initialized using an "Item Group"

Inquiry method that can be used to read the "Item List" specified for this MpnSubscription.
Note that if the single-item-constructor was used, this method will return an array of length 1 containing such item.
Note: if the MpnSubscription has been created by the client, such as when obtained through LightstreamerClient#getMpnSubscriptions, items are always expressed with an "Item Group"", even if originally the MPN subscription used an "Item List".

Lifecycle: This method can only be called if the MpnSubscription has been initialized with an "Item List".

Returns an array containing the MpnSubscriptionListener instances that were added to this client.

Inquiry method that can be used to read the mode specified for this MpnSubscription.

Lifecycle: This method can be called at any time.

Inquiry method that gets the JSON structure requested by the user to be used as the format of push notifications.
This JSON structure is sent by the server to the push notification service provider (FCM or APNs), hence it must follow its specifications.

Inquiry method that can be used to read the buffer size, configured though MpnSubscription#setRequestedBufferSize, to be requested to the Server for this MpnSubscription.

Lifecycle: This method can be called at any time.

Inquiry method that can be used to read the max frequency, configured through MpnSubscription#setRequestedMaxFrequency, to be requested to the Server for this MpnSubscription.

Lifecycle: This method can be called at any time.

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 MpnSubscription#isActive, MpnSubscription#isSubscribed and MpnSubscription#isTriggered are all false.
• ACTIVE: when the MPN subscription has been submitted to the server, but no confirm has been received yet. In this status MpnSubscription#isActive is true, MpnSubscription#isSubscribed and MpnSubscription#isTriggered are false.
• 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 MpnSubscription#isActive and MpnSubscription#isSubscribed are true, MpnSubscription#isTriggered is false.
• TRIGGERED: when the MPN subscription has a trigger expression set, has been successfully subscribed on the server and the trigger expression has been evaluated to true at least once. In this status MpnSubscription#isActive, MpnSubscription#isSubscribed and MpnSubscription#isTriggered are all true.

Lifecycle: This method can be called at any time.

The server-side timestamp of the subscription status.

Lifecycle: This method can be called at any time.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument status_timestamp on any MpnSubscriptionListener listening to the related MpnSubscription.

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 MpnSubscription may exists at any given time referring to the same MPN subscription, and thus with the same subscription ID. For instance, copying an MpnSubscription with the copy initializer creates a second MpnSubscription instance with the same subscription ID. Also, the coalescing flag of LightstreamerClient#subscribeMpn may cause the assignment of a pre-existing MPN subscription ID to the new subscription.
Two MpnSubscription 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 method can be called at any time.

Inquiry method that gets the trigger expression requested by the user.

Checks if the MpnSubscription is currently "active" or not.
Most of the MpnSubscription properties cannot be modified if an MpnSubscription is "active".
The status of an MpnSubscription is changed to "active" through the LightstreamerClient#subscribeMpn method and back to "inactive" through the LightstreamerClient#unsubscribeMpn and LightstreamerClient#unsubscribeMpnSubscriptions ones.

Lifecycle: This method can be called at any time.

Checks if the MpnSubscription is currently subscribed to through the server or not.
This flag is switched to true by server sent subscription events, and back to false in case of client disconnection, LightstreamerClient#unsubscribeMpn or LightstreamerClient#unsubscribeMpnSubscriptions calls, and server sent unsubscription events.

Lifecycle: This method can be called at any time.

Checks if the MpnSubscription is currently triggered or not.
This flag is switched to true 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 "subscribed" states. It is switched back to false if the subscription is modified with a LightstreamerClient#subscribeMpn call on a copy of it, deleted with LightstreamerClient#unsubscribeMpn or LightstreamerClient#unsubscribeMpnSubscriptions calls, and server sent subscription events.

Lifecycle: This method can be called at any time.

Removes a listener from the MpnSubscription instance so that it will not receive events anymore.

Lifecycle: a listener can be removed at any time.

Setter method that sets the name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items for this MpnSubscription.
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 MpnSubscription. Multiple MpnSubscriptions have to be defined.

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

Lifecycle: This method can only be called while the MpnSubscription instance is in its "inactive" state.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument adapter on any MpnSubscriptionListener listening to the related MpnSubscription.

Setter method that sets the "Field List" to be subscribed to through Lightstreamer Server.
Any call to this method will override any "Field List" or "Field Schema" previously specified.

Lifecycle: This method can only be called while the MpnSubscription instance is in its "inactive" state.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument schema on any MpnSubscriptionListener listening to the related MpnSubscription.

Setter method that sets the "Field Schema" to be subscribed to through Lightstreamer Server.
Any call to this method will override any "Field List" or "Field Schema" previously specified.

Lifecycle: This method can only be called while the MpnSubscription instance is in its "inactive" state.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument schema on any MpnSubscriptionListener listening to the related MpnSubscription.

Setter method that sets the "Item Group" to be subscribed to through Lightstreamer Server.
Any call to this method will override any "Item List" or "Item Group" previously specified.

Lifecycle: This method can only be called while the MpnSubscription instance is in its "inactive" state.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument group on any MpnSubscriptionListener listening to the related MpnSubscription.

Setter method that sets the "Item List" to be subscribed to through Lightstreamer Server.
Any call to this method will override any "Item List" or "Item Group" previously specified.

Lifecycle: This method can only be called while the MpnSubscription instance is in its "inactive" state.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument group on any MpnSubscriptionListener listening to the related MpnSubscription.

Sets the 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 (FCM or 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:

• { "notification" : { "body" : "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.
A special server-managed argument may also be used:

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

The MpnBuilder object provides methods to build an appropriate JSON structure from its defining fields.
Note: if the MpnSubscription has been created by the client, such as when obtained through LightstreamerClient#getMpnSubscriptions, 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 be changed at any time

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument notification_format on any MpnSubscriptionListener listening to the related MpnSubscription.

Setter method that sets the length to be requested to Lightstreamer Server for the internal queuing buffers for the items in the MpnSubscription.
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.
Note that the Server may pose an upper limit on the size of its internal buffers.

Default value: null, meaning to lean on the Server default based on the subscription 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 method can only be called while the MpnSubscription instance is in its "inactive" state.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument requested_buffer_size on any MpnSubscriptionListener listening to the related MpnSubscription.

Setter method that sets the maximum update frequency to be requested to Lightstreamer Server for all the items in the MpnSubscription.
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 further 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).

Default value: null, meaning to lean on the Server default based on the subscription 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 method can only be called while the MpnSubscription instance is in its "inactive" state.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument requested_max_frequency on any MpnSubscriptionListener listening to the related MpnSubscription.

Sets the boolean expression that will be 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 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 MpnSubscription#setNotificationFormat 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 MpnSubscription has been created by the client, such as when obtained through LightstreamerClient#getMpnSubscriptions, 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 be changed at any time.

Notification: A change to this setting will be notified through a call to MpnSubscriptionListener#onPropertyChanged with argument trigger on any MpnSubscriptionListener listening to the related MpnSubscription.