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


Copyright © 2011 Research In Motion. All Rights Reserved.