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:

• a type of PushApplicationType.ENTERPRISE_PUSH
• a bypass subscription flag set to true (PushApplication.isBypassSubscription() == true)

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.