Package com.lightstreamer.client.mpn

Class MpnSubscription

java.lang.Object
com.lightstreamer.client.mpn.MpnSubscription
public class MpnSubscription extends Object
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 listener needed to monitor its status. Real-time data is routed via native push notifications.
In order to successfully subscribe an MPN subscription, first an MpnDevice must be created and registered on the LightstreamerClient with LightstreamerClient.registerForMpn(MpnDevice).
After creation, an MpnSubscription object is in the "inactive" state. When an MpnSubscription object is subscribed to on an LightstreamerClient object, through the LightstreamerClient.subscribe(MpnSubscription, boolean) 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 MpnSubscription object switches to the "subscribed" state.
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 switches to "triggered" state and a single push notification is sent. Once triggered, no other push notifications are sent.
When an MpnSubscription is subscribed on the server, it acquires a permanent subscription ID that the server later uses to identify the same MPN subscription on subsequent sessions.
An MpnSubscription 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 Subscription apply to MpnSubscription.
An MpnSubscription 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 with the LightstreamerClient.getMpnSubscriptions(String) method.

  • Constructor Summary

    Constructors
    Constructor
    Description
    MpnSubscription(MpnSubscription copyFrom)
    Creates an MPNSubscription object copying all properties from the specified MPN subscription.
    MpnSubscription(Subscription copyFrom)
    Creates an MpnSubscription object copying subscription mode, items, fields and data adapter from the specified real-time subscription.
    The object can be supplied to LightstreamerClient.subscribe(MpnSubscription, boolean) in order to bring the MPN subscription to "active" state.
    Note that all of the methods used to describe the subscription to the server, except setTriggerExpression(String) and setNotificationFormat(String), can only be called while the instance is in the "inactive" state.
    MpnSubscription(String subscriptionMode)
    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 LightstreamerClient.subscribe(MpnSubscription, boolean) 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.
    MpnSubscription(String subscriptionMode, String[] items, String[] 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 LightstreamerClient.subscribe(MpnSubscription, boolean) 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.
    MpnSubscription(String subscriptionMode, String item, String[] 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 LightstreamerClient.subscribe(MpnSubscription, boolean) 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.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addListener(MpnSubscriptionListener listener)
    Adds a listener that will receive events from the MpnSubscription instance.
    The same listener can be added to several different MpnSubscription instances.
    String
    getActualNotificationFormat()
    Inquiry method that gets the JSON structure used by the Sever to send notifications.
    String
    getActualTriggerExpression()
    Inquiry method that gets the trigger expression evaluated by the Sever.
    String
    getDataAdapter()
    Inquiry method that can be used to read the name of the Data Adapter specified for this MpnSubscription through setDataAdapter(String).
    String[]
    getFields()
    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(String), fields are always expressed with a "Field Schema"", even if originally the MPN subscription used a "Field List".
    String
    getFieldSchema()
    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(String), fields are always expressed with a "Field Schema"", even if originally the MPN subscription used a "Field List".
    String
    getItemGroup()
    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(String), items are always expressed with an "Item Group"", even if originally the MPN subscription used an "Item List".
    String[]
    getItems()
    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(String), items are always expressed with an "Item Group"", even if originally the MPN subscription used an "Item List".
    List<MpnSubscriptionListener>
    getListeners()
    Returns the list containing the MpnSubscriptionListener instances that were added to this MpnSubscription.
    String
    getMode()
    Inquiry method that can be used to read the mode specified for this MpnSubscription.
    String
    getNotificationFormat()
    Inquiry method that gets the JSON structure requested by the user to be used as the format of push notifications.
    String
    getRequestedBufferSize()
    Inquiry method that can be used to read the buffer size, configured though setRequestedBufferSize(java.lang.String), to be requested to the Server for this MpnSubscription.
    String
    getRequestedMaxFrequency()
    Inquiry method that can be used to read the max frequency, configured through setRequestedMaxFrequency(String), to be requested to the Server for this MpnSubscription.
    String
    getStatus()
    The status of the subscription.
    The status can be: UNKNOWN: when the MPN subscription has just been created or deleted (i.e.
    long
    getStatusTimestamp()
    The server-side timestamp of the subscription status.
    String
    getSubscriptionId()
    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.
    String
    getTriggerExpression()
    Inquiry method that gets the trigger expression requested by the user.
    boolean
    isActive()
    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.subscribe(MpnSubscription, boolean) method and back to "inactive" through the LightstreamerClient.unsubscribe(MpnSubscription) and LightstreamerClient.unsubscribeMpnSubscriptions(String) ones.
    boolean
    isSubscribed()
    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.unsubscribe(MpnSubscription) or LightstreamerClient.unsubscribeMpnSubscriptions(String) calls, and server sent unsubscription events.
    boolean
    isTriggered()
    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.
    void
    removeListener(MpnSubscriptionListener listener)
    Removes a listener from the MpnSubscription instance so that it will not receive events anymore.
    void
    setDataAdapter(String dataAdapter)
    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.
    void
    setFields(String[] fields)
    Setter method that sets the "Field List" to be subscribed to through Lightstreamer Server.
    void
    setFieldSchema(String schemaName)
    Setter method that sets the "Field Schema" to be subscribed to through Lightstreamer Server.
    void
    setItemGroup(String groupName)
    Setter method that sets the "Item Group" to be subscribed to through Lightstreamer Server.
    void
    setItems(String[] items)
    Setter method that sets the "Item List" to be subscribed to through Lightstreamer Server.
    void
    setNotificationFormat(String format)
    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 (i.e.
    void
    setRequestedBufferSize(String size)
    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.
    void
    setRequestedMaxFrequency(String freq)
    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.
    void
    setTriggerExpression(String expr)
    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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • MpnSubscription

      public MpnSubscription(@Nonnull String subscriptionMode, @Nonnull String[] items, @Nonnull String[] 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 LightstreamerClient.subscribe(MpnSubscription, boolean) 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.
      Parameters:
      subscriptionMode - The subscription mode for the items, required by Lightstreamer Server. Permitted values are:
      • MERGE
      • DISTINCT
      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 setItems(String[]) and setItemGroup(String).
      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 setFields(String[]) and setFieldSchema(String).
      Throws:
      IllegalArgumentException - If no or invalid subscription mode is passed.
      IllegalArgumentException - If either the items or the fields array is left null.
      IllegalArgumentException - If the specified "Item List" or "Field List" is not valid; see setItems(String[]) and setFields(String[]) for details.

    • MpnSubscription

      public MpnSubscription(@Nonnull String subscriptionMode, @Nonnull String item, @Nonnull String[] 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 LightstreamerClient.subscribe(MpnSubscription, boolean) 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.
      Parameters:
      subscriptionMode - The subscription mode for the items, required by Lightstreamer Server. Permitted values are:
      • MERGE
      • DISTINCT
      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 setFields(String[]) and setFieldSchema(String).
      Throws:
      IllegalArgumentException - If no or invalid subscription mode is passed.
      IllegalArgumentException - If either the item or the fields array is left null.
      IllegalArgumentException - If the specified "Field List" is not valid; see setFields(String[]) for details.

    • MpnSubscription

      public MpnSubscription(@Nonnull String subscriptionMode)
      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 LightstreamerClient.subscribe(MpnSubscription, boolean) 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.
      Parameters:
      subscriptionMode - The subscription mode for the items, required by Lightstreamer Server. Permitted values are:
      • MERGE
      • DISTINCT
      Throws:
      IllegalArgumentException - If no or invalid subscription mode is passed.

    • MpnSubscription

      public MpnSubscription(@Nonnull Subscription copyFrom)
      Creates an MpnSubscription object copying subscription mode, items, fields and data adapter from the specified real-time subscription.
      The object can be supplied to LightstreamerClient.subscribe(MpnSubscription, boolean) in order to bring the MPN subscription to "active" state.
      Note that all of the methods used to describe the subscription to the server, except setTriggerExpression(String) and setNotificationFormat(String), can only be called while the instance is in the "inactive" state.
      Parameters:
      copyFrom - The Subscription object to copy properties from.

    • MpnSubscription

      public MpnSubscription(@Nonnull MpnSubscription copyFrom)
      Creates an MPNSubscription object copying all properties from the specified MPN subscription. The object can be supplied to LightstreamerClient.subscribe(MpnSubscription, boolean) in order to bring the MPN subscription to "active" state. Note that all of the methods used to describe the subscription to the server, except setTriggerExpression(String) and setNotificationFormat(String), can only be called while the instance is in the "inactive" state.
      Parameters:
      copyFrom - The MpnSubscription object to copy properties from.

  • Method Details

    • addListener

      public void addListener(@Nonnull MpnSubscriptionListener listener)
      Adds a listener that will receive events from the MpnSubscription instance.
      The same listener can be added to several different MpnSubscription instances.
      Parameters:
      listener - An object that will receive the events as documented in the MpnSubscriptionListener interface.
      See Also:
      Lifecycle:
      A listener can be added at any time. A call to add a listener already present will be ignored.

    • removeListener

      public void removeListener(@Nonnull MpnSubscriptionListener listener)
      Removes a listener from the MpnSubscription instance so that it will not receive events anymore.
      Parameters:
      listener - The listener to be removed.
      See Also:
      Lifecycle:
      A listener can be removed at any time.

    • getListeners

      @Nonnull public List<MpnSubscriptionListener> getListeners()
      Returns the list containing the MpnSubscriptionListener instances that were added to this MpnSubscription.
      Returns:
      a list containing the listeners that were added to this subscription.
      See Also:

    • getNotificationFormat

      @Nullable public String getNotificationFormat()
      Inquiry method that gets the JSON structure requested by the user to be used as the format of push notifications.
      Returns:
      the JSON structure requested by the user to be used as the format of push notifications.
      See Also:

    • getActualNotificationFormat

      @Nullable public String getActualNotificationFormat()
      Inquiry method that gets the JSON structure used by the Sever to send notifications.
      Returns:
      the JSON structure used by the Server to send notifications or null if the value is not available.
      See Also:

    • setNotificationFormat

      public void setNotificationFormat(@Nonnull String format)
      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 (i.e. Google's FCM), 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:
      • { "android" : { "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(String), 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).
      Parameters:
      format - the JSON structure to be used as the format of push notifications.
      See Also:
      Lifecycle:
      This property can be changed at any time.
      Notification:
      A change to this setting will be notified through a call to MpnSubscriptionListener.onPropertyChanged(String) with argument notification_format on any MpnSubscriptionListener listening to the related MpnSubscription.

    • getTriggerExpression

      @Nullable public String getTriggerExpression()
      Inquiry method that gets the trigger expression requested by the user.
      Returns:
      returns the trigger requested by the user or null if the value is not available.
      See Also:

    • getActualTriggerExpression

      @Nullable public String getActualTriggerExpression()
      Inquiry method that gets the trigger expression evaluated by the Sever.
      Returns:
      returns the trigger sent by the Server or null if the value is not available.
      See Also:

    • setTriggerExpression

      public void setTriggerExpression(@Nullable String expr)
      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 setNotificationFormat(String) 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(String), 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).
      Parameters:
      expr - the boolean expression that acts as a trigger to deliver the push notification. If the value is null, no trigger is set on the subscription.
      See Also:
      Lifecycle:
      This property can be changed at any time.
      Notification:
      A change to this setting will be notified through a call to MpnSubscriptionListener.onPropertyChanged(String) with argument trigger on any MpnSubscriptionListener listening to the related MpnSubscription.

    • isActive

      public boolean isActive()
      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.subscribe(MpnSubscription, boolean) method and back to "inactive" through the LightstreamerClient.unsubscribe(MpnSubscription) and LightstreamerClient.unsubscribeMpnSubscriptions(String) ones.
      Returns:
      true if the MpnSubscription is currently "active", false otherwise.
      See Also:
      Lifecycle:
      This method can be called at any time.

    • isSubscribed

      public boolean isSubscribed()
      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.unsubscribe(MpnSubscription) or LightstreamerClient.unsubscribeMpnSubscriptions(String) calls, and server sent unsubscription events.
      Returns:
      true if the MpnSubscription has been successfully subscribed on the server, false otherwise.
      See Also:
      Lifecycle:
      This method can be called at any time.

    • isTriggered

      public boolean isTriggered()
      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.subscribe(MpnSubscription, boolean) call on a copy of it, deleted with LightstreamerClient.unsubscribe(MpnSubscription) or LightstreamerClient.unsubscribeMpnSubscriptions(String) calls, and server sent subscription events.
      Returns:
      true if the MpnSubscription's trigger expression has been evaluated to true at least once, false otherwise.
      See Also:
      Lifecycle:
      This method can be called at any time.

    • getStatus

      @Nonnull public String getStatus()
      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 isActive(), isSubscribed() and isTriggered() are all false.
      • ACTIVE: when the MPN susbcription has been submitted to the server, but no confirm has been received yet. In this status isActive() is true, isSubscribed() and 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 isActive() and isSubscribed() are true, 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 isActive(), isSubscribed() and isTriggered() are all true.
      Returns:
      the status of the subscription.
      See Also:
      Lifecycle:
      This method can be called at any time.

    • getStatusTimestamp

      public long getStatusTimestamp()
      The server-side timestamp of the subscription status.
      Returns:
      The server-side timestamp of the subscription status, expressed as a Java time.
      See Also:
      Lifecycle:
      This method can be called at any time.
      Notification:
      A change to this setting will be notified through a call to MpnSubscriptionListener.onPropertyChanged(String) with argument status_timestamp on any MpnSubscriptionListener listening to the related MpnSubscription.

    • setItems

      public void setItems(@Nullable String[] items)
      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.
      Parameters:
      items - an array of items to be subscribed to through the server.
      Throws:
      IllegalArgumentException - if any of the item names in the "Item List" contains a space or is a number or is empty/null.
      IllegalStateException - if the MpnSubscription is currently "active".
      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(String) with argument group on any MpnSubscriptionListener listening to the related MpnSubscription.

    • getItems

      @Nonnull public String[] getItems()
      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(String), items are always expressed with an "Item Group"", even if originally the MPN subscription used an "Item List".
      Returns:
      the "Item List" to be subscribed to through the server, or null if the MpnSubscription was initialized with an "Item Group" or was not initialized at all.
      Lifecycle:
      This method can only be called if the MpnSubscription has been initialized with an "Item List".

    • setItemGroup

      public void setItemGroup(@Nonnull String groupName)
      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.
      Parameters:
      groupName - A String to be expanded into an item list by the Metadata Adapter.
      Throws:
      IllegalStateException - if the MpnSubscription is currently "active".
      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(String) with argument group on any MpnSubscriptionListener listening to the related MpnSubscription.

    • getItemGroup

      @Nonnull public String getItemGroup()
      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(String), items are always expressed with an "Item Group"", even if originally the MPN subscription used an "Item List".
      Returns:
      the "Item Group" to be subscribed to through the server, or null if the MpnSubscription was initialized with an "Item List" or was not initialized at all.
      Lifecycle:
      This method can only be called if the MpnSubscription has been initialized using an "Item Group"

    • setFields

      public void setFields(@Nullable String[] fields)
      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.
      Parameters:
      fields - an array of fields to be subscribed to through the server.
      Throws:
      IllegalArgumentException - if any of the field names in the list contains a space or is empty/null.
      IllegalStateException - if the MpnSubscription is currently "active".
      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(String) with argument schema on any MpnSubscriptionListener listening to the related MpnSubscription.

    • getFields

      @Nonnull public String[] getFields()
      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(String), fields are always expressed with a "Field Schema"", even if originally the MPN subscription used a "Field List".
      Returns:
      the "Field List" to be subscribed to through the server, or null if the MpnSubscription was initialized with a "Field Schema" or was not initialized at all.
      Lifecycle:
      This method can only be called if the MpnSubscription has been initialized using a "Field List".

    • setFieldSchema

      public void setFieldSchema(@Nonnull String schemaName)
      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.
      Parameters:
      schemaName - A String to be expanded into a field list by the Metadata Adapter.
      Throws:
      IllegalStateException - if the MpnSubscription is currently "active".
      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(String) with argument schema on any MpnSubscriptionListener listening to the related MpnSubscription.

    • getFieldSchema

      @Nonnull public String getFieldSchema()
      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(String), fields are always expressed with a "Field Schema"", even if originally the MPN subscription used a "Field List".
      Returns:
      the "Field Schema" to be subscribed to through the server, or null if the MpnSubscription was initialized with a "Field List" or was not initialized at all.
      Lifecycle:
      This method can only be called if the MpnSubscription has been initialized using a "Field Schema"

    • setDataAdapter

      public void setDataAdapter(@Nullable String dataAdapter)
      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.
      Parameters:
      dataAdapter - the name of the Data Adapter. A null value is equivalent to the "DEFAULT" name.
      Throws:
      IllegalStateException - if the Subscription is currently "active".
      See Also:
      Default:
      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(String) with argument adapter on any MpnSubscriptionListener listening to the related MpnSubscription.

    • getDataAdapter

      @Nullable public String getDataAdapter()
      Inquiry method that can be used to read the name of the Data Adapter specified for this MpnSubscription through setDataAdapter(String).
      Returns:
      the name of the Data Adapter; returns null if no name has been configured, so that the "DEFAULT" Adapter Set is used.
      Lifecycle:
      This method can be called at any time.

    • setRequestedBufferSize

      public void setRequestedBufferSize(@Nullable String size)
      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.
      Parameters:
      size - An integer number, representing the length of the internal queuing buffers to be used in the Server. If the string "unlimited" is supplied, then no buffer size limit is requested (the check is case insensitive). It is also possible to supply a null value to stick to the Server default (which currently depends on the subscription mode).
      Throws:
      IllegalStateException - if the MpnSubscription is currently "active".
      IllegalArgumentException - if the specified value is not null nor "unlimited" nor a valid positive integer number.
      See Also:
      Default:
      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(String) with argument requested_buffer_size on any MpnSubscriptionListener listening to the related MpnSubscription.

    • getRequestedBufferSize

      @Nullable public String getRequestedBufferSize()
      Inquiry method that can be used to read the buffer size, configured though setRequestedBufferSize(java.lang.String), to be requested to the Server for this MpnSubscription.
      Returns:
      An integer number, representing the buffer size to be requested to the server, or the string "unlimited", or null.
      Lifecycle:
      This method can be called at any time.

    • setRequestedMaxFrequency

      public void setRequestedMaxFrequency(@Nullable String freq)
      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.
      Parameters:
      freq - A decimal number, representing the maximum update frequency (expressed in updates per second) for each item in the Subscription; 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 null value to stick to the Server default (which currently corresponds to "unlimited"). The check for the string constants is case insensitive.
      Throws:
      IllegalStateException - if the MpnSubscription is currently "active".
      IllegalArgumentException - if the specified value is not null nor the special "unlimited" value nor a valid positive number.
      Default:
      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(String) with argument requested_max_frequency on any MpnSubscriptionListener listening to the related MpnSubscription.
      General 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).

    • getRequestedMaxFrequency

      @Nullable public String getRequestedMaxFrequency()
      Inquiry method that can be used to read the max frequency, configured through setRequestedMaxFrequency(String), to be requested to the Server for this MpnSubscription.
      Returns:
      A decimal number, representing the max frequency to be requested to the server (expressed in updates per second), or the string "unlimited", or null.
      Lifecycle:
      This method can be called at any time.

    • getMode

      @Nonnull public String getMode()
      Inquiry method that can be used to read the mode specified for this MpnSubscription.
      Returns:
      the MpnSubscription mode specified in the constructor.
      Lifecycle:
      This method can be called at any time.

    • getSubscriptionId

      @Nullable public String getSubscriptionId()
      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 instace, copying an MpnSubscription with the copy initializer creates a second MpnSubscription instance with the same subscription ID. Also, the coalescing flag of LightstreamerClient.subscribe(MpnSubscription, boolean) 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.
      Returns:
      the MPN subscription ID.
      Lifecycle:
      This method can be called at any time.