subscribeMpn method

Future<void> subscribeMpn(
  1. MpnSubscription sub,
  2. bool coalescing
)

Operation method that subscribes an MpnSubscription on server's MPN Module.

This operation adds the MpnSubscription to the list of "active" subscriptions. MPN subscriptions are activated on the server as soon as possible (i.e. as soon as there is a session available and subsequently as soon as the MPN device registration succeeds). Differently than real-time subscriptions, MPN subscriptions are persisted on the server's MPN Module database and survive the session they were created on.
If the coalescing flag is set, the activation of two MPN subscriptions with the same Adapter Set, Data Adapter, Group, Schema and trigger expression will be considered the same MPN subscription. Activating two such subscriptions will result in the second activation modifying the first MpnSubscription (that could have been issued within a previous session). If the coalescing flag is not set, two activations are always considered different MPN subscriptions, whatever the Adapter Set, Data Adapter, Group, Schema and trigger expression are set.
The rationale behind the coalescing flag is to allow simple apps to always activate their MPN subscriptions when the app starts, without worrying if the same subscriptions have been activated before or not. In fact, since MPN subscriptions are persistent, if they are activated every time the app starts and the coalescing flag is not set, every activation is a new MPN subscription, leading to multiple push notifications for the same event.

General Edition Note MPN is an optional feature, available 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).

Lifecycle An MpnSubscription can be given to the LightstreamerClient once an MpnDevice registration has been requested. The MpnSubscription immediately enters the "active" state.
Once "active", an MpnSubscription instance cannot be provided again to an LightstreamerClient unless it is first removed from the "active" state through a call to unsubscribe.
Note that forwarding of the subscription to the server is made in a separate thread.
A successful subscription to the server will be notified through an MpnSubscriptionListener.onSubscription event.

  • sub An MpnSubscription object, carrying all the information to route real-time data via push notifications.
  • coalescing A flag that specifies if the MPN subscription must coalesce with any pre-existing MPN subscription with the same Adapter Set, Data Adapter, Group, Schema and trigger expression.

Throws IllegalStateException if the given MPN subscription does not contain a field list/field schema.

Throws IllegalStateException if the given MPN subscription does not contain a item list/item group.

Throws IllegalStateException if there is no MPN device registered.

Throws IllegalStateException if the given MPN subscription is already active.

⚠ WARNING ⚠ The completion of the returned Future indicates that the operation has been accepted and is in progress, but not necessarily completed. To receive notifications about events generated by the operation, it is necessary to register an MpnSubscriptionListener.

Implementation

Future<void> subscribeMpn(MpnSubscription sub, bool coalescing) async {
  var arguments = <String, dynamic>{
    'subscription': sub._toMap(),
    'coalescing': coalescing
  };
  await NativeBridge.instance.client_subscribeMpn(_id, sub._id, sub, arguments);
  // NB _remoteActive is set after the remote call to ensure that, when the call returns,
  // the remote image of the local subscription has been created
  sub._remoteActive = true;
  //
  cleanResources(); // no need to await here
}