com.lightstreamer.ls_client.mpn

Interface MpnSubscription

public interface MpnSubscription

The MpnSubscription class wraps the key (as an MpnKey object) and the specifications (as an MpnInfo object) of a mobile push notifications (MPN) subscription. It represents a view on the actual MPN subscription stored on the Server's database. The MpnSubscription class supports operations like checking its current status, modifying the specifications and deactivating the MPN subscription.
MPN subscriptions are cached locally and the cache is stored in the LSClient instance that originated (i.e. activated or inquired) the MPN subscription. Thus, once an MpnSubscription object, with a certain MPN key, has been obtained from an LSClient instance, any operation returning the same MPN subscription from the same LSClient instance will return the same MpnSubscription instance. On the other hand, deactivating an MPN subscription removes it from the local cache and marks its corresponding MpnSubscription instance as deactivated (see isDeactivated()).
Moreover, the LSClient local cache survives a reconnection: if the LSClient reconnects with the same base parameters (i.e. ConnectionInfo.pushServerUrl, ConnectionInfo.adapter and ConnectionInfo.user), the MPN subscription cache is preserved. If one of these parameters changes, the cache is cleared and any dangling MpnSubscription instance is made invalid (no more operations will be possible on it).
MpnSubscription instances keep a reference to their originating LSClient, see getClient(). In order for any operation to be successful, the originating LSClient must be connected at the moment the operation is executed.
Note that, while the MpnKey instance is constant, the MpnInfo instance may be replaced by calls that modify the MPN subscription's specifications, e.g. modify(com.lightstreamer.ls_client.mpn.MpnInfo), or LSClient.activateMpn(com.lightstreamer.ls_client.mpn.MpnInfo, boolean) with coalescing flag set, or by calls that update the local cache from the Server, e.g. LSClient.inquireMpn(MpnKey), LSClient.inquireMpn(MpnSubscriptionStatus) and LSClient.inquireAllMpn().
Since MPN subscriptions are stored on the Server on a per-device and per-app basis, under normal conditions only the device/app pair that created an MPN subscription may be accessing or modifying it or its cached MpnSubscription representation.

Method Summary

Modifier and Type	Method and Description
MpnStatusInfo	checkStatus() Inquires the status of the MPN subscription on the Server.
void	deactivate() Deactivates the MPN subscription.
LSClient	getClient() The LSClient instance to that originated (i.e.
MpnInfo	getMpnInfo() The specifications of this MPN subscription.
MpnKey	getMpnKey() The MPN key identifying this MPN subscription.
boolean	isDeactivated() Tells if this MPN subscription has been deactivated or not.
void	modify(MpnInfo mpnInfo) Modifies the specifications of the MPN subscription.

Method Detail

getClient

LSClient getClient()

The LSClient instance to that originated (i.e. activated or inquired) this MpnSubscription instance.

Returns:

The LSClient instance.

getMpnKey

MpnKey getMpnKey()

The MPN key identifying this MPN subscription.

Returns:

The MPN subscription's key.

getMpnInfo

MpnInfo getMpnInfo()

The specifications of this MPN subscription. The returned object is a copy of the original MpnInfo object.
The stored object may be replaced over time by calls that modify the MPN subscription's specifications, e.g. modify(com.lightstreamer.ls_client.mpn.MpnInfo), or LSClient.activateMpn(com.lightstreamer.ls_client.mpn.MpnInfo, boolean) with coalescing flag set, or by calls that update the local cache from the Server, e.g. LSClient.inquireMpn(MpnKey), LSClient.inquireMpn(MpnSubscriptionStatus) and LSClient.inquireAllMpn().
See the MpnSubscription description for more information.

Returns:

a copy of the MPN subscription's specifications.

isDeactivated

boolean isDeactivated()

Tells if this MPN subscription has been deactivated or not. May be changed by deactivation calls, e.g. deactivate(), or LSClient.deactivateMpn(com.lightstreamer.ls_client.mpn.MpnSubscriptionStatus) and LSClient.deactivateAllMpn(), or by calls that update the local cache from the Server, e.g. LSClient.inquireMpn(com.lightstreamer.ls_client.mpn.MpnKey) and LSClient.inquireAllMpn().
See the MpnSubscription description for more information.

Returns:

true if the MPN subscription has been deactivated.

checkStatus

MpnStatusInfo checkStatus()
                   throws SubscrException,
                          PushServerException,
                          PushUserException,
                          PushConnException

Inquires the status of the MPN subscription on the Server.
If the MPN subscription has been forcibly deactivated on the Server, the call will result in a PushUserException with error code 46 (subscription unknown) or 45 (device unknown, if no more subscriptions exist for this device and application).
Note that the status of an MPN subscription is never cached.
The method is blocking: it will return only after receiving the Server response; in case a batch is open, this will happen only upon the execution of the batch. See LSClient.openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener) for details on timeout settings.

Returns:

The MPN subscription status info, i.e. whether it is active, triggered or suspended, and the time when the status has been set.

Throws:

SubscrException - Thrown if the connection is closed, or if the MPN subscription is known to be deactivated.

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in Server response. In normal conditions, this exception should never happen.

PushUserException - Thrown in case the operation has been refused by the Lightstreamer Server.

modify

void modify(MpnInfo mpnInfo)
     throws SubscrException,
            PushServerException,
            PushUserException,
            PushConnException

Modifies the specifications of the MPN subscription. Once the change has been submitted to the server, the mpnInfo field is updated with the passed mpnInfo instance, whereas the MPN key remains unchanged.
If the MPN subscription has been forcibly deactivated on the Server, the call will result in a PushUserException with error code 46 (subscription unknown) or 45 (device unknown, if no more subscriptions exist for this device and application).
The operation works only on the current MPN subscription (i.e. the MPN subscription identified by the MPN key). No coalescence is possible with this operation: even if the new specifications had the same adapter set, data adapter, group, schema and trigger expression of another MPN subscription, this MPN subscription would remain distinct. See LSClient.activateMpn(com.lightstreamer.ls_client.mpn.MpnInfo, boolean) for more information on coalescence.
The same limitations that apply during activation (see LSClient.activateMpn(com.lightstreamer.ls_client.mpn.MpnInfo, boolean)) apply during modification. Additionally, moving MPN subscriptions from an adapter set to another is not allowed. This means the adapterSet field of SimpleTableInfo must be the same of the original MPN subscription AND the same of the current connection. If this field is nil, the adapter set of the current connection is considered as specified.
Note that MPN subscriptions are cached locally, see MpnSubscription description for more information. This method always contacts the Server and updates the related MPN subscription in the local cache.
The method is blocking: it will return only after receiving the Server response; in case a batch is open, this will happen only upon the execution of the batch. See LSClient.openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener) for details on timeout settings.

Parameters:

mpnInfo - Contains the new table and format specifications of the mobile push notifications. A copy of the object is stored internally.

Throws:

SubscrException - Thrown if the connection is closed, or if the MPN subscription is known to be deactivated.

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in Server response. In normal conditions, this exception should never happen.

PushUserException - Thrown in case the operation has been refused by the Lightstreamer Server.

deactivate

void deactivate()
         throws SubscrException,
                PushServerException,
                PushUserException,
                PushConnException

Deactivates the MPN subscription. Once deactivated, no more mobile push notifications (i.e. cloud messages) will be sent on table update. A deactivation has also the effect of deleting the MPN subscription.
If the MPN subscription has been forcibly deactivated on the Server, the call will result in a PushUserException with error code 46 (subscription unknown) or 45 (device unknown, if no more subscriptions exist for this device and application).
Note that MPN subscriptions are cached locally, see MpnSubscription description for more information. This method always contacts the Server and updates the related MPN subscription in the local cache.
The method is blocking: it will return only after receiving the Server response; in case a batch is open, this will happen only upon the execution of the batch. See LSClient.openConnection(com.lightstreamer.ls_client.ConnectionInfo, com.lightstreamer.ls_client.ConnectionListener) for details on timeout settings.

Throws:

SubscrException - Thrown if the connection is closed, or if the MPN subscription is known to be deactivated.

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in Server response. In normal conditions, this exception should never happen.

PushUserException - Thrown in case the operation has been refused by the Lightstreamer Server.