net.rim.pushsdk.subscription
Interface SubscriptionService

batchIncrementConsecutiveFailedPushCount(List<SubscriberPartial> subscribers)Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

void

batchResetConsecutiveFailedPushCount(List<SubscriberPartial> subscribers)Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

getConsecutiveFailedPushCount(SubscriberPartial subscriber)Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

getSizeByIdPattern(String subscriberIdPattern)
Gets a count of all the subscribers in storage whose id contains the given subscriberIdPattern.

int

getSubscribeCount(String pushApplicationId,
Date fromDate,
Date toDate)
Gets a count of the number of new subscribers to an application for a given date range.

int

getSuspendCount(String pushApplicationId,
Date fromDate,
Date toDate)
Gets a count of the number of users that had their subscriptions suspended for an application between the given date range.

int

getUnsubscribeCount(String pushApplicationId,
Date fromDate,
Date toDate)
Gets a count of the number of users that unsubscribed from an application between the given date range.

void

incrementConsecutiveFailedPushCount(String pushApplicationId,
String subscriberId)Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

resetConsecutiveFailedPushCount(String pushApplicationId,
String subscriberId)Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

validateSubscriptions(String pushApplicationId,
List<String> subscriberIds)
Validates the passed in list of subscriber ids to determine which ones do not exist, which ones are active, which ones are
inactive, and which ones are suspended.

Method Detail

subscribe

This method will perform this service's own subscribe logic as well as calling the
ContentProviderSubscriptionServiceonSubscribeSuccess(SubscribeRequest) or
onSubscribeFailure(SubscribeRequest) method depending on success or failure of this service's subscribe.

Parameters:

subscribeRequest - object containing all the information required for a subscribe (if the type field is not set, it will be set
during the subscribe to PUBLIC for Public Push apps and ENTERPRISE for Enterprise Push apps)

This method will perform this service's own unsubscribe logic as well as calling the
ContentProviderSubscriptionServiceonUnsubscribeSuccess(UnsubscribeRequest) or
onUnsubscribeFailure(UnsubscribeRequest) method depending on success or failure of this service's unsubscribe.

Parameters:

unsubscribeRequest - object containing all the information required for an unsubscribe

This method will perform this service's own suspend logic as well as calling the
ContentProviderSubscriptionServiceonSuspendSuccess(SuspendRequest) or
onSuspendFailure(SuspendRequest) method depending on success or failure of this service's suspend.

Parameters:

suspendRequest - object containing all the information required for a suspend

This method will perform this service's own resume logic as well as calling the
ContentProviderSubscriptionServiceonResumeSuccess(ResumeRequest) or
onResumeFailure(ResumeRequest) method depending on success or failure of this service's resume.

Parameters:

resumeRequest - object containing all the information required for a resume

notifyPPG

Notifies the PPG directly with a suspend/resume/unsubscribe request for a given address (e.g. PIN, email address, or
subscriber id for Web Signals).

IMPORTANT: This method should ONLY be used if errors have appeared in the logs indicating that communication with
the PPG failed through the subscription servlets and direct manual communication with the PPG is needed. These errors are
of the form "PPGCommunicationFailureException caught - after retry".

This method can only be called for push applications of type "Public Push", "Web Signal" or "Public+Enterprise Push". For
the "Public+Enterprise Push" type, it is the responsibility of the content provider to only call this method for public
(BIS) subscribers to the push application.

Parameters:

subscriptionType - the subscription operation to be performed on the PPG (subscribe is not supported)

findByIdPattern

Finds a list of subscribers whose id contains the given subscriberIdPattern.

Note: Index arguments are present to address memory concerns, since if we retrieve a full list it might be quite large.
Indexes are inclusive and start at 0.

Note: If the number of subscribers requested (endIndex - startIndex + 1) is above a certain threshold (defined by the
"subscription.find.max.results" property in PushSDK.properties), then the find operation will not be executed
and an IllegalArgumentException will be returned. This is to help ensure that memory concerns are being
addressed.

findByAppId

Note: Index arguments are present to address memory concerns, since if we retrieve a full list it might be quite large.
Indexes are inclusive and start at 0.

Note: If the number of subscribers requested (endIndex - startIndex + 1) is above a certain threshold (defined by the
"subscription.find.max.results" property in PushSDK.properties), then the find operation will not be executed
and an IllegalArgumentException will be returned. This is to help ensure that memory concerns are being
addressed.

findByAppIdAndStatus

Finds a list of subscribers with the specified push application id and status.

Note: Index arguments are present to address memory concerns, since if we retrieve a full list it might be quite large.
Indexes are inclusive and start at 0.

Note: If the number of subscribers requested (endIndex - startIndex + 1) is above a certain threshold (defined by the
"subscription.find.max.results" property in PushSDK.properties), then the find operation will not be executed
and an IllegalArgumentException will be returned. This is to help ensure that memory concerns are being
addressed.

findByAppIdAndIdsAndStatus

Finds a list of subscribers for the given push application id that are in the specified subscriber id list with the
specified status. (e.g. find all active subscribers that match the subscriber ids in the passed in list for the given push
application).

Note that this find method makes use of threads. This is to decrease the processing time when dealing with a large list of
subscriber ids. It makes use of the SubStatusAlternateMatchManager class for subscriber matching.

Parameters:

pushApplicationId - the id of the push application

subscriberIds - only subscribers with one of these ids will be returned

findByAppIdAndType

Finds a list of subscribers with the specified push application id and type.

Note: Index arguments are present to address memory concerns, since if we retrieve a full list it might be quite large.
Indexes are inclusive and start at 0.

Note: If the number of subscribers requested (endIndex - startIndex + 1) is above a certain threshold (defined by the
"subscription.find.max.results" property in PushSDK.properties), then the find operation will not be executed
and an IllegalArgumentException will be returned. This is to help ensure that memory concerns are being
addressed.

findByAppIdAndTypeAndStatus

Finds a list of subscribers with the specified push application id, type, and status.

Note: Index arguments are present to address memory concerns, since if we retrieve a full list it might be quite large.
Indexes are inclusive and start at 0.

Note: If the number of subscribers requested (endIndex - startIndex + 1) is above a certain threshold (defined by the
"subscription.find.max.results" property in PushSDK.properties), then the find operation will not be executed
and an IllegalArgumentException will be returned. This is to help ensure that memory concerns are being
addressed.

validateSubscriptions

Validates the passed in list of subscriber ids to determine which ones do not exist, which ones are active, which ones are
inactive, and which ones are suspended.

There are two subscription validation algorithms. The one that is used depends on the size of the
subscriberIds list that is passed in.

If the size of the subscriberIds list is less than or equal to the "subscription.validation.high.water.mark"
property in PushSDK.properties, each subscriber id from the list will be looked up in storage and put into its
appropriate list in the validation results based on its status or if it cannot be found.

If the size of the subscriberIds list is greater than the "subscription.validation.high.water.mark" property
in PushSDK.properties, a performance enhancing algorithm is used to divide up the subscriber ids into their
appropriate lists in the validation results.

Note: Logging with a level of DEBUG can be turned on to get information back on how long subscription validation is taking,
and which of the subscription validation algorithms was used.

Parameters:

pushApplicationId - the push application id to which the subscriber ids are subscribed to

incrementConsecutiveFailedPushCount

Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

Increments the count of consecutive failed push counts for a subscriber by 1.

resetConsecutiveFailedPushCount

Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

Resets the count of consecutive failed push counts for a subscriber back to 0.

batchIncrementConsecutiveFailedPushCount

Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

Increments in a batch the count of consecutive failed push counts for subscribers by 1.

batchResetConsecutiveFailedPushCount

Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

Resets in a batch the count of consecutive failed push counts for subscribers back to 0.

getConsecutiveFailedPushCount

Deprecated.As of release 1.1, the SDK will no longer keep a count of consecutive failed pushes when result notification is
received from the PPG. If this functionality is desired it should be implemented by push initiator's themselves
by subclassing the FailureNotificationListener from the acknowledgement component. The SDK no longer keeps this
count because the public/BIS PPG will be implementing this logic on the platform side instead. For
enterprise/BES the push initiator must implement the logic if desired.

matchByAppIdAndIdsAndStatus

Returns a list of subscribers for the given push application id that are in the specified subscriber id list with the
specified status. (e.g. find all active subscribers that match the ids in the passed in list for the given push
application).

Note that this method is used directly by the SubStatusAlternateMatchManager class and differs from the
findByAppIdAndIdsAndStatus method. It is not threaded and does not divide up the subscriber ids into several
queries to be made to storage based on the "max.in.clause.values" property in PushSDK.properties.

Parameters:

pushApplicationId - the id of the push application

subscriberIds - only subscribers with one of these ids will be returned

getSubscribeCount

Gets a count of the number of new subscribers to an application for a given date range. Returns 0 if the push application
does not exist or if there were no new subscribers in the specified date range.

The count will be determined based on those individuals that have a subscribe date between the two dates specified.

Note: If a subscriber has subscribed and then chooses to resubscribe at a later time, this count will only reflect the date
at which they resubscribed since the subscribe date in storage will be overwritten with the latest date.

getUnsubscribeCount

Gets a count of the number of users that unsubscribed from an application between the given date range. Returns 0 if the
push application does not exist or if there were no new unsubscribed users in the specified date range.

The count will be determined based on those individuals that have an unsubscribe date between the two dates specified.

Note: If a subscriber has unsubscribed from a push application and then unsubscribes again at a later time, this count will
only reflect the date at which they most recently unsubscribed since the unsubscribe date in storage will be overwritten
with the latest date.

getResumeCount

Gets a count of the number of users that had their subscriptions resumed for an application between the given date range.
Returns 0 if the push application does not exist or if there were no new resumed users in the specified date range.

The count will be determined based on those individuals that have a resume date between the two dates specified.

Note: If a subscriber has resumed their subscription and then resumes again at a later time, this count will only reflect
the date at which they most recently resumed since the resume date in storage will be overwritten with the latest date.

getSuspendCount

Gets a count of the number of users that had their subscriptions suspended for an application between the given date range.
Returns 0 if the push application does not exist or if there were no new suspended users in the specified date range.

The count will be determined based on those individuals that have a suspend date between the two dates specified.

Note: If a subscriber has suspended their subscription and then suspends again at a later time, this count will only
reflect the date at which they most recently suspended since the suspend date in storage will be overwritten with the
latest date.

getDeviceModelCount

Gets a count of the number of users of a push application (regardless of status) for each BlackBerry device model. Returns
an empty list if the push application does not exist or if there are no subscribers for the given application.

getDeviceModelCount

Gets a count of the number of users of a push application with a given status for each BlackBerry device model. Returns an
empty list if the push application does not exist or if there are no subscribers of the given status for the application.

getOsVersionCount

Gets a count of the number of users of a push application (regardless of status) for each OS version running on a
BlackBerry device. Returns an empty list if the push application does not exist or if there are no subscribers for the
given application.

getOsVersionCount

Gets a count of the number of users of a push application with a given status for each OS version running on a BlackBerry
device. Returns an empty list if the push application does not exist or if there are no subscribers of the given status for
the application.

Syncs the status of subscribers in storage with the status on the PPG end.

The reason behind wanting to sync is that it is possible for the statuses of subscribers on the PPG side and on the SDK
side to become out of sync with each other over time.
There are two scenarios:

During a subscription operation (e.g. resume or suspend), the SDK might have unsuccessfully attempted to notify the PPG
of a status change. Therefore, the status on the SDK side would be updated, but the status on the PPG side would not be.

For push applications that have a service level of Push Essentials, there is no support for acknowledgements. The PPG
is able to detect if a user has deleted the application on their device and can no longer receive pushes for that
application. The user would be unsubscribed on the PPG side. Since there is no support for acknowledgements, the SDK side
would have no way of knowing about these users being unsubscribed. A sync would update the status of the subscribers on the
SDK side.

This method is threaded so that multiple sync requests can be sent to the PPG and processed more efficiently. A
SubQueryFailureException or PushSDKException will be thrown if there are issues sending requests
to the PPG or getting responses back from the PPG. Any errors that occur during the updating of the statuses of subscribers
will appear in the returned SubscriberSyncResult object.

The update errors that are returned in the SubscriberSyncResult object can be handled as follows:

The syncing occurs as follows: Note: INACTIVE status has precedence over SUSPENDED status which has precedence over ACTIVE status. The reason for
this precedence during the syncing process is that it is assumed that it is generally safer to not push to a user than push
to a user when you should not be pushing to them.

Important: This method only applies to PPGs that support subscription operations (presently only public (BIS) PPGs).
For push applications of type Public+Enterprise Push, only the public (BIS) subscribers will be attempted to be synced with
the public (BIS) PPG. The enterprise (BES) subscribers will be left untouched.

Parameters:

pushApplicationId - the id of the push application

status - the status of a subscriber in the SDK

startIndex - the start index to sync subscribers from

endIndex - the end index to stop syncing subscribers at

syncedBy - an identifier that identifies the caller of this API. The syncedBy value will be placed into the log files at
info level for audit purposes

syncSubscribersByStatusInPPG

Syncs the status of subscribers in storage by looking up subscribers on the PPG end that have the given status and updates
the corresponding subscribers on the SDK side.

WARNING: As of 1.1, the public (BIS) PPG will start limiting the number of results it returns when querying the PPG
with an ACTIVE or SUSPENDED status for statusInPPG. If the push application corresponding to
pushApplicationId has a large number of ACTIVE subscribers, then you might get a "22006" error back from the
public (BIS) PPG when passing a value of ACTIVE for statusInPPG. The same goes for the SUSPENDED case. If a
"22006" error is encountered, please use
syncSubscribersWithPPGForStatus(String, SubscriberStatus, int, int, String) for syncing instead.

The reason behind wanting to sync is that it is possible for the statuses of subscribers on the PPG side and on the SDK
side to become out of sync with each other over time.
There are two scenarios:

During a subscription operation (e.g. resume or suspend), the SDK might have unsuccessfully attempted to notify the PPG
of a status change. Therefore, the status on the SDK side would be updated, but the status on the PPG side would not be.

For push applications that have a service level of Push Essentials, there is no support for acknowledgements. The PPG
is able to detect if a user has deleted the application on their device and can no longer receive pushes for that
application. The user would be unsubscribed on the PPG side. Since there is no support for acknowledgements, the SDK side
would have no way of knowing about these users being unsubscribed. A sync would update the status of the subscribers on the
SDK side.

This method is threaded so that the results back from the sync request can be processed more efficiently. Any errors that
occur during the updating of the statuses of subscribers will appear in the returned SubscriberSyncResult
object.

The update errors that are returned in the SubscriberSyncResult object can be handled as follows:

Syncs the status of subscribers in storage with the status on the PPG end.

The reason behind wanting to sync is that it is possible for the statuses of subscribers on the PPG side and on the SDK
side to become out of sync with each other over time.
There are two scenarios:

During a subscription operation (e.g. resume or suspend), the SDK might have unsuccessfully attempted to notify the PPG
of a status change. Therefore, the status on the SDK side would be updated, but the status on the PPG side would not be.

For push applications that have a service level of Push Essentials, there is no support for acknowledgements. The PPG
is able to detect if a user has deleted the application on their device and can no longer receive pushes for that
application. The user would be unsubscribed on the PPG side. Since there is no support for acknowledgements, the SDK side
would have no way of knowing about these users being unsubscribed. A sync would update the status of the subscribers on the
SDK side.

This method is threaded so that multiple sync requests can be sent to the PPG and processed more efficiently. A
SubQueryFailureException or PushSDKException will be thrown if there are issues sending requests
to the PPG or getting responses back from the PPG. Any errors that occur during the updating of the statuses of subscribers
will appear in the returned SubscriberSyncResult object.

The update errors that are returned in the SubscriberSyncResult object can be handled as follows:

For each SDK error, call the unsubscribe or suspendSubscription method based on the
subscription type of the failure.

For each PPG error, call the notifyPPG method.

The syncing occurs as follows: Note: INACTIVE status has precedence over SUSPENDED status which has precedence over ACTIVE status. The reason for
this precedence during the syncing process is that it is assumed that it is generally safer to not push to a user than push
to a user when you should not be pushing to them.

Status in SDK: SUSPENDED, Status in PPG: ACTIVE; Action: Call the notifyPPG method to suspend on the PPG
end.

Status in SDK: INACTIVE, Status in PPG: SUSPENDED; Action: Call the notifyPPG method to unsubscribe on the
PPG end.

Status in SDK: INACTIVE, Status in PPG: INACTIVE; Action: None.

Status in SDK: INACTIVE, Status in PPG: ACTIVE; Action: Call the notifyPPG method to unsubscribe on the
PPG end.

Important: This method only applies to PPGs that support subscription operations (presently only public (BIS) PPGs).
For push applications of type Public+Enterprise Push, only the public (BIS) subscribers will be attempted to be synced with
the public (BIS) PPG. The enterprise (BES) subscribers will be left untouched.

Parameters:

pushApplicationId - the id of the push application

syncedBy - an identifier that identifies the caller of this API. The syncedBy value will be placed into the log files at
info level for audit purposes

Syncs the status of subscribers in storage with the status on the PPG end.

The reason behind wanting to sync is that it is possible for the statuses of subscribers on the PPG side and on the SDK
side to become out of sync with each other over time.
There are two scenarios:

During a subscription operation (e.g. resume or suspend), the SDK might have unsuccessfully attempted to notify the PPG
of a status change. Therefore, the status on the SDK side would be updated, but the status on the PPG side would not be.

For push applications that have a service level of Push Essentials, there is no support for acknowledgements. The PPG
is able to detect if a user has deleted the application on their device and can no longer receive pushes for that
application. The user would be unsubscribed on the PPG side. Since there is no support for acknowledgements, the SDK side
would have no way of knowing about these users being unsubscribed. A sync would update the status of the subscribers on the
SDK side.

This method is threaded so that multiple sync requests can be sent to the PPG and processed more efficiently. A
SubQueryFailureException or PushSDKException will be thrown if there are issues sending requests
to the PPG or getting responses back from the PPG. Any errors that occur during the updating of the statuses of subscribers
will appear in the returned SubscriberSyncResult object.

The update errors that are returned in the SubscriberSyncResult object can be handled as follows:

For each SDK error, call the unsubscribe or suspendSubscription method based on the
subscription type of the failure.

For each PPG error, call the notifyPPG method.

See the syncSubscribersWithPPG(pushApplicationId, syncedBy) method for a description of the syncing rules.

Note: This method will only look at subscribers in the SDK of a given status. A full sync is recommended for normal use.
This method is more for when errors occur during the syncing process for subscribers of a certain status and a partial
resync is needed. For a full sync, see the syncSubscribersWithPPG(pushApplicationId, syncedBy) method.

Parameters:

pushApplicationId - the id of the push application

status - the status of a subscriber in the SDK

syncedBy - an identifier that identifies the caller of this API. The syncedBy value will be placed into the log files at
info level for audit purposes