net.rim.pushsdk.pushappmgmt
Interface PushApplicationService

All Known Implementing Classes:
PushApplicationServiceImpl

public interface PushApplicationService

Business service methods relating to managing push applications.

Author:
mdicesare

Method Summary
 void addPushApplication(PushApplication pushApplication)
          Adds the specified push application to the persistent store.
 void changePushApplicationCredentials(String id, String currentUsername, String newUsername, String currentPassword, String newPassword, String modifiedBy)
          Deprecated. As of release 1.1, replaced by changePushApplicationPublicCredentials(String, String, String, String) for updating the public credentials of a push application and changePushApplicationEnterpriseCredentials(String, String, String, String, String, String) for updating the enterprise credentials of a push application.
 void changePushApplicationEnterpriseCredentials(String id, String currentUsername, String newUsername, String currentPassword, String newPassword, String modifiedBy)
          Change the enterprise username and password of a push application that has a type of Enterprise Push or Public+Enterprise Push.
 void changePushApplicationPublicCredentials(String id, String currentPassword, String newPassword, String modifiedBy)
          Change the public password of a push application that has a type of Public Push, Web Signal, or Public+Enterprise Push.
 void changePushApplicationTypeFromEnterpriseToPublicAndEnterprise(String id, String publicPassword, String publicNotifyUrl, String modifiedBy)
          Changes the type of a push application from Enterprise Push to Public+Enterprise Push.
 void changePushApplicationTypeFromPublicToPublicAndEnterprise(String id, String enterpriseUsername, String enterprisePassword, String enterpriseNotifyUrl, String modifiedBy)
          Changes the type of a push application from Public Push to Public+Enterprise Push.
 void deletePushApplication(String id, String deletedBy, boolean shouldUnsubscribeBeforeDelete)
          Warning!
Removes a push application and any related entities entirely and permanently from the persistent store.
 void disablePushApplication(String id, String modifiedBy)
          Disables (sets to inactive) a push application.
 void enablePushApplication(String id, Date expiryDate, String modifiedBy)
          Enables (sets to active) a push application.
 List<PushApplication> findAll()
          Finds a list of all the push applications in storage.
 PushApplication findById(String id)
          Finds the push application with the specified push application id.
 PushApplication findByIdAndValidate(String id)
          Finds the push application with the specified push application id and validates the push application.
 PushApplication findByName(String name)
          Finds the push application with the specified name.
 List<PushApplication> findByStatus(PushApplicationStatus status)
          Finds a list of push applications with the specified status.
 List<PushApplication> findByType(PushApplicationType type)
          Finds a list of push applications with the specified type.
 void setPushApplicationDAO(PushApplicationDAO pushApplicationDAO)
          Support for dependency injection.
 void setPushSDKProperties(PushSDKProperties pushSDKProperties)
          Support for dependency injection.
 void setPushStatsDAO(PushStatsDAO pushStatsDAO)
          Support for dependency injection.
 void updatePushApplication(PushApplication pushApplication)
          Updates the details of a push application.
 

Method Detail

addPushApplication

void addPushApplication(PushApplication pushApplication)
                        throws InvalidPushAppException,
                               PushSDKException
Adds the specified push application to the persistent store.

Parameters:
pushApplication - the push application to add
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if a push application already exists with the given id or name
PushSDKException - if any other errors occur

updatePushApplication

void updatePushApplication(PushApplication pushApplication)
                           throws InvalidPushAppException,
                                  PushSDKException
Updates the details of a push application. Note: This method CANNOT be used to change the credentials (username and password) of a push application. It will throw an IllegalArgumentException if the credentials are attempted to be changed.

Parameters:
pushApplication - the updated push application
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found or another push application already exists with the updated name
PushSDKException - if any other errors occur

changePushApplicationTypeFromPublicToPublicAndEnterprise

void changePushApplicationTypeFromPublicToPublicAndEnterprise(String id,
                                                              String enterpriseUsername,
                                                              String enterprisePassword,
                                                              String enterpriseNotifyUrl,
                                                              String modifiedBy)
                                                              throws InvalidPushAppException,
                                                                     PushSDKException
Changes the type of a push application from Public Push to Public+Enterprise Push.

Parameters:
id - the id of the push application
enterpriseUsername - an optional username for enterprise (BES) pushes; null if not required
enterprisePassword - an optional password for enterprise (BES) pushes; null if not required
enterpriseNotifyUrl - a full notification URL for enterprise (BES) acknowledgements; null if using a service level of Push Essentials
modifiedBy - the user that is changing the push application's type
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found or is of an incorrect type
PushSDKException - if any other errors occur
Since:
1.1
See Also:
PushApplicationType

changePushApplicationTypeFromEnterpriseToPublicAndEnterprise

void changePushApplicationTypeFromEnterpriseToPublicAndEnterprise(String id,
                                                                  String publicPassword,
                                                                  String publicNotifyUrl,
                                                                  String modifiedBy)
                                                                  throws InvalidPushAppException,
                                                                         PushSDKException
Changes the type of a push application from Enterprise Push to Public+Enterprise Push.

Note: If the Enterprise Push application you are changing the type for has the "bypass subscription" flag set to true, you must first update this flag to false (since Public+Enterprise Push applications do not support the bypassing of subscriptions) using the updatePushApplication method. This method can then be called.

Parameters:
id - the id of the push application
publicPassword - a password for public (BIS) pushes
publicNotifyUrl - a notification URL fragment for public (BIS) acknowledgements; null if using a service level of Push Essentials
modifiedBy - the user that is changing the push application's type
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found or is of an incorrect type
PushSDKException - if any other errors occur
Since:
1.1
See Also:
PushApplicationType

findById

PushApplication findById(String id)
                         throws PushSDKException
Finds the push application with the specified push application id.

Parameters:
id - the id of the push application to lookup
Returns:
the push application; null if the push application cannot be found
Throws:
PushSDKException - if any other errors occur

findByIdAndValidate

PushApplication findByIdAndValidate(String id)
                                    throws InvalidPushAppException,
                                           PushSDKException
Finds the push application with the specified push application id and validates the push application. Validations performed: the application exists in the persistence store, the application is active, the application is not expired.

Parameters:
id - the id of the push application to lookup
Returns:
the push application; null if the push application is not found
Throws:
InvalidPushAppException - if the push application specified fails validation
PushSDKException - if any other errors occur

findByName

PushApplication findByName(String name)
                           throws PushSDKException
Finds the push application with the specified name.

Parameters:
name - the name of the push application to lookup
Returns:
the push application; null if the push application is not found
Throws:
PushSDKException - if any other errors occur

findByStatus

List<PushApplication> findByStatus(PushApplicationStatus status)
                                   throws PushSDKException
Finds a list of push applications with the specified status.

Parameters:
status - the status of a push application
Returns:
a list of push applications; otherwise, an empty list, if no matches could be found
Throws:
PushSDKException - if any other errors occur
See Also:
PushApplicationStatus

findByType

List<PushApplication> findByType(PushApplicationType type)
                                 throws PushSDKException
Finds a list of push applications with the specified type.

Parameters:
type - the type of a push application
Returns:
a list of push applications; otherwise, an empty list, if no matches could be found
Throws:
PushSDKException - if any other errors occur
Since:
1.1
See Also:
PushApplicationType

findAll

List<PushApplication> findAll()
                              throws PushSDKException
Finds a list of all the push applications in storage.

Returns:
a list of push applications; otherwise, an empty list, if there are none in storage
Throws:
PushSDKException - if any other errors occur

disablePushApplication

void disablePushApplication(String id,
                            String modifiedBy)
                            throws InvalidPushAppException,
                                   PushSDKException
Disables (sets to inactive) a push application.

Parameters:
id - the id of the push application
modifiedBy - the user that disabled the push application
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found or is already disabled
PushSDKException - if any other errors occur

enablePushApplication

void enablePushApplication(String id,
                           Date expiryDate,
                           String modifiedBy)
                           throws InvalidPushAppException,
                                  PushSDKException
Enables (sets to active) a push application.

Parameters:
id - the id of the push application
expiryDate - the new expiry date for the push application; if null is specified, the expiry date will remain unchanged
modifiedBy - the user that enabled the push application
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found or is already enabled
PushSDKException - if any other errors occur

deletePushApplication

void deletePushApplication(String id,
                           String deletedBy,
                           boolean shouldUnsubscribeBeforeDelete)
                           throws InvalidPushAppException,
                                  PushSDKException
Warning!
Removes a push application and any related entities entirely and permanently from the persistent store. Related entities include any push messages sent to the push application and any subscriptions for the push application.

Parameters:
id - the id of the push application to remove entirely and permanently
deletedBy - an identifier that identifies the caller of this API. The deletedBy value will be placed into the log files at info level for audit purposes
shouldUnsubscribeBeforeDelete - whether or not to unsubscribe the users of this push application from the content provider and the PPG (if the PPG supports subscription) before performing the delete operation; a value of 'true' will ensure that the onAutomaticUnsubscribe method is called in the ContentProviderSubscriptionService interface. By implementing onAutomaticUnsubscribe you can perform any of your own application's custom logic for each subscriber being auto unsubscribed
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found
PushSDKException - if any other errors occur

changePushApplicationCredentials

@Deprecated
void changePushApplicationCredentials(String id,
                                                 String currentUsername,
                                                 String newUsername,
                                                 String currentPassword,
                                                 String newPassword,
                                                 String modifiedBy)
                                      throws InvalidPushAppException,
                                             IncorrectUsernameException,
                                             IncorrectPasswordException,
                                             PushSDKException
Deprecated. As of release 1.1, replaced by changePushApplicationPublicCredentials(String, String, String, String) for updating the public credentials of a push application and changePushApplicationEnterpriseCredentials(String, String, String, String, String, String) for updating the enterprise credentials of a push application.

Changes the username and password of a push application.

Parameters:
id - the id of the push application
currentUsername - the current username of the push application (Note: for an application with a type of Public Push, this parameter is ignored, since it needs to match the id.)
newUsername - the new username for the push application (Note: for an application with a type of Public Push, this parameter is ignored, since it needs to match the id.)
currentPassword - the current password of the push application
newPassword - the new password for the push application
modifiedBy - the user that is changing the push application's credentials
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found
IncorrectUsernameException - if the current username does not match the username found for the push application in storage
IncorrectPasswordException - if the current password does not match the password found for the push application in storage
PushSDKException - if any other errors occur

changePushApplicationPublicCredentials

void changePushApplicationPublicCredentials(String id,
                                            String currentPassword,
                                            String newPassword,
                                            String modifiedBy)
                                            throws InvalidPushAppException,
                                                   IncorrectPasswordException,
                                                   PushSDKException
Change the public password of a push application that has a type of Public Push, Web Signal, or Public+Enterprise Push.

Parameters:
id - the id of the push application
currentPassword - the current password of the push application
newPassword - the new password for the push application
modifiedBy - the user that is changing the push application's public credentials
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found or is of an incorrect type
IncorrectPasswordException - if the current public password does not match the public password found for the push application in storage
PushSDKException - if any other errors occur
Since:
1.1

changePushApplicationEnterpriseCredentials

void changePushApplicationEnterpriseCredentials(String id,
                                                String currentUsername,
                                                String newUsername,
                                                String currentPassword,
                                                String newPassword,
                                                String modifiedBy)
                                                throws InvalidPushAppException,
                                                       IncorrectUsernameException,
                                                       IncorrectPasswordException,
                                                       PushSDKException
Change the enterprise username and password of a push application that has a type of Enterprise Push or Public+Enterprise Push.

Parameters:
id - the id of the push application
currentUsername - the current username of the push application (might be null)
newUsername - the new username for the push application (might be null)
currentPassword - the current password of the push application (might be null)
newPassword - the new password for the push application (might be null)
modifiedBy - the user that is changing the push application's enterprise credentials
Throws:
IllegalArgumentException - if any of the information passed in fails validation
InvalidPushAppException - if the push application could not be found or is of an incorrect type
IncorrectUsernameException - if the current enterprise username does not match the enterprise username for the push application in storage
IncorrectPasswordException - if the current enterprise password does not match the enterprise password found for the push application in storage
PushSDKException - if any other errors occur
Since:
1.1

setPushApplicationDAO

void setPushApplicationDAO(PushApplicationDAO pushApplicationDAO)
Support for dependency injection. Sets the PushApplicationDAO to use.

Parameters:
pushApplicationDAO - an instance of a PushApplicationDAO implementation

setPushSDKProperties

void setPushSDKProperties(PushSDKProperties pushSDKProperties)
Support for dependency injection. This will override the default PushSDKProperties implementation.

Parameters:
pushSDKProperties - an instance of a PushSDKProperties implementation

setPushStatsDAO

void setPushStatsDAO(PushStatsDAO pushStatsDAO)
Support for dependency injection. Sets the PushStatsDAO to use.

Parameters:
pushStatsDAO - the Push Stats Data Access Object


Copyright © 2011 Research In Motion. All Rights Reserved.