net.rim.pushsdk.pap
Interface PapService

All Known Implementing Classes:

AcknowledgementPapServiceImpl, PapServiceImpl

public interface PapService

Interface defining push operations to send PAP 2.1/2.0 XML to a Push Proxy Gateway (PPG) and parse the PAP XML responses.

Author:

mdicesare

Method Summary
CancelResponse	cancel(String username, String password, CancelMessageControl cancelMessage) Sends a cancel request using the attributes in the cancelMessage.
void	onNotification(ResultNotification resultNotification, Map<String,String[]> notificationParameters) Implement this method in order to perform custom actions on result notification.
PushResponse	push(String username, String password, String destination, PushMessageControl pushMessage, Content content) Sends a push request with the specified content using the specified attributes.
ResultNotificationResponseControl	receiveNotification(String notificationMessage, Map<String,String[]> requestParameters) Called when a result notification message is received from the PPG (e.g.
void	setHttpClient(HttpClient httpClient) Support for dependency injection.
void	setPushSDKProperties(PushSDKProperties pushSDKProperties) Support for dependency injection.
StatusQueryResponse	statusQuery(String username, String password, StatusQueryMessageControl statusQueryMessage) Sends a status query request using the attributes in the statusQueryMessage.

Method Detail

push

PushResponse push(String username,
                  String password,
                  String destination,
                  PushMessageControl pushMessage,
                  Content content)
                  throws PushSDKException,
                         BadMessageException,
                         UnauthorizedException

Sends a push request with the specified content using the specified attributes.

Note: If content was specified, then this method will check if a Push-Message-Id header has been specified as part of the top-most Content. If it has not, a Push-Message-ID header will be automatically added with the push id. This may assist in implementing duplicate message detection on the device side and various other use cases.

Parameters:

username - the username of the Push Initiator (for a public (BIS) push, this would be the application id; for an enterprise (BES) push, this might be null)

password - the password of the Push Initiator (for a public (BIS) push, this would be the application password; for an enterprise (BES) push, this might be null)

destination - for a public (BIS) push, the application id to push the content to; for an enterprise (BES) push, the application port to push the content to

pushMessage - the push message attributes needed to construct the PAP request

content - the content of the push message

Returns:

the PAP response from the push request

Throws:

IllegalArgumentException - if any of the information passed in fails validation

BadMessageException - if the PPG returned a badmessage-response (i.e. the PPG could not understand/parse the PAP XML sent by the SDK)

PushSDKException - if the message could not be sent for various other reasons (e.g. a malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by this SDK, etc.)

UnauthorizedException - the push did not succeed due to authorization failure at the PPG

cancel

CancelResponse cancel(String username,
                      String password,
                      CancelMessageControl cancelMessage)
                      throws PushSDKException,
                             BadMessageException,
                             UnauthorizedException

Sends a cancel request using the attributes in the cancelMessage.

Parameters:

username - the username of the Push Initiator (for a public (BIS) push, this would be the application id; for an enterprise (BES) push, this might be null)

password - the password of the Push Initiator (for a public (BIS) push, this would be the application password; for an enterprise (BES) push, this might be null)

cancelMessage - the cancel message attributes needed to construct the PAP request

Returns:

the PAP response from the cancel request

Throws:

IllegalArgumentException - if any of the information passed in fails validation

BadMessageException - if the PPG returned a badmessage-response (i.e. the PPG could not understand/parse the PAP XML sent by this SDK)

PushSDKException - if the cancel could not be sent for various other reasons (e.g. a malformed PPG URL, the PAP XML response returned by the PPG could not be parsed by this SDK, etc.)

UnauthorizedException - the cancel did not succeed due to authorization failure at the PPG

statusQuery

StatusQueryResponse statusQuery(String username,
                                String password,
                                StatusQueryMessageControl statusQueryMessage)
                                throws PushSDKException,
                                       BadMessageException,
                                       UnauthorizedException

Sends a status query request using the attributes in the statusQueryMessage.

Parameters:

username - the username of the Push Initiator (for a public (BIS) push, this would be the application id; for an enterprise (BES) push, this might be null)

password - the password of the Push Initiator (for a public (BIS) push, this would be the application password; for an enterprise (BES) push, this might be null)

statusQueryMessage - the status query message attributes needed to construct the PAP request

Returns:

the PAP response from the status query request

Throws:

IllegalArgumentException - if any of the information passed in fails validation

BadMessageException - if the PPG returned a badmessage-response (i.e. the PPG could not understand/parse the PAP XML sent by this SDK)

PushSDKException - if the PAP XML response returned by the PPG could not be parsed by this SDK

PushSDKException - if the status query could not be sent for various other reasons (e.g. a malformed PPG URL, if the PAP XML response returned by the PPG could not be parsed by this SDK, etc.)

UnauthorizedException - the status query did not succeed due to authorization failure at the PPG

onNotification

void onNotification(ResultNotification resultNotification,
                    Map<String,String[]> notificationParameters)
                    throws PushSDKException

Implement this method in order to perform custom actions on result notification.
The default implementation does nothing.

Parameters:

resultNotification - the result notification sent by the PPG

notificationParameters - request parameters from the result notification sent by the PPG

Throws:

PushSDKException - if the result notification cannot be processed

receiveNotification

ResultNotificationResponseControl receiveNotification(String notificationMessage,
                                                      Map<String,String[]> requestParameters)

Called when a result notification message is received from the PPG (e.g. by a servlet).
The default implementation will unmarshal the result notification and validate its fields, construct the result notification response, and call the onNotification method with the result notification request.

Parameters:

notificationMessage - PAP result notification XML message as a UTF-8 string

requestParameters - Request parameters from the result notification sent by the PPG

Returns:

result notification response to be sent to the PPG

setHttpClient

void setHttpClient(HttpClient httpClient)

Support for dependency injection. This will override the default HttpClient implementation.

Parameters:

httpClient - the HTTP client

setPushSDKProperties

void setPushSDKProperties(PushSDKProperties pushSDKProperties)

Support for dependency injection. This will override the default PushSDKProperties implementation.

Parameters:

pushSDKProperties - the push SDK properties