net.rim.pushsdk.subscription
Class SubscriptionServiceImpl

java.lang.Object
  extended by net.rim.pushsdk.subscription.SubscriptionServiceImpl
All Implemented Interfaces:
SubscriptionService

public abstract class SubscriptionServiceImpl
extends Object
implements SubscriptionService

Implementation of the SubscriptionService interface.

Dependencies that must be injected to properly initialize this object for use:
- pushApplicationService
- subscriptionDAO
- httpClient
- pushSDKProperties
- contentProviderSubscriptionService
- subscriptionQueryService

Author:
mdandrea

Field Summary
protected  PushApplicationService pushAppService
          The instance of PushApplicationService to use.
protected  PushSDKProperties pushSDKProperties
          The instance of PushSDKProperties to use.
 
Constructor Summary
SubscriptionServiceImpl()
           
 
Method Summary
 void batchIncrementConsecutiveFailedPushCount(List<SubscriberPartial> subscribers)
          Deprecated. 
 void batchResetConsecutiveFailedPushCount(List<SubscriberPartial> subscribers)
          Deprecated. 
protected abstract  SubActiveMatchManager createSubActiveMatchManager()
          Create a new instance of a SubActiveMatchManager for use by subscription validation.
protected abstract  SubStatusAlternateMatchManager createSubStatusAlternateMatchManager()
          Create a new instance of a SubStatusAlternateMatchManager for use by the findByAppIdAndIdsAndStatus method.
protected abstract  SubStatusMatchManager createSubStatusMatchManager()
          Create a new instance of a SubStatusMatchManager for use by subscription validation.
protected abstract  SubSyncByAddressDAO createSubSyncByAddressDAO()
          Create a new instance of a SubSyncByAddressDAO for use by the sync methods.
protected abstract  SubSyncByAddressManager createSubSyncByAddressManager()
          Create a new instance of a SubSyncByAddressManager for use by the sync methods.
protected abstract  SubSyncByStatusManager createSubSyncByStatusManager()
          Create a new instance of a SubSyncByStatusManager for use by the sync methods.
 void deleteInactiveSubscription(String pushApplicationId, String subscriberId, String deletedBy)
          Deletes an inactive subscription from storage.
 void deleteSubscriptions(String pushApplicationId, String deletedBy)
          Warning!
Deletes all the subscriptions from storage (and potentially the cache) for a push application entirely and permanently.
 List<SubscriberPartial> findByAddressAndIdAndNotStatus(String address, String subscriberId, SubscriberStatus status)
          Finds a list of subscribers with the specified address and the specified subscriber id and NOT the specified status.
 List<SubscriberPartial> findByAddressAndNotIdAndNotStatus(String address, String subscriberId, SubscriberStatus status)
          Finds a list of subscribers with the specified address and NOT the specified subscriber id and NOT the specified status.
 List<SubscriberPartial> findByAppId(String pushApplicationId, int startIndex, int endIndex)
          Finds a list of subscribers with the specified push application id.
 List<SubscriberPartial> findByAppIdAndAddress(String pushApplicationId, String address)
          Finds a list of subscribers with the specified push application id and address.
 Subscriber findByAppIdAndId(String pushApplicationId, String subscriberId)
          Finds the subscriber with the specified id and push application id.
 List<SubscriberPartial> findByAppIdAndIdsAndStatus(String pushApplicationId, List<String> subscriberIds, SubscriberStatus status)
          Finds a list of subscribers for the given push application id that are in the specified subscriber id list with the specified status.
 List<SubscriberPartial> findByAppIdAndStatus(String pushApplicationId, SubscriberStatus status, int startIndex, int endIndex)
          Finds a list of subscribers with the specified push application id and status.
 List<SubscriberPartial> findByAppIdAndType(String pushApplicationId, SubscriberType type, int startIndex, int endIndex)
          Finds a list of subscribers with the specified push application id and type.
 List<SubscriberPartial> findByAppIdAndTypeAndStatus(String pushApplicationId, SubscriberType type, SubscriberStatus status, int startIndex, int endIndex)
          Finds a list of subscribers with the specified push application id, type, and status.
 List<SubscriberPartial> findById(String subscriberId)
          Finds a list of subscribers with the specified id.
 List<SubscriberPartial> findByIdAndNotStatus(String subscriberId, SubscriberStatus status)
          Finds a list of subscribers with the specified id and NOT the specified status.
 List<SubscriberPartial> findByIdAndStatus(String subscriberId, SubscriberStatus status)
          Finds a list of subscribers with the specified id and status.
 List<SubscriberPartial> findByIdPattern(String subscriberIdPattern, int startIndex, int endIndex)
          Finds a list of subscribers whose id contains the given subscriberIdPattern.
 int getConsecutiveFailedPushCount(SubscriberPartial subscriber)
          Deprecated. 
 List<DeviceModelCount> getDeviceModelCount(String pushApplicationId)
          Gets a count of the number of users of a push application (regardless of status) for each BlackBerry device model.
 List<DeviceModelCount> getDeviceModelCount(String pushApplicationId, SubscriberStatus status)
          Gets a count of the number of users of a push application with a given status for each BlackBerry device model.
 List<OsVersionCount> getOsVersionCount(String pushApplicationId)
          Gets a count of the number of users of a push application (regardless of status) for each OS version running on a BlackBerry device.
 List<OsVersionCount> getOsVersionCount(String pushApplicationId, SubscriberStatus status)
          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.
 int getResumeCount(String pushApplicationId, Date fromDate, Date toDate)
          Gets a count of the number of users that had their subscriptions resumed for an application between the given date range.
 int getSizeByAppId(String pushApplicationId)
          Gets a count of all the subscribers in storage with the specified push application id.
 int getSizeByAppIdAndStatus(String pushApplicationId, SubscriberStatus status)
          Gets a count of all the subscribers in storage with the specified push application id and status.
 int getSizeByAppIdAndType(String pushApplicationId, SubscriberType type)
          Gets a count of all the subscribers in storage with the specified push application id and type.
 int getSizeByAppIdAndTypeAndStatus(String pushApplicationId, SubscriberType type, SubscriberStatus status)
          Gets a count of all the subscribers in storage with the specified push application id, type, and status.
 int 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. 
 List<SubscriberPartial> matchByAppIdAndIdsAndStatus(String pushApplicationId, List<String> subscriberIds, SubscriberStatus status)
          Returns a list of subscribers for the given push application id that are in the specified subscriber id list with the specified status.
 void notifyPPG(SubscriptionType subscriptionType, String pushApplicationId, String address)
          Notifies the PPG directly with a suspend/resume/unsubscribe request for a given address (e.g.
 void resetConsecutiveFailedPushCount(String pushApplicationId, String subscriberId)
          Deprecated. 
 void resumeSubscription(ResumeRequest resumeRequest)
          Resumes a user's subscription to a push application.
 void setContentProviderSubscriptionService(ContentProviderSubscriptionService contentProviderSubscriptionService)
          Support for dependency injection.
 void setHttpClient(HttpClient httpClient)
          Support for dependency injection.
 void setPushApplicationService(PushApplicationService pushApplicationService)
          Support for dependency injection.
 void setPushSDKProperties(PushSDKProperties pushSDKProperties)
          Support for dependency injection.
 void setSubscriptionDAO(SubscriptionDAO subscriptionDAO)
          Support for dependency injection.
 void setSubscriptionQueryService(SubscriptionQueryService subscriptionQueryService)
          Support for dependency injection.
 void subscribe(SubscribeRequest subRequest)
          Subscribes a user to a push application.
 void suspendSubscription(SuspendRequest suspRequest)
          Suspends a user's subscription to a push application.
 SubscriberSyncResult syncSubscribersByStatusInPPG(String pushApplicationId, SubscriberStatus statusInPPG, String syncedBy)
          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.
 SubscriberSyncResult syncSubscribersWithPPG(String pushApplicationId, String syncedBy)
          Deprecated. 
 SubscriberSyncResult syncSubscribersWithPPGByStatus(String pushApplicationId, SubscriberStatus status, String syncedBy)
          Deprecated. 
 SubscriberSyncResult syncSubscribersWithPPGForStatus(String pushApplicationId, SubscriberStatus status, int startIndex, int endIndex, String syncedBy)
          Syncs the status of subscribers in storage with the status on the PPG end.
 Subscriber syncSubscriberWithPPG(String pushApplicationId, String subscriberId, String syncedBy)
          Syncs the status of a single subscriber in storage with its status on the PPG end.
 void unsubscribe(UnsubscribeRequest unsubRequest)
          Unsubscribes a user from a push application.
protected  void validateSubscribeFields(SubscribeRequest subRequest)
          Validates the fields present in the passed in subscribe request.
protected  Subscriber validateSubscriberExists(String pushApplicationId, String subscriberId)
          Verifies that the subscriber exists for the given push application id and subscriber id.
protected  void validateSubscriberUniqueKey(String pushApplicationId, String subscriberId)
          Validates the push application id and subscriber id passed in (i.e.
 SubscriptionValidationResult 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

pushAppService

protected PushApplicationService pushAppService
The instance of PushApplicationService to use.


pushSDKProperties

protected PushSDKProperties pushSDKProperties
The instance of PushSDKProperties to use.

Constructor Detail

SubscriptionServiceImpl

public SubscriptionServiceImpl()
Method Detail

setSubscriptionDAO

public void setSubscriptionDAO(SubscriptionDAO subscriptionDAO)
Description copied from interface: SubscriptionService
Support for dependency injection. Sets the Subscription Data Access Object to be used by this service.

Specified by:
setSubscriptionDAO in interface SubscriptionService
Parameters:
subscriptionDAO - a Subscriber Data Access Object

setPushApplicationService

public void setPushApplicationService(PushApplicationService pushApplicationService)
Description copied from interface: SubscriptionService
Support for dependency injection. Sets the Push Application Service to be used by this service.

Specified by:
setPushApplicationService in interface SubscriptionService
Parameters:
pushApplicationService - a Push Application Service Object

setHttpClient

public void setHttpClient(HttpClient httpClient)
Description copied from interface: SubscriptionService
Support for dependency injection. This will override the default HttpClient implementation.

Specified by:
setHttpClient in interface SubscriptionService

setPushSDKProperties

public void setPushSDKProperties(PushSDKProperties pushSDKProperties)
Description copied from interface: SubscriptionService
Support for dependency injection. This will override the default PushSDKProperties implementation.

Specified by:
setPushSDKProperties in interface SubscriptionService

setContentProviderSubscriptionService

public void setContentProviderSubscriptionService(ContentProviderSubscriptionService contentProviderSubscriptionService)
Description copied from interface: SubscriptionService
Support for dependency injection. Sets the Content Provider Subscription Service to be used by this service.

Specified by:
setContentProviderSubscriptionService in interface SubscriptionService
Parameters:
contentProviderSubscriptionService - a Content Provider Subscription Service Object

setSubscriptionQueryService

public void setSubscriptionQueryService(SubscriptionQueryService subscriptionQueryService)
Description copied from interface: SubscriptionService
Support for dependency injection. Sets the Subscription Query Service to be used by this service.

Specified by:
setSubscriptionQueryService in interface SubscriptionService
Parameters:
subscriptionQueryService - a Subscription Query Service Object

subscribe

public void subscribe(SubscribeRequest subRequest)
               throws InvalidPushAppException,
                      CPSubscriptionFailureException,
                      PushSDKException
Description copied from interface: SubscriptionService
Subscribes a user to a push application.

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

Specified by:
subscribe in interface SubscriptionService
Parameters:
subRequest - 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)
Throws:
InvalidPushAppException - if the push application specified is invalid
CPSubscriptionFailureException - if there were issues performing the content provider's subscribe operation
PushSDKException - if any unrecoverable errors occur
See Also:
ContentProviderSubscriptionService

unsubscribe

public void unsubscribe(UnsubscribeRequest unsubRequest)
                 throws SubDoesNotExistException,
                        InvalidPushAppException,
                        CPSubscriptionFailureException,
                        PushSDKException
Description copied from interface: SubscriptionService
Unsubscribes a user from a push application.

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

Specified by:
unsubscribe in interface SubscriptionService
Parameters:
unsubRequest - object containing all the information required for an unsubscribe
Throws:
SubDoesNotExistException - if the subscriber specified cannot be found
InvalidPushAppException - if the push application specified is invalid
CPSubscriptionFailureException - if there were issues performing the content provider's unsubscribe operation
PushSDKException - if any unrecoverable errors occur
See Also:
ContentProviderSubscriptionService

suspendSubscription

public void suspendSubscription(SuspendRequest suspRequest)
                         throws SubDoesNotExistException,
                                InvalidSubStatusException,
                                InvalidPushAppException,
                                CPSubscriptionFailureException,
                                PushSDKException
Description copied from interface: SubscriptionService
Suspends a user's subscription to a push application.

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

Specified by:
suspendSubscription in interface SubscriptionService
Parameters:
suspRequest - object containing all the information required for a suspend
Throws:
SubDoesNotExistException - if the subscriber specified cannot be found
InvalidSubStatusException - if the current status of the subscriber does not allow for this operation
InvalidPushAppException - if the push application specified is invalid
CPSubscriptionFailureException - if there were issues performing the content provider's suspend operation
PushSDKException - if any unrecoverable errors occur
See Also:
ContentProviderSubscriptionService

resumeSubscription

public void resumeSubscription(ResumeRequest resumeRequest)
                        throws SubDoesNotExistException,
                               InvalidSubStatusException,
                               InvalidPushAppException,
                               CPSubscriptionFailureException,
                               PushSDKException
Description copied from interface: SubscriptionService
Resumes a user's subscription to a push application.

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

Specified by:
resumeSubscription in interface SubscriptionService
Parameters:
resumeRequest - object containing all the information required for a resume
Throws:
SubDoesNotExistException - if the subscriber specified cannot be found
InvalidSubStatusException - if the current status of the subscriber does not allow for this operation
InvalidPushAppException - if the push application specified is invalid
CPSubscriptionFailureException - if there were issues performing the content provider's resume operation
PushSDKException - if any unrecoverable errors occur
See Also:
ContentProviderSubscriptionService

deleteInactiveSubscription

public void deleteInactiveSubscription(String pushApplicationId,
                                       String subscriberId,
                                       String deletedBy)
                                throws SubDoesNotExistException,
                                       InvalidSubStatusException,
                                       InvalidPushAppException,
                                       PushSDKException
Description copied from interface: SubscriptionService
Deletes an inactive subscription from storage.

Specified by:
deleteInactiveSubscription in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
subscriberId - the id of the subscriber
deletedBy - the id of the user deleting the inactive subscription; used for logging purposes only
Throws:
SubDoesNotExistException - if the subscriber specified cannot be found
InvalidSubStatusException - if the subscriber being deleted is not inactive
InvalidPushAppException - if the push application specified is invalid
PushSDKException - if any unrecoverable errors occur

deleteSubscriptions

public void deleteSubscriptions(String pushApplicationId,
                                String deletedBy)
                         throws InvalidPushAppException,
                                PushSDKException
Description copied from interface: SubscriptionService
Warning!
Deletes all the subscriptions from storage (and potentially the cache) for a push application entirely and permanently.

Note: This method should be used with caution as it will remove ALL subscriptions regardless of their status.

Specified by:
deleteSubscriptions in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
deletedBy - the id of the user deleting the inactive subscription; used for logging purposes only
Throws:
InvalidPushAppException - if the push application specified is invalid
PushSDKException - if any unrecoverable errors occur

findByAppIdAndId

public Subscriber findByAppIdAndId(String pushApplicationId,
                                   String subscriberId)
                            throws PushSDKException
Description copied from interface: SubscriptionService
Finds the subscriber with the specified id and push application id.

Specified by:
findByAppIdAndId in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
subscriberId - the id of the subscriber
Returns:
the subscriber, if found; otherwise, null
Throws:
PushSDKException - if any unrecoverable errors occur

findByAppIdAndAddress

public List<SubscriberPartial> findByAppIdAndAddress(String pushApplicationId,
                                                     String address)
                                              throws PushSDKException
Description copied from interface: SubscriptionService
Finds a list of subscribers with the specified push application id and address.

Specified by:
findByAppIdAndAddress in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
address - the address of the subscriber (case insensitive)
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur

findByAddressAndNotIdAndNotStatus

public List<SubscriberPartial> findByAddressAndNotIdAndNotStatus(String address,
                                                                 String subscriberId,
                                                                 SubscriberStatus status)
                                                          throws PushSDKException
Description copied from interface: SubscriptionService
Finds a list of subscribers with the specified address and NOT the specified subscriber id and NOT the specified status.

Specified by:
findByAddressAndNotIdAndNotStatus in interface SubscriptionService
Parameters:
address - the address of the subscriber (case insensitive)
subscriberId - the id of the subscriber
status - a subscriber status
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

findByAddressAndIdAndNotStatus

public List<SubscriberPartial> findByAddressAndIdAndNotStatus(String address,
                                                              String subscriberId,
                                                              SubscriberStatus status)
                                                       throws PushSDKException
Description copied from interface: SubscriptionService
Finds a list of subscribers with the specified address and the specified subscriber id and NOT the specified status.

Specified by:
findByAddressAndIdAndNotStatus in interface SubscriptionService
Parameters:
address - the address of the subscriber (case insensitive)
subscriberId - the id of the subscriber
status - a subscriber status
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

findById

public List<SubscriberPartial> findById(String subscriberId)
                                 throws PushSDKException
Description copied from interface: SubscriptionService
Finds a list of subscribers with the specified id.

Specified by:
findById in interface SubscriptionService
Parameters:
subscriberId - the id of the subscriber
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur

findByIdAndStatus

public List<SubscriberPartial> findByIdAndStatus(String subscriberId,
                                                 SubscriberStatus status)
                                          throws PushSDKException
Description copied from interface: SubscriptionService
Finds a list of subscribers with the specified id and status.

Specified by:
findByIdAndStatus in interface SubscriptionService
Parameters:
subscriberId - the id of the subscriber
status - a subscriber status
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

findByIdAndNotStatus

public List<SubscriberPartial> findByIdAndNotStatus(String subscriberId,
                                                    SubscriberStatus status)
                                             throws PushSDKException
Description copied from interface: SubscriptionService
Finds a list of subscribers with the specified id and NOT the specified status.

Specified by:
findByIdAndNotStatus in interface SubscriptionService
Parameters:
subscriberId - the id of the subscriber
status - a subscriber status
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

findByAppId

public List<SubscriberPartial> findByAppId(String pushApplicationId,
                                           int startIndex,
                                           int endIndex)
                                    throws PushSDKException
Description copied from interface: SubscriptionService
Finds a list of subscribers with the specified push application id.

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.

Specified by:
findByAppId in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
startIndex - the index of the first entry to be retrieved
endIndex - the index of the last entry to be retrieved
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur

findByAppIdAndStatus

public List<SubscriberPartial> findByAppIdAndStatus(String pushApplicationId,
                                                    SubscriberStatus status,
                                                    int startIndex,
                                                    int endIndex)
                                             throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
findByAppIdAndStatus in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
status - a subscriber status
startIndex - the index of the first entry to be retrieved
endIndex - the index of the last entry to be retrieved
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

findByAppIdAndType

public List<SubscriberPartial> findByAppIdAndType(String pushApplicationId,
                                                  SubscriberType type,
                                                  int startIndex,
                                                  int endIndex)
                                           throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
findByAppIdAndType in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
type - the type of a subscriber
startIndex - the index of the first entry to be retrieved
endIndex - the index of the last entry to be retrieved
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberType

findByAppIdAndTypeAndStatus

public List<SubscriberPartial> findByAppIdAndTypeAndStatus(String pushApplicationId,
                                                           SubscriberType type,
                                                           SubscriberStatus status,
                                                           int startIndex,
                                                           int endIndex)
                                                    throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
findByAppIdAndTypeAndStatus in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
type - the type of a subscriber
status - the status of a subscriber
startIndex - the index of the first entry to be retrieved
endIndex - the index of the last entry to be retrieved
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberType, SubscriberStatus

getSizeByAppId

public int getSizeByAppId(String pushApplicationId)
                   throws PushSDKException
Description copied from interface: SubscriptionService
Gets a count of all the subscribers in storage with the specified push application id.

Specified by:
getSizeByAppId in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
Returns:
a count of subscribers
Throws:
PushSDKException - if any unrecoverable errors occur

getSizeByAppIdAndStatus

public int getSizeByAppIdAndStatus(String pushApplicationId,
                                   SubscriberStatus status)
                            throws PushSDKException
Description copied from interface: SubscriptionService
Gets a count of all the subscribers in storage with the specified push application id and status.

Specified by:
getSizeByAppIdAndStatus in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
status - a subscriber status
Returns:
a count of subscribers
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

getSizeByAppIdAndType

public int getSizeByAppIdAndType(String pushApplicationId,
                                 SubscriberType type)
                          throws PushSDKException
Description copied from interface: SubscriptionService
Gets a count of all the subscribers in storage with the specified push application id and type.

Specified by:
getSizeByAppIdAndType in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
type - the type of a subscriber
Returns:
a count of subscribers
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberType

getSizeByAppIdAndTypeAndStatus

public int getSizeByAppIdAndTypeAndStatus(String pushApplicationId,
                                          SubscriberType type,
                                          SubscriberStatus status)
                                   throws PushSDKException
Description copied from interface: SubscriptionService
Gets a count of all the subscribers in storage with the specified push application id, type, and status.

Specified by:
getSizeByAppIdAndTypeAndStatus in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
type - the type of a subscriber
status - the staotus of a subscriber
Returns:
a count of subscribers
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberType, SubscriberStatus

findByAppIdAndIdsAndStatus

public List<SubscriberPartial> findByAppIdAndIdsAndStatus(String pushApplicationId,
                                                          List<String> subscriberIds,
                                                          SubscriberStatus status)
                                                   throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
findByAppIdAndIdsAndStatus in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
subscriberIds - only subscribers with one of these ids will be returned
status - only subscribers that match this status will be returned
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

matchByAppIdAndIdsAndStatus

public List<SubscriberPartial> matchByAppIdAndIdsAndStatus(String pushApplicationId,
                                                           List<String> subscriberIds,
                                                           SubscriberStatus status)
                                                    throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
matchByAppIdAndIdsAndStatus in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
subscriberIds - only subscribers with one of these ids will be returned
status - only subscribers that match this status will be returned
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

validateSubscriptions

public SubscriptionValidationResult validateSubscriptions(String pushApplicationId,
                                                          List<String> subscriberIds)
                                                   throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
validateSubscriptions in interface SubscriptionService
Parameters:
pushApplicationId - the push application id to which the subscriber ids are subscribed to
subscriberIds - list of subscriber ids to validate
Returns:
the result of the validation
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriptionValidationResult

incrementConsecutiveFailedPushCount

@Deprecated
public void incrementConsecutiveFailedPushCount(String pushApplicationId,
                                                           String subscriberId)
                                         throws PushSDKException
Deprecated. 

Description copied from interface: SubscriptionService
Increments the count of consecutive failed push counts for a subscriber by 1.

Specified by:
incrementConsecutiveFailedPushCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
subscriberId - the id of the subscriber
Throws:
PushSDKException - if any unrecoverable errors occur

resetConsecutiveFailedPushCount

@Deprecated
public void resetConsecutiveFailedPushCount(String pushApplicationId,
                                                       String subscriberId)
                                     throws PushSDKException
Deprecated. 

Description copied from interface: SubscriptionService
Resets the count of consecutive failed push counts for a subscriber back to 0.

Specified by:
resetConsecutiveFailedPushCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
subscriberId - the id of the subscriber
Throws:
PushSDKException - if any unrecoverable errors occur

batchIncrementConsecutiveFailedPushCount

@Deprecated
public void batchIncrementConsecutiveFailedPushCount(List<SubscriberPartial> subscribers)
                                              throws PushSDKException
Deprecated. 

Description copied from interface: SubscriptionService
Increments in a batch the count of consecutive failed push counts for subscribers by 1.

Specified by:
batchIncrementConsecutiveFailedPushCount in interface SubscriptionService
Parameters:
subscribers - list of subscribers to increment count
Throws:
PushSDKException - if any unrecoverable errors occur

batchResetConsecutiveFailedPushCount

@Deprecated
public void batchResetConsecutiveFailedPushCount(List<SubscriberPartial> subscribers)
                                          throws PushSDKException
Deprecated. 

Description copied from interface: SubscriptionService
Resets in a batch the count of consecutive failed push counts for subscribers back to 0.

Specified by:
batchResetConsecutiveFailedPushCount in interface SubscriptionService
Parameters:
subscribers - list of subscribers to reset count
Throws:
PushSDKException - if any unrecoverable errors occur

getConsecutiveFailedPushCount

@Deprecated
public int getConsecutiveFailedPushCount(SubscriberPartial subscriber)
                                  throws PushSDKException
Deprecated. 

Description copied from interface: SubscriptionService
Gets the count of consecutive failed pushes for a subscriber.

Specified by:
getConsecutiveFailedPushCount in interface SubscriptionService
Parameters:
subscriber - SubscriberPartial object with push application id and subscriber id set
Returns:
the consecutive failed push count for the subscriber
Throws:
PushSDKException - if any errors occur

findByIdPattern

public List<SubscriberPartial> findByIdPattern(String subscriberIdPattern,
                                               int startIndex,
                                               int endIndex)
                                        throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
findByIdPattern in interface SubscriptionService
Parameters:
subscriberIdPattern - a whole or partial subscriberId to match
startIndex - the index of the first entry to be retrieved
endIndex - the index of the last entry to be retrieved
Returns:
a list of subscribers, if found; otherwise, an empty list
Throws:
PushSDKException - if any unrecoverable errors occur

getSizeByIdPattern

public int getSizeByIdPattern(String subscriberIdPattern)
                       throws PushSDKException
Description copied from interface: SubscriptionService
Gets a count of all the subscribers in storage whose id contains the given subscriberIdPattern.

Specified by:
getSizeByIdPattern in interface SubscriptionService
Parameters:
subscriberIdPattern - a whole or partial subscriberId to match
Returns:
a count of subscribers
Throws:
PushSDKException - if any unrecoverable errors occur

notifyPPG

public void notifyPPG(SubscriptionType subscriptionType,
                      String pushApplicationId,
                      String address)
               throws InvalidPushAppException,
                      PPGCommunicationFailureException,
                      PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
notifyPPG in interface SubscriptionService
Parameters:
subscriptionType - the subscription operation to be performed on the PPG (subscribe is not supported)
pushApplicationId - the id of the push application
address - a subscriber's address (e.g. PIN, email address, or subscriber id for Web Signals)
Throws:
InvalidPushAppException - if the specified push application id does not match an existing push application
PPGCommunicationFailureException - if any errors occur while trying to communicate with the PPG
PushSDKException - if any unrecoverable errors occur

getSubscribeCount

public int getSubscribeCount(String pushApplicationId,
                             Date fromDate,
                             Date toDate)
                      throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
getSubscribeCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
fromDate - inclusive from date parameter of the range
toDate - inclusive to date parameter of the range
Returns:
a count of the number of new subscribers
Throws:
PushSDKException - if any unrecoverable errors occur

getUnsubscribeCount

public int getUnsubscribeCount(String pushApplicationId,
                               Date fromDate,
                               Date toDate)
                        throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
getUnsubscribeCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
fromDate - inclusive from date parameter of the range
toDate - inclusive to date parameter of the range
Returns:
a count of the number of users that unsubscribed
Throws:
PushSDKException - if any unrecoverable errors occur

getResumeCount

public int getResumeCount(String pushApplicationId,
                          Date fromDate,
                          Date toDate)
                   throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
getResumeCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
fromDate - inclusive from date parameter of the range
toDate - inclusive to date parameter of the range
Returns:
a count of the number of users that had their subscriptions resumed
Throws:
PushSDKException - if any unrecoverable errors occur

getSuspendCount

public int getSuspendCount(String pushApplicationId,
                           Date fromDate,
                           Date toDate)
                    throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
getSuspendCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
fromDate - inclusive from date parameter of the range
toDate - inclusive to date parameter of the range
Returns:
a count of the number of users that had their subscriptions suspended
Throws:
PushSDKException - if any unrecoverable errors occur

getDeviceModelCount

public List<DeviceModelCount> getDeviceModelCount(String pushApplicationId)
                                           throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
getDeviceModelCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
Returns:
a list of device model count objects
Throws:
PushSDKException - if any unrecoverable errors occur

getDeviceModelCount

public List<DeviceModelCount> getDeviceModelCount(String pushApplicationId,
                                                  SubscriberStatus status)
                                           throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
getDeviceModelCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
status - the status of a subscriber
Returns:
a list of device model count objects
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

getOsVersionCount

public List<OsVersionCount> getOsVersionCount(String pushApplicationId)
                                       throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
getOsVersionCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
Returns:
a list of OS version count objects
Throws:
PushSDKException - if any unrecoverable errors occur

getOsVersionCount

public List<OsVersionCount> getOsVersionCount(String pushApplicationId,
                                              SubscriberStatus status)
                                       throws PushSDKException
Description copied from interface: SubscriptionService
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.

Specified by:
getOsVersionCount in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
status - the status of a subscriber
Returns:
a list of OS version count objects
Throws:
PushSDKException - if any unrecoverable errors occur
See Also:
SubscriberStatus

syncSubscribersByStatusInPPG

public SubscriberSyncResult syncSubscribersByStatusInPPG(String pushApplicationId,
                                                         SubscriberStatus statusInPPG,
                                                         String syncedBy)
                                                  throws InvalidPushAppException,
                                                         PushSDKException,
                                                         SubQueryFailureException
Description copied from interface: SubscriptionService
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 SubscriptionService.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:

  1. 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.
  2. 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 should NOT be confused with SubscriptionService.syncSubscribersWithPPGForStatus(String, SubscriberStatus, int, int, String). They perform very different functions.

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:

  1. For each SDK error, call SubscriptionService.unsubscribe(UnsubscribeRequest) or SubscriptionService.suspendSubscription(SuspendRequest) based on the subscription type of the failure.
  2. For each PPG error, call SubscriptionService.notifyPPG(SubscriptionType, String, String).

Specified by:
syncSubscribersByStatusInPPG in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
statusInPPG - the status of a subscriber in the PPG (must be either ACTIVE or SUSPENDED)
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
Returns:
any failed results of a subscriber status sync operation
Throws:
InvalidPushAppException - if the push application specified is invalid
PushSDKException - if any unrecoverable errors occur
SubQueryFailureException - if a status query request sent to the PPG during the sync failed
See Also:
SubscriberStatus

syncSubscribersWithPPGByStatus

@Deprecated
public SubscriberSyncResult syncSubscribersWithPPGByStatus(String pushApplicationId,
                                                                      SubscriberStatus status,
                                                                      String syncedBy)
                                                    throws InvalidPushAppException,
                                                           PushSDKException,
                                                           SubQueryFailureException
Deprecated. 

Description copied from interface: SubscriptionService
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:

  1. 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.
  2. 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:

  1. For each SDK error, call the unsubscribe or suspendSubscription method based on the subscription type of the failure.
  2. 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.

Specified by:
syncSubscribersWithPPGByStatus in interface SubscriptionService
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
Returns:
any failed results of a subscriber status sync operation
Throws:
InvalidPushAppException - if the push application specified is invalid
PushSDKException - if any unrecoverable errors occur
SubQueryFailureException - if a status query request sent to the PPG during the sync failed
See Also:
SubscriberStatus

syncSubscribersWithPPG

@Deprecated
public SubscriberSyncResult syncSubscribersWithPPG(String pushApplicationId,
                                                              String syncedBy)
                                            throws InvalidPushAppException,
                                                   PushSDKException,
                                                   SubQueryFailureException
Deprecated. 

Description copied from interface: SubscriptionService
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:

  1. 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.
  2. 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:

  1. For each SDK error, call the unsubscribe or suspendSubscription method based on the subscription type of the failure.
  2. 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.

  1. Status in SDK: ACTIVE, Status in PPG: SUSPENDED; Action: Call the suspendSubscription method.
  2. Status in SDK: ACTIVE, Status in PPG: INACTIVE; Action: Call the unsubscribe method.
  3. Status in SDK: ACTIVE, Status in PPG: ACTIVE; Action: None.
  4. Status in SDK: SUSPENDED, Status in PPG: SUSPENDED; Action: None.
  5. Status in SDK: SUSPENDED, Status in PPG: INACTIVE; Action: Call the unsubscribe method.
  6. Status in SDK: SUSPENDED, Status in PPG: ACTIVE; Action: Call the notifyPPG method to suspend on the PPG end.
  7. Status in SDK: INACTIVE, Status in PPG: SUSPENDED; Action: Call the notifyPPG method to unsubscribe on the PPG end.
  8. Status in SDK: INACTIVE, Status in PPG: INACTIVE; Action: None.
  9. 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.

Specified by:
syncSubscribersWithPPG in interface SubscriptionService
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
Returns:
any failed results of a subscriber status sync operation
Throws:
InvalidPushAppException - if the push application specified is invalid
PushSDKException - if any unrecoverable errors occur
SubQueryFailureException - if a status query request sent to the PPG during the sync failed

syncSubscribersWithPPGForStatus

public SubscriberSyncResult syncSubscribersWithPPGForStatus(String pushApplicationId,
                                                            SubscriberStatus status,
                                                            int startIndex,
                                                            int endIndex,
                                                            String syncedBy)
                                                     throws InvalidPushAppException,
                                                            PushSDKException,
                                                            SubQueryFailureException
Description copied from interface: SubscriptionService
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:

  1. 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.
  2. 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:

  1. For each SDK error, call SubscriptionService.unsubscribe(UnsubscribeRequest) or SubscriptionService.suspendSubscription(SuspendRequest) based on the subscription type of the failure.
  2. For each PPG error, call SubscriptionService.notifyPPG(SubscriptionType, String, String).

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.

  1. Status in SDK: ACTIVE, Status in PPG: SUSPENDED; Action: Call SubscriptionService.suspendSubscription(SuspendRequest).
  2. Status in SDK: ACTIVE, Status in PPG: INACTIVE; Action: Call SubscriptionService.unsubscribe(UnsubscribeRequest).
  3. Status in SDK: ACTIVE, Status in PPG: ACTIVE; Action: None.
  4. Status in SDK: SUSPENDED, Status in PPG: SUSPENDED; Action: None.
  5. Status in SDK: SUSPENDED, Status in PPG: INACTIVE; Action: Call SubscriptionService.unsubscribe(UnsubscribeRequest).
  6. Status in SDK: SUSPENDED, Status in PPG: ACTIVE; Action: Call SubscriptionService.notifyPPG(SubscriptionType, String, String) to suspend on the PPG end.
  7. Status in SDK: INACTIVE, Status in PPG: SUSPENDED; Action: Call SubscriptionService.notifyPPG(SubscriptionType, String, String) to unsubscribe on the PPG end.
  8. Status in SDK: INACTIVE, Status in PPG: INACTIVE; Action: None.
  9. Status in SDK: INACTIVE, Status in PPG: ACTIVE; Action: Call SubscriptionService.notifyPPG(SubscriptionType, String, String) 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.

Specified by:
syncSubscribersWithPPGForStatus in interface SubscriptionService
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
Returns:
any failed results of a subscriber status sync operation
Throws:
InvalidPushAppException - if the push application specified is invalid
PushSDKException - if any unrecoverable errors occur
SubQueryFailureException - if a status query request sent to the PPG during the sync failed

syncSubscriberWithPPG

public Subscriber syncSubscriberWithPPG(String pushApplicationId,
                                        String subscriberId,
                                        String syncedBy)
                                 throws InvalidPushAppException,
                                        SubDoesNotExistException,
                                        PushSDKException,
                                        SubQueryFailureException,
                                        CPSubscriptionFailureException,
                                        PPGCommunicationFailureException
Description copied from interface: SubscriptionService
Syncs the status of a single subscriber in storage with its status on the PPG end.

WARNING: This method should not be overused. It should only be used for syncing those subscribers that have reported issues receiving pushes on their device.

Recommended use:

  1. Look up the status of the subscriber in the SDK using the SubscriptionService.findByAppIdAndId(String, String).
  2. Perform the sync by calling this method.
  3. Look up the status of the subscriber again to see if it has changed as a result of being out of sync with the PPG.

Specified by:
syncSubscriberWithPPG in interface SubscriptionService
Parameters:
pushApplicationId - the id of the push application
subscriberId - the id of the subscriber
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
Returns:
the newly synced subscriber
Throws:
InvalidPushAppException - if the push application specified is invalid
SubDoesNotExistException - if the subscriber specified could not be found
PushSDKException - if any unrecoverable errors occur
SubQueryFailureException - if a status query request sent to the PPG during the sync failed
CPSubscriptionFailureException - if there was an error performing a content provider's subscription operation during the sync
PPGCommunicationFailureException - if there was an error trying to communicate with the PPG while performing a subscription operation during the sync

createSubSyncByAddressDAO

protected abstract SubSyncByAddressDAO createSubSyncByAddressDAO()
Create a new instance of a SubSyncByAddressDAO for use by the sync methods. A new instance will be created each time a sync method is called.

Returns:
a SubSyncByAddressDAO

createSubSyncByAddressManager

protected abstract SubSyncByAddressManager createSubSyncByAddressManager()
Create a new instance of a SubSyncByAddressManager for use by the sync methods. A new instance will be created each time a sync method is called.

Returns:
a SubSyncByAddressManager

createSubSyncByStatusManager

protected abstract SubSyncByStatusManager createSubSyncByStatusManager()
Create a new instance of a SubSyncByStatusManager for use by the sync methods. A new instance will be created each time a sync method is called.

Returns:
a SubSyncByStatusManager

createSubActiveMatchManager

protected abstract SubActiveMatchManager createSubActiveMatchManager()
Create a new instance of a SubActiveMatchManager for use by subscription validation. A new instance will be created each time subscription validation is called.

Returns:
a SubActiveMatchManager

createSubStatusMatchManager

protected abstract SubStatusMatchManager createSubStatusMatchManager()
Create a new instance of a SubStatusMatchManager for use by subscription validation. A new instance will be created each time subscription validation is called.

Returns:
a SubStatusMatchManager

createSubStatusAlternateMatchManager

protected abstract SubStatusAlternateMatchManager createSubStatusAlternateMatchManager()
Create a new instance of a SubStatusAlternateMatchManager for use by the findByAppIdAndIdsAndStatus method. A new instance will be created each time findByAppIdAndIdsAndStatus is called.

Returns:
a SubStatusAlternateMatchManager

validateSubscribeFields

protected void validateSubscribeFields(SubscribeRequest subRequest)
Validates the fields present in the passed in subscribe request.

Parameters:
subRequest - the subscribe request

validateSubscriberUniqueKey

protected void validateSubscriberUniqueKey(String pushApplicationId,
                                           String subscriberId)
Validates the push application id and subscriber id passed in (i.e. make sure they are not null or empty).

Parameters:
pushApplicationId - the id of the push application
subscriberId - the id of the subscriber

validateSubscriberExists

protected Subscriber validateSubscriberExists(String pushApplicationId,
                                              String subscriberId)
                                       throws org.springframework.dao.DataAccessException,
                                              SubDoesNotExistException
Verifies that the subscriber exists for the given push application id and subscriber id.

Parameters:
pushApplicationId - the id of the push application
subscriberId - the id of the subscriber
Returns:
the validated subscriber
Throws:
org.springframework.dao.DataAccessException - if an error occurred retrieving the subscriber from storage
SubDoesNotExistException - if the subscriber could not be found


Copyright © 2011 Research In Motion. All Rights Reserved.