Package net.rim.pushsdk.subscription.cp

This package contains an interface that content providers must implement to handle their own subscription operations.


Interface Summary
ContentProviderSubscriptionService Interface which allows a content provider to perform their own subscription actions.

Class Summary
ContentProviderSubServiceImpl Basic implementation of the ContentProviderSubscriptionService interface.

Exception Summary
CPSubscriptionFailureException Exception throw when a content provider's subscription action fails.

Package net.rim.pushsdk.subscription.cp Description

This package contains an interface that content providers must implement to handle their own subscription operations.

Content provider subscription operations:

A content provider is allowed to implement their own actions to be taken on the four subscription operations: subscribe, unsubscribe, resume, and suspend.
The content provider can define different actions on a subscription operation's success or failure.

See the Content Provider Subscription Service (ContentProviderSubscriptionService) interface for the exact methods that need to be implemented.

The default implementation of these methods, in the ContentProviderSubServiceImpl class, is to do nothing. They are essentially empty methods.

Let us examine the case of a subscribe operation to find out exactly when these methods are called:
A request is made to the subscribe servlet.
The first step is to authenticate the user. This is done through container-managed authentication or a call to the authenticateSubscriber(BaseAuthenticationRequest authenticationRequest) method from the ContentProviderAuthenticationService interface.
If authentication is successful, then the subscribe(SubscribeRequest) method on the SubscriptionService interface will be called.

The following logic appears in the subscribe(SubscribeRequest) method:
Validation is done on the input, and if it fails, the onSubscribeFailure method (see the ContentProviderSubscriptionService interface) is called.
If validation does end up passing and the SDK successfully subscribes the user, then the content provider's onSubscribeSuccess method is called.
If the content provider's own subscribe operation fails, a CPSubscriptionFailureException exception should be thrown. In this case, the SDK's subscribe operation would be rolled back and the user's subscription would no longer be present in the SDK's storage (e.g. database).
If the content provider's subscription operation succeeds, then any necessary automatic unsubscribe calls to the PPG (e.g. if we are dealing with a swap scenario) are done at the end. These cannot be rolled back, and if one fails (even after a single retry), none of the previous attempts can/will be rolled back.

Copyright © 2011 Research In Motion. All Rights Reserved.