net.rim.pushsdk.push
Interface PushService

All Known Implementing Classes:
PushServiceImpl

public interface PushService

Interface for sending push messages, cancelling a previously submitted message or querying the status of a previously submitted message.

It is mandatory that all setters for collaborating objects are called prior to using the methods offered by this interface.

Note that, for PushService and related parameters and results classes, an "address" is a subscriber id (i.e. Subscriber.getId()).
The only exception to this is when pushing to a push application with:

in which case an address is the client address (i.e. PIN or email address).

Author:
mdicesare, mdandrea

Field Summary
static String ADDRESS_COUNT_PARAMETER
          The name of the address count HTTP request parameter to be appended to the end of a notification URL.
static String APPID_REQUEST_PARAMETER
          The name of the application id HTTP request parameter to be appended to the end of a notification URL.
 
Method Summary
 CancelResult cancel(String applicationId, String pushId)
          Sends a cancel request using the attributes specified.
 CancelResult cancel(String applicationId, String pushId, List<String> addresses)
          Sends a cancel request using the attributes specified.
 CancelResult cancel(String applicationId, String pushId, String address)
          Sends a cancel request using the attributes specified.
 PushResult push(PushParameters pushParameters)
          Sends a push request using the attributes in the specified PushParameters.
 void setPapService(PapService papService)
          Support for dependency injection.
 void setPushApplicationService(PushApplicationService pushAppService)
          Support for dependency injection.
 void setPushCountService(PushCountService pushCountService)
          Support for dependency injection.
 void setPushIdGenerator(IdGenerator pushIdGenerator)
          Support for dependency injection.
 void setPushRequestDetailService(PushRequestDetailService pushRequestDetailService)
          Support for dependency injection.
 void setPushRequestService(PushRequestService pushRequestService)
          Support for dependency injection.
 void setPushSDKProperties(PushSDKProperties pushSDKProperties)
          Support for dependency injection.
 void setPushStatsService(PushStatsService pushStatsService)
          Support for dependency injection.
 void setSubscriptionService(SubscriptionService subscriptionService)
          Support for dependency injection.
 StatusResult statusQueryAll(String applicationId, String pushId)
          Queries the status of a previously submitted push request for all addresses.
 StatusResult statusQueryAll(String applicationId, String pushId, List<String> addresses)
          Queries the status of a previously submitted push request.
 StatusResult statusQueryAll(String applicationId, String pushId, String address)
          Queries the status of a previously submitted push request.
 StatusResult statusQueryCompleted(String applicationId, String pushId)
          Queries the status of a push request for addresses to which delivery has completed.
 StatusResult statusQueryFailed(String applicationId, String pushId)
          Queries the status of a push request for addresses to which delivery has failed.
 StatusResult statusQueryPending(String applicationId, String pushId)
          Queries the status of a push request for addresses to which delivery is pending.
 

Field Detail

APPID_REQUEST_PARAMETER

static final String APPID_REQUEST_PARAMETER
The name of the application id HTTP request parameter to be appended to the end of a notification URL.

See Also:
Constant Field Values

ADDRESS_COUNT_PARAMETER

static final String ADDRESS_COUNT_PARAMETER
The name of the address count HTTP request parameter to be appended to the end of a notification URL.

See Also:
Constant Field Values
Method Detail

push

PushResult push(PushParameters pushParameters)
                throws PushSDKException,
                       UnauthorizedException,
                       InvalidPushAppException,
                       InvalidPushRequestException
Sends a push request using the attributes in the specified PushParameters.

The PushResult will contain the outcome of the push request. See the PushResult class for more details about what is returned.

Parameters:
pushParameters - defines the attributes of the push message to send
Returns:
the result of the push operation
Throws:
IllegalArgumentException - if any of the information passed in fails validation; or, if the following scenario occurs: 1) the push application being pushed to has a type of PushApplicationType.PUBLIC_PUSH and is storing push requests, 2) the push_all address is used, and 3) the number of active subscribers for the application exceeds PushSDKProperties.getSubscriptionFindMaxResults().
UnauthorizedException - the push did not succeed due to an authorization failure at the PPG
InvalidPushAppException - the push did not succeed since the application being pushed to was invalid
InvalidPushRequestException - the push did not succeed due to an invalid push id (either not a unique id or was unable to generate a new push id)
PushSDKException - if the push could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

cancel

CancelResult cancel(String applicationId,
                    String pushId,
                    List<String> addresses)
                    throws PushSDKException,
                           UnauthorizedException,
                           InvalidPushAppException,
                           InvalidPushRequestException
Sends a cancel request using the attributes specified.

The CancelResult will contain the outcome of the cancel request. See the CancelResult class for more details about what is returned.

Note: Cancelling a message is not guaranteed and is only a best effort. To know if the cancel succeeded, you must issue a status query or if you are using acknowledgements you will be notified asynchronously when the final outcome is known by the PPG.

Note: If the push application is not storing push requests, and if the addresses specified are subscriber IDs, then they will be mapped to client addresses (e.g. PINs) using the currently known mapping. This may result in incorrect results if a subscriber or device swap occurred after the push request was issued.

Parameters:
pushId - the id of the previously submitted push request to cancel
addresses - optional parameter that contains a list of addresses for which the request should be cancelled
Returns:
the result of the cancel operation
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the cancel did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the cancel did not succeed due to an invalid pushId provided
InvalidPushAppException - the cancel did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the cancel could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

cancel

CancelResult cancel(String applicationId,
                    String pushId,
                    String address)
                    throws PushSDKException,
                           UnauthorizedException,
                           InvalidPushAppException,
                           InvalidPushRequestException
Sends a cancel request using the attributes specified.

The CancelResult will contain the outcome of the cancel request. See the CancelResult class for more details about what is returned.

Note: Cancelling a message is not guaranteed and is only a best effort. To know if the cancel succeeded, you must issue a status query or if you are using acknowledgements you will be notified asynchronously when the final outcome is known by the PPG.

Note: If the push application is not storing push requests, and if the address specified is a subscriber ID, then it will be mapped to a client address (e.g. PIN) using the currently known mapping. This may result in incorrect results if a subscriber or device swap occurred after the push request was issued.

Parameters:
pushId - the id of the previously submitted push request to cancel
address - optional parameter that contains an address for which the request should be cancelled
Returns:
the result of the cancel operation
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the cancel did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the cancel did not succeed due to an invalid pushId provided
InvalidPushAppException - the cancel did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the cancel could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

cancel

CancelResult cancel(String applicationId,
                    String pushId)
                    throws PushSDKException,
                           UnauthorizedException,
                           InvalidPushAppException,
                           InvalidPushRequestException
Sends a cancel request using the attributes specified. This will attempt to cancel the push for all addresses specified in the original push request (matching the pushId specified).

The CancelResult will contain the outcome of the cancel request. See the CancelResult class for more details about what is returned.

Note: Cancelling a message is not guaranteed and is only a best effort. To know if the cancel succeeded, you must issue a status query or if you are using acknowledgements you will be notified asynchronously when the final outcome is known by the PPG.

Parameters:
pushId - the id of the previously submitted push request to cancel
Returns:
the result of the cancel operation
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the cancel did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the cancel did not succeed due to an invalid pushId provided
InvalidPushAppException - the cancel did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the cancel could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

statusQueryAll

StatusResult statusQueryAll(String applicationId,
                            String pushId,
                            List<String> addresses)
                            throws PushSDKException,
                                   UnauthorizedException,
                                   InvalidPushRequestException,
                                   InvalidPushAppException
Queries the status of a previously submitted push request.

The StatusResult will contain the outcome of the status query request. See the StatusResult class for more details about what is returned.

Note: If the push application is not storing push requests, and if the addresses specified are subscriber IDs, then they will be mapped to client addresses (e.g. PINs) using the currently known mapping. This may result in incorrect results if a subscriber or device swap occurred after the push request was issued.

Parameters:
applicationId - the unique id of the push application to query
pushId - the id of the push that this request is querying about
addresses - the list of the addresses from the original push request that this call is querying about
Returns:
the response from the status query request
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the status query did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the status query did not succeed due to an invalid pushId provided
InvalidPushAppException - the status query did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the status query could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

statusQueryAll

StatusResult statusQueryAll(String applicationId,
                            String pushId,
                            String address)
                            throws PushSDKException,
                                   UnauthorizedException,
                                   InvalidPushRequestException,
                                   InvalidPushAppException
Queries the status of a previously submitted push request.

The StatusResult will contain the outcome of the status query request. See the StatusResult class for more details about what is returned.

Note: If the push application is not storing push requests, and if the address specified is a subscriber ID, then it will be mapped to a client address (e.g. PIN) using the currently known mapping. This may result in incorrect results if a subscriber or device swap occurred after the push request was issued.

Parameters:
applicationId - the unique id of the push application to query
pushId - the id of the push that this request is querying about
address - the address from the original push request that this call is querying about
Returns:
the response from the status query request
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the status query did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the status query did not succeed due to an invalid pushId provided
InvalidPushAppException - the status query did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the status query could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

statusQueryAll

StatusResult statusQueryAll(String applicationId,
                            String pushId)
                            throws PushSDKException,
                                   UnauthorizedException,
                                   InvalidPushRequestException,
                                   InvalidPushAppException
Queries the status of a previously submitted push request for all addresses.

The StatusResult will contain the outcome of the status query request. See the StatusResult class for more details about what is returned.

Parameters:
applicationId - the unique id of the push application to query
pushId - the id of the push that this request is querying about
Returns:
the response from the status query request
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the status query did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the status query did not succeed due to an invalid pushId provided
InvalidPushAppException - the status query did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the status query could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

statusQueryCompleted

StatusResult statusQueryCompleted(String applicationId,
                                  String pushId)
                                  throws PushSDKException,
                                         UnauthorizedException,
                                         InvalidPushRequestException,
                                         InvalidPushAppException
Queries the status of a push request for addresses to which delivery has completed.

The StatusResult will contain the outcome of the status query request. See the StatusResult class for more details about what is returned.

Parameters:
applicationId - the unique id of the push application to query
pushId - the id of the push that this request is querying about
Returns:
the response from the status query request
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the status query did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the status query did not succeed due to an invalid pushId provided
InvalidPushAppException - the status query did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the status query could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

statusQueryFailed

StatusResult statusQueryFailed(String applicationId,
                               String pushId)
                               throws PushSDKException,
                                      UnauthorizedException,
                                      InvalidPushRequestException,
                                      InvalidPushAppException
Queries the status of a push request for addresses to which delivery has failed.

The StatusResult will contain the outcome of the status query request. See the StatusResult class for more details about what is returned.

Parameters:
applicationId - the unique id of the push application to query
pushId - the id of the push that this request is querying about
Returns:
the response from the status query request
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the status query did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the status query did not succeed due to an invalid pushId provided
InvalidPushAppException - the status query did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the status query could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

statusQueryPending

StatusResult statusQueryPending(String applicationId,
                                String pushId)
                                throws PushSDKException,
                                       UnauthorizedException,
                                       InvalidPushRequestException,
                                       InvalidPushAppException
Queries the status of a push request for addresses to which delivery is pending.

The StatusResult will contain the outcome of the status query request. See the StatusResult class for more details about what is returned.

Parameters:
applicationId - the unique id of the push application to query
pushId - the id of the push that this request is querying about
Returns:
the response from the status query request
Throws:
IllegalArgumentException - if any of the information passed in fails validation
UnauthorizedException - the status query did not succeed due to an authorization failure at the PPG
InvalidPushRequestException - the status query did not succeed due to an invalid pushId provided
InvalidPushAppException - the status query did not succeed due to an invalid push application associated with the provided push request
PushSDKException - if the status query could not be sent for various other reasons (e.g. malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by the SDK, etc.). The exception stack trace will have details of the error.

setPushIdGenerator

void setPushIdGenerator(IdGenerator pushIdGenerator)
Support for dependency injection. Inject an implementation of an IdGenerator collaborating object - this is used when a pushId is null on the push() method.

Parameters:
pushIdGenerator - an instance of an IdGenerator implementation (must be thread safe)

setPapService

void setPapService(PapService papService)
Support for dependency injection. Inject an implementation of a papService collaborating object - this is used to send the PAP messages to the PPG.

Parameters:
papService - an instance of a papService implementation (must be thread safe)

setPushSDKProperties

void setPushSDKProperties(PushSDKProperties pushSDKProperties)
Support for dependency injection. Inject an implementation of a PushSDKProperties collaborating object - this is used to read global configuration properties.

Parameters:
pushSDKProperties - an instance of a PushSDKProperties implementation (must be thread safe)

setPushApplicationService

void setPushApplicationService(PushApplicationService pushAppService)
Support for dependency injection. Inject an implementation of a PushApplicationService collaborating object - this is used to interface with the business service that manages push applications.

Parameters:
pushAppService - an instance of a PushApplicationService implementation (must be thread safe)

setSubscriptionService

void setSubscriptionService(SubscriptionService subscriptionService)
Support for dependency injection. Inject an implementation of a SubscriptionService collaborating object - this is used to interface with the business service that manages subscriptions.

Parameters:
subscriptionService - an instance of a SubscriptionService implementation (must be thread safe)

setPushRequestService

void setPushRequestService(PushRequestService pushRequestService)
Support for dependency injection. Inject an implementation of a PushRequestService collaborating object - this is used to interface with the business service that manages push requests.

Parameters:
pushRequestService - an instance of a PushRequestService implementation (must be thread safe)

setPushRequestDetailService

void setPushRequestDetailService(PushRequestDetailService pushRequestDetailService)
Support for dependency injection. Inject an implementation of a PushRequestDetailService collaborating object - this is used to interface with the business service that manages push request details.

Parameters:
pushRequestDetailService - an instance of a PushRequestDetailService implementation (must be thread safe)

setPushCountService

void setPushCountService(PushCountService pushCountService)
Support for dependency injection. Inject an implementation of a PushCountService collaborating object - this is used to interface with the business service that manages tracking pushes that are complete.


setPushStatsService

void setPushStatsService(PushStatsService pushStatsService)
Support for dependency injection. Inject an implementation of a PushStatsService collaborating object - this is used to interface with the business service that manages tracking push statistics.



Copyright © 2011 Research In Motion. All Rights Reserved.